EclipseLink 2.2.0, build 'v20110202-r8913' API Reference

org.eclipse.persistence.jaxb
Class JAXBBinder

java.lang.Object
  extended by javax.xml.bind.Binder
      extended by org.eclipse.persistence.jaxb.JAXBBinder

public class JAXBBinder
extends Binder

INTERNAL

Purpose: Provide a TopLink implementation of the javax.xml.bind.Binder interface

Responsibilities:

See Also:
Binder
Author:
mmacivor
Since:
Oracle TopLink 11.1.1.0.0

Constructor Summary
JAXBBinder(XMLContext xmlContext)
           
 
Method Summary
 ValidationEventHandler getEventHandler()
          Return the current event handler or the default event handler if one hasn't been set.
 java.lang.Object getJAXBNode(java.lang.Object obj)
          Gets the JAXB object associated with the given XML element.
 java.lang.Object getProperty(java.lang.String propName)
          Get the particular property in the underlying implementation of Binder.
 javax.xml.validation.Schema getSchema()
          Gets the last Schema object (including null) set by the Binder.setSchema(Schema) method.
 XMLBinder getXMLBinder()
           
 java.lang.Object getXMLNode(java.lang.Object obj)
          Gets the XML element associated with the given JAXB object.
 void marshal(java.lang.Object obj, java.lang.Object xmlNode)
          Marshal a JAXB object tree to a new XML document.
 void setEventHandler(ValidationEventHandler handler)
          Allow an application to register a ValidationEventHandler.
 void setProperty(java.lang.String propName, java.lang.Object value)
          Set the particular property in the underlying implementation of Binder.
 void setSchema(javax.xml.validation.Schema schema)
          Specifies whether marshal, unmarshal and update methods performs validation on their XML content.
 java.lang.Object unmarshal(java.lang.Object obj)
          Unmarshal XML infoset view to a JAXB object tree.
 JAXBElement unmarshal(java.lang.Object obj, java.lang.Class javaClass)
          Unmarshal XML root element by provided declaredType to a JAXB object tree.
 java.lang.Object updateJAXB(java.lang.Object obj)
          Takes an XML node and updates its associated JAXB object and its descendants.
 java.lang.Object updateXML(java.lang.Object obj)
          Takes an JAXB object and updates its associated XML node and its descendants.
 java.lang.Object updateXML(java.lang.Object obj, java.lang.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

JAXBBinder

public JAXBBinder(XMLContext xmlContext)
Method Detail

marshal

public void marshal(java.lang.Object obj,
                    java.lang.Object xmlNode)
             throws MarshalException
Description copied from class: Binder
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 Binder.updateXML(Object, Object) or Binder.updateJAXB(Object).

When Binder.getSchema() is non-null, the marshalled xml content is validated during this operation.

Specified by:
marshal in class Binder
Parameters:
obj - The content tree to be marshalled.
xmlNode - The parameter must be a Node that accepts children.
Throws:
MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Binder is unable to marshal jaxbObject (or any object reachable from jaxbObject).

unmarshal

public java.lang.Object unmarshal(java.lang.Object obj)
                           throws JAXBException
Description copied from class: Binder
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. The method Binder.unmarshal(Object, Class) enables an application to specify the JAXB mapped class that the xmlNode should be mapped to.

Specified by:
unmarshal in class Binder
Parameters:
obj - 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
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Binder is unable to perform the XML to Java binding.

unmarshal

public JAXBElement unmarshal(java.lang.Object obj,
                             java.lang.Class javaClass)
                      throws JAXBException
Description copied from class: Binder
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, Binder.updateXML(Object, Object) or Binder.updateJAXB(Object).

When Binder.getSchema() is non-null, xmlNode and its descendants is validated during this operation.

Specified by:
unmarshal in class Binder
Parameters:
obj - the document/element to unmarshal XML data from.
javaClass - 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
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Binder is unable to perform the XML to Java binding.

getXMLNode

public java.lang.Object getXMLNode(java.lang.Object obj)
Description copied from class: Binder
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.

Specified by:
getXMLNode in class Binder
Parameters:
obj - 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 Binder, or if it is not associated with an XML element.

updateXML

public java.lang.Object updateXML(java.lang.Object obj)
Description copied from class: Binder
Takes an JAXB object and updates its associated XML node and its descendants.

This is a convenience method of:

 updateXML( jaxbObject, getXMLNode(jaxbObject));
 

Specified by:
updateXML in class Binder

updateXML

public java.lang.Object updateXML(java.lang.Object obj,
                                  java.lang.Object xmlNode)
Description copied from class: Binder
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.

Specified by:
updateXML in class Binder
Parameters:
obj - 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.

getJAXBNode

public java.lang.Object getJAXBNode(java.lang.Object obj)
Description copied from class: Binder
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.

Specified by:
getJAXBNode in class Binder
Returns:
null if the specified XML node is not known to this Binder, or if it is not associated with a JAXB object.

updateJAXB

public java.lang.Object updateJAXB(java.lang.Object obj)
                            throws JAXBException
Description copied from class: Binder
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.

Specified by:
updateJAXB in class Binder
Returns:
Returns the updated JAXB object. Typically, this is the same object that was returned from earlier Binder.marshal(Object,Object) or Binder.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.

setSchema

public void setSchema(javax.xml.validation.Schema schema)
Description copied from class: Binder
Specifies whether marshal, unmarshal and update methods performs validation on their XML content.

Specified by:
setSchema in class Binder
Parameters:
schema - set to null to disable validation.
See Also:
Unmarshaller.setSchema(Schema)

getSchema

public javax.xml.validation.Schema getSchema()
Description copied from class: Binder
Gets the last Schema object (including null) set by the Binder.setSchema(Schema) method.

Specified by:
getSchema in class Binder
Returns:
the Schema object for validation or null if not present

setEventHandler

public void setEventHandler(ValidationEventHandler handler)
Description copied from class: Binder
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.

Specified by:
setEventHandler in class Binder
Parameters:
handler - the validation event handler

getEventHandler

public ValidationEventHandler getEventHandler()
Description copied from class: Binder
Return the current event handler or the default event handler if one hasn't been set.

Specified by:
getEventHandler in class Binder
Returns:
the current ValidationEventHandler or the default event handler if it hasn't been set

getProperty

public java.lang.Object getProperty(java.lang.String propName)
                             throws PropertyException
Description copied from class: Binder
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.

Specified by:
getProperty in class Binder
Parameters:
propName - 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

setProperty

public void setProperty(java.lang.String propName,
                        java.lang.Object value)
                 throws PropertyException
Description copied from class: Binder
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.

Specified by:
setProperty in class Binder
Parameters:
propName - 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

getXMLBinder

public XMLBinder getXMLBinder()

EclipseLink 2.2.0, build 'v20110202-r8913' API Reference