javax.xml.bind
类 Binder

java.lang.Object
  javax.xml.bind.Binder<XmlNode>

public abstract class Binder<XmlNode>
     

      extends 
      Object
     

在 XML 信息集节点和表示相同 XML 文档的 JAXB 对象之间启用同步。

此类的实例维护了保留视图的信息集的 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 实例是使用工厂方法 JAXBContext.createBinder() 或 JAXBContext.createBinder(Class) 创建的。

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

从以下版本开始：

JAXB 2.0

Binder

public Binder()

unmarshal

public abstract Object unmarshal(XmlNode xmlNode)
                          throws JAXBException

将 XML 信息集视图解组为 JAXB 对象树。

此方法类似于添加了维持 XML 节点与生成的 JAXB 对象之间关联功能的 Unmarshaller.unmarshal(Node)，它还支持未来更新操作，如 updateXML(Object, Object) 或 updateJAXB(Object)。

当 getSchema() 为非 null 时，可以在执行此操作期间验证 xmlNode 及其子节点。

当 Binder 的 JAXBContext 不存在将 xmlNode 的 XML 元素名称或类型（通过 @xsi:type 指定）映射到 JAXB 映射类的映射关系时，此方法抛出 UnmarshalException。unmarshal(Object, Class) 方法使应用程序能够指定 xmlNode 应该映射到哪个 JAXB 映射类。

参数：

xmlNode - 要解组其中的 XML 数据的文档/元素。

返回：

JAXB 对象树的新创建的根对象。

抛出：

JAXBException - 如果进行解组期间发生不可预料的错误

UnmarshalException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false，或者 Binder 不能执行 XML 到 Java 的绑定。

IllegalArgumentException - 如果节点参数为 null

unmarshal

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

根据提供的 declaredType 将 XML 根元素解组为 JAXB 对象树。

通过声明的类型实现解组

此方法类似于添加了维持 XML 节点与生成的 JAXB 对象之间关联功能的 Unmarshaller.unmarshal(Node, Class)，它还支持未来更新操作，如 updateXML(Object, Object) 或 updateJAXB(Object)。

当 getSchema() 为非 null 时，可以在执行此操作期间验证 xmlNode 及其子节点。

参数：

xmlNode - 要解组其中的 XML 数据的文档/元素。

declaredType - 用来保存 node 的 XML 数据的适当 JAXB 映射类。

返回：

node 的 JAXB 元素表示形式

抛出：

JAXBException - 如果进行解组期间发生不可预料的错误

UnmarshalException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false，或者 Binder 不能执行 XML 到 Java 的绑定。

IllegalArgumentException - 如果任何输入参数为 null

从以下版本开始：

JAXB2.0

marshal

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

将 JAXB 对象树编组为新的 XML 文档。

此方法类似于添加了维持 JAXB 对象和产生的 XML 节点之间关联功能的 Marshaller.marshal(Object, Node)，它还支持未来更新操作，如 updateXML(Object, Object) 或 updateJAXB(Object)。

当 getSchema() 为非 null 时，可在执行此操作期间验证已编组的 xml 内容。

参数：

jaxbObject - 将被编组的内容树。

xmlNode - 该参数必须是一个接受子节点的节点。

抛出：

JAXBException - 如果进行解组期间发生不可预料的错误。

MarshalException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false，或者 Binder 不能编组 jaxbObject（或任何可从 jaxbObject 获得的对象）。

IllegalArgumentException - 如果任何方法的参数为 null

getXMLNode

public abstract XmlNode getXMLNode(Object jaxbObject)

获取与给定 JAXB 对象关联的 XML 元素。

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

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

参数：

jaxbObject - 可从以前对返回 JAXB 对象树的 bind 或 update 方法的调用中获得的实例。

返回：

如果指定的 JAXB 对象对于此 Binder 为未知对象，或者该对象与 XML 元素没有任何关联，则返回 null。

抛出：

IllegalArgumentException - 如果 jaxbObject 参数为 null

getJAXBNode

public abstract Object getJAXBNode(XmlNode xmlNode)

获取与给定 XML 元素关联的 JAXB 对象。

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

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

返回：

如果 XML 节点对于此 Binder 为未知节点，或者该节点与 JAXB 对象没有任何关联，则返回 null。

抛出：

IllegalArgumentException - 如果节点参数为 null

updateXML

public abstract XmlNode updateXML(Object jaxbObject)
                           throws JAXBException

取一个 JAXB 对象，并更新与其关联的 XML 节点和该节点的子级。

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

updateXML( jaxbObject, getXMLNode(jaxbObject));
 

抛出：

JAXBException - 如果更新相应的 XML 内容时出现任何不可预料的问题。

IllegalArgumentException - 如果 jaxbObject 参数为 null

updateXML

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

JAXB 对象树中所做的更改在与其关联的 XML 解析树中得到更新。

可将此操作视为“原地（in-place）”编组。不同点在于，此操作不是创建一个全新的 XML 树，而是在试图尽可能多地保留 XML 的同时更新现有的树。

例如，没有绑定到 JAXB 的 XML 中的未知元素/属性将保持不变（而编组操作将创建一个不包含任何元素/属性的新树。）

另一方面，此操作会更新 XML 节点与 JAXB 对象之间的关联。

参数：

jaxbObject - 可能已修改的 JAXB 对象树的根

xmlNode - 更新目标 XML 解析树的根

返回：

返回已更新的 XML 节点。通常，此节点是作为 xmlNode 传入的同一节点，但可能是不同的对象，例如在对象的标记名称发生更改时。

抛出：

JAXBException - 如果更新相应 XML 内容时出现任何不可预料的问题。

IllegalArgumentException - 如何任何输入参数为 null

updateJAXB

public abstract Object updateJAXB(XmlNode xmlNode)
                           throws JAXBException

取一个 XML 节点，并更新与其关联的 JAXB 对象和该对象的子级。

可将此操作视为“原地”解组。不同点在于，此操作不是创建一个全新 JAXB 树，而是更新现有的树，尽可能多地重用 JAXB 对象。

另一方面，此操作会更新 XML 节点与 JAXB 对象之间的关联。

返回：

返回已更新的 JAXB 对象。通常，此对象是从较早的 marshal(Object,Object) 或 updateJAXB(Object) 方法调用中返回的同一对象，但可以是不同的对象，例如在 XML 元素的名称发生更改时。

抛出：

JAXBException - 如果更新相应的 JAXB 映射内容时出现任何不可预料的问题。

IllegalArgumentException - 如果节点参数为 null

setSchema

public abstract void setSchema(Schema schema)

指定 marshal、unmarshal 和 update 方法是否在其 XML 内容上执行验证。

参数：

schema - 可将此参数设置为 null 来禁用验证。

另请参见：

Unmarshaller.setSchema(Schema)

getSchema

public abstract Schema getSchema()

获取 setSchema(Schema) 方法设置的最后一个 Schema 对象（包括 null）。

返回：

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

setEventHandler

public abstract void setEventHandler(ValidationEventHandler handler)
                              throws JAXBException

允许应用程序注册 ValidationEventHandler。

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

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

参数：

handler - 验证事件处理程序

抛出：

JAXBException - 如果在设置事件处理程序时发生错误

getEventHandler

public abstract ValidationEventHandler getEventHandler()
                                                throws JAXBException

当前的事件处理程序；如果没有设置，则返回默认事件处理程序。

返回：

当前的 ValidationEventHandler；如果没有设置，则返回默认的事件处理程序

抛出：

JAXBException - 如果获取当前的事件处理程序时发生错误

setProperty

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

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

参数：

name - 要设置的属性的名称。此值可以使用一个常量字段来指定，也可以是一个用户提供的字符串。

value - 要设置的属性值

抛出：

PropertyException - 如果处理给定属性或值时发生错误

IllegalArgumentException - 如果 name 参数为 null

getProperty

public abstract Object getProperty(String name)
                            throws PropertyException

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

参数：

name - 将检索的属性名称

返回：

所请求属性的值

抛出：

PropertyException - 如果检索给定属性或值属性名称时发生错误

IllegalArgumentException - 如果 name 参数为 null