Package org.jibx.runtime
Interface IMarshallingContext
-
- All Known Implementing Classes:
MarshallingContext
public interface IMarshallingContext
User interface for serializer to XML. This provides methods used to set up and control the marshalling process, as well as access to the marshalling object stack while marshalling.- Author:
- Dennis M. Sosnoski
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
endDocument()
End document.int
getIndent()
Get current nesting indent spaces.IMarshaller
getMarshaller(java.lang.String mapname)
Find the marshaller for a particular class in the current context.int
getStackDepth()
Get current marshalling object stack depth.java.lang.Object
getStackObject(int depth)
Get object from marshalling stack.java.lang.Object
getStackTop()
Get top object on marshalling stack.java.lang.Object
getUserContext()
Get the user context object.IXMLWriter
getXmlWriter()
Get the writer being used for output.void
marshalDocument(java.lang.Object root)
Marshal document from root object without XML declaration.void
marshalDocument(java.lang.Object root, java.lang.String enc, java.lang.Boolean alone)
Marshal document from root object.void
marshalDocument(java.lang.Object root, java.lang.String enc, java.lang.Boolean alone, java.io.OutputStream outs)
Marshal document from root object to output stream with encoding.void
marshalDocument(java.lang.Object root, java.lang.String enc, java.lang.Boolean alone, java.io.Writer outw)
Marshal document from root object to writer.void
popNamespaces()
End use of namespace indexes from a separate binding.void
popObject()
Pop marshalled object from stack.void
pushNamespaces(java.lang.String factname)
Use namespace indexes from a separate binding, as identified by that binding's factory class name.void
pushObject(java.lang.Object obj)
Push created object to marshalling stack.void
reset()
Reset to initial state for reuse.void
setIndent(int count)
Set nesting indent spaces.void
setIndent(int count, java.lang.String newline, char indent)
Set nesting indentation.void
setOutput(java.io.OutputStream outs, java.lang.String enc)
Set output stream and encoding.void
setOutput(java.io.OutputStream outs, java.lang.String enc, ICharacterEscaper esc)
Set output stream with encoding and escaper.void
setOutput(java.io.Writer outw)
Set output writer.void
setOutput(java.io.Writer outw, ICharacterEscaper esc)
Set output writer and escaper.void
setUserContext(java.lang.Object obj)
Set a user context object.void
setXmlWriter(IXMLWriter xwrite)
Set the writer being used for output.void
startDocument(java.lang.String enc, java.lang.Boolean alone)
Start document, writing the XML declaration.void
startDocument(java.lang.String enc, java.lang.Boolean alone, java.io.OutputStream outs)
Start document with output stream and encoding.void
startDocument(java.lang.String enc, java.lang.Boolean alone, java.io.Writer outw)
Start document with writer.
-
-
-
Method Detail
-
setOutput
void setOutput(java.io.OutputStream outs, java.lang.String enc, ICharacterEscaper esc) throws JiBXException
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.- 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
void setOutput(java.io.OutputStream outs, java.lang.String enc) throws JiBXException
Set output stream and encoding.- Parameters:
outs
- stream for document data outputenc
- document output encoding, ornull
uses UTF-8 default- Throws:
JiBXException
- if error setting output
-
setOutput
void setOutput(java.io.Writer outw, ICharacterEscaper esc)
Set output writer and escaper.- Parameters:
outw
- writer for document data outputesc
- escaper for writing characters
-
setOutput
void setOutput(java.io.Writer outw)
Set output writer. This assumes the standard UTF-8 encoding.- Parameters:
outw
- writer for document data output
-
getXmlWriter
IXMLWriter getXmlWriter()
Get the writer being used for output.- Returns:
- XML writer used for output
-
setXmlWriter
void setXmlWriter(IXMLWriter xwrite)
Set the writer being used for output.- Parameters:
xwrite
- XML writer used for output
-
getIndent
int getIndent()
Get current nesting indent spaces. This returns the number of spaces used to show indenting, if used.- Returns:
- number of spaces indented per level, or negative if indentation disabled
-
setIndent
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.- Parameters:
count
- number of spaces to indent per level, or disable indentation if negative
-
setIndent
void setIndent(int count, java.lang.String newline, char indent)
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.- 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
-
reset
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.
-
startDocument
void startDocument(java.lang.String enc, java.lang.Boolean alone) throws JiBXException
Start document, writing the XML declaration. This can only be validly called immediately following one of the set output methods; otherwise the output document will be corrupt.- Parameters:
enc
- document encoding,null
uses UTF-8 defaultalone
- standalone document flag,null
if not specified- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
startDocument
void startDocument(java.lang.String enc, java.lang.Boolean alone, java.io.OutputStream outs) throws JiBXException
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.- Parameters:
enc
- document encoding,null
uses UTF-8 defaultalone
- standalone document flag,null
if not specifiedouts
- stream for document data output- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
startDocument
void startDocument(java.lang.String enc, java.lang.Boolean alone, java.io.Writer outw) throws JiBXException
Start document with writer. The effect is the same as from first setting the writer, then making the call to start document.- Parameters:
enc
- document encoding,null
uses UTF-8 defaultalone
- standalone document flag,null
if not specifiedoutw
- writer for document data output- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
endDocument
void endDocument() throws JiBXException
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.- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
marshalDocument
void marshalDocument(java.lang.Object root) throws JiBXException
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()
.- 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
void marshalDocument(java.lang.Object root, java.lang.String enc, java.lang.Boolean alone) throws JiBXException
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(String, Boolean)
, a call to marshal the root object using this context, and finally a call toendDocument()
.- Parameters:
root
- object at root of structure to be marshalled, which must have a top-level mapping in the bindingenc
- document encoding,null
uses UTF-8 defaultalone
- standalone document flag,null
if not specified- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
marshalDocument
void marshalDocument(java.lang.Object root, java.lang.String enc, java.lang.Boolean alone, java.io.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(String, Boolean)
, a call to marshal the root object using this context, and finally a call toendDocument()
.- Parameters:
root
- object at root of structure to be marshalled, which must have a top-level mapping in the bindingenc
- document encoding,null
uses UTF-8 defaultalone
- standalone document flag,null
if not specifiedouts
- stream for document data output- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
marshalDocument
void marshalDocument(java.lang.Object root, java.lang.String enc, java.lang.Boolean alone, java.io.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(String, Boolean)
, a call to marshal the root object using this context, and finally a call toendDocument()
.- Parameters:
root
- object at root of structure to be marshalled, which must have a top-level mapping in the bindingenc
- document encoding,null
uses UTF-8 defaultalone
- standalone document flag,null
if not specifiedoutw
- writer for document data output- Throws:
JiBXException
- on any error (possibly wrapping other exception)
-
setUserContext
void setUserContext(java.lang.Object obj)
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).- Parameters:
obj
- user context object, ornull
if clearing existing context object- See Also:
getUserContext()
-
getUserContext
java.lang.Object getUserContext()
Get the user context object.- Returns:
- user context object, or
null
if no context object set - See Also:
setUserContext(Object)
-
pushObject
void pushObject(java.lang.Object obj)
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.- Parameters:
obj
- object being marshalled
-
popObject
void popObject() throws JiBXException
Pop marshalled object from stack.- Throws:
JiBXException
- if no object on stack
-
getStackDepth
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 of the marshalling.- Returns:
- number of objects in marshalling stack
-
getStackObject
java.lang.Object getStackObject(int depth)
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 of the marshalling.- 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
java.lang.Object getStackTop()
Get top object on marshalling stack. This is safe to call even when no objects are on the stack.- Returns:
- object from marshalling stack, or
null
if none
-
getMarshaller
IMarshaller getMarshaller(java.lang.String mapname) throws JiBXException
Find the marshaller for a particular class in the current context.- 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)
-
pushNamespaces
void pushNamespaces(java.lang.String factname)
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).- Parameters:
factname
- binding factory class name for binding defining namespaces
-
popNamespaces
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.
-
-