java.lang.Object javax.xml.bind.Binder<XmlNode>
public abstract class Binder<XmlNode>
Enable synchronization between XML infoset nodes and JAXB objects representing same XML document.
An instance of this class maintains the association between XML nodes of an infoset preserving view and a JAXB representation of an XML document. Navigation between the two views is provided by the methods getXMLNode(Object) and getJAXBNode(Object) .
Modifications can be made to either the infoset preserving view or the JAXB representation of the document while the other view remains unmodified. The binder is able to synchronize the changes made in the modified view back into the other view using the appropriate Binder update methods, updateXML(Object, Object) or updateJAXB(Object) .
A typical usage scenario is the following:
A Binder instance is created using the factory method JAXBContext.createBinder() or JAXBContext.createBinder(Class) .
The template parameter, XmlNode, is the root interface/class for the XML infoset preserving representation. A Binder implementation is required to minimally support an XmlNode value of org.w3c.dom.Node.class. A Binder implementation can support alternative XML infoset preserving representations.
Constructor Summary | |
---|---|
Binder
() |
Method Summary | ||
---|---|---|
abstract ValidationEventHandler |
getEventHandler
() Return the current event handler or the default event handler if one hasn't been set. |
|
abstract Object |
getJAXBNode
(
XmlNode
xmlNode) Gets the JAXB object associated with the given XML element. |
|
abstract Object |
getProperty
(
String
name) Get the particular property in the underlying implementation of Binder . |
|
abstract Schema |
getSchema
() Gets the last Schema object (including null) set by the setSchema(Schema) method. |
|
abstract XmlNode |
getXMLNode
(
Object
jaxbObject) Gets the XML element associated with the given JAXB object. |
|
abstract void |
marshal
(
Object
jaxbObject,
XmlNode
xmlNode) Marshal a JAXB object tree to a new XML document. |
|
abstract void |
setEventHandler
(
ValidationEventHandler
handler) Allow an application to register a ValidationEventHandler . |
|
abstract void |
setProperty
(
String
name,
Object
value) Set the particular property in the underlying implementation of Binder . |
|
abstract void |
setSchema
(
Schema
schema) Specifies whether marshal, unmarshal and update methods performs validation on their XML content. |
|
abstract Object |
unmarshal
(
XmlNode
xmlNode) Unmarshal XML infoset view to a JAXB object tree. |
|
abstract
|
unmarshal
(
XmlNode
xmlNode,
Class
<T> declaredType) Unmarshal XML root element by provided declaredType to a JAXB object tree. |
|
abstract Object |
updateJAXB
(
XmlNode
xmlNode) Takes an XML node and updates its associated JAXB object and its descendants. |
|
abstract XmlNode |
updateXML
(
Object
jaxbObject) Takes an JAXB object and updates its associated XML node and its descendants. |
|
abstract XmlNode |
updateXML
(
Object
jaxbObject,
XmlNode
xmlNode) Changes in JAXB object tree are updated in its associated XML parse tree. |
Methods inherited from class java.lang. Object |
---|
clone , equals , finalize , getClass , hashCode , notify , notifyAll , toString , wait , wait , wait |
Constructor Detail |
---|
public Binder()
Method Detail |
---|
public abstract Object unmarshal(XmlNode xmlNode) throws JAXBException
This method is similar to Unmarshaller.unmarshal(Node) with the addition of maintaining the association between XML nodes and the produced JAXB objects, enabling future update operations, updateXML(Object, Object) or updateJAXB(Object) .
When getSchema() is non-null, xmlNode and its descendants is validated during this operation.
This method throws UnmarshalException when the Binder's JAXBContext does not have a mapping for the XML element name or the type, specifiable via @xsi:type , of xmlNode to a JAXB mapped class. The method unmarshal(Object, Class) enables an application to specify the JAXB mapped class that the xmlNode should be mapped to.
public abstract <T> JAXBElement<T> unmarshal(XmlNode xmlNode, Class<T> declaredType) throws JAXBException
Implements Unmarshal by Declared Type
This method is similar to Unmarshaller.unmarshal(Node, Class) with the addition of maintaining the association between XML nodes and the produced JAXB objects, enabling future update operations, updateXML(Object, Object) or updateJAXB(Object) .
When getSchema() is non-null, xmlNode and its descendants is validated during this operation.
public abstract void marshal(Object jaxbObject, XmlNode xmlNode) throws JAXBException
This method is similar to Marshaller.marshal(Object, Node) with the addition of maintaining the association between JAXB objects and the produced XML nodes, enabling future update operations such as updateXML(Object, Object) or updateJAXB(Object) .
When getSchema() is non-null, the marshalled xml content is validated during this operation.
public abstract XmlNode getXMLNode(Object jaxbObject)
Once a JAXB object tree is associated with an XML fragment, this method enables navigation between the two trees.
An association between an XML element and a JAXB object is established by the bind methods and the update methods. Note that this association is partial; not all XML elements have associated JAXB objects, and not all JAXB objects have associated XML elements.
public abstract Object getJAXBNode(XmlNode xmlNode)
Once a JAXB object tree is associated with an XML fragment, this method enables navigation between the two trees.
An association between an XML element and a JAXB object is established by the unmarshal, marshal and update methods. Note that this association is partial; not all XML elements have associated JAXB objects, and not all JAXB objects have associated XML elements.
public abstract XmlNode updateXML(Object jaxbObject) throws JAXBException
This is a convenience method of:
updateXML( jaxbObject, getXMLNode(jaxbObject));
public abstract XmlNode updateXML(Object jaxbObject, XmlNode xmlNode) throws JAXBException
This operation can be thought of as an "in-place" marshalling. The difference is that instead of creating a whole new XML tree, this operation updates an existing tree while trying to preserve the XML as much as possible.
For example, unknown elements/attributes in XML that were not bound to JAXB will be left untouched (whereas a marshalling operation would create a new tree that doesn't contain any of those.)
As a side-effect, this operation updates the association between XML nodes and JAXB objects.
public abstract Object updateJAXB(XmlNode xmlNode) throws JAXBException
This operation can be thought of as an "in-place" unmarshalling. The difference is that instead of creating a whole new JAXB tree, this operation updates an existing tree, reusing as much JAXB objects as possible.
As a side-effect, this operation updates the association between XML nodes and JAXB objects.
public abstract void setSchema(Schema schema)
public abstract Schema getSchema()
public abstract void setEventHandler(ValidationEventHandler handler) throws JAXBException
The ValidationEventHandler will be called by the JAXB Provider if any validation errors are encountered during calls to any of the Binder unmarshal, marshal and update methods.
Calling this method with a null parameter will cause the Binder to revert back to the default default event handler.
public abstract ValidationEventHandler getEventHandler() throws JAXBException
public abstract void setProperty(String name, Object value) throws PropertyException
public abstract Object getProperty(String name) throws PropertyException