Binder (Java EE 5)

此类的实例维护了保留视图的信息集的 XML 节点与 XML 文档的 JAXB 表示形式之间的关联。两个视图之间的导航由方法 #getXMLNode(Object) 和 #getJAXBNode(Object) 提供。

可以在其他视图保持不变的情况下，对保留视图的信息集或文档的 JAXB 表示形式进行修改。Binder 能够使用适当的 Binder 更新方法（#updateXML(Object, Object) 或 #updateJAXB(Object)）将在修改视图中所做的更改同步到其他视图中。

下面是一个典型的使用场景：

• 将 XML 文档加载为 XML 信息集表示形式
• 将 #unmarshal(Object) XML 信息集视图加载到 JAXB 视图。（注意保存资源，可以只将 XML 信息集视图的子树解组为 JAXB 视图。）
• XML 文档的应用程序访问/更新 JAXB 视图。
• #updateXML(Object) 可将对 JAXB 视图的修改同步到 XML 信息集视图中。更新操作将尽可能多地保留原始 XML 信息集（如注释、PI 等等）

Binder 实例是使用工厂方法 createBinder() 或 createBinder(Class) 创建的。

模板参数 XmlNode 是保留表示形式的 XML 信息集的根接口/类。Binder 实现至少需要支持 org.w3c.dom.Node.class 的一个 XmlNode 值。Binder 实现可以支持保留表示形式的备用 XML 信息集。

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 getXMLNode(Object) and 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, updateXML(Object, Object) or updateJAXB(Object).

A typical usage scenario is the following:

• load XML document into an XML infoset representation
• 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.
• 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.

Since:

JAXB 2.0

Author:

Kohsuke Kawaguchi ([email protected]) Joseph Fialli

public Binder()

英文文档：

Binder

public Binder()

英文文档：

unmarshal

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

IllegalArgumentException - If the node parameter is null

英文文档：

unmarshal

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

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:

JAXB2.0

英文文档：

marshal

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

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

abstract public Object getXMLNode(Object jaxbObject)
获取与给定 JAXB 对象关联的 XML 元素。

一旦 JAXB 对象树与 XML 片段关联，此方法将在两树之间启用导航。

XML 元素与 JAXB 对象之间的关联是通过 bind 方法和 update 方法建立的。注意，此关联是片面的；并不是所有 XML 元素都有关联的 JAXB 对象，也不是所有 JAXB 对象都有关联的 XML 元素。

jaxbObject	可从以前对返回 JAXB 对象树的 bind 或 update 方法的调用中获得的实例。
return	如果指定的 JAXB 对象对于此 Binder 为未知对象，或者该对象与 XML 元素没有任何关联，则返回 null。
Throws	IllegalArgumentException: 如果 jaxbObject 参数为 null

英文文档：

getXMLNode

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

Throws:

IllegalArgumentException - If the jaxbObject parameter is null

英文文档：

getJAXBNode

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:

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

Throws:

IllegalArgumentException - If the node parameter is null

abstract public Object updateXML(Object jaxbObject) throws JAXBException
取一个 JAXB 对象，并更新与其关联的 XML 节点和该节点的子级。

这是如下调用的一种便捷方法：

updateXML( jaxbObject, getXMLNode(jaxbObject));
 

Throws	JAXBException: 如果更新相应的 XML 内容时出现任何不可预料的问题。
Throws	IllegalArgumentException: 如果 jaxbObject 参数为 null

英文文档：

updateXML

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));
 

Throws:

JAXBException - If any unexpected problem occurs updating corresponding XML content.

IllegalArgumentException - If the jaxbObject parameter is null

英文文档：

updateXML

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

IllegalArgumentException - If any of the input parameters are null

英文文档：

updateJAXB

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:

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.

Throws:

JAXBException - If any unexpected problem occurs updating corresponding JAXB mapped content.

IllegalArgumentException - If node parameter is null

abstract public void setSchema(javax.xml.validation.Schema schema)
指定 marshal、unmarshal 和 update 方法是否在其 XML 内容上执行验证。

schema	可将此参数设置为 null 来禁用验证。
See also	setSchema(Schema)

英文文档：

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.

See Also:

Unmarshaller.setSchema(Schema)

abstract public javax.xml.validation.Schema getSchema()
获取 #setSchema(Schema) 方法设置的最后一个 Schema 对象（包括 null）。

return

用于验证的 Schema 对象，如果不存在这样的对象，则返回 null

英文文档：

getSchema

public abstract Schema getSchema()

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

Returns:

the Schema object for validation or null if not present

abstract public void setEventHandler(ValidationEventHandler handler) throws JAXBException
允许应用程序注册 ValidationEventHandler。

如果在调用任何 Binder 的 unmarshal、marshal 和 update 方法期间遇到验证错误，JAXB 提供者将调用 ValidationEventHandler。

调用带有 null 参数的此方法将导致 Binder 转而调用默认事件处理程序。

handler	验证事件处理程序
Throws	JAXBException: 如果在设置事件处理程序时发生错误

英文文档：

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

abstract public ValidationEventHandler getEventHandler() throws JAXBException
当前的事件处理程序；如果没有设置，则返回默认事件处理程序。

return	当前的 ValidationEventHandler；如果没有设置，则返回默认的事件处理程序
Throws	JAXBException: 如果获取当前的事件处理程序时发生错误

英文文档：

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

abstract public void setProperty(String name, Object value) throws PropertyException
设置 Binder 的基础实现中的特定属性。此方法只用于设置某个标准 JAXB 定义的 unmarshal/marshal 属性或者特定于提供者的 binder、unmarshal 或 marshal 属性。试图设置未定义的属性将导致抛出 PropertyException。请参阅受支持的 Unmarshal 属性和受支持的 Marshal 属性。

name	要设置的属性的名称。此值可以使用一个常量字段来指定，也可以是一个用户提供的字符串。
value	要设置的属性值
Throws	PropertyException: 如果处理给定属性或值时发生错误
Throws	IllegalArgumentException: 如果 name 参数为 null

英文文档：

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

IllegalArgumentException - If the name parameter is null

abstract public Object getProperty(String name) throws PropertyException
获取 Binder 的基础实现中的特定属性。此方法只用于获取某个标准 JAXB 定义的 unmarshal/marshal 属性或者特定于提供者的 binder、unmarshal 或 marshal 属性。试图获取未定义的属性将导致抛出 PropertyException。请参阅受支持的 Unmarshal 属性和受支持的 Marshal 属性。

name	将检索的属性名称
return	所请求属性的值
Throws	PropertyException: 如果检索给定属性或值属性名称时发生错误
Throws	IllegalArgumentException: 如果 name 参数为 null

英文文档：

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

IllegalArgumentException - If the name parameter is null

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.