Java Architecture for XML Binding 2.3.1 · javax.xml.bind.Binder

Access	Constructor and Description
public	Binder()

Method Summary

Modifier and Type	Method and Description
public abstract ValidationEventHandler	Returns: the current ValidationEventHandler or the default event handler if it hasn't been set getEventHandler() Return the current event handler or the default event handler if one hasn't been set.
public abstract Object	Returns: null if the specified XML node is not known to this `Binder`, or if it is not associated with a JAXB object. getJAXBNode(XmlNode xmlNode) Gets the JAXB object associated with the given XML element.
public abstract Object	Returns: the value of the requested property getProperty(String the name of the property to retrieve name) Get the particular property in the underlying implementation of `Binder`.
public abstract Schema	Returns: the Schema object for validation or null if not present getSchema() Gets the last `Schema` object (including null) set by the `setSchema(Schema)` method.
public abstract XmlNode	Returns: null if the specified JAXB object is not known to this `Binder`, or if it is not associated with an XML element. getXMLNode(Object An instance that is reachable from a prior call to a bind or update method that returned a JAXB object tree. jaxbObject) Gets the XML element associated with the given JAXB object.
public abstract void	marshal(Object The content tree to be marshalled. jaxbObject, XmlNode The parameter must be a Node that accepts children. xmlNode) Marshal a JAXB object tree to a new XML document.
public abstract void	setEventHandler(ValidationEventHandler the validation event handler handler) Allow an application to register a `ValidationEventHandler`.
public abstract void	setProperty(String 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. name, Object the value of the property to be set value) Set the particular property in the underlying implementation of `Binder`.
public abstract void	setSchema(Schema set to null to disable validation. schema) Specifies whether marshal, unmarshal and update methods performs validation on their XML content.
public abstract Object	Returns: the newly created root object of the JAXB object tree. unmarshal(XmlNode the document/element to unmarshal XML data from. xmlNode) Unmarshal XML infoset view to a JAXB object tree.
public abstract <T> JAXBElement<T>	Returns: JAXB Element representation of `node` unmarshal(XmlNode the document/element to unmarshal XML data from. xmlNode, Class<T> appropriate JAXB mapped class to hold `node`'s XML data. declaredType) Unmarshal XML root element by provided `declaredType` to a JAXB object tree.
public abstract Object	Returns: Returns the updated JAXB object. Typically, this is the same object that was returned from earlier `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. updateJAXB(XmlNode xmlNode) Takes an XML node and updates its associated JAXB object and its descendants.
public abstract XmlNode	updateXML(Object jaxbObject) Takes an JAXB object and updates its associated XML node and its descendants.
public abstract XmlNode	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. updateXML(Object root of potentially modified JAXB object tree jaxbObject, XmlNode root of update target XML parse tree xmlNode) Changes in JAXB object tree are updated in its associated XML parse tree.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Binder	back to summary
public Binder()

Method Detail

getEventHandler	back to summary
public abstract ValidationEventHandler getEventHandler() throws JAXBException Return the current event handler or the default event handler if one hasn't been set. Returns:ValidationEventHandler the current ValidationEventHandler or the default event handler if it hasn't been set Exceptions JAXBException: if an error was encountered while getting the current event handler

getEventHandler

back to summary

public abstract ValidationEventHandler getEventHandler() throws JAXBException

Return the current event handler or the default event handler if one hasn't been set.

Returns:ValidationEventHandler

the current ValidationEventHandler or the default event handler if it hasn't been set

Exceptions

JAXBException:: if an error was encountered while getting the current event handler

getJAXBNode back to summary

getJAXBNode	back to summary
public abstract Object getJAXBNode(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. Returns:Object null if the specified XML node is not known to this `Binder`, or if it is not associated with a JAXB object. Exceptions IllegalArgumentException: If the node parameter is null

public abstract Object getJAXBNode(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.

Returns:Object

null if the specified XML node is not known to this Binder, or if it is not associated with a JAXB object.

Exceptions

IllegalArgumentException:: If the node parameter is null

getProperty back to summary

getProperty	back to summary
public abstract Object getProperty(String name) throws PropertyException 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:String the name of the property to retrieve Returns:Object the value of the requested property Exceptions PropertyException: when there is an error retrieving the given property or value property name IllegalArgumentException: If the name parameter is null

public abstract Object getProperty(String name) throws PropertyException

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:String: the name of the property to retrieve

Returns:Object

the value of the requested property

Exceptions

PropertyException:: when there is an error retrieving the given property or value property name
IllegalArgumentException:: If the name parameter is null

getSchema back to summary

getSchema	back to summary
public abstract Schema getSchema() Gets the last `Schema` object (including null) set by the `setSchema(Schema)` method. Returns:Schema the Schema object for validation or null if not present

public abstract Schema getSchema()

Gets the last Schema object (including null) set by the setSchema(Schema) method.

Returns:Schema: the Schema object for validation or null if not present

getXMLNode back to summary

getXMLNode	back to summary
public abstract XmlNode getXMLNode(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. Parameters jaxbObject:Object An instance that is reachable from a prior call to a bind or update method that returned a JAXB object tree. Returns:XmlNode null if the specified JAXB object is not known to this `Binder`, or if it is not associated with an XML element. Exceptions IllegalArgumentException: If the jaxbObject parameter is null

public abstract XmlNode getXMLNode(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.

Parameters

jaxbObject:Object: An instance that is reachable from a prior call to a bind or update method that returned a JAXB object tree.

Returns:XmlNode

null if the specified JAXB object is not known to this Binder, or if it is not associated with an XML element.

Exceptions

IllegalArgumentException:: If the jaxbObject parameter is null

marshal back to summary

marshal	back to summary
public abstract void marshal(Object jaxbObject, XmlNode xmlNode) throws JAXBException Marshal a JAXB object tree to a new XML document. 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. Parameters jaxbObject:Object The content tree to be marshalled. xmlNode:XmlNode The parameter must be a Node that accepts children. Exceptions 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 null

public abstract void marshal(Object jaxbObject, XmlNode xmlNode) throws JAXBException

Marshal a JAXB object tree to a new XML document.

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.

Parameters

jaxbObject:Object: The content tree to be marshalled.
xmlNode:XmlNode: The parameter must be a Node that accepts children.

Exceptions

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 null

setEventHandler back to summary

setEventHandler	back to summary
public abstract void setEventHandler(ValidationEventHandler handler) throws JAXBException 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:ValidationEventHandler the validation event handler Exceptions JAXBException: if an error was encountered while setting the event handler

public abstract void setEventHandler(ValidationEventHandler handler) throws JAXBException

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:ValidationEventHandler: the validation event handler

Exceptions

JAXBException:: if an error was encountered while setting the event handler

setProperty back to summary

setProperty	back to summary
public abstract void setProperty(String name, Object value) throws PropertyException 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:String 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:Object the value of the property to be set Exceptions PropertyException: when there is an error processing the given property or value IllegalArgumentException: If the name parameter is null

public abstract void setProperty(String name, Object value) throws PropertyException

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:String: 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:Object: the value of the property to be set

Exceptions

PropertyException:: when there is an error processing the given property or value
IllegalArgumentException:: If the name parameter is null

setSchema back to summary

setSchema	back to summary
public abstract void setSchema(Schema schema) Specifies whether marshal, unmarshal and update methods performs validation on their XML content. Parameters schema:Schema set to null to disable validation. See Also `Unmarshaller#setSchema(Schema)`

public abstract void setSchema(Schema schema)

Specifies whether marshal, unmarshal and update methods performs validation on their XML content.

Parameters

schema:Schema: set to null to disable validation.

See Also

Unmarshaller#setSchema(Schema)

unmarshal back to summary

unmarshal	back to summary
public abstract Object unmarshal(XmlNode xmlNode) throws JAXBException 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, `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. Parameters xmlNode:XmlNode the document/element to unmarshal XML data from. Returns:Object the newly created root object of the JAXB object tree. Exceptions JAXBException: If any unexpected errors occur while unmarshalling UnmarshalException: 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 null

public abstract Object unmarshal(XmlNode xmlNode) throws JAXBException

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, 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.

Parameters

xmlNode:XmlNode: the document/element to unmarshal XML data from.

Returns:Object

the newly created root object of the JAXB object tree.

Exceptions

JAXBException:: If any unexpected errors occur while unmarshalling
UnmarshalException:: 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 null

unmarshal back to summary

unmarshal	back to summary
public abstract <T> JAXBElement<T> unmarshal(XmlNode xmlNode, Class<T> declaredType) throws JAXBException Unmarshal XML root element by provided `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. Parameters xmlNode:XmlNode the document/element to unmarshal XML data from. declaredType:Class<T> appropriate JAXB mapped class to hold `node`'s XML data. Returns:JAXBElement<T> JAXB Element representation of `node` Exceptions JAXBException: If any unexpected errors occur while unmarshalling UnmarshalException: 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 null Since 1.6, JAXB 2.0

public abstract <T> JAXBElement<T> unmarshal(XmlNode xmlNode, Class<T> declaredType) throws JAXBException

Unmarshal XML root element by provided 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.

Parameters

xmlNode:XmlNode: the document/element to unmarshal XML data from.
declaredType:Class<T>: appropriate JAXB mapped class to hold node's XML data.

Returns:JAXBElement<T>

JAXB Element representation of node

Exceptions

JAXBException:: If any unexpected errors occur while unmarshalling
UnmarshalException:: 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 null

Since

1.6, JAXB 2.0

updateJAXB back to summary

updateJAXB	back to summary
public abstract Object updateJAXB(XmlNode xmlNode) throws JAXBException 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:Object Returns the updated JAXB object. Typically, this is the same object that was returned from earlier `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. Exceptions JAXBException: If any unexpected problem occurs updating corresponding JAXB mapped content. IllegalArgumentException: If node parameter is null

public abstract Object updateJAXB(XmlNode xmlNode) throws JAXBException

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:Object

Returns the updated JAXB object. Typically, this is the same object that was returned from earlier 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.

Exceptions

JAXBException:: If any unexpected problem occurs updating corresponding JAXB mapped content.
IllegalArgumentException:: If node parameter is null

updateXML	back to summary
public abstract XmlNode updateXML(Object jaxbObject) throws JAXBException Takes an JAXB object and updates its associated XML node and its descendants. This is a convenience method of: updateXML( jaxbObject, getXMLNode(jaxbObject)); Exceptions JAXBException: If any unexpected problem occurs updating corresponding XML content. IllegalArgumentException: If the jaxbObject parameter is null

updateXML

back to summary

public abstract XmlNode updateXML(Object jaxbObject) throws JAXBException

Takes an JAXB object and updates its associated XML node and its descendants.

This is a convenience method of:

updateXML( jaxbObject, getXMLNode(jaxbObject));

Exceptions

JAXBException:: If any unexpected problem occurs updating corresponding XML content.
IllegalArgumentException:: If the jaxbObject parameter is null

updateXML	back to summary
public abstract XmlNode updateXML(Object jaxbObject, XmlNode xmlNode) throws JAXBException 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:Object root of potentially modified JAXB object tree xmlNode:XmlNode root of update target XML parse tree Returns:XmlNode 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. Exceptions JAXBException: If any unexpected problem occurs updating corresponding XML content. IllegalArgumentException: If any of the input parameters are null

updateXML

back to summary

public abstract XmlNode updateXML(Object jaxbObject, XmlNode xmlNode) throws JAXBException

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:Object: root of potentially modified JAXB object tree
xmlNode:XmlNode: root of update target XML parse tree

Returns:XmlNode

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.

Exceptions

JAXBException:: If any unexpected problem occurs updating corresponding XML content.
IllegalArgumentException:: If any of the input parameters are null

public abstract Class Binder<XmlNode>

Constructor Summary

Method Summary

Constructor Detail

Method Detail