## 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
`void` `endDocument()` End document.
`int` `getIndent()` Get current nesting indent spaces.
`IMarshaller` `getMarshaller(int index, java.lang.String name)` Find the marshaller for a particular class index 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` `popObject()` Pop marshalled object from stack.
`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 output
    `enc` - document output encoding, or `null` uses UTF-8 default
    `esc` - 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 output
    `enc` - document output encoding, or `null` 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 output
    `esc` - 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 default
    `alone` - 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 default
    `alone` - standalone document flag, `null` if not specified
    `outs` - 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 default
    `alone` - standalone document flag, `null` if not specified
    `outw` - 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 to `endDocument()`.

  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 to `startDocument(java.lang.String, java.lang.Boolean)`, a call to marshal the root object using this context, and finally a call to `endDocument()`.

  Parameters:
    `root` - object at root of structure to be marshalled, which must have a top-level mapping in the binding
    `enc` - document encoding, `null` uses UTF-8 default
    `alone` - 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 to `startDocument(java.lang.String, java.lang.Boolean)`, a call to marshal the root object using this context, and finally a call to `endDocument()`.

  Parameters:
    `root` - object at root of structure to be marshalled, which must have a top-level mapping in the binding
    `enc` - document encoding, `null` uses UTF-8 default
    `alone` - standalone document flag, `null` if not specified
    `outs` - 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 to `startDocument(java.lang.String, java.lang.Boolean)`, a call to marshal the root object using this context, and finally a call to `endDocument()`.

  Parameters:
    `root` - object at root of structure to be marshalled, which must have a top-level mapping in the binding
    `enc` - document encoding, `null` uses UTF-8 default
    `alone` - standalone document flag, `null` if not specified
    `outw` - 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 the `reset()` method, so to make use of this you need to first call the appropriate version of the `setOutput()` method, then this method, and finally one of the `marshalDocument` methods which uses the previously-set output (not the ones which take a stream or writer as parameter, since they call `setOutput()` themselves).

  Parameters:
    `obj` - user context object, or `null` 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(int index,
                              java.lang.String name)
                              throws JiBXException

  Find the marshaller for a particular class index in the current context.

  Parameters:
    `index` - class index for marshalling definition
    `name` - fully qualified name of class to be marshalled (used only for validation)
  Returns:
    marshalling handler for class
  Throws:
    `JiBXException` - on any error (possibly wrapping other exception)

Project Web Site |