Module  java.xml.bind
软件包  javax.xml.bind

Class 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信息集维护表示的根接口/类。 要求最小化支持XmlNode值为org.w3c.dom.Node.class Binder实现。 Binder实现可以支持替代的XML信息集保留表示。

    从以下版本开始：
    1.6，JAXB 2.0

    • 构造方法详细信息

      • Binder

        public Binder​()

    • 方法详细信息

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

        如果在任何Binder拆组，组织和更新方法的调用期间遇到任何验证错误，则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。 参见Supported Unmarshal Properties和Supported Marshal Properties 。
        参数
        name - 要设置的属性的名称。 可以使用常数字段或用户提供的字符串指定此值。
        value - 要设置的属性的值
        异常
        PropertyException - 处理给定属性或值时出错
        IllegalArgumentException - 如果name参数为空