|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
| 上一個類別 下一個類別 | 框架 無框架 | |||||||||
| 摘要： 巢狀 | 欄位 | 建構子 | 方法 | 詳細資訊： 欄位 | 建構子 | 方法 | |||||||||
public interface Unmarshaller
Unmarshaller 類別管理將 XML 資料反序列化為新創建的 Java 內容階層樹的過程，並可在解組時有選擇地驗證 XML 資料。它針對各種不同的輸入種類別提供各種重載的 unmarshal 方法。
從 File 解組：
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
Unmarshaller u = jc.createUnmarshaller();
Object o = u.unmarshal( new File( "nosferatu.xml" ) );
從 InputStream 解組：
InputStream is = new FileInputStream( "nosferatu.xml" );
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
Unmarshaller u = jc.createUnmarshaller();
Object o = u.unmarshal( is );
從 URL 解組：
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
Unmarshaller u = jc.createUnmarshaller();
URL url = new URL( "http://beaker.east/nosferatu.xml" );
Object o = u.unmarshal( url );
使用 javax.xml.transform.stream.StreamSource 從 StringBuffer 解組：
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
Unmarshaller u = jc.createUnmarshaller();
StringBuffer xmlStr = new StringBuffer( "<?xml version="1.0"?>..." );
Object o = u.unmarshal( new StreamSource( new StringReader( xmlStr.toString() ) ) );
從 org.w3c.dom.Node 解組：
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
Unmarshaller u = jc.createUnmarshaller();
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
DocumentBuilder db = dbf.newDocumentBuilder();
Document doc = db.parse(new File( "nosferatu.xml"));
Object o = u.unmarshal( doc );
使用客戶端指定的驗證 SAX2.0 解析器從 javax.xml.transform.sax.SAXSource 解組：
// configure a validating SAX2.0 parser (Xerces2)
static final String JAXP_SCHEMA_LANGUAGE =
"http://java.sun.com/xml/jaxp/properties/schemaLanguage";
static final String JAXP_SCHEMA_LOCATION =
"http://java.sun.com/xml/jaxp/properties/schemaSource";
static final String W3C_XML_SCHEMA =
"http://www.w3.org/2001/XMLSchema";
System.setProperty( "javax.xml.parsers.SAXParserFactory",
"org.apache.xerces.jaxp.SAXParserFactoryImpl" );
SAXParserFactory spf = SAXParserFactory.newInstance();
spf.setNamespaceAware(true);
spf.setValidating(true);
SAXParser saxParser = spf.newSAXParser();
try {
saxParser.setProperty(JAXP_SCHEMA_LANGUAGE, W3C_XML_SCHEMA);
saxParser.setProperty(JAXP_SCHEMA_LOCATION, "http://....");
} catch (SAXNotRecognizedException x) {
// exception handling omitted
}
XMLReader xmlReader = saxParser.getXMLReader();
SAXSource source =
new SAXSource( xmlReader, new InputSource( "http://..." ) );
// Setup JAXB to unmarshal
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
Unmarshaller u = jc.createUnmarshaller();
ValidationEventCollector vec = new ValidationEventCollector();
u.setEventHandler( vec );
// turn off the JAXB provider's default validation mechanism to
// avoid duplicate validation
u.setValidating( false )
// unmarshal
Object o = u.unmarshal( source );
// check for events
if( vec.hasEvents() ) {
// iterate over events
}
從 StAX XMLStreamReader 解組：
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
Unmarshaller u = jc.createUnmarshaller();
javax.xml.stream.XMLStreamReader xmlStreamReader =
javax.xml.stream.XMLInputFactory().newInstance().createXMLStreamReader( ... );
Object o = u.unmarshal( xmlStreamReader );
從 StAX XMLEventReader 解組：
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
Unmarshaller u = jc.createUnmarshaller();
javax.xml.stream.XMLEventReader xmlEventReader =
javax.xml.stream.XMLInputFactory().newInstance().createXMLEventReader( ... );
Object o = u.unmarshal( xmlEventReader );
解組可以反序列化表示整個 XML 文檔或 XML 文檔子階層樹的 XML 資料。通常，使用解組全體宣告的根元素所描述的 unmarshal 方法便已足夠。通過利用全體元素宣告和型別定義到 JAXB 映射類別的JAXBContext映射，這些 unmarshal 方法可以啟動對 XML 資料的根元素的解組。當JAXBContext映射不足以解組 XML 資料的根元素時，應用程序可以使用借助 declaredType 進行解組的方法說明解組過程。在 XML 資料的根元素對應於網要中的本地元素宣告的情況下，這些方法對於解組很有用。
unmarshal 方法從不返回 null。如果解組過程無法將 XML 內容的根解組到 JAXB 映射物件，則將報告一個致命錯誤，通過拋出 JAXBException 終止處理過程。
不帶 declaredType 參數的 unmarshal 方法使用JAXBContext來解組 XML 資料的根元素。JAXBContext實例是用來創建此 Unmarshaller 的實例。JAXBContext實例維護全體宣告的 XML 元素和型別定義名稱到 JAXB 映射類別的映射。該 unmarshal 方法檢查JAXBContext是否存在根元素的 XML 名稱和/或 @xsi:type 到 JAXB 映射類別的映射。如果存在這種映射，則使用適當的 JAXB 映射類別來解組 XML 資料。注意，當根元素名稱未知且根元素具有 @xsi:type 時，將使用該 JAXB 映射類別作為JAXBElement值來解組 XML 資料。當JAXBContext物件沒有根元素名稱的映射，也沒有其 @xsi:type（如果存在） 的映射時，那麼將通過拋出UnmarshalException立即中止解組操作。通過使用下一節描述的借助 declaredType 的 unmarshal 方法，可以解決這種異常現象。
帶declaredType參數的 unmarshal 方法使應用程序即使在根元素 XML 名稱的JAXBContext中不存在映射時，也能夠反序列化 XML 資料的根元素。該 unmarshaller 使用指定為 declaredType 參數的、應用程序提供的映射來解組根元素。注意，即使根元素的元素名稱是通過JAXBContext映射的，declaredType參數也會覆寫該映射，以便在使用這些 unmarshal 方法時反序列化根元素。此外，當 XML 資料的根元素具有 xsi:type 屬性，且該屬性的值參考一個通過JAXBContext映射到 JAXB 映射類別的型別定義時，根元素的 xsi:type 屬性將優先於 unmarshal 方法的 declaredType 參數。這些方法總是返回一個 JAXBElement<declaredType> 實例。下表顯示了如何設置返回 JAXBElement 實例的屬性。
通過宣告的型別進行解組所返回的 JAXBElement JAXBElement 屬性 值 名稱 xml 元素名稱值 declaredType 的實例declaredType unmarshal 方法的 declaredType參數作用域 null（實際作用域未知）
以下是通過 declaredType 進行解組的方法的一個範例。
借助 declaredType 從 org.w3c.dom.Node 解組：
Schema fragment for example
<xs:schema>
<xs:complexType name="FooType">...<\xs:complexType>
<!-- global element declaration "PurchaseOrder" -->
<xs:element name="PurchaseOrder">
<xs:complexType>
<xs:sequence>
<!-- local element declaration "foo" -->
<xs:element name="foo" type="FooType"/>
...
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
Unmarshaller u = jc.createUnmarshaller();
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
DocumentBuilder db = dbf.newDocumentBuilder();
Document doc = db.parse(new File( "nosferatu.xml"));
Element fooSubtree = ...; // traverse DOM till reach xml element foo, constrained by a
// local element declaration in schema.
// FooType is the JAXB mapping of the type of local element declaration foo.
JAXBElement<FooType> foo = u.unmarshal( fooSubtree, FooType.class);
支持相容 SAX2.0 的解析器
客戶端應用程序能夠選擇自己的相容 SAX2.0 的解析器。如果沒有選擇 SAX 解析器，則將使用 JAXB 提供者的預設解析器。儘管 JAXB 提供者的預設解析器不必是與 SAX2.0 相容的，但所有提供者必須允許客戶端應用程序指定它們自己的 SAX2.0 解析器。一些提供者可能要求客戶端應用程序在網要編譯時指定 SAX2.0 解析器。有關詳細資訊，請參閱 unmarshal(Source)。
驗證和格式良好性
客戶端應用程序可以通過 setSchema(javax.xml.validation.Schema) API 來啟用或禁用 JAXP 1.3 驗證機制。複雜的客戶端可以指定它們自己的相容 SAX 2.0 的解析器，並使用
unmarshal(Source)API 來繞開 JAXP 1.3 驗證機制。由於要解組的無效 XML 內容是在 JAXB 2.0 中定義的，這使 Unmarshaller 預設的驗證事件處理程序比在 JAXB 1.0 中更為寬鬆。當向
JAXBContext註冊由 JAXB 1.0 綁定解析器所產生的網要派生程式碼時，預設的解組驗證處理程序是DefaultValidationEventHandler，它將在遇到致命錯誤（或錯誤）之後終止編組操作。對於 JAXB 2.0 客戶端應用程序，不存在顯式定義的預設驗證處理程序，預設事件處理只在遇到致命錯誤時終止編組操作。
當前沒有任何需要 Unmarshaller 上的所有 JAXB 提供者都支持的屬性。但是，一些提供者可能支持它們自己的特定於提供者的屬性集。
Unmarshaller提供了兩種樣式的回調機制，這些機制允許在解組過程的關鍵點上進行特定於應用程序的處理。在「類別定義的」事件回調中，解組期間會觸發放置在 JAXB 映射類別中的特定於應用程序的程式碼。「外部偵聽器」允許用一個回調方法集中處理解組事件，而不是通過各種型別事件回調處理。「類別定義」的事件回調方法允許任何 JAXB 映射類別通過定義帶有以下方法簽章的方法指定自己的特定回調方法：
類別定義的回調方法應該在回調方法需要存取類別的非公共方法和/或欄位時使用。// This method is called immediately after the object is created and before the unmarshalling of this // object begins.The callback provides an opportunity to initialize JavaBean properties prior to unmarshalling. void beforeUnmarshal(Unmarshaller, Object parent); //This method is called after all the properties (except IDREF) are unmarshalled for this object, //but before this object is set to the parent object. void afterUnmarshal(Unmarshaller, Object parent);外部偵聽器回調機制允許
Unmarshaller.Listener實例使用setListener(Listener)註冊。外部偵聽器接收所有回調事件，從而允許用比逐個類別地定義回調方法更為集中的方式處理事件。外部偵聽器在解組過程將編組到 JAXB 元素或 JAXB 映射類別時接收事件。「類別定義的」事件回調方法和外部偵聽器事件回調方法相互獨立，可以對一個事件同時調用。兩種偵聽器回調方法都存在時，按照
Unmarshaller.Listener.beforeUnmarshal(Object, Object)和Unmarshaller.Listener.afterUnmarshal(Object, Object)中定義的順序對它們進行調用。拋出異常的事件回調方法會終止當前的解組過程。
JAXBContext,
Marshaller,
Validator| 巢狀類別摘要 | |
|---|---|
static class |
Unmarshaller.Listener
向 Unmarshaller 註冊此類別的一個實作的實例，以便外部偵聽解組事件。 |
| 方法摘要 | ||
|---|---|---|
|
getAdapter(Class<A> type)
獲取與指定型別關聯的適配器。 |
|
AttachmentUnmarshaller |
getAttachmentUnmarshaller()
|
|
ValidationEventHandler |
getEventHandler()
返回當前的事件處理程序，如果沒有設置事件處理程序，則返回預設的事件處理程序。 |
|
Unmarshaller.Listener |
getListener()
返回向此 Unmarshaller 註冊的 Unmarshaller.Listener。 |
|
Object |
getProperty(String name)
獲取 Unmarshaller 底層實作中的特定屬性。 |
|
Schema |
getSchema()
獲取用於執行解組時驗證的 JAXP 1.3 Schema 物件。 |
|
UnmarshallerHandler |
getUnmarshallerHandler()
獲取可用作 XML 管線中的元件的 unmarshaller 處理程序物件。 |
|
boolean |
isValidating()
已過時。 從 JAXB 2.0 開始，請參閱 getSchema() |
|
|
setAdapter(Class<A> type,
A adapter)
將已配置的 XmlAdapter 實例與此 unmarshaller 關聯。 |
|
void |
setAdapter(XmlAdapter adapter)
將已配置的 XmlAdapter 實例與此 unmarshaller 關聯。 |
|
void |
setAttachmentUnmarshaller(AttachmentUnmarshaller au)
將解析 cid（內容 id URI）的上下文與作為附件傳遞的二進制資料關聯。 |
|
void |
setEventHandler(ValidationEventHandler handler)
允許應用程序註冊 ValidationEventHandler。 |
|
void |
setListener(Unmarshaller.Listener listener)
向此 Unmarshaller 註冊解組事件回調 Unmarshaller.Listener。 |
|
void |
setProperty(String name,
Object value)
設置 Unmarshaller 底層實作中的特定屬性。 |
|
void |
setSchema(Schema schema)
指定應用作驗證後續解組操作依據的 JAXP 1.3 Schema 物件。 |
|
void |
setValidating(boolean validating)
已過時。 從 JAXB2.0 開始，請參閱 setSchema(javax.xml.validation.Schema) |
|
Object |
unmarshal(File f)
從指定的檔案解組 XML 資料並返回得到的內容階層樹。 |
|
Object |
unmarshal(InputSource source)
從指定的 SAX InputSource 解組 XML 資料並返回得到的內容階層樹。 |
|
Object |
unmarshal(InputStream is)
從指定的 InputStream 解組 XML 資料並返回得到的內容階層樹。 |
|
Object |
unmarshal(Node node)
從指定的 DOM 階層樹解組全體 XML 資料並返回得到的內容階層樹。 |
|
|
unmarshal(Node node,
Class<T> declaredType)
通過 JAXB 映射的 declaredType 解組 XML 資料並返回得到的內容階層樹。 |
|
Object |
unmarshal(Reader reader)
從指定的 Reader 解組 XML 資料並返回得到的內容階層樹。 |
|
Object |
unmarshal(Source source)
從指定的 XML Source 解組 XML 資料並返回得到的內容階層樹。 |
|
|
unmarshal(Source source,
Class<T> declaredType)
從 declaredType 指定的 XML Source 解組 XML 資料並返回得到的內容階層樹。 |
|
Object |
unmarshal(URL url)
從指定的 URL 解組 XML 資料並返回得到的內容階層樹。 |
|
Object |
unmarshal(XMLEventReader reader)
從指定的 pull 解析器解組 XML 資料並返回得到的內容階層樹。 |
|
|
unmarshal(XMLEventReader reader,
Class<T> declaredType)
將根元素解組到 JAXB 映射的 declaredType 並返回得到的內容階層樹。 |
|
Object |
unmarshal(XMLStreamReader reader)
從指定的 pull 解析器解組 XML 資料並返回得到的內容階層樹。 |
|
|
unmarshal(XMLStreamReader reader,
Class<T> declaredType)
將根元素解組到 JAXB 映射的 declaredType 並返回得到的內容階層樹。 |
|
| 方法詳細資訊 |
|---|
Object unmarshal(File f)
throws JAXBException
實作解組全體根元素。
f - 將從中解組 XML 資料的檔案
JAXBException - 如果在解組時發生不可預料的錯誤
UnmarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false 或著 Unmarshaller 不能執行 XML 到 Java 的綁定。請參閱解組 XML 資料
IllegalArgumentException - 如果 File 參數為 null
Object unmarshal(InputStream is)
throws JAXBException
實作解組全體根元素。
is - 將從中解組 XML 資料的 InputStream
JAXBException - 如果在解組時發生不可預料的錯誤
UnmarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false 或者 Unmarshaller 不能執行 XML 到 Java 的綁定。請參閱解組 XML 資料
IllegalArgumentException - 如果 InputStream 參數為 null
Object unmarshal(Reader reader)
throws JAXBException
實作解組全體根元素。
reader - 將從中解組 XML 資料的 Reader
JAXBException - 如果在解組時發生不可預料的錯誤
UnmarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false 或者 Unmarshaller 不能執行 XML 到 Java 的綁定。請參閱解組 XML 資料
IllegalArgumentException - 如果 InputStream 參數為 null
Object unmarshal(URL url)
throws JAXBException
實作解組全體根元素。
url - 將從中解組 XML 資料的 URL
JAXBException - 如果在解組時發生不可預料的錯誤
UnmarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false 或者 Unmarshaller 不能執行 XML 到 Java 的綁定。請參閱解組 XML 資料
IllegalArgumentException - 如果 URL 參數為 null
Object unmarshal(InputSource source)
throws JAXBException
實作解組全體根元素。
source - 將從中解組 XML 資料的輸入源
JAXBException - 如果在解組時發生不可預料的錯誤
UnmarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false 或者 Unmarshaller 不能執行 XML 到 Java 的綁定。請參閱解組 XML 資料
IllegalArgumentException - 如果 InputSource 參數為 null
Object unmarshal(Node node)
throws JAXBException
實作解組全體根元素。
node - 要從中解組 XML 資料的文檔/元素。調用者至少必須支持 Document 和 Element。
JAXBException - 如果在解組時發生不可預料的錯誤
UnmarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false 或者 Unmarshaller 不能執行 XML 到 Java 的綁定。請參閱解組 XML 資料
IllegalArgumentException - 如果 Node 參數為 nulunmarshal(org.w3c.dom.Node, Class)
<T> JAXBElement<T> unmarshal(Node node,
Class<T> declaredType)
throws JAXBException
實作借助宣告的型別進行解組。
node - 從中解組 XML 資料的文檔/元素。調用者至少必須支持 Document 和 Element。declaredType - 用來保存 node 的 XML 資料的適當 JAXB 映射類別。
JAXBException - 如果在解組時發生不可預料的錯誤
UnmarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false 或者 Unmarshaller 不能執行 XML 到 Java 的綁定。請參閱解組 XML 資料
IllegalArgumentException - 如果任何參數為 null
Object unmarshal(Source source)
throws JAXBException
實作解組全體根元素。
客戶端應用程序可以選擇不使用隨 JAXB 提供者一起提供的預設解析器機制。任何相容 SAX 2.0 的解析器都可以取代 JAXB 提供者的預設機制。要實作這一點，客戶端應用程序必須正確配置一個套件含 XMLReader 的 SAXSource，並且該 XMLReader 是由 SAX 2.0 解析器提供者實作的。如果 XMLReader 有一個向它註冊的 org.xml.sax.ErrorHandler，則將使用 JAXB 提供者替換它，以便通過 JAXB 的 ValidationEventHandler 機制報告驗證錯誤。如果 SAXSource 不包含 XMLReader，則將使用 JAXB 提供者的預設解析器機制。
也可以使用此解析器替換機制來替換 JAXB 提供者的解組時驗證引擎。客戶端應用程序必須正確配置其相容 SAX 2.0 的解析器來執行驗證（如上例所示）。解析器在解組操作期間遇到的任何 SAXParserExceptions 都將由 JAXB 提供者處理，並將其轉換為 JAXB ValidationEvent 物件，這些物件將通過已經向 Unmarshaller 註冊的 ValidationEventHandler 報告給客戶端。註： 在為了實作解組而指定一個替換驗證 SAX 2.0 解析器時，無需替換 JAXB 提供者使用的驗證引擎來執行按需應變的驗證。
客戶端應用程序指定將在解組期間使用的替換解析器機制的唯一方法是通過 unmarshal(SAXSource) API。所有其他形式的 unmarshal 方法（檔案、URL、Node 等等）將使用 JAXB 提供者的預設解析器和驗證器機制。
source - 將從中解組 XML 資料的 XML Source（提供者只需支持 SAXSource、DOMSource 和 StreamSource）
JAXBException - 如果在解組時發生不可預料的錯誤
UnmarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false 或者 Unmarshaller 不能執行 XML 到 Java 的綁定。請參閱解組 XML 資料
IllegalArgumentException - 如果 Source 參數為 nulunmarshal(javax.xml.transform.Source, Class)
<T> JAXBElement<T> unmarshal(Source source,
Class<T> declaredType)
throws JAXBException
實作借助宣告的型別進行解組。
請參閱 SAX 2.0 解析器的可插入性
source - 將從中解組 XML 資料的 XML Source（提供者只需支持 SAXSource、DOMSource 和 StreamSource）declaredType - 用來保存 source 的 xml 根元素的適當 JAXB 映射類別
JAXBException - 如果在解組時發生不可預料的錯誤
UnmarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false 或者 Unmarshaller 不能執行 XML 到 Java 的綁定。請參閱解組 XML 資料
IllegalArgumentException - 如果任何參數為 null
Object unmarshal(XMLStreamReader reader)
throws JAXBException
實作解組全體根元素。
此方法假定該解析器處於 START_DOCUMENT 或 START_ELEMENT 事件上。解組將從起始事件開始，到相應的終止事件結束。如果此方法成功返回，則 reader 將指向終止事件後面的標記。
reader - 要讀取的解析器。
JAXBException - 如果在解組時發生不可預料的錯誤
UnmarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false 或者 Unmarshaller 不能執行 XML 到 Java 的綁定。請參閱解組 XML 資料
IllegalArgumentException - 如果 reader 參數為 null
IllegalStateException - 如果 reader 沒有指向 START_DOCUMENT 或 START_ELEMENT 事件。unmarshal(javax.xml.stream.XMLStreamReader, Class)
<T> JAXBElement<T> unmarshal(XMLStreamReader reader,
Class<T> declaredType)
throws JAXBException
此方法實作借助 declaredType 進行解組。
此方法假定該解析器處於 START_DOCUMENT 或 START_ELEMENT 事件上。解組將從起始事件開始，到相應的終止事件結束。如果此方法成功返回，則 reader 將指向終止事件後面的標記。
reader - 要讀取的解析器。declaredType - 用來保存 reader 的 START_ELEMENT XML 資料的適當 JAXB 映射類別。
JAXBException - 如果在解組時發生不可預料的錯誤
UnmarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false 或者 Unmarshaller 不能執行 XML 到 Java 的綁定。請參閱解組 XML 資料
IllegalArgumentException - 如果任何參數為 null
Object unmarshal(XMLEventReader reader)
throws JAXBException
此方法是一個解組全體根方法。
此方法假定該解析器處於 START_DOCUMENT 或 START_ELEMENT 事件上。解組將從起始事件開始，到相應的終止事件結束。如果此方法成功返回，則 reader 將指向終止事件後面的標記。
reader - 要讀取的解析器。
JAXBException - 如果在解組時發生不可預料的錯誤
UnmarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false 或者 Unmarshaller 不能執行 XML 到 Java 的綁定。請參閱解組 XML 資料
IllegalArgumentException - 如果 reader 參數為 null
IllegalStateException - 如果 reader 沒有指向 START_DOCUMENT 或 START_ELEMENT 事件。unmarshal(javax.xml.stream.XMLEventReader, Class)
<T> JAXBElement<T> unmarshal(XMLEventReader reader,
Class<T> declaredType)
throws JAXBException
此方法實作借助 declaredType 進行解組。
此方法假定該解析器處於 START_DOCUMENT 或 START_ELEMENT 事件上。解組將從起始事件開始，到相應的終止事件結束。如果此方法成功返回，則 reader 將指向終止事件後面的標記。
reader - 要讀取的解析器。declaredType - 用來保存 reader 的 START_ELEMENT XML 資料的適當 JAXB 映射類別。
JAXBException - 如果在解組時發生不可預料的錯誤
UnmarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false 或者 Unmarshaller 不能執行 XML 到 Java 的綁定。請參閱解組 XML 資料
IllegalArgumentException - 如果任何參數為 nullUnmarshallerHandler getUnmarshallerHandler()
JAXB 提供者可以為此方法的多次調用返回相同的處理程序物件。換句話說，此方法不必創建新的 UnmarshallerHandler 實例。如果應用程序需要使用多個 UnmarshallerHandler，那麼它應該創建多個 Unmarshaller。
UnmarshallerHandler
void setValidating(boolean validating)
throws JAXBException
setSchema(javax.xml.validation.Schema)
此方法只能在調用某一 unmarshal 方法之前或之後調用。
此方法只控制 JAXB 提供者的預設解組時驗證機制，不會影響指定自己的驗證相容 SAX 2.0 的解析器的客戶端。指定自己的解組時驗證機制的客戶端可能希望通過此 API 關閉 JAXB 提供者的預設驗證機制，以避免“雙重驗證”。
此方法從 JAXB 2.0 開始已經廢棄，請使用新的 setSchema(javax.xml.validation.Schema) API。
validating - 如果 Unmarshaller 應該在解組期間執行驗證，則該參數為 true；否則為 false
JAXBException - 如果在解組期間啟用或禁用驗證時發生錯誤
UnsupportedOperationException - 如果對根據參考 JAXB 2.0 映射類別的 JAXBContext 而創建的 Unmarshaller 調用此方法，則拋出該異常
boolean isValidating()
throws JAXBException
getSchema()
此 API 返回 JAXB 提供者的預設解組時驗證機制的狀態。
此方法從 JAXB 2.0 開始已經廢棄，請使用新的 getSchema() API。
JAXBException - 如果在檢索驗證標誌時發生錯誤
UnsupportedOperationException - 如果對根據參考 JAXB 映射類別的 JAXBContext 而創建的 Unmarshaller 調用此方法，則拋出該異常
void setEventHandler(ValidationEventHandler handler)
throws JAXBException
如果在調用任何 unmarshal 方法期間遇到任何錯誤，則 ValidationEventHandler 將由 JAXB 提供者調用。如果客戶端應用程序沒有在調用 unmarshal 方法之前註冊 ValidationEventHandler，則 ValidationEvents 將由預設事件處理程序處理，預設事件處理程序將在遇到第一個錯誤或致命錯誤時終止解組操作。
調用帶有 null 參數的此方法將導致 Unmarshaller 重新使用預設事件處理程序。
handler - 驗證事件處理程序
JAXBException - 如果在設置事件處理程序期間遇到錯誤
ValidationEventHandler getEventHandler()
throws JAXBException
JAXBException - 如果獲取當前的事件處理程序時遇到錯誤
void setProperty(String name,
Object value)
throws PropertyException
name - 要設置的屬性的名稱。此值可以使用一個常數欄位來指定，也可以是一個使用者提供的字元串。value - 要設置的屬性值
PropertyException - 如果處理給定屬性或值時發生錯誤
IllegalArgumentException - 如果 name 參數為 null
Object getProperty(String name)
throws PropertyException
name - 要檢索的屬性的名稱
PropertyException - 如果檢索給定屬性或值屬性名稱時發生錯誤
IllegalArgumentException - 如果 name 參數為 nullvoid setSchema(Schema schema)
Schema 物件。向此方法傳遞 null 將禁用驗證。
此方法將替換已過時的 setValidating(boolean) API。
最初，此屬性被設置為 null。
schema - 作為驗證解組操作依據的 Schema 物件；為 null 表示禁用驗證
UnsupportedOperationException - 如果對根據參考 JAXB 1.0 映射類別的 JAXBContext 而創建的 Unmarshaller 調用此方法，則拋出該異常Schema getSchema()
Schema 物件。如果沒有在 unmarshaller 上設置 Schema，則此方法將返回 null，指示不會執行解組時驗證。
此方法用於替換已過時的 isValidating() API，並可存取 Schema 物件。要確定 Unmarshaller 是否啟用了驗證，只需測試返回型別是否為 null：
boolean isValidating = u.getSchema()!=null;
UnsupportedOperationException - 如果對根據參考 JAXB 1.0 映射類別的 JAXBContext 而創建的 Unmarshaller 調用此方法，則拋出該異常void setAdapter(XmlAdapter adapter)
XmlAdapter 實例與此 unmarshaller 關聯。
這是調用 setAdapter(adapter.getClass(),adapter); 的一個便捷方法。
IllegalArgumentException - 如果 adapter 參數為 null。
UnsupportedOperationException - 如果基於 JAXB 1.0 實作調用。setAdapter(Class,XmlAdapter)
<A extends XmlAdapter> void setAdapter(Class<A> type,
A adapter)
XmlAdapter 實例與此 unmarshaller 關聯。
每個 unmarshaller 都可以在內部維護一個 Map<Class,XmlAdapter>，可用來解組使用 XmlJavaTypeAdapter 註釋其欄位/方法的類別。
此方法允許應用程序使用已配置好的 XmlAdapter 實例。如果沒有給出適配器實例，則 unmarshaller 將調用其預設建構子創建一個實例。
type - 適配器的型別。當 XmlJavaTypeAdapter.value() 參考此型別時，將使用指定的實例。adapter - 將要使用的適配器實例。如果為 null，則將註銷此型別的當前適配器集合。
IllegalArgumentException - 如果 type 參數為 null。
UnsupportedOperationException - 如果基於 JAXB 1.0 實作調用。<A extends XmlAdapter> A getAdapter(Class<A> type)
setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter) 方法的反向操作。
IllegalArgumentException - 如果 type 參數為 null。
UnsupportedOperationException - 如果基於 JAXB 1.0 實作調用。void setAttachmentUnmarshaller(AttachmentUnmarshaller au)
將解析 cid（內容 id URI）的上下文與作為附件傳遞的二進制資料關聯。
通過 setSchema(Schema) 啟用的解組時驗證，即使在 unmarshaller 執行 XOP 處理時也必須支持。
IllegalStateException - 如果試圖在解組操作期間同時調用此方法。AttachmentUnmarshaller getAttachmentUnmarshaller()
void setListener(Unmarshaller.Listener listener)
向此 Unmarshaller 註冊解組事件回調 Unmarshaller.Listener。
每個 Unmarshaller 只有一個 Listener。設置 Listener 將替換以前設置的 Listener。通過將 listener 設置為 null 可註銷當前的 Listener。
listener - 為此 Unmarshaller 提供解組事件回調Unmarshaller.Listener getListener()
返回向此 Unmarshaller 註冊的 Unmarshaller.Listener。
Unmarshaller.Listener；如果未向此 Unmarshaller 註冊任何 Listener，則返回 null。
|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
| 上一個類別 下一個類別 | 框架 無框架 | |||||||||
| 摘要： 巢狀 | 欄位 | 建構子 | 方法 | 詳細資訊： 欄位 | 建構子 | 方法 | |||||||||
版權所有 2008 Sun Microsystems, Inc. 保留所有權利。請遵守GNU General Public License, version 2 only。