com.openharbor.beck.unmarshal
Interface Unmarshaller

All Known Subinterfaces:

DocumentReferenceUnmarshaller

All Known Implementing Classes:

DefaultUnmarshaller, XPathUnmarshaller

public interface Unmarshaller

Maps an XML attribute or element to a Java object or primitive value. An Unmarshaller is a proxy that stores data into the underlying object. During unmarshalling, an Unmarshaller is allocated to (roughly) each element and each attribute; the Unmarshaller's concern is to convert one Java object or primitive from some XML data.

An Unmarshaller may be serially re-used (and most that extend DefaultUnmarshaller are). Also, an Unmarshaller may delay part of its work until after the processing of subsequent XML. To enable both behaviors, Unmarshaller users are required to call engage() and disengage() to inform the Unmarshaller when it's in use. The Unmarshaller may make itself available for re-use, if and how it chooses; or it may elect to ignore engagement, and let itself become garbage when disengaged.

Method Summary

void	addChild(Unmarshaller childUnmarshaller) Create a reference from this object to the given child object.
void	addValue(char[] from, int start, int length) Add characters from XML content (text) to the value of the mapped object.
void	disengage() Un-do a previous engagement.
java.lang.Object	endObject() Conclude the mapping of this object, and return it.
void	engage() Prevent re-using this Unmarshaller until a matching call to disengage() is made.
java.lang.Class	getChildClass(XMLThing childSource) Choose the class of the object to be mapped from a contained XML attribute or element.
java.lang.Object	getObject()
java.lang.Class	getObjectClass()
Unmarshaller	getParent() The set allocated to the XML element that contains this Unmarshaller's XML source.
XMLThing	getSource() The XML element or attribute from which this Unmarshaller is currently mapping data.
java.lang.String	getSourceXPath()
XMLContext	getXMLContext()
void	setObject(java.lang.Object object)
void	setObjectClass(java.lang.Class c) Set the expected class of the object to be mapped from XML.
void	setXMLContext(XMLContext context) Set the functor for resolving an XML namespace prefix to the namespace URI.
void	startObject(java.util.Map documentState, Unmarshaller parent, XMLThing source) Begin mapping an object from an XML element or attribute.

Method Detail

engage

public void engage()

Prevent re-using this Unmarshaller until a matching call to disengage() is made. This method may be called repeatedly; the Unmarshaller should maintain an engagement counter or similar state to correlate calls to engage and disengage.

disengage

public void disengage()
               throws java.lang.Exception

Un-do a previous engagement. For best performance, when the last engagement is disengaged, we recommend making this available for re-use; e.g. by calling getMapFromXML().recycle(this). But this optimization is not required.

Throws:

java.lang.Exception

setXMLContext

public void setXMLContext(XMLContext context)

Set the functor for resolving an XML namespace prefix to the namespace URI.

getXMLContext

public XMLContext getXMLContext()

setObjectClass

public void setObjectClass(java.lang.Class c)

Set the expected class of the object to be mapped from XML. A null Class indicates that the object class is unknown.

getObjectClass

public java.lang.Class getObjectClass()

Returns:

the expected class of the object to be mapped from XML. A null Class indicates that the object class is unknown.

startObject

public void startObject(java.util.Map documentState,
                        Unmarshaller parent,
                        XMLThing source)
                 throws java.lang.Exception

Begin mapping an object from an XML element or attribute.

Throws:

java.lang.Exception

getParent

public Unmarshaller getParent()

The set allocated to the XML element that contains this Unmarshaller's XML source.

getSource

public XMLThing getSource()

The XML element or attribute from which this Unmarshaller is currently mapping data.

getSourceXPath

public java.lang.String getSourceXPath()

Returns:

The XPath of getSource().

getChildClass

public java.lang.Class getChildClass(XMLThing childSource)
                              throws java.lang.Exception

Choose the class of the object to be mapped from a contained XML attribute or element.

Returns:

the chosen class, or null to indicate that the child's class is not determined by this Unmarshaller.

Throws:

java.lang.Exception

addChild

public void addChild(Unmarshaller childUnmarshaller)
              throws java.lang.Exception

Create a reference from this object to the given child object. For example, set a reference-valued JavaBean property, or add a member to a Collection.

Throws:

java.lang.Exception

addValue

public void addValue(char[] from,
                     int start,
                     int length)
              throws java.lang.Exception

Add characters from XML content (text) to the value of the mapped object. This method may be called repeatedly, as the XML parser encounters content fragments. The implementation of this method should accumulate the characters from consecutive calls, and map all of them (concatenated) to the object value.

Throws:

java.lang.Exception

endObject

public java.lang.Object endObject()
                           throws java.lang.Exception

Conclude the mapping of this object, and return it.

Returns:

the object that this Unmarshaller mapped from XML.

Throws:

java.lang.Exception

getObject

public java.lang.Object getObject()

setObject

public void setObject(java.lang.Object object)