public abstract class Binder<XmlNode> extends Object
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:
unmarshal(Object)
XML infoset view to JAXB view.
(Note to conserve resources, it is possible to only unmarshal a
subtree of the XML infoset view to the JAXB view.)updateXML(Object)
synchronizes modifications to JAXB 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)
.
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 and Description |
---|
Binder() |
Modifier and Type | Method and Description |
---|---|
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 <T> JAXBElement<T> |
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.
|
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.
xmlNode
- the document/element to unmarshal XML data from.JAXBException
- If any unexpected errors occur while unmarshallingUnmarshalException
- If the ValidationEventHandler
returns false from its handleEvent
method or the
Binder
is unable to perform the XML to Java
binding.IllegalArgumentException
- If the node parameter is nullpublic abstract <T> JAXBElement<T> unmarshal(XmlNode xmlNode, Class<T> declaredType) throws JAXBException
declaredType
to a JAXB 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 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.
xmlNode
- the document/element to unmarshal XML data from.declaredType
- appropriate JAXB mapped class to hold node
's XML data.node
JAXBException
- If any unexpected errors occur while unmarshallingUnmarshalException
- If the ValidationEventHandler
returns false from its handleEvent
method or the
Binder
is unable to perform the XML to Java
binding.IllegalArgumentException
- If any of the input parameters are nullpublic 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.
jaxbObject
- The content tree to be marshalled.xmlNode
- The parameter must be a Node that accepts children.JAXBException
- If any unexpected problem occurs during the marshalling.MarshalException
- If the ValidationEventHandler
returns false from its handleEvent
method or the
Binder
is unable to marshal jaxbObject
(or any
object reachable from jaxbObject
).IllegalArgumentException
- If any of the method parameters are nullpublic 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.
jaxbObject
- An instance that is reachable from a prior
call to a bind or update method that returned
a JAXB object tree.Binder
, or if it is not associated with an
XML element.IllegalArgumentException
- If the jaxbObject parameter is nullpublic 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.
Binder
, or if it is not associated with a
JAXB object.IllegalArgumentException
- If the node parameter is nullpublic abstract XmlNode updateXML(Object jaxbObject) throws JAXBException
This is a convenience method of:
updateXML( jaxbObject, getXMLNode(jaxbObject));
JAXBException
- If any unexpected problem occurs updating corresponding XML content.IllegalArgumentException
- If the jaxbObject parameter is nullpublic 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.
jaxbObject
- root of potentially modified JAXB object treexmlNode
- root of update target XML parse treeJAXBException
- If any unexpected problem occurs updating corresponding XML content.IllegalArgumentException
- If any of the input parameters are nullpublic 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.
marshal(Object,Object)
or
updateJAXB(Object)
method invocation,
but it maybe
a different object, for example when the name of the XML
element has changed.JAXBException
- If any unexpected problem occurs updating corresponding JAXB mapped content.IllegalArgumentException
- If node parameter is nullpublic abstract void setSchema(Schema schema)
schema
- set to null to disable validation.Unmarshaller.setSchema(Schema)
public abstract Schema getSchema()
Schema
object (including null) set by the
setSchema(Schema)
method.public abstract void setEventHandler(ValidationEventHandler handler) throws JAXBException
ValidationEventHandler
.
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.
handler
- the validation event handlerJAXBException
- if an error was encountered while setting the
event handlerpublic abstract ValidationEventHandler getEventHandler() throws JAXBException
JAXBException
- if an error was encountered while getting the
current event handlerpublic abstract void setProperty(String name, Object value) throws PropertyException
Binder
. This method can only be used to set one of
the standard JAXB 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.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 setPropertyException
- when there is an error processing the given
property or valueIllegalArgumentException
- If the name parameter is nullpublic abstract Object getProperty(String name) throws PropertyException
Binder
. This method can only
be used to get one of
the standard JAXB 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.name
- the name of the property to retrievePropertyException
- when there is an error retrieving the given property or value
property nameIllegalArgumentException
- If the name parameter is nullCopyright © 2020 JBoss by Red Hat. All rights reserved.