概觀  軟體套件   類別  使用  階層樹  已過時  索引  說明 
JavaTM 2 Platform
Standard Ed. 6
 上一個類別   下一個類別 框架    無框架    
摘要： 巢狀 | 欄位 | 建構子 | 方法 詳細資訊： 欄位 | 建構子 | 方法

javax.xml.bind
類別 Binder<XmlNode>

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)）將在修改視圖中所做的更改同步到其他視圖中。

下面是一個典型的使用場景：

Binder 實例是使用處理器方法 JAXBContext.createBinder() 或 JAXBContext.createBinder(Class) 創建的。

模板參數 XmlNode 是保留表示形式的 XML 資訊集的根介面/類別。Binder 實作至少需要支持 org.w3c.dom.Node.class 的一個 XmlNode 值。Binder 實作可以支持保留表示形式的備用 XML 資訊集。

從以下版本開始：
JAXB 2.0

建構子摘要
Binder()
           
 
方法摘要
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, Class<T> declaredType)
          根據提供的 declaredType 將 XML 根元素解組為 JAXB 物件階層樹。
abstract  Object updateJAXB(XmlNode xmlNode)
          取一個 XML 節點，並更新與其關聯的 JAXB 物件和該物件的子級。
abstract  XmlNode updateXML(Object jaxbObject)
          取一個 JAXB 物件，並更新與其關聯的 XML 節點和該節點的子級。
abstract  XmlNode updateXML(Object jaxbObject, XmlNode xmlNode)
          JAXB 物件階層樹中所做的更改在與其關聯的 XML 解析階層樹中得到更新。
 
從類別 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 物件階層樹。

此方法類似於添加了維持 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
概觀  軟體套件   類別  使用  階層樹  已過時  索引  說明 
JavaTM 2 Platform
Standard Ed. 6
 上一個類別   下一個類別 框架    無框架    
摘要： 巢狀 | 欄位 | 建構子 | 方法 詳細資訊： 欄位 | 建構子 | 方法
提交錯誤或意見

版權所有 2008 Sun Microsystems, Inc. 保留所有權利。請遵守GNU General Public License, version 2 only。