FileDocCategorySizeDatePackage
Binder.javaAPI DocJava SE 6 API15818Tue Jun 10 00:27:04 BST 2008javax.xml.bind

Binder

public abstract class Binder extends Object
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 {@link #getXMLNode(Object)} and {@link #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, {@link #updateXML(Object, Object)} or {@link #updateJAXB(Object)}.

A typical usage scenario is the following:

  • load XML document into an XML infoset representation
  • {@link #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.
  • {@link #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 {@link JAXBContext#createBinder()} or {@link 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) Joseph Fialli
since
JAXB 2.0

Fields Summary
Constructors Summary
Methods Summary
public abstract javax.xml.bind.ValidationEventHandlergetEventHandler()
Return the current event handler or the default event handler if one hasn't been set.

return
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

public abstract java.lang.ObjectgetJAXBNode(XmlNode xmlNode)
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.

return
null if the specified XML node is not known to this {@link Binder}, or if it is not associated with a JAXB object.
throws
IllegalArgumentException If the node parameter is null

public abstract java.lang.ObjectgetProperty(java.lang.String name)
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.

param
name the name of the property to retrieve
return
the value of the requested property
throws
PropertyException when there is an error retrieving the given property or value property name
throws
IllegalArgumentException If the name parameter is null

public abstract javax.xml.validation.SchemagetSchema()
Gets the last {@link Schema} object (including null) set by the {@link #setSchema(Schema)} method.

return
the Schema object for validation or null if not present

public abstract XmlNodegetXMLNode(java.lang.Object jaxbObject)
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.

param
jaxbObject An instance that is reachable from a prior call to a bind or update method that returned a JAXB object tree.
return
null if the specified JAXB object is not known to this {@link Binder}, or if it is not associated with an XML element.
throws
IllegalArgumentException If the jaxbObject parameter is null

public abstract voidmarshal(java.lang.Object jaxbObject, XmlNode xmlNode)
Marshal a JAXB object tree to a new XML document.

This method is similar to {@link 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 {@link #updateXML(Object, Object)} or {@link #updateJAXB(Object)}.

When {@link #getSchema()} is non-null, the marshalled xml content is validated during this operation.

param
jaxbObject The content tree to be marshalled.
param
xmlNode The parameter must be a Node that accepts children.
throws
JAXBException If any unexpected problem occurs during the marshalling.
throws
MarshalException If the {@link ValidationEventHandler ValidationEventHandler} returns false from its handleEvent method or the Binder is unable to marshal jaxbObject (or any object reachable from jaxbObject).
throws
IllegalArgumentException If any of the method parameters are null

public abstract voidsetEventHandler(javax.xml.bind.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.

Calling this method with a null parameter will cause the Binder to revert back to the default default event handler.

param
handler the validation event handler
throws
JAXBException if an error was encountered while setting the event handler

public abstract voidsetProperty(java.lang.String name, java.lang.Object value)
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.

param
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.
param
value the value of the property to be set
throws
PropertyException when there is an error processing the given property or value
throws
IllegalArgumentException If the name parameter is null

public abstract voidsetSchema(javax.xml.validation.Schema schema)
Specifies whether marshal, unmarshal and update methods performs validation on their XML content.

param
schema set to null to disable validation.
see
Unmarshaller#setSchema(Schema)

public abstract java.lang.Objectunmarshal(XmlNode xmlNode)
Unmarshal XML infoset view to a JAXB object tree.

This method is similar to {@link Unmarshaller#unmarshal(Node)} with the addition of maintaining the association between XML nodes and the produced JAXB objects, enabling future update operations, {@link #updateXML(Object, Object)} or {@link #updateJAXB(Object)}.

When {@link #getSchema()} is non-null, xmlNode and its descendants is validated during this operation.

This method throws {@link UnmarshalException} when the Binder's {@link 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 {@link #unmarshal(Object, Class)} enables an application to specify the JAXB mapped class that the xmlNode should be mapped to.

param
xmlNode the document/element to unmarshal XML data from.
return
the newly created root object of the JAXB object tree.
throws
JAXBException If any unexpected errors occur while unmarshalling
throws
UnmarshalException If the {@link ValidationEventHandler ValidationEventHandler} returns false from its handleEvent method or the Binder is unable to perform the XML to Java binding.
throws
IllegalArgumentException If the node parameter is null

public abstract javax.xml.bind.JAXBElementunmarshal(XmlNode xmlNode, java.lang.Class declaredType)
Unmarshal XML root element by provided declaredType to a JAXB object tree.

Implements Unmarshal by Declared Type

This method is similar to {@link Unmarshaller#unmarshal(Node, Class)} with the addition of maintaining the association between XML nodes and the produced JAXB objects, enabling future update operations, {@link #updateXML(Object, Object)} or {@link #updateJAXB(Object)}.

When {@link #getSchema()} is non-null, xmlNode and its descendants is validated during this operation.

param
xmlNode the document/element to unmarshal XML data from.
param
declaredType appropriate JAXB mapped class to hold node's XML data.
return
JAXB Element representation of node
throws
JAXBException If any unexpected errors occur while unmarshalling
throws
UnmarshalException If the {@link ValidationEventHandler ValidationEventHandler} returns false from its handleEvent method or the Binder is unable to perform the XML to Java binding.
throws
IllegalArgumentException If any of the input parameters are null
since
JAXB2.0

public abstract java.lang.ObjectupdateJAXB(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.

return
Returns the updated JAXB object. Typically, this is the same object that was returned from earlier {@link #marshal(Object,Object)} or {@link #updateJAXB(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 JAXB mapped content.
throws
IllegalArgumentException If node parameter is null

public abstract XmlNodeupdateXML(java.lang.Object jaxbObject)
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

public abstract XmlNodeupdateXML(java.lang.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.

param
jaxbObject root of potentially modified JAXB object tree
param
xmlNode root of update target XML parse tree
return
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.
throws
IllegalArgumentException If any of the input parameters are null