| java.lang.Object
 javax.xml.bind.Binder
| Binder | | abstract public class Binder (Code) | | 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
Binder.getXMLNode(Object) and
Binder.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,
Binder.updateXML(Object,Object) or
Binder.updateJAXB(Object) .
A typical usage scenario is the following:
- load XML document into an XML infoset representation
-
Binder.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.)
- application access/updates JAXB view of XML document.
-
Binder.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.
author:
Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
author:
Joseph Fialli
since:
JAXB 2.0 |
| Method Summary | |
| abstract public ValidationEventHandler | getEventHandler()
Return the current event handler or the default event handler if one
hasn't been set. | | abstract public Object | getJAXBNode(XmlNode xmlNode)
Gets the JAXB object associated with the given XML element. | | abstract public Object | getProperty(String name)
Get the particular property in the underlying implementation of
Binder. | | abstract public Schema | getSchema()
Gets the last
Schema object (including null) set by the
Binder.setSchema(Schema) method. | | abstract public XmlNode | getXMLNode(Object jaxbObject)
Gets the XML element associated with the given JAXB object. | | abstract public void | marshal(Object jaxbObject, XmlNode xmlNode)
Marshal a JAXB object tree to a new XML document.
This method is similar to
Marshaller.marshal(ObjectNode) with the addition of maintaining the association between JAXB objects
and the produced XML nodes,
enabling future update operations such as
Binder.updateXML(Object,Object) or
Binder.updateJAXB(Object) .
When
Binder.getSchema() is non-null, the marshalled
xml content is validated during this operation.
Parameters:
jaxbObject - The content tree to be marshalled. | | abstract public void | setEventHandler(ValidationEventHandler handler)
Allow an application to register a 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. | | abstract public void | setProperty(String name, Object value)
Set the particular property in the underlying implementation of
Binder. | | abstract public void | setSchema(Schema schema)
Specifies whether marshal, unmarshal and update methods
performs validation on their XML content. | | abstract public Object | unmarshal(XmlNode xmlNode)
Unmarshal XML infoset view to a JAXB object tree.
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,
Binder.updateXML(Object,Object) or
Binder.updateJAXB(Object) .
When
Binder.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. | | abstract public JAXBElement<T> | unmarshal(XmlNode xmlNode, Class<T> declaredType)
Unmarshal XML root element by provided declaredType
to a JAXB object tree. | | abstract public Object | updateJAXB(XmlNode xmlNode)
Takes an XML node and updates its associated JAXB 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 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.
Returns the updated JAXB object. | | abstract public XmlNode | updateXML(Object jaxbObject)
Takes an JAXB object and updates
its associated XML node and its descendants. | | abstract public XmlNode | updateXML(Object jaxbObject, XmlNode xmlNode)
Changes in JAXB 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 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.
Parameters:
jaxbObject - root of potentially modified JAXB object tree
Parameters:
xmlNode - root of update target XML parse treeReturns the updated XML node. |
| getEventHandler | | abstract public ValidationEventHandler getEventHandler() throws JAXBException(Code) | | Return the current event handler or the default event handler if one
hasn't been set.
the current ValidationEventHandler or the default event handlerif it hasn't been set
throws:
JAXBException - if an error was encountered while getting thecurrent event handler |
| getJAXBNode | | abstract public Object getJAXBNode(XmlNode xmlNode)(Code) | | Gets the JAXB object associated with the given XML element.
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.
null if the specified XML node is not known to thisBinder, or if it is not associated with aJAXB object.
throws:
IllegalArgumentException - If the node parameter is null |
| getProperty | | abstract public Object getProperty(String name) throws PropertyException(Code) | | Get the particular property in the underlying implementation of
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.
Parameters:
name - the name of the property to retrieve the value of the requested property
throws:
PropertyException - when there is an error retrieving the given property or valueproperty name
throws:
IllegalArgumentException - If the name parameter is null |
| getXMLNode | | abstract public XmlNode getXMLNode(Object jaxbObject)(Code) | | Gets the XML element associated with the given JAXB object.
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.
Parameters:
jaxbObject - An instance that is reachable from a prior call to a bind or update method that returneda JAXB object tree.null if the specified JAXB object is not known to thisBinder, or if it is not associated with anXML element.
throws:
IllegalArgumentException - If the jaxbObject parameter is null |
| setEventHandler | | abstract public void setEventHandler(ValidationEventHandler handler) throws JAXBException(Code) | | Allow an application to register a 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.
Parameters:
handler - the validation event handler
throws:
JAXBException - if an error was encountered while setting theevent handler |
| setProperty | | abstract public void setProperty(String name, Object value) throws PropertyException(Code) | | Set the particular property in the underlying implementation of
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.
Parameters:
name - the name of the property to be set. This value can eitherbe specified using one of the constant fields or a usersupplied string.
Parameters:
value - the value of the property to be set
throws:
PropertyException - when there is an error processing the givenproperty or value
throws:
IllegalArgumentException - If the name parameter is null |
| setSchema | | abstract public void setSchema(Schema schema)(Code) | | Specifies whether marshal, unmarshal and update methods
performs validation on their XML content.
Parameters:
schema - set to null to disable validation.
See Also: Unmarshaller.setSchema(Schema) |
| updateJAXB | | abstract public Object updateJAXB(XmlNode xmlNode) throws JAXBException(Code) | | Takes an XML node and updates its associated JAXB 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 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.
Returns the updated JAXB object. Typically, this is the sameobject that was returned from earlierBinder.marshal(Object,Object) orBinder.updateJAXB(Object) method invocation,but it maybea different object, for example when the name of the XMLelement has changed.
throws:
JAXBException - If any unexpected problem occurs updating corresponding JAXB mapped content.
throws:
IllegalArgumentException - If node parameter is null |
| updateXML | | abstract public XmlNode updateXML(Object jaxbObject) throws JAXBException(Code) | | Takes an JAXB object and updates
its associated XML node and its descendants.
This is a convenience method of:
updateXML( jaxbObject, getXMLNode(jaxbObject));
throws:
JAXBException - If any unexpected problem occurs updating corresponding XML content.
throws:
IllegalArgumentException - If the jaxbObject parameter is null |
| updateXML | | abstract public XmlNode updateXML(Object jaxbObject, XmlNode xmlNode) throws JAXBException(Code) | | Changes in JAXB 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 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.
Parameters:
jaxbObject - root of potentially modified JAXB object tree
Parameters:
xmlNode - root of update target XML parse treeReturns the updated XML node. Typically, this is the samenode you passed in as xmlNode, but it maybea different object, for example when the tag name of the objecthas changed.
throws:
JAXBException - If any unexpected problem occurs updating corresponding XML content.
throws:
IllegalArgumentException - If any of the input parameters are null |
|
|