Binder (Java Platform SE 8 )

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更新方法（ updateXML(Object, Object)或updateJAXB(Object)）将修改后的视图中所做的更改同步到其他视图。

典型的使用场景如下：
- 将XML文档加载到XML信息集表示中
- unmarshal(Object)到JAXB视图的XML信息集视图。（注意节省资源，只能将XML信息集视图的子树解组到JAXB视图。）
- 应用程序访问/更新XML文档的JAXB视图。
- updateXML(Object)将JAXB视图的修改同步到XML信息集视图中。更新操作保留尽可能多的原始XML信息集（即注释，PI，...）
Binder实例使用工厂方法JAXBContext.createBinder()或JAXBContext.createBinder(Class)创建。

模板参数XmlNode是XML信息集维护表示的根接口/类。需要一个Binder实现来最低限度地支持XmlNode值org.w3c.dom.Node.class 。 Binder实现可以支持替代的XML信息集保留表示。
从以下版本开始：

JAXB 2.0

构造方法摘要

构造方法
Constructor and Description
`Binder()`

方法摘要

所有方法接口方法抽象方法
Modifier and Type	Method and Description
`abstract ValidationEventHandler`	`getEventHandler()` 返回当前事件处理程序或默认事件处理程序（如果尚未设置）。
`abstract Object`	`getJAXBNode(XmlNode xmlNode)` 获取与给定XML元素关联的JAXB对象。
`abstract Object`	`getProperty(String name)` 获取基础实现中的特定属性 `Binder` 。
`abstract Schema`	`getSchema()` 获取由`setSchema(Schema)`方法设置的最后`Schema`对象（包括null）。
`abstract XmlNode`	`getXMLNode(Object jaxbObject)` 获取与给定JAXB对象关联的XML元素。
`abstract void`	`marshal(Object jaxbObject, XmlNode xmlNode)` 将JAXB对象树编组到新的XML文档。
`abstract void`	`setEventHandler(ValidationEventHandler handler)` 允许申请注册一个 `ValidationEventHandler` 。
`abstract void`	`setProperty(String name, Object value)` 在底层实现中设置特定的属性 `Binder` 。
`abstract void`	`setSchema(Schema schema)` 指定marshal，unmarshal和update方法是否对其XML内容执行验证。
`abstract Object`	`unmarshal(XmlNode xmlNode)` 将XML信息集视图解组到JAXB对象树。
`abstract <T> JAXBElement<T>`	`unmarshal(XmlNode xmlNode, 类<T> declaredType)` 通过向JAXB对象树提供 `declaredType`解组XML根元素。
`abstract Object`	`updateJAXB(XmlNode xmlNode)` 获取一个XML节点并更新其关联的JAXB对象及其后代。
`abstract XmlNode`	`updateXML(Object jaxbObject)` 获取JAXB对象并更新其关联的XML节点及其后代。
`abstract XmlNode`	`updateXML(Object jaxbObject, XmlNode xmlNode)` 在其关联的XML解析树中更新JAXB对象树中的更改。

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- 构造方法详细信息
  - Binder
```
public Binder()
```
- 方法详细信息
  - unmarshal
```
public abstract Object unmarshal(XmlNode xmlNode)
                          throws JAXBException
```
    将XML信息集视图解组到JAXB对象树。
    该方法类似于Unmarshaller.unmarshal(Node) ，其中添加了维护XML节点和生成的JAXB对象之间的关联，从而实现将来的更新操作， updateXML(Object, Object)或updateJAXB(Object) 。
    
    当getSchema()为非空时， xmlNode及其后代在此操作期间被验证。
    
    此方法抛出UnmarshalException当粘合剂的JAXBContext不具有XML元素名称或类型到JAXB映射类的映射，经由@xsi:type可指定的xmlNode。 方法unmarshal(Object, Class)使应用程序能够指定xmlNode应映射到的JAXB映射类。
    
    参数
    
    xmlNode - 从中解开XML数据的文件/元素。
    
    结果
    
    新创建的JAXB对象树的根对象。
    
    异常
    
    JAXBException - 解组时是否发生意外错误
    
    UnmarshalException - 如果ValidationEventHandler从其handleEvent方法返回false，或者Binder无法执行XML到Java绑定。
    
    IllegalArgumentException - 如果节点参数为空
  - unmarshal
```
public abstract <T> JAXBElement<T> unmarshal(XmlNode xmlNode,
                                             类<T> declaredType)
                                      throws JAXBException
```
    通过向JAXB对象树提供declaredType解组XML根元素。
    实现Unmarshal by Declared Type
    
    该方法类似于Unmarshaller.unmarshal(Node, Class) ，其中添加了维护XML节点和生成的JAXB对象之间的关联，从而实现将来的更新操作， updateXML(Object, Object)或updateJAXB(Object) 。
    
    当getSchema()为非空时， xmlNode及其后代在此操作期间被验证。
    
    参数
    
    xmlNode - 从中解开XML数据的文档/元素。
    
    declaredType - 适当的JAXB映射类保存 node的XML数据。
    
    结果
    
    JAXB Element表示 node
    
    异常
    
    JAXBException - 解组时是否发生意外错误
    
    UnmarshalException - 如果ValidationEventHandler从其handleEvent方法返回false，或Binder无法执行XML到Java绑定。
    
    IllegalArgumentException - 如果任何输入参数为空
    
    从以下版本开始：
    
    JAXB2.0
  - marshal
```
public abstract void marshal(Object jaxbObject,
                             XmlNode xmlNode)
                      throws JAXBException
```
    将JAXB对象树编组到新的XML文档。
    此方法类似于Marshaller.marshal(Object, Node) ，增加了维护JAXB对象和生成的XML节点之间的关联，从而实现了未来的更新操作，例如updateXML(Object, Object)或updateJAXB(Object) 。
    
    当getSchema()为非空值时，在此操作期间验证已编组的xml内容。
    
    参数
    
    jaxbObject - 要编组的内容树。
    
    xmlNode - 参数必须是接受子节点的节点。
    
    异常
    
    JAXBException - 如果在编组过程中发生意外问题。
    
    MarshalException - 如果ValidationEventHandler从其handleEvent方法返回false，或者Binder无法组织jaxbObject （或任何可从jaxbObject可访问的对象）。
    
    IllegalArgumentException - 如果任何方法参数为空
  - getXMLNode
```
public abstract XmlNode getXMLNode(Object jaxbObject)
```
    获取与给定JAXB对象关联的XML元素。
    一旦JAXB对象树与XML片段相关联，该方法就可以在两个树之间进行导航。
    
    通过绑定方法和更新方法建立XML元素和JAXB对象之间的关联。请注意，此关联是部分的; 并不是所有的XML元素都具有关联的JAXB对象，并不是所有的JAXB对象都具有关联的XML元素。
    
    参数
    
    jaxbObject - 从先前调用返回JAXB对象树的绑定或更新方法可访问的实例。
    
    结果
    
    如果指定的JAXB对象不知道此Binder ，或者如果它不与XML元素相关联，则为null。
    
    异常
    
    IllegalArgumentException - 如果jaxbObject参数为空
  - 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 - 如果节点参数为空
  - updateXML
```
public abstract XmlNode updateXML(Object jaxbObject)
                           throws JAXBException
```
    获取JAXB对象并更新其关联的XML节点及其后代。
    这是一种方便的方法：
```
  updateXML( jaxbObject, getXMLNode(jaxbObject)); 
```
    异常
    
    JAXBException - 如果任何意外的问题发生更新对应的XML内容。
    
    IllegalArgumentException - 如果jaxbObject参数为空
  - updateXML
```
public abstract XmlNode updateXML(Object jaxbObject,
                                  XmlNode xmlNode)
                           throws JAXBException
```
    在其关联的XML解析树中更新JAXB对象树中的更改。
    这个操作可以被认为是一个“就地”编组。不同的是，这个操作不是创建一个全新的XML树，而是更新一个现有的树，同时尽可能地保留XML。
    
    例如，未绑定到JAXB的XML中的未知元素/属性将保持不变（而编组操作将创建不包含任何这些的新树）。
    
    作为副作用，此操作更新XML节点和JAXB对象之间的关联。
    
    参数
    
    jaxbObject - 潜在修改的JAXB对象树的根
    
    xmlNode - 更新目标XML解析树的根
    
    结果
    
    返回更新的XML节点。通常，这是与xmlNode一样传递的节点，但它可能是一个不同的对象，例如当对象的标签名称已更改时。
    
    异常
    
    JAXBException - 如果任何意外的问题发生更新对应的XML内容。
    
    IllegalArgumentException - 如果任何输入参数为空
  - 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 - 如果节点参数为空
  - 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 。
    ValidationEventHandler将由JAXB提供程序调用，如果在调用任何Binder拆组，组织和更新方法时遇到任何验证错误。
    
    使用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。参见Supported Unmarshal Properties和Supported Marshal Properties 。
    
    参数
    
    name - 要设置的属性的名称。可以使用常量字段或用户提供的字符串指定此值。
    
    value - 要设置的属性的值
    
    异常
    
    PropertyException - 处理给定属性或值时出错
    
    IllegalArgumentException - 如果name参数为null
  - getProperty
```
public abstract Object getProperty(String name)
                            throws PropertyException
```
    获取Binder基础实现中的特定属性 。此方法只能用于获取标准JAXB定义的解组/元数据属性之一或粘合剂，解组或元组的提供者特定属性。尝试获取未定义的属性将导致抛出PropertyException。参见Supported Unmarshal Properties和Supported Marshal Properties 。
    
    参数
    
    name - 要检索的属性的名称
    
    结果
    
    请求的属性的值
    
    异常
    
    PropertyException - 检索给定属性或值属性名称时出现错误
    
    IllegalArgumentException - 如果name参数为null

Class Binder<XmlNode>

构造方法摘要

方法摘要

Methods inherited from class java.lang.Object

构造方法详细信息

Binder

方法详细信息

unmarshal

unmarshal

marshal

getXMLNode

getJAXBNode

updateXML

updateXML

updateJAXB

setSchema

getSchema

setEventHandler

getEventHandler

setProperty

getProperty