javax.xml.bind
類別 JAXBContext
java.lang.Object
javax.xml.bind.JAXBContext
public abstract class JAXBContext
- extends Object
JAXBContext 類別提供到 JAXB API 的客戶端入口點。它提供了管理實作 JAXB 綁定框架操作所需的 XML/Java 綁定資訊的抽象，這些操作包括：解組、編組和驗證。
客戶端應用程序通常使用以下兩種樣式的 newInstance 方法之一來獲得此類別的新實例，但是該方法還有其他可用的特殊形式：
特別要求：該提供者必須提供包含以下方法簽章的實作類別：
public static JAXBContext createContext( String contextPath, ClassLoader classLoader, Map properties ) throws JAXBException
public static JAXBContext createContext( Class[] classes, Map properties ) throws JAXBException
以下 JAXB 1.0 要求只是 java 介面/實作綁定的網要所需要的。它不適用於 JAXB 註釋類別。JAXB 提供者必須在每個包含網要派生類別的套件中產生一個 jaxb.properties 檔案。該屬性檔案必須包含名為 javax.xml.bind.context.factory 的屬性，其值為實作 createContext API 的類別的名稱。
該提供者提供的類別不一定是可分派給 javax.xml.bind.JAXBContext 的，只是必須提供一個實作 createContext API 的類別。
此外，提供者必須在執行 marshal 和 unmarshal 方法的任何客戶端調用之前調用 DatatypeConverter.setDatatypeConverter api。這在配置將在執行這些操作期間使用的資料型別轉換器時是必需的。
解組
Unmarshaller 類別使客戶端應用程序能夠將 XML 資料轉換為 Java 內容物件階層樹。unmarshal 方法允許將網要中宣告的任何全體 XML 元素解組為實例文檔的根。此外，unmarshal 方法允許將未被識別的根元素（該元素具有一個參考了網要中宣告的型別定義的 xsi:type 屬性值）解組為實例文檔的根。JAXBContext 物件允許跨網要集合（已在 contextPath 中列出）合併全體元素和型別定義。因為網要集合中的每個網要可能屬於不同的名稱空間，所以統一解組上下文的網要應該與名稱空間無關。這意味著客戶端應用程序能夠解組 contextPath 中列出的任何網要實例的 XML 文檔。例如：
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
Unmarshaller u = jc.createUnmarshaller();
FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok
BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok
BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath
客戶端應用程序還可以顯式產生 Java 內容階層樹，而不是解組現有的 XML 資料。對於所有 JAXB 註釋值類別，應用程序可以使用建構子來創建內容。對於網要派生的介面/實作類別以及未綁定到 JAXB 註釋類別的元素的創建，應用程序需要存取和瞭解每個網要派生的 ObjectFactory 類別，這些類別存在於 contextPath 中包含的每個 java 套件中。對於每個網要派生的 java 類別，都有一個產生該型別的物件的靜態處理器方法。例如，假定在編譯網要之後有一個套件 com.acme.foo，它包含一個名為 PurchaseOrder 的網要派生介面。為了創建該型別的物件，客戶端應用程序將使用如下處理器方法：
com.acme.foo.PurchaseOrder po =
com.acme.foo.ObjectFactory.createPurchaseOrder();
一旦客戶端應用程序有一個網要派生物件的實例，它就可以使用 mutator 方法在該實例上設置內容。
有關產生的 ObjectFactory 類別的更多資訊，請參閱該規範的第 4.2 節「Java 套件」。
特別要求：在包含名為 ObjectFactory 的套件所需的所有物件處理器方法以及靜態 newInstance( javaContentInterface ) 方法的每個包中，該提供者都必須產生一個類別。
編組
Marshaller 類別使客戶端應用程序能夠將 Java 內容階層樹轉換回 XML 資料。對使用處理器方法手動創建的內容階層樹進行編組與對作為 unmarshal 操作結果的內容階層樹進行編組沒有什麼區別。客戶端可以將 java 內容階層樹編組回 java.io.OutputStream 或 java.io.Writer 的 XML 資料。編組進程可以產生已註冊 ContentHandler 的 SAX2 事件串流，也可以產生一個 DOM 節點物件。客戶端應用程序控制著輸出編碼，還控制著是將 XML 資料編組為一個完整的文檔還是編組為一個片段。
下面是一個解組 XML 文檔、然後將其編組回來的簡單範例：
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
// unmarshal from foo.xml
Unmarshaller u = jc.createUnmarshaller();
FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) );
// marshal to System.out
Marshaller m = jc.createMarshaller();
m.marshal( fooObj, System.out );
驗證
自 JAXB 1.0 以後，驗證已經發生了很大的變化。Validator 類別已經廢棄，成為了一個可選項。這意味著建議您不要使用此類別，實際上，根據您的 JAXB 提供者，該類別甚至根本不可用。在 JAXB 1.0 運行時系統上進行部署時，依賴 Validator 的 JAXB 1.0 客戶端仍然可以正常工作。在 JAXB 2.0 中，Unmarshaller 已包括一些公開 JAXP 1.3 javax.xml.validation 框架的便捷方法。有關詳細資訊，請參閱 Unmarshaller.setSchema(javax.xml.validation.Schema) API。
JAXB 運行時綁定框架的相容性
以下 JAXB 1.0 限制僅適用於將網要綁定到介面/實作類別。因為此綁定不需要通用的運行時系統，所以 JAXB 客戶端應用程序不必嘗試混合使用不同的提供者提供的運行時物件（JAXBContext、Marshaller 等）。這並不意味著客戶端應用程序是不可移植的，只是意味著客戶端必須使用由用來編譯網要的同一提供者提供的運行時系統。
- 從以下版本開始：
- JAXB1.0
- 另請參見：
Marshaller,
Unmarshaller,
S 7.4.1.1 "Package Annotations" in Java Language Specification, 3rd Edition
| 從類別 java.lang.Object 繼承的方法 |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
JAXB_CONTEXT_FACTORY
public static final String JAXB_CONTEXT_FACTORY
- 屬性名稱，它包含能夠創建新的 JAXBContext 物件的類別名稱。
- 另請參見：
- 常數欄位值
JAXBContext
protected JAXBContext()
newInstance
public static JAXBContext newInstance(String contextPath)
throws JAXBException
獲得 JAXBContext 類別的新實例。
這是 newInstance 方法的一個便捷方法。它使用當前執行緒的上下文類別載入器。要指定如何使用不同的類別載入器，可以通過 Thread.setContextClassLoader() api 設置它，或者使用 newInstance 方法。
- 拋出：
JAXBException - 如果在創建 JAXBContext 時遇到錯誤，比如：
- 在包中尋找 ObjectFactory.class 或 jaxb.index 失敗
- 包含在 contextPath 中的全體元素之間出現混淆
- 尋找上下文處理器提供者屬性的值失敗
- 混合使用相同 contextPath 上的不同提供者的網要派生包
newInstance
public static JAXBContext newInstance(String contextPath,
ClassLoader classLoader)
throws JAXBException
獲得 JAXBContext 類別的新實例。
客戶端應用程序必須提供上下文路徑，該路徑是一個冒號 (':', \u003A) 分隔的 java 套件名稱列表，它包含網要派生類別和/或完全限定的 JAXB 註釋類別。網要派生的程式碼是通過為每個包產生的 ObjectFactory.class 在 JAXBContext 中註冊的。開發人員註釋的 JAXB 映射類別在 jaxb.index 資源檔案中列出，而不是在上下文路徑中列出，列出這些類別所採用的格式如下所述。注意，java 套件可以包含網要派生類別和使用者註釋 JAXB 類別。此外，java 套件可能包含必須處理的 JAXB 套件註釋。（請參閱 JLS 第 3 版的第 7.4.1 節“包註釋”）。
每個 contextPath 上列出的套件都必須滿足下面的一個或兩個條件，否則將拋出 JAXBException：
- 必須包含 ObjectFactory.class
- 必須包含 jaxb.index
jaxb.index 的格式
該檔案應該套件含換行符分隔的類別名稱列表。空格、製表符和空行被忽略。註釋字元是 '#' (0x23)；每行上的第一個註釋字元後面的所有字元都被忽略。檔案必須使用 UTF-8 編碼。從列出的類別中獲得的類別也可以在 JAXBContext 中註冊，正如 newInstance(Class...) 定義的那樣。
對 jaxb.index 檔案中出現的類別名稱的限制是：
- 不一定以 ".class" 結尾。
- 類別名稱與包含 jaxb.index 檔案的套件相關。只允許使用直接出現在包含 jaxb.index 檔案的套件中的類別。
- 不允許使用完全限定的類別名稱。只允許與當前包相關的限定類別名稱指定一個巢狀類別或內部類別。
為了維護與將 JAXB 1.0 網要綁定到 java 介面/實作的相容（可通過將網要自定義為 jaxb:globalBindings valueClass="false" 來啟用此綁定）, JAXB 提供者需要確保上下文路徑上的每個包都有一個 jaxb.properties 檔案，該檔案包含一個 javax.xml.bind.context.factory 屬性值，以及解析為相同提供者的所有值。
此要求不適用於 JAXB 註釋類別。如果 contextPath 上列出的各種包之間存在任何全體 XML 元素名稱衝突，則將拋出 JAXBException。
在相同的上下文路徑中混合使用從多個 JAXB 提供者中產生的介面/實作綁定可能導致拋出 JAXBException。
- 參數：
contextPath - 套件含網要派生類別和/或 java 網要（JAXB 註釋）映射類別的 java 套件名稱的列表classLoader - 此類別載入器將用於定位實作類別。
- 返回：
- 新的 JAXBContext 實例
- 拋出：
JAXBException - 如果創建 JAXBContext 時遇到錯誤，如下所示：
- 在包中尋找 ObjectFactory.class 或 jaxb.index 失敗
- 包含在 contextPath 中的全體元素之間出現混淆
- 尋找上下文處理器提供者屬性的值失敗
- 混合使用相同 contextPath 上的不同提供者的網要派生包
newInstance
public static JAXBContext newInstance(String contextPath,
ClassLoader classLoader,
Map<String,?> properties)
throws JAXBException
獲得 JAXBContext 類別的新實例。
多數情況下，這與 newInstance(String, ClassLoader) 相同，但此版本允許傳入特定於提供者的屬性來配置 JAXBContext 的實例。
屬性的解釋取決於實作。
- 參數：
contextPath - 套件含網要派生類別的 java 套件名稱的列表classLoader - 此類別載入器將用於定位實作類別。properties - 特定於提供者的屬性
- 返回：
- 新的 JAXBContext 實例
- 拋出：
JAXBException - 如果創建 JAXBContext 時遇到錯誤，如下所示：
- 在包中尋找 ObjectFactory.class 或 jaxb.index 失敗
- 包含在 contextPath 中的全體元素之間出現混淆
- 尋找上下文處理器提供者屬性的值失敗
- 混合使用相同 contextPath 上的不同提供者的網要派生包
- 從以下版本開始：
- JAXB 2.0
newInstance
public static JAXBContext newInstance(Class... classesToBeBound)
throws JAXBException
獲得 JAXBContext 類別的新實例。
客戶端應用程序必須提供新上下文物件需要識別的類別的列表。
新的上下文不僅要識別所有指定的類別，還要識別直接/間接從指定類別中靜態參考的全部類別。所參考類別的子類別或 @XmlTransient 參考類別都不用在 JAXBContext 中註冊。例如，在下面的 Java 程式碼中，如果執行 newInstance(Foo.class)，則新創建的 JAXBContext 將識別 Foo 和 Bar，但不識別 Zot 或 FooBar：
class Foo {
@XmlTransient FooBar c;
Bar b;
}
class Bar { int x; }
class Zot extends Bar { int y; }
class FooBar { }
因此，典型的客戶端應用程序只需指定最高層類別，但需要小心。
注意，對於每個在 JAXBContext 中註冊的 java 套件，當存在可選的套件註釋時，必須對它們進行處理。（請參閱 JLS 第 3 版的第 7.4.1 節“包註釋”）。
- 參數：
classesToBeBound - 將通過新的 JAXBContext 識別的 java 類別的列表。可以為空，在這種情況下，將返回只知道規範中定義的類別的 JAXBContext。
- 返回：
- 新的 JAXBContext 實例。該實例始終是一個非 null 的有效物件。
- 拋出：
JAXBException - 如果創建 JAXBContext 時遇到錯誤（但不限於這些錯誤），如下所示：
- 未發現任何 JAXB 實作
- 類別以不正確的方式使用了 JAXB 註釋
- 類別包含有衝突的註釋（比如有相同型別名稱的兩個類別）
- JAXB 實作不能尋找特定於提供者的帶外資訊（例如在開發時產生的附加檔案）。
IllegalArgumentException - 如果參數中包含 null（即 newInstance(null);）- 從以下版本開始：
- JAXB 2.0
newInstance
public static JAXBContext newInstance(Class[] classesToBeBound,
Map<String,?> properties)
throws JAXBException
獲得 JAXBContext 類別的新實例。
可重載 newInstance(Class...) 來配置「屬性」，以實例化 JAXBContext。
屬性的解釋是特定於實作的。
- 參數：
classesToBeBound - 將通過新 JAXBContext 識別的 java 類別的列表。可以為空，在這種情況下，將返回只知道規範中定義的類別的 JAXBContext。
- 返回：
- 新的 JAXBContext 實例。該實例始終是一個非 null 的有效物件。
- 拋出：
JAXBException - 如果創建 JAXBContext 時遇到錯誤（但不限於這些錯誤），比如：
- 未發現任何 JAXB 實作
- 類別以不正確的方式使用了 JAXB 註釋
- 類別包含有衝突的註釋（比如有相同型別名稱的兩個類別）
- JAXB 實作不能尋找特定於提供者的帶外資訊（例如在開發時產生的附加檔案）。
IllegalArgumentException - 如果參數中包含 null（即 newInstance(null);）- 從以下版本開始：
- JAXB 2.0
createUnmarshaller
public abstract Unmarshaller createUnmarshaller()
throws JAXBException
- 創建一個可以用來將 XML 資料轉換為 java 內容階層樹的 Unmarshaller 物件。
- 返回：
- Unmarshaller 物件
- 拋出：
JAXBException - 如果創建 Unmarshaller 物件時遇到錯誤
createMarshaller
public abstract Marshaller createMarshaller()
throws JAXBException
- 創建一個可以用來將 java 內容階層樹轉換為 XML 資料的 Marshaller 物件。
- 返回：
- Marshaller 物件
- 拋出：
JAXBException - 如果創建 Marshaller 物件時遇到錯誤
createValidator
public abstract Validator createValidator()
throws JAXBException
- 已過時。 從 JAXB 2.0 開始
Validator 已成為一個可選項，並且在 JAXB 2.0 中已過時。有關詳細資訊，請參閱 Validator 的 javadoc。
創建一個可用於根據源網要驗證 java 內容階層樹的 Validator 物件。
- 返回：
- 一個 Validator 物件
- 拋出：
JAXBException - 如果創建 Validator 物件時遇到錯誤
createBinder
public <T> Binder<T> createBinder(Class<T> domType)
- 創建一個可用於關聯/原地解組/編組操作的 Binder 物件。
- 參數：
domType - 選擇通過傳入其 DOM 節點類別獲得使用的 DOM API。
- 返回：
- 總是返回新的有效 Binder 物件。
- 拋出：
UnsupportedOperationException - 如果該實作不支持對應於 domType 的 DOM API。- 從以下版本開始：
- JAXB 2.0
createBinder
public Binder<Node> createBinder()
- 為 W3C DOM 創建一個 Binder。
- 返回：
- 總是返回新的有效 Binder 物件。
- 從以下版本開始：
- JAXB 2.0
createJAXBIntrospector
public JAXBIntrospector createJAXBIntrospector()
- 創建一個可以用於內省 JAXB 物件的 JAXBIntrospector 物件。
- 返回：
- 總是返回非 null 的有效 JAXBIntrospector 物件。
- 拋出：
UnsupportedOperationException - 在 JAXB 1.0 實作上調用此方法將拋出 UnsupportedOperationException。- 從以下版本開始：
- JAXB 2.0
generateSchema
public void generateSchema(SchemaOutputResolver outputResolver)
throws IOException
- 產生此上下文的網要文檔。
- 參數：
outputResolver - 此物件控制網要將被發送的輸出。
- 拋出：
IOException - 如果 SchemaOutputResolver 拋出 IOException。
UnsupportedOperationException - 在 JAXB 1.0 實作上調用此方法將拋出 UnsupportedOperationException。- 從以下版本開始：
- JAXB 2.0
提交錯誤或意見版權所有 2008 Sun Microsystems, Inc. 保留所有權利。請遵守GNU General Public License, version 2 only。