org.jibx.runtime
Interface IUnmarshallingContext

All Known Implementing Classes:

UnmarshallingContext

public interface IUnmarshallingContext

User interface for deserializer from XML. This provides methods used to set up and control the marshalling process, as well as access to the unmarshalling object stack while unmarshalling.

Author:

Dennis M. Sosnoski

Method Summary

java.lang.String	getDocumentName() Return the supplied document name.
int	getStackDepth() Get current unmarshalling object stack depth.
java.lang.Object	getStackObject(int depth) Get object from unmarshalling stack.
java.lang.Object	getStackTop() Get top object on unmarshalling stack.
IUnmarshaller	getUnmarshaller(java.lang.String mapname) Find the unmarshaller for a particular class in the current context.
java.lang.Object	getUserContext() Get the user context object.
boolean	isAt(java.lang.String ns, java.lang.String name) Check if next tag is start of element.
boolean	isEnd() Check if next tag is an end tag.
boolean	isStart() Check if next tag is a start tag.
void	popObject() Pop unmarshalled object from stack.
void	pushObject(java.lang.Object obj) Push created object to unmarshalling stack.
void	reset() Reset unmarshalling information.
void	setDocument(java.io.InputStream ins, java.lang.String enc) Set document to be parsed from stream.
void	setDocument(java.io.InputStream ins, java.lang.String name, java.lang.String enc) Set named document to be parsed from stream.
void	setDocument(java.io.Reader rdr) Set document to be parsed from reader.
void	setDocument(java.io.Reader rdr, java.lang.String name) Set named document to be parsed from reader.
void	setUserContext(java.lang.Object obj) Set a user context object.
java.lang.Object	unmarshalDocument(java.io.InputStream ins, java.lang.String enc) Unmarshal document from stream to object.
java.lang.Object	unmarshalDocument(java.io.InputStream ins, java.lang.String name, java.lang.String enc) Unmarshal named document from stream to object.
java.lang.Object	unmarshalDocument(java.io.Reader rdr) Unmarshal document from reader to object.
java.lang.Object	unmarshalDocument(java.io.Reader rdr, java.lang.String name) Unmarshal named document from reader to object.
java.lang.Object	unmarshalElement() Unmarshal the current element.

Method Detail

setDocument

void setDocument(java.io.InputStream ins,
                 java.lang.String enc)
                 throws JiBXException

Set document to be parsed from stream.

Parameters:

ins - stream supplying document data

enc - document input encoding, or null if to be determined by parser

Throws:

JiBXException - if error creating parser

setDocument

void setDocument(java.io.Reader rdr)
                 throws JiBXException

Set document to be parsed from reader.

Parameters:

rdr - reader supplying document data

Throws:

JiBXException - if error creating parser

setDocument

void setDocument(java.io.InputStream ins,
                 java.lang.String name,
                 java.lang.String enc)
                 throws JiBXException

Set named document to be parsed from stream.

Parameters:

ins - stream supplying document data

name - document name

enc - document input encoding, or null if to be determined by parser

Throws:

JiBXException - if error creating parser

setDocument

void setDocument(java.io.Reader rdr,
                 java.lang.String name)
                 throws JiBXException

Set named document to be parsed from reader.

Parameters:

rdr - reader supplying document data

name - document name

Throws:

JiBXException - if error creating parser

reset

void reset()

Reset unmarshalling information. This releases all references to unmarshalled objects and prepares the context for potential reuse. It is automatically called when input is set.

unmarshalElement

java.lang.Object unmarshalElement()
                                  throws JiBXException

Unmarshal the current element. If not currently positioned at a start or end tag this first advances the parse to the next start or end tag. There must be an unmarshalling defined for the current element, and this unmarshalling is used to build an object from that element.

Returns:

unmarshalled object from element

Throws:

JiBXException - on any error (possibly wrapping other exception)

unmarshalDocument

java.lang.Object unmarshalDocument(java.io.InputStream ins,
                                   java.lang.String enc)
                                   throws JiBXException

Unmarshal document from stream to object. The effect of this is the same as if setDocument(java.io.InputStream, java.lang.String) were called, followed by unmarshalElement()

Parameters:

ins - stream supplying document data

enc - document input encoding, or null if to be determined by parser

Returns:

unmarshalled object

Throws:

JiBXException - if error creating parser

unmarshalDocument

java.lang.Object unmarshalDocument(java.io.Reader rdr)
                                   throws JiBXException

Unmarshal document from reader to object. The effect of this is the same as if setDocument(java.io.InputStream, java.lang.String) were called, followed by unmarshalElement()

Parameters:

rdr - reader supplying document data

Returns:

unmarshalled object

Throws:

JiBXException - if error creating parser

unmarshalDocument

java.lang.Object unmarshalDocument(java.io.InputStream ins,
                                   java.lang.String name,
                                   java.lang.String enc)
                                   throws JiBXException

Unmarshal named document from stream to object. The effect of this is the same as if setDocument(java.io.InputStream, java.lang.String) were called, followed by unmarshalElement()

Parameters:

ins - stream supplying document data

name - document name

enc - document input encoding, or null if to be determined by parser

Returns:

unmarshalled object

Throws:

JiBXException - if error creating parser

unmarshalDocument

java.lang.Object unmarshalDocument(java.io.Reader rdr,
                                   java.lang.String name)
                                   throws JiBXException

Unmarshal named document from reader to object. The effect of this is the same as if setDocument(java.io.InputStream, java.lang.String) were called, followed by unmarshalElement()

Parameters:

rdr - reader supplying document data

name - document name

Returns:

unmarshalled object

Throws:

JiBXException - if error creating parser

getDocumentName

java.lang.String getDocumentName()

Return the supplied document name.

Returns:

supplied document name (null if none)

isAt

boolean isAt(java.lang.String ns,
             java.lang.String name)
             throws JiBXException

Check if next tag is start of element. If not currently positioned at a start or end tag this first advances the parse to the next start or end tag.

Parameters:

ns - namespace URI for expected element (may be null or the empty string for the empty namespace)

name - element name expected

Returns:

true if at start of element with supplied name, false if not

Throws:

JiBXException - on any error (possibly wrapping other exception)

isStart

boolean isStart()
                throws JiBXException

Check if next tag is a start tag. If not currently positioned at a start or end tag this first advances the parse to the next start or end tag.

Returns:

true if at start of element, false if at end

Throws:

JiBXException - on any error (possibly wrapping other exception)

isEnd

boolean isEnd()
              throws JiBXException

Check if next tag is an end tag. If not currently positioned at a start or end tag this first advances the parse to the next start or end tag.

Returns:

true if at end of element, false if at start

Throws:

JiBXException - on any error (possibly wrapping other exception)

getUnmarshaller

IUnmarshaller getUnmarshaller(java.lang.String mapname)
                              throws JiBXException

Find the unmarshaller for a particular class in the current context.

Parameters:

mapname - unmarshaller mapping name (generally the class name to be handled, or abstract mapping type name)

Returns:

unmarshalling handler for class

Throws:

JiBXException - if unable to create unmarshaller

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 setDocument() method, then this method, and finally the unmarshalElement() method.

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 unmarshalling stack. This must be called before beginning the unmarshalling of the object. It is only called for objects with structure, not for those converted directly to and from text.

Parameters:

obj - object being unmarshalled

popObject

void popObject()
               throws JiBXException

Pop unmarshalled object from stack.

Throws:

JiBXException - if stack empty

getStackDepth

int getStackDepth()

Get current unmarshalling object stack depth. This allows tracking nested calls to unmarshal one object while in the process of unmarshalling another object. The bottom item on the stack is always the root object being unmarshalled.

Returns:

number of objects in unmarshalling stack

getStackObject

java.lang.Object getStackObject(int depth)

Get object from unmarshalling stack. This stack allows tracking nested calls to unmarshal one object while in the process of unmarshalling another object. The bottom item on the stack is always the root object being unmarshalled.

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 unmarshalling stack

getStackTop

java.lang.Object getStackTop()

Get top object on unmarshalling stack. This is safe to call even when no objects are on the stack.

Returns:

object from unmarshalling stack, or null if none