Package org.jibx.runtime.impl
Class MarshallingContext
java.lang.Object
org.jibx.runtime.impl.MarshallingContext
- All Implemented Interfaces:
IMarshallingContext
JiBX serializer supplying convenience methods for marshalling. Most of these
methods are designed for use in code generated by the binding generator.
- Author:
- Dennis M. Sosnoski
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final int
Starting size for object stack.private OutByteBuffer
Buffer used when writing to stream (lazy create,null
if unused).private String[]
Names of classes included in mapping definition.private StringIntHashMap
Map from fully-qualified class name to index in internal tables.private IBindingFactory
Binding factory used to create this unmarshaller.private HashMap
Shared map from IDs to objects.private char
Character used for indenting.private int
Indent character count per level.private IMarshaller[]
Marshallers for classes in mapping definition (lazy create of actual marshaller instances)private String
Character sequence for end of line.private Object[]
Stack of objects being marshalled.private int
Current marshalling stack depth.private int
Index past end of last fixed marshaller class.private String[]
Transient marshaller classes for mapping definition (null
for mappings out of context).private String[]
URIs for namespaces used in binding.protected Object
User context object (not used by JiBX, only for user convenience).private IXMLWriter
Output document handler.static final String
Fixed XML namespace. -
Constructor Summary
ConstructorsConstructorDescriptionMarshallingContext
(String[] classes, String[] mcs, String[] uris, IBindingFactory ifact) Constructor. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addMarshalling
(String mapname, String name) Define marshalling for class.Generate integer attribute.Generate enumeration attribute.Generate text attribute.buildNameString
(int index, String name) Build name with optional namespace.Close start tag with content to follow.Close start tag with no content (empty tag).content
(int value) Add integer content to current element.Add enumeration content to current element.Add text content to current element.private ICharacterEscaper
createEscaper
(String enc) Create character escaper for encoding.Generate complete element with integer content.Generate complete element with enumeration content.Generate complete element with text content.void
End document.Generate end tag for element.Return the binding factory used to create this unmarshaller.getIdMap()
Get shared ID map.int
Get current nesting indent spaces.getMarshaller
(String mapname) Find the marshaller for a particular class index in the current context.String[]
Get namespace URIs for mapping.int
Get current marshalling object stack depth.getStackObject
(int depth) Get object from marshalling stack.Get top object on marshalling stack.Get the user context object.Get the writer being used for output.Marshal all items in a collection.Marshal all items in a collection.marshalCollection
(Vector col) Marshal all items in a collection.void
marshalDocument
(Object root) Marshal document from root object without XML declaration.void
marshalDocument
(Object root, String enc, Boolean alone) Marshal document from root object.void
marshalDocument
(Object root, String enc, Boolean alone, OutputStream outs) Marshal document from root object to output stream with encoding.void
marshalDocument
(Object root, String enc, Boolean alone, Writer outw) Marshal document from root object to writer.protected void
marshalRoot
(Object root) Marshal document from root object.void
End use of namespace indexes from a separate binding.void
Pop marshalled object from stack.void
pushNamespaces
(String factname) Use namespace indexes from a separate binding, as identified by that binding's factory class name.void
pushObject
(Object obj) Push created object to marshalling stack.void
removeMarshalling
(String mapname) Undefine marshalling for element.void
reset()
Reset to initial state for reuse.void
setFromContext
(MarshallingContext parent) Initializes the context to use the same marshalled text destination and parameters as another marshalling context.void
setIndent
(int count) Set nesting indent spaces.void
Set nesting indentation.void
setOutput
(OutputStream outs, String enc) Set output stream and encoding.void
setOutput
(OutputStream outs, String enc, ICharacterEscaper esc) Set output stream with encoding and escaper.void
Set output writer.void
setOutput
(Writer outw, ICharacterEscaper esc) Set output writer and escaper.void
setUserContext
(Object obj) Set a user context object.void
setXmlWriter
(IXMLWriter xwrite) Set the writer being used for output.void
startDocument
(String enc, Boolean alone) Start document.void
startDocument
(String enc, Boolean alone, OutputStream outs) Start document with output stream and encoding.void
startDocument
(String enc, Boolean alone, Writer outw) Start document with writer.Generate start tag for element without attributes.startTagAttributes
(int index, String name) Generate start tag for element with attributes.startTagNamespaces
(int index, String name, int[] nums, String[] prefs) Generate start tag for element with namespaces.writeCData
(String text) Write CDATA text to document.writeContent
(String text) Write content value with character entity substitutions.
-
Field Details
-
XML_NAMESPACE
Fixed XML namespace.- See Also:
-
INITIAL_STACK_SIZE
private static final int INITIAL_STACK_SIZEStarting size for object stack.- See Also:
-
m_factory
Binding factory used to create this unmarshaller. -
m_classIndexMap
Map from fully-qualified class name to index in internal tables. -
m_classes
Names of classes included in mapping definition. -
m_transientBase
private int m_transientBaseIndex past end of last fixed marshaller class. -
m_transientMarshallerClasses
Transient marshaller classes for mapping definition (null
for mappings out of context). -
m_marshallers
Marshallers for classes in mapping definition (lazy create of actual marshaller instances) -
m_uris
URIs for namespaces used in binding. -
m_stackDepth
private int m_stackDepthCurrent marshalling stack depth. -
m_objectStack
Stack of objects being marshalled. -
m_indentCount
private int m_indentCountIndent character count per level. -
m_newLine
Character sequence for end of line. -
m_indentChar
private char m_indentCharCharacter used for indenting. -
m_idMap
Shared map from IDs to objects. This is not used directly by the marshalling code, but is available for user extensions (lazy create). -
m_writer
Output document handler. -
m_byteBuffer
Buffer used when writing to stream (lazy create,null
if unused). -
m_userContext
User context object (not used by JiBX, only for user convenience).
-
-
Constructor Details
-
MarshallingContext
Constructor.- Parameters:
classes
- ordered array of class names included in mapping definition (reference kept, must be constant)mcs
- names of marshaller classes for indexes with fixed marshallers (as opposed to mapping slots, which may be overridden; reference kept, must be constant)uris
- ordered array of URIs for namespaces used in binding (must be constant; the value in position 0 must always be the empty string "", and the value in position 1 must always be the XML namespace "http://www.w3.org/XML/1998/namespace")ifact
- binding factory creating this unmarshaller
-
-
Method Details
-
createEscaper
Create character escaper for encoding.- Parameters:
enc
- document output encoding, ornull
for default- Returns:
- character escaper for encoding
- Throws:
JiBXException
- if error creating setting output
-
setOutput
Set output stream with encoding and escaper. This forces handling of the output stream to use the Java character encoding support with the supplied escaper.- Specified by:
setOutput
in interfaceIMarshallingContext
- Parameters:
outs
- stream for document data outputenc
- document output encoding, ornull
uses UTF-8 defaultesc
- escaper for writing characters to stream- Throws:
JiBXException
- if error setting output
-
setOutput
Set output stream and encoding. This uses the standard escaper for the specified encoding.- Specified by:
setOutput
in interfaceIMarshallingContext
- Parameters:
outs
- stream for document data outputenc
- document output encoding, ornull
for default- Throws:
JiBXException
- if error creating setting output
-
setOutput
Set output writer and escaper.- Specified by:
setOutput
in interfaceIMarshallingContext
- Parameters:
outw
- writer for document data outputesc
- escaper for writing characters
-
setOutput
Set output writer.- Specified by:
setOutput
in interfaceIMarshallingContext
- Parameters:
outw
- writer for document data output
-
getXmlWriter
Get the writer being used for output.- Specified by:
getXmlWriter
in interfaceIMarshallingContext
- Returns:
- XML writer used for output
-
setXmlWriter
Set the writer being used for output.- Specified by:
setXmlWriter
in interfaceIMarshallingContext
- Parameters:
xwrite
- XML writer used for output
-
getIndent
public int getIndent()Get current nesting indent spaces. This returns the number of spaces used to show indenting, if used.- Specified by:
getIndent
in interfaceIMarshallingContext
- Returns:
- number of spaces indented per level, or negative if indentation disabled
-
setIndent
public void setIndent(int count) Set nesting indent spaces. This is advisory only, and implementations of this interface are free to ignore it. The intent is to indicate that the generated output should use indenting to illustrate element nesting.- Specified by:
setIndent
in interfaceIMarshallingContext
- Parameters:
count
- number of spaces to indent per level, or disable indentation if negative
-
setIndent
Set nesting indentation. This is advisory only, and implementations of this interface are free to ignore it. The intent is to indicate that the generated output should use indenting to illustrate element nesting.- Specified by:
setIndent
in interfaceIMarshallingContext
- Parameters:
count
- number of character to indent per level, or disable indentation if negative (zero means new line only)newline
- sequence of characters used for a line ending (null
means use the single character '\n')indent
- whitespace character used for indentation
-
setFromContext
Initializes the context to use the same marshalled text destination and parameters as another marshalling context. This method is designed for use when an initial context needs to create and invoke a secondary context (generally from a different binding) in the course of an marshalling operation. Note that once the secondary context has been used it's generally necessary to do aXMLWriterBase.flush()
operation on the writer used by the that context before resuming output on the parent.- Parameters:
parent
- context supplying target for marshalled document text- Throws:
IOException
- on error writing output
-
reset
public void reset()Reset to initial state for reuse. The context is serially reusable, as long as this method is called to clear any retained state information between uses. It is automatically called when output is set.- Specified by:
reset
in interfaceIMarshallingContext
-
getFactory
Return the binding factory used to create this unmarshaller.- Returns:
- binding factory
-
getNamespaces
Get namespace URIs for mapping. This gets the full ordered array of namespaces known in the binding used for this marshalling, where the index number of each namespace URI is the namespace index used to lookup the prefix when marshalling a name in that namespace. The returned array must not be modified.- Returns:
- array of namespaces
-
startDocument
Start document. This can only be validly called immediately following one of the set output methods; otherwise the output document will be corrupt.- Specified by:
startDocument
in interfaceIMarshallingContext
- Parameters:
enc
- document encoding,null
if not specifiedalone
- standalone document flag,null
if not specified- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
startDocument
Start document with output stream and encoding. The effect is the same as from first setting the output stream and encoding, then making the call to start document.- Specified by:
startDocument
in interfaceIMarshallingContext
- Parameters:
enc
- document encoding,null
if not specifiedalone
- standalone document flag,null
if not specifiedouts
- stream for document data output- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
startDocument
Start document with writer. The effect is the same as from first setting the writer, then making the call to start document.- Specified by:
startDocument
in interfaceIMarshallingContext
- Parameters:
enc
- document encoding,null
if not specifiedalone
- standalone document flag,null
if not specifiedoutw
- writer for document data output- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
endDocument
End document. Finishes all output and closes the document. Note that if this is called with an imcomplete marshalling the result will not be well-formed XML.- Specified by:
endDocument
in interfaceIMarshallingContext
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
buildNameString
Build name with optional namespace. Just returns the appropriate name format.- Parameters:
index
- namespace URI index numbername
- local name part of name- Returns:
- formatted name string
-
startTag
Generate start tag for element without attributes.- Parameters:
index
- namespace URI index numbername
- element name- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
startTagAttributes
Generate start tag for element with attributes. This only opens the start tag, allowing attributes to be added immediately following this call.- Parameters:
index
- namespace URI index numbername
- element name- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
attribute
Generate text attribute. This can only be used following an open start tag with attributes.- Parameters:
index
- namespace URI index numbername
- attribute namevalue
- text value for attribute (cannot benull
)- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
attribute
Generate integer attribute. This can only be used following an open start tag.- Parameters:
index
- namespace URI index numbername
- attribute namevalue
- integer value for attribute- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
attribute
public MarshallingContext attribute(int index, String name, int value, String[] table) throws JiBXException Generate enumeration attribute. The actual text to be written is obtained by indexing into the supplied array of values. This can only be used following an open start tag.- Parameters:
index
- namespace URI index numbername
- attribute namevalue
- integer enumeration value (zero-based)table
- text values in enumeration- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
closeStartContent
Close start tag with content to follow.- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
closeStartEmpty
Close start tag with no content (empty tag).- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
content
Add text content to current element.- Parameters:
value
- text element content- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
content
Add integer content to current element.- Parameters:
value
- integer element content- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
content
Add enumeration content to current element. The actual text to be written is obtained by indexing into the supplied array of values.- Parameters:
value
- integer enumeration value (zero-based)table
- text values in enumeration- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
endTag
Generate end tag for element.- Parameters:
index
- namespace URI index numbername
- element name- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
element
Generate complete element with text content.- Parameters:
index
- namespace URI index numbername
- element namevalue
- text element content- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
element
Generate complete element with integer content.- Parameters:
index
- namespace URI index numbername
- element namevalue
- integer element content- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
element
public MarshallingContext element(int index, String name, int value, String[] table) throws JiBXException Generate complete element with enumeration content. The actual text to be written is obtained by indexing into the supplied array of values.- Parameters:
index
- namespace URI index numbername
- element namevalue
- integer enumeration value (zero-based)table
- text values in enumeration- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
writeCData
Write CDATA text to document.- Parameters:
text
- content value text- Returns:
- this context (to allow chained calls)
- Throws:
IOException
- on error writing to document
-
writeContent
Write content value with character entity substitutions.- Parameters:
text
- content value text- Returns:
- this context (to allow chained calls)
- Throws:
IOException
- on error writing to document
-
marshalCollection
Marshal all items in a collection. This variation is for generic collections.- Parameters:
col
- collection of items to be marshalled- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
marshalCollection
Marshal all items in a collection. This variation is for ArrayList collections.- Parameters:
col
- collection of items to be marshalled- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
marshalCollection
Marshal all items in a collection. This variation is for Vector collections.- Parameters:
col
- collection of items to be marshalled- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
addMarshalling
Define marshalling for class. Adds the marshalling definition for a particular mapping name.- Parameters:
mapname
- mapping name associated with unmarshallername
- marshaller class name handling- Throws:
JiBXException
- if unknown mapping name
-
removeMarshalling
Undefine marshalling for element. Removes the marshalling definition for a particular mapping name.- Parameters:
mapname
- mapping name associated with unmarshaller- Throws:
JiBXException
- if unknown mapping name
-
startTagNamespaces
public MarshallingContext startTagNamespaces(int index, String name, int[] nums, String[] prefs) throws JiBXException Generate start tag for element with namespaces. This creates the actual start tag, along with any necessary namespace declarations. Previously active namespace declarations are not duplicated. The tag is left incomplete, allowing other attributes to be added. TODO: Handle nested default namespaces declarations, prefixes for outers- Parameters:
index
- namespace URI index numbername
- element namenums
- array of namespace indexes defined by this element (must be constant, reference is kept until end of element)prefs
- array of namespace prefixes mapped by this element (nonull
values, use "" for default namespace declaration)- Returns:
- this context (to allow chained calls)
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
getMarshaller
Find the marshaller for a particular class index in the current context.- Specified by:
getMarshaller
in interfaceIMarshallingContext
- Parameters:
mapname
- marshaller mapping name (generally the class name to be handled, or abstract mapping type name)- Returns:
- marshalling handler for class
- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
marshalRoot
Marshal document from root object. This internal method just verifies that the object is marshallable, then calls the marshal method on the object itself.- Parameters:
root
- object at root of structure to be marshalled, which must have a top-level mapping in the binding- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
marshalDocument
Marshal document from root object without XML declaration. This can only be validly called immediately following one of the set output methods; otherwise the output document will be corrupt. The effect of this method is the same as the sequence of a call to marshal the root object using this context followed by a call toendDocument()
.- Specified by:
marshalDocument
in interfaceIMarshallingContext
- Parameters:
root
- object at root of structure to be marshalled, which must have a top-level mapping in the binding- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
marshalDocument
Marshal document from root object. This can only be validly called immediately following one of the set output methods; otherwise the output document will be corrupt. The effect of this method is the same as the sequence of a call tostartDocument(java.lang.String, java.lang.Boolean)
, a call to marshal the root object using this context, and finally a call toendDocument()
.- Specified by:
marshalDocument
in interfaceIMarshallingContext
- Parameters:
root
- object at root of structure to be marshalled, which must have a top-level mapping in the bindingenc
- document encoding,null
if not specifiedalone
- standalone document flag,null
if not specified- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
marshalDocument
public void marshalDocument(Object root, String enc, Boolean alone, OutputStream outs) throws JiBXException Marshal document from root object to output stream with encoding. The effect of this method is the same as the sequence of a call tostartDocument(java.lang.String, java.lang.Boolean)
, a call to marshal the root object using this context, and finally a call toendDocument()
.- Specified by:
marshalDocument
in interfaceIMarshallingContext
- Parameters:
root
- object at root of structure to be marshalled, which must have a top-level mapping in the bindingenc
- document encoding,null
if not specifiedalone
- standalone document flag,null
if not specifiedouts
- stream for document data output- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
marshalDocument
public void marshalDocument(Object root, String enc, Boolean alone, Writer outw) throws JiBXException Marshal document from root object to writer. The effect of this method is the same as the sequence of a call tostartDocument(java.lang.String, java.lang.Boolean)
, a call to marshal the root object using this context, and finally a call toendDocument()
.- Specified by:
marshalDocument
in interfaceIMarshallingContext
- Parameters:
root
- object at root of structure to be marshalled, which must have a top-level mapping in the bindingenc
- document encoding,null
if not specifiedalone
- standalone document flag,null
if not specifiedoutw
- writer for document data output- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
pushNamespaces
Use namespace indexes from a separate binding, as identified by that binding's factory class name. The target binding must be a precompiled base binding of the binding used to create this marshalling context, either directly or by way of some other precompiled base binding(s).- Specified by:
pushNamespaces
in interfaceIMarshallingContext
- Parameters:
factname
- binding factory class name for binding defining namespaces
-
popNamespaces
public void popNamespaces()End use of namespace indexes from a separate binding. This will undo the effect of the most-recent call topushNamespaces(String)
, restoring whatever namespace usage was in effect prior to that call.- Specified by:
popNamespaces
in interfaceIMarshallingContext
-
getIdMap
Get shared ID map. The ID map returned is not used directly by the marshalling code, but is provided to support user extensions.- Returns:
- ID map
-
setUserContext
Set a user context object. This context object is not used directly by JiBX, but can be accessed by all types of user extension methods. The context object is automatically cleared by thereset()
method, so to make use of this you need to first call the appropriate version of thesetOutput()
method, then this method, and finally one of themarshalDocument
methods which uses the previously-set output (not the ones which take a stream or writer as parameter, since they callsetOutput()
themselves).- Specified by:
setUserContext
in interfaceIMarshallingContext
- Parameters:
obj
- user context object, ornull
if clearing existing context object- See Also:
-
getUserContext
Get the user context object.- Specified by:
getUserContext
in interfaceIMarshallingContext
- Returns:
- user context object, or
null
if no context object set - See Also:
-
pushObject
Push created object to marshalling stack. This must be called before beginning the marshalling of the object. It is only called for objects with structure, not for those converted directly to and from text.- Specified by:
pushObject
in interfaceIMarshallingContext
- Parameters:
obj
- object being marshalled
-
popObject
Pop marshalled object from stack.- Specified by:
popObject
in interfaceIMarshallingContext
- Throws:
JiBXException
- if no object on stack
-
getStackDepth
public int getStackDepth()Get current marshalling object stack depth. This allows tracking nested calls to marshal one object while in the process of marshalling another object. The bottom item on the stack is always the root object being marshalled.- Specified by:
getStackDepth
in interfaceIMarshallingContext
- Returns:
- number of objects in marshalling stack
-
getStackObject
Get object from marshalling stack. This stack allows tracking nested calls to marshal one object while in the process of marshalling another object. The bottom item on the stack is always the root object being marshalled.- Specified by:
getStackObject
in interfaceIMarshallingContext
- Parameters:
depth
- object depth in stack to be retrieved (must be in the range of zero to the current depth minus one).- Returns:
- object from marshalling stack
-
getStackTop
Get top object on marshalling stack. This is safe to call even when no objects are on the stack.- Specified by:
getStackTop
in interfaceIMarshallingContext
- Returns:
- object from marshalling stack, or
null
if none
-