This documentation differs from the official API. Jadeite adds extra features to the API including: variable font sizes, constructions examples, placeholders for classes and methods, and auto-generated “See Also” links. Additionally it is missing some items found in standard Javadoc documentation, including: generics type information, “Deprecated” tags and comments, “See Also” links, along with other minor differences. Please send any questions or feedback to bam@cs.cmu.edu.


javax.xml.bind
class Binder

java.lang.Object extended by javax.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:

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.


Constructor Summary

          
 
Method Summary
abstract ValidationEventHandler

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

          Gets the JAXB object associated with the given XML element.
abstract Object

          Get the particular property in the underlying implementation of Binder.
abstract Schema

          Gets the last javax.xml.validation.Schema object (including null) set by the javax.xml.bind.Binder.setSchema method.
abstract Object
getXMLNode(Object jaxbObject)

          Gets the XML element associated with the given JAXB object.
abstract void
marshal(Object jaxbObject, Object xmlNode)

          Marshal a JAXB object tree to a new XML document.
abstract void

          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(Object xmlNode)

          Unmarshal XML infoset view to a JAXB object tree.
abstract JAXBElement
unmarshal(Object xmlNode, Class declaredType)

          Unmarshal XML root element by provided declaredType to a JAXB object tree.
abstract Object
updateJAXB(Object xmlNode)

          Takes an XML node and updates its associated JAXB object and its descendants.
abstract Object
updateXML(Object jaxbObject)

          Takes an JAXB object and updates its associated XML node and its descendants.
abstract Object
updateXML(Object jaxbObject, Object xmlNode)

          Changes in JAXB object tree are updated in its associated XML parse tree.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Binder

public Binder()
Method Detail

getEventHandler

public abstract ValidationEventHandler getEventHandler()
                                                throws JAXBException
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

getJAXBNode

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

Parameters:
xmlNode
Returns:
null if the specified XML node is not known to this {@link Binder}, or if it is not associated with a JAXB object.

getProperty

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 - 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 name

getSchema

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

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

getXMLNode

public abstract Object 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 - An instance that is reachable from a prior call to a bind or update method that returned a JAXB object tree.
Returns:
null if the specified JAXB object is not known to this {@link Binder}, or if it is not associated with an XML element.

marshal

public abstract void marshal(Object jaxbObject,
                             Object xmlNode)
                      throws JAXBException
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.

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.

setEventHandler

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 - the validation event handler
Throws:
JAXBException - if an error was encountered while setting the event handler

setProperty

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 - 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 value

setSchema

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

Parameters:
schema - set to null to disable validation.

unmarshal

public abstract Object unmarshal(Object xmlNode)
                          throws JAXBException
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.

Parameters:
xmlNode - the document/element to unmarshal XML data from.
Returns:
the newly created root object of the JAXB object tree.
Throws:
JAXBException - If any unexpected errors occur while unmarshalling

unmarshal

public abstract JAXBElement unmarshal(Object xmlNode,
                                      Class 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 {@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.

Parameters:
xmlNode - the document/element to unmarshal XML data from.
declaredType - appropriate JAXB mapped class to hold node's XML data.
Returns:
JAXB Element representation of node
Throws:
JAXBException - If any unexpected errors occur while unmarshalling

updateJAXB

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

Parameters:
xmlNode
Returns:
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.

updateXML

public abstract Object 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));
 

Parameters:
jaxbObject
Throws:
JAXBException - If any unexpected problem occurs updating corresponding XML content.

updateXML

public abstract Object updateXML(Object jaxbObject,
                                 Object 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 - root of potentially modified JAXB object tree
xmlNode - 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.


This documentation differs from the official API. Jadeite adds extra features to the API including: variable font sizes, constructions examples, placeholders for classes and methods, and auto-generated “See Also” links. Additionally it is missing some items found in standard Javadoc documentation, including: generics type information, “Deprecated” tags and comments, “See Also” links, along with other minor differences. Please send any questions or feedback to bam@cs.cmu.edu.
This page displays the Jadeite version of the documention, which is derived from the offical documentation that contains this copyright notice:
Copyright 2008 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.
The official Sun™ documentation can be found here at http://java.sun.com/javase/6/docs/api/.