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

javax.xml.bind
介面 Marshaller

所有已知實作類別：
AbstractMarshallerImpl
public interface Marshaller

Marshaller 類別負責管理將 Java 內容階層樹序列化回 XML 資料的過程。它提供了基本的編組方法：

假定以下安裝程式碼適用於下列所有程式碼片段： 

JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
Unmarshaller u = jc.createUnmarshaller();
Object element = u.unmarshal( new File( "foo.xml" ) );
Marshaller m = jc.createMarshaller();

編組到 File 中： 

OutputStream os = new FileOutputStream( "nosferatu.xml" );
m.marshal( element, os );

編組到 SAX ContentHandler 中： 

// assume MyContentHandler instanceof ContentHandler
m.marshal( element, new MyContentHandler() );

編組到 DOM Node 中： 

DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
DocumentBuilder db = dbf.newDocumentBuilder();
Document doc = db.newDocument();

m.marshal( element, doc );

編組到 java.io.OutputStream 中： 

m.marshal( element, System.out );

編組到 java.io.Writer 中： 

m.marshal( element, new PrintWriter( System.out ) );

編組到 javax.xml.transform.SAXResult 中： 

// assume MyContentHandler instanceof ContentHandler
SAXResult result = new SAXResult( new MyContentHandler() );

m.marshal( element, result );

編組到 javax.xml.transform.DOMResult 中： 

DOMResult result = new DOMResult();
       
m.marshal( element, result );

編組到 javax.xml.transform.StreamResult 中： 

StreamResult result = new StreamResult( System.out );
 
m.marshal( element, result );

編組到 javax.xml.stream.XMLStreamWriter 中： 

XMLStreamWriter xmlStreamWriter = 
XMLOutputFactory.newInstance().createXMLStreamWriter( ... );
 
m.marshal( element, xmlStreamWriter );

編組到 javax.xml.stream.XMLEventWriter 中： 

XMLEventWriter xmlEventWriter = 
XMLOutputFactory.newInstance().createXMLEventWriter( ... );
 
m.marshal( element, xmlEventWriter );

對通過 JAXB 元素確定的內容階層樹進行編組

重載的 Marshaller.marshal(java.lang.Object, ...) 方法的第一個參數必須是由 JAXBIntrospector.isElement(java.lang.Object) 計算的 JAXB 元素；否則，Marshaller.marshal 方法必須拋出 MarshalException。存在兩種能編組非 JAXB 元素實例的機制。一種方法是將該實例包裹為 JAXBElement 值，並將外覆器物件作為第一個參數傳遞給 Marshaller.marshal 方法。對於 java 到網要的綁定，還可以簡單地使用 @XmlRootElement 註釋該實例的類別。

編碼

預設情況下，在將 XML 資料產生到 java.io.OutputStream 或 java.io.Writer 中時，Marshaller 將使用 UTF-8 編碼。可以使用 setProperty API 更改執行這些編組操作期間所使用的輸出編碼。期望客戶端應用程序根據 W3C XML 1.0 Recommendation 中的定義提供 Java 平臺支持的有效字元編碼名稱。

驗證和格式良好性

客戶端應用程序不需要在調用任何編組 API 之前驗證 Java 內容階層樹。此外，在將 Java 內容階層樹編組回 XML 資料時，不要求它對於其源網要有效。不同的 JAXB 提供者可支持編組各種級別的無效 Java 內容階層樹，但所有 JAXB 提供者都必須能夠將有效的內容階層樹編組回 XML 資料。當因為無效內容導致 JAXB 提供者無法完成編組操作時，JAXB 提供者必須拋出 MarshalException。一些 JAXB 提供者完全允許編組無效內容，而另一些 JAXB 提供者將在出現第一個驗證錯誤時失敗。

即使沒有為編組操作顯式地啟用網要驗證，但在操作過程中可能要檢測某些型別的驗證事件。這些驗證事件將被報告給已註冊的事件處理程序。如果客戶端應用程序沒有在調用某個編組 API 之前註冊事件處理程序，則事件將被轉發給預設的事件處理程序，預設處理程序將在遇到第一個錯誤或遇到致命錯誤之後終止編組操作。注意，對於 JAXB 2.0 和以後的版本，不再使用 DefaultValidationEventHandler。

支持的屬性

所有 JAXB 提供者都要支持以下這組屬性。某些提供者還可以支持其他屬性。

jaxb.encoding：值必須是 java.lang.String
編組 XML 資料時使用的輸出編碼。預設情況下，如果未指定此屬性，則 Marshaller 將使用 "UTF-8"。
jaxb.formatted.output：值必須是 java.lang.Boolean
此屬性控制 Marshaller 是否使用換行和縮排對得到的 XML 資料進行格式化。此屬性為 true 值表示可讀性強的縮排 xml 資料，而屬性值為 false 則表示未格式化的 xml 資料。如果未指定此屬性，則 Marshaller 將該屬性值預設為 false（未格式化）。
jaxb.schemaLocation：值必須是 java.lang.String
此屬性允許客戶端應用程序在產生的 XML 資料中指定 xsi:schemaLocation 屬性。該 schemaLocation 屬性值的格式將以便於理解的、非標準的形式在 W3C XML Schema Part 0:Primer 的第 5.6 節中討論，並在 W3C XML Schema Part 1:Structures 的第 2.6 節中指定。
jaxb.noNamespaceSchemaLocation：值必須是 java.lang.String
此屬性允許客戶端應用程序在產生的 XML 資料中指定 xsi:noNamespaceSchemaLocation 屬性。該 schemaLocation 屬性值的格式將以便於理解的、非標準的形式在 W3C XML Schema Part 0:Primer 的第 5.6 節中討論，並在 W3C XML Schema Part 1:Structures 的第 2.6 節中指定。
jaxb.fragment：值必須是 java.lang.Boolean
此屬性決定 Marshaller 是否將產生文檔級事件。如果未指定該屬性，則預設為 false。將其設置為 true 時，根據所使用的編組 API，此屬性具有不同的含義：

編組事件回調

Marshaller 提供了兩種樣式的回調機制，這些機制允許在解組過程的關鍵點上進行特定於應用程序的處理。在「類別定義的」事件回調中，編組期間會觸發位於 JAXB 映射類別中的特定於應用程序的程式碼。「外部偵聽器」允許用一個回調方法集中處理編組事件，而不是通過各種型別事件回調處理。

類別定義的事件回調方法允許任何 JAXB 映射類別通過定義帶有以下方法簽章的方法指定自己的特定回調方法： 

// Invoked by Marshaller after it has created an instance of this object.
boolean beforeMarshal(Marshaller, Object parent);
 
// Invoked by Marshaller after it has marshalled all properties of this object.
void afterMmarshal(Marshaller, Object parent);
類別定義的事件回調方法應該在回調方法需要存取該類別的非公共方法和/或欄位時使用。

外部偵聽器回調機制支持 Marshaller.Listener 實例使用 setListener(Listener) 的註冊。外部偵聽器接收所有回調事件，從而允許用比逐個類別地定義回調方法更為集中的方式處理事件。

「類別定義的」事件回調方法和外部偵聽器事件回調方法相互獨立，可以對一個事件同時調用。兩種偵聽器回調方法都存在時，按照 Marshaller.Listener.beforeMarshal(Object) 和 Marshaller.Listener.afterMarshal(Object) 中定義的順序對它們進行調用。

拋出異常的事件回調方法會終止當前的編組進程。

從以下版本開始：
JAXB 1.0
另請參見：
JAXBContext, Validator, Unmarshaller

巢狀類別摘要
static class Marshaller.Listener
          

向 Marshaller 註冊此類別的一個實作的實例，以從外部偵聽編組事件。
 
欄位摘要
static String JAXB_ENCODING
          用來指定已編組 XML 資料中輸出編碼的屬性名稱。
static String JAXB_FORMATTED_OUTPUT
          用來指定是否使用換行和縮排對已編組 XML 資料進行格式化的屬性名稱。
static String JAXB_FRAGMENT
          用來指定 marshaller 是否將產生文檔級事件（即調用 startDocument 或 endDocument）的屬性名稱。
static String JAXB_NO_NAMESPACE_SCHEMA_LOCATION
          用來指定將放置在已編組 XML 輸出中的 xsi:noNamespaceSchemaLocation 屬性值的屬性名稱。
static String JAXB_SCHEMA_LOCATION
          用來指定將放置在已編組 XML 輸出中的 xsi:schemaLocation 屬性值的屬性名稱。
 
方法摘要
<A extends XmlAdapter>
A
getAdapter(Class<A> type)
          獲取與指定型別關聯的適配器。
 AttachmentMarshaller getAttachmentMarshaller()
           
 ValidationEventHandler getEventHandler()
          返回當前的事件處理程序，如果沒有設置該處理程序，則返回預設的事件處理程序。
 Marshaller.Listener getListener()
          返回向此 Marshaller 註冊的 Marshaller.Listener。
 Node getNode(Object contentTree)
          獲取內容階層樹的 DOM 階層樹視圖（可選）。
 Object getProperty(String name)
          獲取 Marshaller 底層實作中的特定屬性。
 Schema getSchema()
          獲取用於執行編組時驗證的 JAXP 1.3 Schema 物件。
 void marshal(Object jaxbElement, ContentHandler handler)
          將以 jaxbElement 為根的內容階層樹編組到 SAX2 事件中。
 void marshal(Object jaxbElement, Node node)
          將以 jaxbElement 為根的內容階層樹編組到 DOM 階層樹中。
 void marshal(Object jaxbElement, OutputStream os)
          將以 jaxbElement 為根的內容階層樹編組到輸出串流中。
 void marshal(Object jaxbElement, Result result)
          將以 jaxbElement 為根的內容階層樹編組到指定的 javax.xml.transform.Result 中。
 void marshal(Object jaxbElement, Writer writer)
          將以 jaxbElement 為根的內容階層樹編組到 Writer 中。
 void marshal(Object jaxbElement, XMLEventWriter writer)
          將以 jaxbElement 為根的內容階層樹編組到 XMLEventWriter 中。
 void marshal(Object jaxbElement, XMLStreamWriter writer)
          將以 jaxbElement 為根的內容階層樹編組到 XMLStreamWriter 中。
<A extends XmlAdapter>
void
setAdapter(Class<A> type, A adapter)
          將已配置的 XmlAdapter 實例與此 marshaller 關聯。
 void setAdapter(XmlAdapter adapter)
          將已配置的 XmlAdapter 實例與此 marshaller 關聯。
 void setAttachmentMarshaller(AttachmentMarshaller am)
          與上下文關聯，使 XML 文檔內的二進制資料能夠以優化的 XML 二進制附件的形式傳送。
 void setEventHandler(ValidationEventHandler handler)
          允許應用程序註冊一個驗證事件處理程序。
 void setListener(Marshaller.Listener listener)
           向此 Marshaller 註冊編組事件回調 Marshaller.Listener。
 void setProperty(String name, Object value)
          設置 Marshaller 底層實作中的特定屬性。
 void setSchema(Schema schema)
          指定應該用作驗證後續編組操作依據的 JAXP 1.3 Schema 物件。
 

欄位詳細資訊

JAXB_ENCODING

static final String JAXB_ENCODING
用來指定已編組 XML 資料中輸出編碼的屬性名稱。

另請參見：
常數欄位值

JAXB_FORMATTED_OUTPUT

static final String JAXB_FORMATTED_OUTPUT
用來指定是否使用換行和縮排對已編組 XML 資料進行格式化的屬性名稱。

另請參見：
常數欄位值

JAXB_SCHEMA_LOCATION

static final String JAXB_SCHEMA_LOCATION
用來指定將放置在已編組 XML 輸出中的 xsi:schemaLocation 屬性值的屬性名稱。

另請參見：
常數欄位值

JAXB_NO_NAMESPACE_SCHEMA_LOCATION

static final String JAXB_NO_NAMESPACE_SCHEMA_LOCATION
用來指定將放置在已編組 XML 輸出中的 xsi:noNamespaceSchemaLocation 屬性值的屬性名稱。

另請參見：
常數欄位值

JAXB_FRAGMENT

static final String JAXB_FRAGMENT
用來指定 marshaller 是否將產生文檔級事件（即調用 startDocument 或 endDocument）的屬性名稱。

另請參見：
常數欄位值
方法詳細資訊

marshal

void marshal(Object jaxbElement,
             Result result)
             throws JAXBException
將以 jaxbElement 為根的內容階層樹編組到指定的 javax.xml.transform.Result 中。

所有 JAXB 提供者至少必須支持 DOMResult、SAXResult 和 StreamResult。它也可以支持 Result 的其他派生類別。

參數：
jaxbElement - 要編組的內容階層樹的根。
result - XML 將被發送到此 Result
拋出：
JAXBException - 如果在編組期間發生任何不可預料的問題。
MarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false，或者 Marshaller 不能編組 obj（或任何可從 obj 獲得的物件）。請參閱編組 JAXB 元素。
IllegalArgumentException - 如果任何方法參數為 null

marshal

void marshal(Object jaxbElement,
             OutputStream os)
             throws JAXBException
將以 jaxbElement 為根的內容階層樹編組到輸出串流中。

參數：
jaxbElement - 要編組的內容階層樹的根。
os - XML 將被添加到此串流。
拋出：
JAXBException - 如果在編組期間發生任何不可預料的問題。
MarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false，或者 Marshaller 不能編組 obj（或任何可從 obj 獲得的物件）。請參閱編組 JAXB 元素。
IllegalArgumentException - 如果任何方法參數為 null

marshal

void marshal(Object jaxbElement,
             Writer writer)
             throws JAXBException
將以 jaxbElement 為根的內容階層樹編組到 Writer 中。

參數：
jaxbElement - 要編組的內容階層樹的根。
writer - XML 將被發送到此編寫器。
拋出：
JAXBException - 如果在編組期間發生任何不可預料的問題。
MarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false，或者 Marshaller 不能編組 obj（或任何可從 obj 獲得的物件）。請參閱編組 JAXB 元素。
IllegalArgumentException - 如果任何方法參數為 null

marshal

void marshal(Object jaxbElement,
             ContentHandler handler)
             throws JAXBException
將以 jaxbElement 為根的內容階層樹編組到 SAX2 事件中。

參數：
jaxbElement - 要編組的內容階層樹的根。
handler - XML 將被作為 SAX2 事件發送到此處理程序。
拋出：
JAXBException - 如果在編組期間發生任何不可預料的問題。
MarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false，或者 Marshaller 不能編組 obj（或任何可從 obj 獲得的物件）。請參閱編組 JAXB 元素。
IllegalArgumentException - 如果任何方法參數為 null

marshal

void marshal(Object jaxbElement,
             Node node)
             throws JAXBException
將以 jaxbElement 為根的內容階層樹編組到 DOM 階層樹中。

參數：
jaxbElement - 要編組的內容階層樹。
node - DOM 節點將作為此節點的子節點添加。此參數必須是一個可接受子節點（Document、DocumentFragment 或 Element）的 Node。
拋出：
JAXBException - 如果在編組期間發生任何不可預料的問題。
MarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false，或者 Marshaller 不能編組 jaxbElement（或任何可從 jaxbElement 獲得的物件）。請參閱編組 JAXB 元素。
IllegalArgumentException - 如果任何方法參數為 null

marshal

void marshal(Object jaxbElement,
             XMLStreamWriter writer)
             throws JAXBException
將以 jaxbElement 為根的內容階層樹編組到 XMLStreamWriter 中。

參數：
jaxbElement - 要編組的內容階層樹。
writer - XML 將被發送到此編寫器。
拋出：
JAXBException - 如果在編組期間發生任何不可預料的問題。
MarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false，或者 Marshaller 不能編組 obj（或任何可從 obj 獲得的物件）。請參閱編組 JAXB 元素。
IllegalArgumentException - 如果任何方法參數為 null
從以下版本開始：
JAXB 2.0

marshal

void marshal(Object jaxbElement,
             XMLEventWriter writer)
             throws JAXBException
將以 jaxbElement 為根的內容階層樹編組到 XMLEventWriter 中。

參數：
jaxbElement - 要編組的以 jaxbElement 為根的內容階層樹。
writer - XML 將被發送到此編寫器。
拋出：
JAXBException - 如果在編組期間發生任何不可預料的問題。
MarshalException - 如果 ValidationEventHandler 從其 handleEvent 方法返回 false，或者 Marshaller 不能編組 obj（或任何可從 obj 獲得的物件）。請參閱編組 JAXB 元素。
IllegalArgumentException - 如果任何方法參數為 null
從以下版本開始：
JAXB 2.0

getNode

Node getNode(Object contentTree)
             throws JAXBException
獲取內容階層樹的 DOM 階層樹視圖（可選）。 如果更新了返回的 DOM 階層樹，則這些更改也可以在內容階層樹中看見。使用 marshal(Object, org.w3c.dom.Node) 強行將內容階層樹的深層複製轉換成 DOM 表示形式。

參數：
contentTree - XML 內容的 JAXB Java 表示形式
返回：
contentTree 的 DOM 階層樹視圖
拋出：
UnsupportedOperationException - 如果 JAXB 提供者實作不支持內容階層樹的 DOM 視圖
IllegalArgumentException - 如果任何方法參數為 null
JAXBException - 如果發生任何不可預料的問題

setProperty

void setProperty(String name,
                 Object value)
                 throws PropertyException
設置 Marshaller 底層實作中的特定屬性。此方法只能用於設置上文中標準 JAXB 定義的屬性之一或特定於提供者的屬性。試圖設置未定義的屬性將導致拋出 PropertyException。請參閱支持的屬性。

參數：
name - 要設置的屬性的名稱。此值可以使用一個常數欄位來指定，也可以是一個使用者提供的字元串。
value - 要設置的屬性值
拋出：
PropertyException - 如果處理給定屬性或值時發生錯誤
IllegalArgumentException - 如果 name 參數為 null

getProperty

Object getProperty(String name)
                   throws PropertyException
獲取 Marshaller 底層實作中的特定屬性。此方法只能用於獲取上文中標準 JAXB 定義的屬性之一或特定於提供者的屬性。試圖獲取未定義的屬性將導致拋出 PropertyException。請參閱支持的屬性。

參數：
name - 將檢索的屬性的名稱
返回：
所請求屬性的值
拋出：
PropertyException - 如果檢索給定屬性或值屬性名稱時發生錯誤
IllegalArgumentException - 如果 name 參數為 null

setEventHandler

void setEventHandler(ValidationEventHandler handler)
                     throws JAXBException
允許應用程序註冊一個驗證事件處理程序。

如果在調用任何編組 API 期間遇到任何驗證錯誤，則 JAXB 提供者將調用驗證事件處理程序。如果客戶端應用程序沒有在調用某個 marshal 方法之前註冊驗證事件處理程序，則將使用預設事件處理程序處理驗證事件，預設處理程序將在遇到第一個錯誤或致命錯誤之後將終止編組操作。

調用帶有 null 參數的此方法將導致 Marshaller 重新使用預設事件處理程序。

參數：
handler - 驗證事件處理程序
拋出：
JAXBException - 如果在設置事件處理程序時遇到錯誤

getEventHandler

ValidationEventHandler getEventHandler()
                                       throws JAXBException
返回當前的事件處理程序，如果沒有設置該處理程序，則返回預設的事件處理程序。

返回：
當前的 ValidationEventHandler，如果沒有設置該處理程序，則返回預設的事件處理程序
拋出：
JAXBException - 如果獲取當前的事件處理程序時遇到錯誤

setAdapter

void setAdapter(XmlAdapter adapter)
將已配置的 XmlAdapter 實例與此 marshaller 關聯。

這是調用 setAdapter(adapter.getClass(),adapter) 的一個便捷方法。

拋出：
IllegalArgumentException - 如果 adapter 參數為 null。
UnsupportedOperationException - 如果基於 JAXB 1.0 實作調用。
從以下版本開始：
JAXB 2.0
另請參見：
setAdapter(Class,XmlAdapter)

setAdapter

<A extends XmlAdapter> void setAdapter(Class<A> type,
                                       A adapter)
將已配置的 XmlAdapter 實例與此 marshaller 關聯。

每個 marshaller 都可以在內部維護一個 Map<Class,XmlAdapter>，可用來編組使用 XmlJavaTypeAdapter 註釋其欄位/方法的類別。

此方法允許應用程序使用已配置好的 XmlAdapter 實例。如果沒有給出適配器實例，則 marshaller 將調用其預設建構子創建一個實例。

參數：
type - 適配器的型別。當 XmlJavaTypeAdapter.value() 參考此型別時，將使用指定的實例。
adapter - 將要使用的適配器實例。如果為 null，則將註銷此型別的當前適配器集合。
拋出：
IllegalArgumentException - 如果 type 參數為 null。
UnsupportedOperationException - 如果基於 JAXB 1.0 實作調用。
從以下版本開始：
JAXB 2.0

getAdapter

<A extends XmlAdapter> A getAdapter(Class<A> type)
獲取與指定型別關聯的適配器。 這是 setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter) 方法的反向操作。

拋出：
IllegalArgumentException - 如果 type 參數為 null。
UnsupportedOperationException - 如果基於 JAXB 1.0 實作調用。
從以下版本開始：
JAXB 2.0

setAttachmentMarshaller

void setAttachmentMarshaller(AttachmentMarshaller am)

與上下文關聯，使 XML 文檔內的二進制資料能夠以優化的 XML 二進制附件的形式傳送。可以使用存儲在 xml 文檔中的內容 id URI (cid) 從 XML 文檔內容網要參考附件。

拋出：
IllegalStateException - 如果試圖在執行編組操作期間同時調用此方法。

getAttachmentMarshaller

AttachmentMarshaller getAttachmentMarshaller()

setSchema

void setSchema(Schema schema)
指定應該用作驗證後續編組操作依據的 JAXP 1.3 Schema 物件。向此方法傳遞 null 將禁用驗證。

此方法允許調用者在對已編組的 XML 進行編組時驗證它。

最初，此屬性被設置為 null。

參數：
schema - 作為驗證編組操作依據的 Schema 物件；為 null 表示禁用驗證
拋出：
UnsupportedOperationException - 如果對根據參考 JAXB 1.0 映射類別的 JAXBContext 而創建的 Marshaller 調用此方法，則拋出該異常
從以下版本開始：
JAXB 2.0

getSchema

Schema getSchema()
獲取用於執行編組時驗證的 JAXP 1.3 Schema 物件。如果未在 marshaller 上設置 Schema，則此方法將返回 null，指示不執行編組時驗證。

返回：
返回用於執行編組時驗證的 Schema 物件；如果該物件不存在，則返回 null。
拋出：
UnsupportedOperationException - 如果對根據參考 JAXB 1.0 映射類別的 JAXBContext 而創建的 Marshaller 調用此方法，則拋出該異常
從以下版本開始：
JAXB 2.0

setListener

void setListener(Marshaller.Listener listener)

向此 Marshaller 註冊編組事件回調 Marshaller.Listener。

每個 Marshaller 只有一個 Listener。設置 Listener 將替換以前設置的 Listener。通過將 listener 設置為 null 可註銷當前的 Listener。

參數：
listener - 實作 Marshaller.Listener 的類別的實例
從以下版本開始：
JAXB 2.0

getListener

Marshaller.Listener getListener()

返回向此 Marshaller 註冊的 Marshaller.Listener。

返回：
註冊的 Marshaller.Listener；如果未向此 Marshaller 註冊任何 Listener，則返回 null。
從以下版本開始：
JAXB 2.0
概觀  軟體套件   類別  使用  階層樹  已過時  索引  說明 
JavaTM 2 Platform
Standard Ed. 6
 上一個類別   下一個類別 框架    無框架    
摘要： 巢狀 | 欄位 | 建構子 | 方法 詳細資訊： 欄位 | 建構子 | 方法
提交錯誤或意見

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