- Type Parameters:
XmlNode
- the template parameter,XmlNode
, is the root interface/class for the XML infoset preserving representation. A Binder implementation is required to minimally support anXmlNode
value oforg.w3c.dom.Node.class
. A Binder implementation can support alternative XML infoset preserving representations.
An instance of this class maintains the association between XML nodes of
an infoset preserving view and a Jakarta XML Binding 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
Jakarta XML Binding 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:
- load XML document into an XML infoset representation
unmarshal(Object)
XML infoset view to Jakarta XML Binding view. (Note to conserve resources, it is possible to only unmarshal a subtree of the XML infoset view to the Jakarta XML Binding view.)- application access/updates Jakarta XML Binding view of XML document.
updateXML(Object)
synchronizes modifications to Jakarta XML Binding view back into the XML infoset view. Update operation preserves as much of original XML infoset as possible (i.e. comments, PI, ...)
A Binder instance is created using the factory method
JAXBContext.createBinder()
or JAXBContext.createBinder(Class)
.
- Author:
- Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com) Joseph Fialli
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionabstract ValidationEventHandler
Return the current event handler or the default event handler if one hasn't been set.abstract Object
getJAXBNode
(XmlNode xmlNode) Gets the Jakarta XML Binding object associated with the given XML element.abstract Object
getProperty
(String name) Get the particular property in the underlying implementation ofBinder
.abstract Schema
Gets the lastSchema
object (including null) set by thesetSchema(Schema)
method.abstract XmlNode
getXMLNode
(Object jaxbObject) Gets the XML element associated with the given Jakarta XML Binding object.abstract void
Marshal a Jakarta XML Binding object tree to a new XML document.abstract void
setEventHandler
(ValidationEventHandler handler) Allow an application to register aValidationEventHandler
.abstract void
setProperty
(String name, Object value) Set the particular property in the underlying implementation ofBinder
.abstract void
Specifies whether marshal, unmarshal and update methods performs validation on their XML content.abstract Object
Unmarshal XML infoset view to a Jakarta XML Binding object tree.abstract <T> JAXBElement
<T> Unmarshal XML root element by provideddeclaredType
to a Jakarta XML Binding object tree.abstract Object
updateJAXB
(XmlNode xmlNode) Takes an XML node and updates its associated Jakarta XML Binding object and its descendants.abstract XmlNode
Takes a Jakarta XML Binding object and updates its associated XML node and its descendants.abstract XmlNode
Changes in Jakarta XML Binding object tree are updated in its associated XML parse tree.
-
Constructor Details
-
Binder
protected Binder()Do-nothing constructor for the derived classes.
-
-
Method Details
-
unmarshal
Unmarshal XML infoset view to a Jakarta XML Binding object tree.This method is similar to
Unmarshaller.unmarshal(Node)
with the addition of maintaining the association between XML nodes and the produced Jakarta XML Binding objects, enabling future update operations,updateXML(Object, Object)
orupdateJAXB(Object)
.When
getSchema()
is non-null,xmlNode
and its descendants is validated during this operation.This method throws
UnmarshalException
when the Binder'sJAXBContext
does not have a mapping for the XML element name or the type, specifiable via@xsi:type
, ofxmlNode
to a Jakarta XML Binding mapped class. The methodunmarshal(Object, Class)
enables an application to specify the Jakarta XML Binding mapped class that thexmlNode
should be mapped to.- Parameters:
xmlNode
- the document/element to unmarshal XML data from.- Returns:
- the newly created root object of the Jakarta XML Binding object tree.
- Throws:
JAXBException
- If any unexpected errors occur while unmarshallingUnmarshalException
- If theValidationEventHandler
returns false from itshandleEvent
method or theBinder
is unable to perform the XML to Java binding.IllegalArgumentException
- If the node parameter is null
-
unmarshal
public abstract <T> JAXBElement<T> unmarshal(XmlNode xmlNode, Class<T> declaredType) throws JAXBException Unmarshal XML root element by provideddeclaredType
to a Jakarta XML Binding object tree.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 Jakarta XML Binding objects, enabling future update operations,updateXML(Object, Object)
orupdateJAXB(Object)
.When
getSchema()
is non-null,xmlNode
and its descendants is validated during this operation.- Type Parameters:
T
- the declared type- Parameters:
xmlNode
- the document/element to unmarshal XML data from.declaredType
- appropriate Jakarta XML Binding mapped class to holdnode
's XML data.- Returns:
- JAXBElement representation
of
node
- Throws:
JAXBException
- If any unexpected errors occur while unmarshallingUnmarshalException
- If theValidationEventHandler
returns false from itshandleEvent
method or theBinder
is unable to perform the XML to Java binding.IllegalArgumentException
- If any of the input parameters are null
-
marshal
Marshal a Jakarta XML Binding object tree to a new XML document.This method is similar to
Marshaller.marshal(Object, Node)
with the addition of maintaining the association between Jakarta XML Binding objects and the produced XML nodes, enabling future update operations such asupdateXML(Object, Object)
orupdateJAXB(Object)
.When
getSchema()
is non-null, the marshalled xml content is validated during this operation.- Parameters:
jaxbObject
- The content tree to be marshalled.xmlNode
- The parameter must be a Node that accepts children.- Throws:
JAXBException
- If any unexpected problem occurs during the marshalling.MarshalException
- If theValidationEventHandler
returns false from itshandleEvent
method or theBinder
is unable to marshaljaxbObject
(or any object reachable fromjaxbObject
).IllegalArgumentException
- If any of the method parameters are null
-
getXMLNode
Gets the XML element associated with the given Jakarta XML Binding object.Once a Jakarta XML Binding object tree is associated with an XML fragment, this method enables navigation between the two trees.
An association between an XML element and a Jakarta XML Binding object is established by the bind methods and the update methods. Note that this association is partial; not all XML elements have associated Jakarta XML Binding objects, and not all Jakarta XML Binding objects have associated XML elements.
- Parameters:
jaxbObject
- An instance that is reachable from a prior call to a bind or update method that returned a Jakarta XML Binding object tree.- Returns:
- null if the specified Jakarta XML Binding object is not known to this
Binder
, or if it is not associated with an XML element. - Throws:
IllegalArgumentException
- If the jaxbObject parameter is null
-
getJAXBNode
Gets the Jakarta XML Binding object associated with the given XML element.Once a Jakarta XML Binding object tree is associated with an XML fragment, this method enables navigation between the two trees.
An association between an XML element and a Jakarta XML Binding object is established by the unmarshal, marshal and update methods. Note that this association is partial; not all XML elements have associated Jakarta XML Binding objects, and not all Jakarta XML Binding objects have associated XML elements.
- Parameters:
xmlNode
- the XML element- Returns:
- null if the specified XML node is not known to this
Binder
, or if it is not associated with a Jakarta XML Binding object. - Throws:
IllegalArgumentException
- If the node parameter is null
-
updateXML
Takes a Jakarta XML Binding object and updates its associated XML node and its descendants.This is a convenience method of:
updateXML( jaxbObject, getXMLNode(jaxbObject));
- Parameters:
jaxbObject
- the XML Binding object- Returns:
- the XML node associated with XML Binding object
- Throws:
JAXBException
- If any unexpected problem occurs updating corresponding XML content.IllegalArgumentException
- If the jaxbObject parameter is null
-
updateXML
Changes in Jakarta XML Binding object tree are updated in its associated XML parse tree.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 Jakarta XML Binding 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 Jakarta XML Binding objects.
- Parameters:
jaxbObject
- root of potentially modified Jakarta XML Binding object treexmlNode
- root of update target XML parse tree- Returns:
- Returns the updated XML node. Typically, this is the same node you passed in as xmlNode, but it maybe a different object, for example when the tag name of the object has changed.
- Throws:
JAXBException
- If any unexpected problem occurs updating corresponding XML content.IllegalArgumentException
- If any of the input parameters are null
-
updateJAXB
Takes an XML node and updates its associated Jakarta XML Binding object and its descendants.This operation can be thought of as an "in-place" unmarshalling. The difference is that instead of creating a whole new Jakarta XML Binding tree, this operation updates an existing tree, reusing as much Jakarta XML Binding objects as possible.
As a side effect, this operation updates the association between XML nodes and Jakarta XML Binding objects.
- Parameters:
xmlNode
- the XML node- Returns:
- Returns the updated Jakarta XML Binding object. Typically, this is the same
object that was returned from earlier
marshal(Object,Object)
orupdateJAXB(Object)
method invocation, but it maybe a different object, for example when the name of the XML element has changed. - Throws:
JAXBException
- If any unexpected problem occurs updating corresponding Jakarta XML Binding mapped content.IllegalArgumentException
- If node parameter is null
-
setSchema
Specifies whether marshal, unmarshal and update methods performs validation on their XML content.- Parameters:
schema
- set to null to disable validation.- See Also:
-
getSchema
Gets the lastSchema
object (including null) set by thesetSchema(Schema)
method.- Returns:
- the Schema object for validation or null if not present
-
setEventHandler
Allow an application to register aValidationEventHandler
.The
ValidationEventHandler
will be called by the Jakarta XML Binding 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 event handler.
- Parameters:
handler
- the validation event handler- Throws:
JAXBException
- if an error was encountered while setting the event handler
-
getEventHandler
Return the current event handler or the default event handler if one hasn't been set.- Returns:
- the current ValidationEventHandler or the default event handler if it hasn't been set
- Throws:
JAXBException
- if an error was encountered while getting the current event handler
-
setProperty
Set the particular property in the underlying implementation ofBinder
. This method can only be used to set one of the standard Jakarta XML Binding defined unmarshal/marshal properties or a provider specific property for binder, unmarshal or marshal. Attempting to set an undefined property will result in a PropertyException being thrown. See Supported Unmarshal Properties and Supported Marshal Properties.- Parameters:
name
- the name of the property to be set. This value can either be specified using one of the constant fields or a user supplied string.value
- the value of the property to be set- Throws:
PropertyException
- when there is an error processing the given property or valueIllegalArgumentException
- If the name parameter is null
-
getProperty
Get the particular property in the underlying implementation ofBinder
. This method can only be used to get one of the standard Jakarta XML Binding defined unmarshal/marshal properties or a provider specific property for binder, unmarshal or marshal. Attempting to get an undefined property will result in a PropertyException being thrown. See Supported Unmarshal Properties and Supported Marshal Properties.- Parameters:
name
- the name of the property to retrieve- Returns:
- the value of the requested property
- Throws:
PropertyException
- when there is an error retrieving the given property or value property nameIllegalArgumentException
- If the name parameter is null
-