Marshaller (Java EE 5)

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, ...) 方法的第一个参数必须是由 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 和以后的版本，不再使用 javax.xml.bind.helpers.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，此属性具有不同的含义：

• marshal(Object,ContentHandler)：Marshaller 不会调用 startDocument() 和 endDocument()。
• marshal(Object,Node)：该属性对此 API 没有影响。
• marshal(Object,OutputStream)：Marshaller 不会生成 xml 声明。
• marshal(Object,Writer)：Marshaller 不会生成 xml 声明。
• marshal(Object,Result)：取决于 Result 对象的类型，请参见 Node、ContentHandler 和 Stream API 的语义。
• marshal(Object,XMLEventWriter)：Marshaller 不会生成 javax.xml.stream.events.XMLEvent#START_DOCUMENT 和 javax.xml.stream.events.XMLEvent#END_DOCUMENT 事件。
• marshal(Object,XMLStreamWriter)：Marshaller 不会生成 javax.xml.stream.events.XMLEvent#START_DOCUMENT 和 javax.xml.stream.events.XMLEvent#END_DOCUMENT 事件。

编组事件回调

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);
 

类定义的事件回调方法应该在回调方法需要访问该类的非公共方法和/或字段时使用。

外部侦听器回调机制支持 Listener 实例使用 setListener(Listener) 的注册。外部侦听器接收所有回调事件，从而允许用比逐个类地定义回调方法更为集中的方式处理事件。

“类定义的”事件回调方法和外部侦听器事件回调方法相互独立，可以对一个事件同时调用。两种侦听器回调方法都存在时，按照 beforeMarshal(Object) 和 afterMarshal(Object) 中定义的顺序对它们进行调用。

抛出异常的事件回调方法会终止当前的编组进程。

version	en $Revision: 1.19 $ $Date: 2006/03/08 16:54:42 $
since	JAXB1.0
See also	javax.xml.bind.JAXBContext, javax.xml.bind.Validator, javax.xml.bind.Unmarshaller

英文文档：

The Marshaller class is responsible for governing the process of serializing Java content trees back into XML data. It provides the basic marshalling methods:

Assume the following setup code for all following code fragments:

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

Marshalling to a File:

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

Marshalling to a SAX ContentHandler:

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

Marshalling to a DOM Node:

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

       m.marshal( element, doc );
    

Marshalling to a java.io.OutputStream:

       m.marshal( element, System.out );
    

Marshalling to a java.io.Writer:

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

Marshalling to a javax.xml.transform.SAXResult:

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

       m.marshal( element, result );
    

Marshalling to a javax.xml.transform.DOMResult:

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

Marshalling to a javax.xml.transform.StreamResult:

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

Marshalling to a javax.xml.stream.XMLStreamWriter:

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

Marshalling to a javax.xml.stream.XMLEventWriter:

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

Marshalling content tree rooted by a JAXB element

The first parameter of the overloaded Marshaller.marshal(java.lang.Object, ...) methods must be a JAXB element as computed by JAXBIntrospector.isElement(java.lang.Object); otherwise, a Marshaller.marshal method must throw a MarshalException. There exist two mechanisms to enable marshalling an instance that is not a JAXB element. One method is to wrap the instance as a value of a JAXBElement, and pass the wrapper element as the first parameter to a Marshaller.marshal method. For java to schema binding, it is also possible to simply annotate the instance's class with @XmlRootElement.

Encoding

By default, the Marshaller will use UTF-8 encoding when generating XML data to a java.io.OutputStream, or a java.io.Writer. Use the setProperty API to change the output encoding used during these marshal operations. Client applications are expected to supply a valid character encoding name as defined in the W3C XML 1.0 Recommendation and supported by your Java Platform.

Validation and Well-Formedness

Client applications are not required to validate the Java content tree prior to calling any of the marshal API's. Furthermore, there is no requirement that the Java content tree be valid with respect to its original schema in order to marshal it back into XML data. Different JAXB Providers will support marshalling invalid Java content trees at varying levels, however all JAXB Providers must be able to marshal a valid content tree back to XML data. A JAXB Provider must throw a MarshalException when it is unable to complete the marshal operation due to invalid content. Some JAXB Providers will fully allow marshalling invalid content, others will fail on the first validation error.

Even when schema validation is not explictly enabled for the marshal operation, it is possible that certain types of validation events will be detected during the operation. Validation events will be reported to the registered event handler. If the client application has not registered an event handler prior to invoking one of the marshal API's, then events will be delivered to a default event handler which will terminate the marshal operation after encountering the first error or fatal error. Note that for JAXB 2.0 and later versions, DefaultValidationEventHandler is no longer used.

Supported Properties

All JAXB Providers are required to support the following set of properties. Some providers may support additional properties.

jaxb.encoding - value must be a java.lang.String

The output encoding to use when marshalling the XML data. The Marshaller will use "UTF-8" by default if this property is not specified.

jaxb.formatted.output - value must be a java.lang.Boolean

This property controls whether or not the Marshaller will format the resulting XML data with line breaks and indentation. A true value for this property indicates human readable indented xml data, while a false value indicates unformatted xml data. The Marshaller will default to false (unformatted) if this property is not specified.

jaxb.schemaLocation - value must be a java.lang.String

This property allows the client application to specify an xsi:schemaLocation attribute in the generated XML data. The format of the schemaLocation attribute value is discussed in an easy to understand, non-normative form in Section 5.6 of the W3C XML Schema Part 0: Primer and specified in Section 2.6 of the W3C XML Schema Part 1: Structures.

jaxb.noNamespaceSchemaLocation - value must be a java.lang.String

This property allows the client application to specify an xsi:noNamespaceSchemaLocation attribute in the generated XML data. The format of the schemaLocation attribute value is discussed in an easy to understand, non-normative form in Section 5.6 of the W3C XML Schema Part 0: Primer and specified in Section 2.6 of the W3C XML Schema Part 1: Structures.

jaxb.fragment - value must be a java.lang.Boolean

This property determines whether or not document level events will be generated by the Marshaller. If the property is not specified, the default is false. This property has different implications depending on which marshal api you are using - when this property is set to true:

• marshal(Object,ContentHandler) - the Marshaller won't invoke ContentHandler.startDocument() and ContentHandler.endDocument().
• marshal(Object,Node) - the property has no effect on this API.
• marshal(Object,OutputStream) - the Marshaller won't generate an xml declaration.
• marshal(Object,Writer) - the Marshaller won't generate an xml declaration.
• marshal(Object,Result) - depends on the kind of Result object, see semantics for Node, ContentHandler, and Stream APIs
• marshal(Object,XMLEventWriter) - the Marshaller will not generate XMLStreamConstants.START_DOCUMENT and XMLStreamConstants.END_DOCUMENT events.
• marshal(Object,XMLStreamWriter) - the Marshaller will not generate XMLStreamConstants.START_DOCUMENT and XMLStreamConstants.END_DOCUMENT events.

Marshal Event Callbacks

"The Marshaller provides two styles of callback mechanisms that allow application specific processing during key points in the unmarshalling process. In 'class defined' event callbacks, application specific code placed in JAXB mapped classes is triggered during marshalling. 'External listeners' allow for centralized processing of marshal events in one callback method rather than by type event callbacks.

Class defined event callback methods allow any JAXB mapped class to specify its own specific callback methods by defining methods with the following method signatures:

   // 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);
 

The class defined event callback methods should be used when the callback method requires access to non-public methods and/or fields of the class.

The external listener callback mechanism enables the registration of a Marshaller.Listener instance with a setListener(Listener). The external listener receives all callback events, allowing for more centralized processing than per class defined callback methods.

The 'class defined' and external listener event callback methods are independent of each other, both can be called for one event. The invocation ordering when both listener callback methods exist is defined in Marshaller.Listener.beforeMarshal(Object) and Marshaller.Listener.afterMarshal(Object).

An event callback method throwing an exception terminates the current marshal process.

Since:

JAXB1.0

Version:

$Revision: 1.19 $ $Date: 2006/03/08 16:54:42 $

Author:

• Kohsuke Kawaguchi, Sun Microsystems, Inc.
• Ryan Shoemaker, Sun Microsystems, Inc.
• Joe Fialli, Sun Microsystems, Inc.

See Also:

JAXBContext, Validator, Unmarshaller

---

Nested Class Summary
static class	Marshaller.Listener            Register an instance of an implementation of this class with a Marshaller to externally listen for marshal events.

 

Field Summary
static String	JAXB_ENCODING           The name of the property used to specify the output encoding in the marshalled XML data.
static String	JAXB_FORMATTED_OUTPUT           The name of the property used to specify whether or not the marshalled XML data is formatted with linefeeds and indentation.
static String	JAXB_FRAGMENT           The name of the property used to specify whether or not the marshaller will generate document level events (ie calling startDocument or endDocument).
static String	JAXB_NO_NAMESPACE_SCHEMA_LOCATION           The name of the property used to specify the xsi:noNamespaceSchemaLocation attribute value to place in the marshalled XML output.
static String	JAXB_SCHEMA_LOCATION           The name of the property used to specify the xsi:schemaLocation attribute value to place in the marshalled XML output.

 

Method Summary
<A extends XmlAdapter> A

getAdapter(Class<A> type)
          Gets the adapter associated with the specified type.  AttachmentMarshaller getAttachmentMarshaller()
             ValidationEventHandler getEventHandler()
          Return the current event handler or the default event handler if one hasn't been set.  Marshaller.Listener getListener()
          Return Marshaller.Listener registered with this Marshaller.  Node getNode(Object contentTree)
          Get a DOM tree view of the content tree(Optional).  Object getProperty(String name)
          Get the particular property in the underlying implementation of Marshaller.  Schema getSchema()
          Get the JAXP 1.3 Schema object being used to perform marshal-time validation.  void marshal(Object jaxbElement, ContentHandler handler)
          Marshal the content tree rooted at jaxbElement into SAX2 events.  void marshal(Object jaxbElement, Node node)
          Marshal the content tree rooted at jaxbElement into a DOM tree.  void marshal(Object jaxbElement, OutputStream os)
          Marshal the content tree rooted at jaxbElement into an output stream.  void marshal(Object jaxbElement, Result result)
          Marshal the content tree rooted at jaxbElement into the specified javax.xml.transform.Result.  void marshal(Object jaxbElement, Writer writer)
          Marshal the content tree rooted at jaxbElement into a Writer.  void marshal(Object jaxbElement, XMLEventWriter writer)
          Marshal the content tree rooted at jaxbElement into a XMLEventWriter.  void marshal(Object jaxbElement, XMLStreamWriter writer)
          Marshal the content tree rooted at jaxbElement into a XMLStreamWriter. setAdapter(Class<A> type, A adapter)
          Associates a configured instance of XmlAdapter with this marshaller.  void setAdapter(XmlAdapter adapter)
          Associates a configured instance of XmlAdapter with this marshaller.  void setAttachmentMarshaller(AttachmentMarshaller am)
          Associate a context that enables binary data within an XML document to be transmitted as XML-binary optimized attachment.  void setEventHandler(ValidationEventHandler handler)
          Allow an application to register a validation event handler.  void setListener(Marshaller.Listener listener)
           Register marshal event callback Marshaller.Listener with this Marshaller.  void setProperty(String name, Object value)
          Set the particular property in the underlying implementation of Marshaller.  void setSchema(Schema schema)
          Specify the JAXP 1.3 Schema object that should be used to validate subsequent marshal operations against.  

Field Detail

英文文档：

JAXB_ENCODING

static final String JAXB_ENCODING

The name of the property used to specify the output encoding in the marshalled XML data.

See Also:

Constant Field Values

---

英文文档：

JAXB_FORMATTED_OUTPUT

static final String JAXB_FORMATTED_OUTPUT

The name of the property used to specify whether or not the marshalled XML data is formatted with linefeeds and indentation.

See Also:

Constant Field Values

---

英文文档：

JAXB_SCHEMA_LOCATION

static final String JAXB_SCHEMA_LOCATION

The name of the property used to specify the xsi:schemaLocation attribute value to place in the marshalled XML output.

See Also:

Constant Field Values

---

英文文档：

JAXB_NO_NAMESPACE_SCHEMA_LOCATION

static final String JAXB_NO_NAMESPACE_SCHEMA_LOCATION

The name of the property used to specify the xsi:noNamespaceSchemaLocation attribute value to place in the marshalled XML output.

See Also:

Constant Field Values

---

英文文档：

JAXB_FRAGMENT

static final String JAXB_FRAGMENT

The name of the property used to specify whether or not the marshaller will generate document level events (ie calling startDocument or endDocument).

See Also:

Constant Field Values

Method Detail

public void marshal(Object jaxbElement, javax.xml.transform.Result result) throws JAXBException
将以 jaxbElement 为根的内容树编组到指定的 javax.xml.transform.Result 中。

所有 JAXB 提供者至少必须支持 javax.xml.transform.dom.DOMResult、javax.xml.transform.sax.SAXResult 和 javax.xml.transform.stream.StreamResult。它也可以支持 Result 的其他派生类。

jaxbElement	要编组的内容树的根。
result	XML 将被发送到此 Result
Throws	JAXBException: 如果进行解组期间发生不可预料的错误。
Throws	MarshalException: 如果 ValidationEventHandler 从其 handleEvent 方法返回 false，或者 Marshaller 不能编组 obj（或任何可从 obj 获得的对象）。请参阅编组 JAXB 元素。
Throws	IllegalArgumentException: 如果任何方法的参数为 null

英文文档：

marshal

void marshal(Object jaxbElement,
             Result result)
             throws JAXBException

Marshal the content tree rooted at jaxbElement into the specified javax.xml.transform.Result.

All JAXB Providers must at least support DOMResult, SAXResult, and StreamResult. It can support other derived classes of Result as well.

Parameters:

jaxbElement - The root of content tree to be marshalled.

result - XML will be sent to this Result

Throws:

JAXBException - If any unexpected problem occurs during the marshalling.

MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.

IllegalArgumentException - If any of the method parameters are null

---

public void marshal(Object jaxbElement, java.io.OutputStream os) throws JAXBException
将以 jaxbElement 为根的内容树编组到输出流中。

jaxbElement	要编组的内容树的根。
os	XML 将被添加到此流。
Throws	JAXBException: 如果进行解组期间发生不可预料的错误。
Throws	MarshalException: 如果 ValidationEventHandler 从其 handleEvent 方法返回 false，或者 Marshaller 不能编组 obj（或任何可从 obj 获得的对象）。请参阅编组 JAXB 元素。
Throws	IllegalArgumentException: 如果任何方法的参数为 null

英文文档：

marshal

void marshal(Object jaxbElement,
             OutputStream os)
             throws JAXBException

Marshal the content tree rooted at jaxbElement into an output stream.

Parameters:

jaxbElement - The root of content tree to be marshalled.

os - XML will be added to this stream.

Throws:

JAXBException - If any unexpected problem occurs during the marshalling.

MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.

IllegalArgumentException - If any of the method parameters are null

---

public void marshal(Object jaxbElement, java.io.Writer writer) throws JAXBException
将以 jaxbElement 为根的内容树编组到 Writer 中。

jaxbElement	要编组的内容树的根。
writer	XML 将被发送到此编写器。
Throws	JAXBException: 如果进行解组期间发生不可预料的错误。
Throws	MarshalException: 如果 ValidationEventHandler 从其 handleEvent 方法返回 false，或者 Marshaller 不能编组 obj（或任何可从 obj 获得的对象）。请参阅编组 JAXB 元素。
Throws	IllegalArgumentException: 如果任何方法的参数为 null

英文文档：

marshal

void marshal(Object jaxbElement,
             Writer writer)
             throws JAXBException

Marshal the content tree rooted at jaxbElement into a Writer.

Parameters:

jaxbElement - The root of content tree to be marshalled.

writer - XML will be sent to this writer.

Throws:

JAXBException - If any unexpected problem occurs during the marshalling.

MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.

IllegalArgumentException - If any of the method parameters are null

---

public void marshal(Object jaxbElement, org.xml.sax.ContentHandler handler) throws JAXBException
将以 jaxbElement 为根的内容树编组到 SAX2 事件中。

jaxbElement	要编组的内容树的根。
handler	XML 将被作为 SAX2 事件发送到此处理程序。
Throws	JAXBException: 如果进行解组期间发生不可预料的错误。
Throws	MarshalException: 如果 ValidationEventHandler 从其 handleEvent 方法返回 false，或者 Marshaller 不能编组 obj（或任何可从 obj 获得的对象）。请参阅编组 JAXB 元素。
Throws	IllegalArgumentException: 如果任何方法的参数为 null

英文文档：

marshal

void marshal(Object jaxbElement,
             ContentHandler handler)
             throws JAXBException

Marshal the content tree rooted at jaxbElement into SAX2 events.

Parameters:

jaxbElement - The root of content tree to be marshalled.

handler - XML will be sent to this handler as SAX2 events.

Throws:

JAXBException - If any unexpected problem occurs during the marshalling.

MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.

IllegalArgumentException - If any of the method parameters are null

---

public void marshal(Object jaxbElement, org.w3c.dom.Node node) throws JAXBException
将以 jaxbElement 为根的内容树编组到 DOM 树中。

jaxbElement	将被编组的内容树。
node	DOM 节点将作为此节点的子节点添加。此参数必须是一个可接受子节点（org.w3c.dom.Document、org.w3c.dom.DocumentFragment 或 org.w3c.dom.Element）的 Node。
Throws	JAXBException: 如果进行解组期间发生不可预料的错误。
Throws	MarshalException: 如果 ValidationEventHandler 从其 handleEvent 方法返回 false，或者 Marshaller 不能编组 jaxbElement（或任何可从 jaxbElement 获得的对象）。请参阅编组 JAXB 元素。
Throws	IllegalArgumentException: 如果任何方法的参数为 null

英文文档：

marshal

void marshal(Object jaxbElement,
             Node node)
             throws JAXBException

Marshal the content tree rooted at jaxbElement into a DOM tree.

Parameters:

jaxbElement - The content tree to be marshalled.

node - DOM nodes will be added as children of this node. This parameter must be a Node that accepts children (Document, DocumentFragment, or Element)

Throws:

JAXBException - If any unexpected problem occurs during the marshalling.

MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal jaxbElement (or any object reachable from jaxbElement). See Marshalling a JAXB element.

IllegalArgumentException - If any of the method parameters are null

---

public void marshal(Object jaxbElement, XMLStreamWriter writer) throws JAXBException
将以 jaxbElement 为根的内容树编组到 javax.xml.stream.XMLStreamWriter 中。

jaxbElement	将被编组的内容树。
writer	XML 将被发送到此编写器。
Throws	JAXBException: 如果进行解组期间发生不可预料的错误。
Throws	MarshalException: 如果 ValidationEventHandler 从其 handleEvent 方法返回 false，或者 Marshaller 不能编组 obj（或任何可从 obj 获得的对象）。请参阅编组 JAXB 元素。
Throws	IllegalArgumentException: 如果任何方法的参数为 null
since	JAXB 2.0

英文文档：

marshal

void marshal(Object jaxbElement,
             XMLStreamWriter writer)
             throws JAXBException

Marshal the content tree rooted at jaxbElement into a XMLStreamWriter.

Parameters:

jaxbElement - The content tree to be marshalled.

writer - XML will be sent to this writer.

Throws:

JAXBException - If any unexpected problem occurs during the marshalling.

MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.

IllegalArgumentException - If any of the method parameters are null

Since:

JAXB 2.0

---

public void marshal(Object jaxbElement, XMLEventWriter writer) throws JAXBException
将以 jaxbElement 为根的内容树编组到 javax.xml.stream.XMLEventWriter 中。

jaxbElement	要编组的以 jaxbElement 为根的内容树。
writer	XML 将被发送到此编写器。
Throws	JAXBException: 如果进行解组期间发生不可预料的错误。
Throws	MarshalException: 如果 ValidationEventHandler 从其 handleEvent 方法返回 false，或者 Marshaller 不能编组 obj（或任何可从 obj 获得的对象）。请参阅编组 JAXB 元素。
Throws	IllegalArgumentException: 如果任何方法的参数为 null
since	JAXB 2.0

英文文档：

marshal

void marshal(Object jaxbElement,
             XMLEventWriter writer)
             throws JAXBException

Marshal the content tree rooted at jaxbElement into a XMLEventWriter.

Parameters:

jaxbElement - The content tree rooted at jaxbElement to be marshalled.

writer - XML will be sent to this writer.

Throws:

JAXBException - If any unexpected problem occurs during the marshalling.

MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.

IllegalArgumentException - If any of the method parameters are null

Since:

JAXB 2.0

---

public org.w3c.dom.Node getNode(Object contentTree) throws JAXBException
获取内容树的 DOM 树视图（可选）。 如果更新了返回的 DOM 树，则这些更改也可以在内容树中看见。使用 #marshal(Object, org.w3c.dom.Node) 强行将内容树的深层复制转换成 DOM 表示形式。

contentTree	XML 内容的 JAXB Java 表示形式
return	contentTree 的 DOM 树视图
Throws	UnsupportedOperationException: 如果 JAXB 提供者实现不支持内容树的 DOM 视图
Throws	IllegalArgumentException: 如果任何方法的参数为 null
Throws	JAXBException: 如果发生任何不可预料的问题

英文文档：

getNode

Node getNode(Object contentTree)
             throws JAXBException

Get a DOM tree view of the content tree(Optional). If the returned DOM tree is updated, these changes are also visible in the content tree. Use marshal(Object, org.w3c.dom.Node) to force a deep copy of the content tree to a DOM representation.

Parameters:

contentTree - - JAXB Java representation of XML content

Returns:

the DOM tree view of the contentTree

Throws:

UnsupportedOperationException - If the JAXB provider implementation does not support a DOM view of the content tree

IllegalArgumentException - If any of the method parameters are null

JAXBException - If any unexpected problem occurs

---

public void setProperty(String name, Object value) throws PropertyException
设置 Marshaller 底层实现中的特定属性。此方法只能用于设置上文中标准 JAXB 定义的属性之一或特定于提供者的属性。试图设置未定义的属性将导致抛出 PropertyException。请参阅支持的属性。

name	要设置的属性的名称。此值可以使用一个常量字段来指定，也可以是用户提供的字符串。
value	要设置的属性值
Throws	PropertyException: 如果处理给定属性或值时发生错误
Throws	IllegalArgumentException: 如果 name 参数为 null

英文文档：

setProperty

void setProperty(String name,
                 Object value)
                 throws PropertyException

Set the particular property in the underlying implementation of Marshaller. This method can only be used to set one of the standard JAXB defined properties above or a provider specific property. Attempting to set an undefined property will result in a PropertyException being thrown. See Supported Properties.

Parameters:

name - the name of the property to be set. This value can either be specified using one of the constant fields or a user supplied string.

value - the value of the property to be set

Throws:

PropertyException - when there is an error processing the given property or value

IllegalArgumentException - If the name parameter is null

---

public Object getProperty(String name) throws PropertyException
获取 Marshaller 底层实现中的特定属性。此方法只能用于获取上文中标准 JAXB 定义的属性之一或特定于提供者的属性。试图获取未定义的属性将导致抛出 PropertyException。请参阅支持的属性。

name	将检索的属性名称
return	所请求属性的值
Throws	PropertyException: 如果检索给定属性或值属性名称时发生错误
Throws	IllegalArgumentException: 如果 name 参数为 null

英文文档：

getProperty

Object getProperty(String name)
                   throws PropertyException

Get the particular property in the underlying implementation of Marshaller. This method can only be used to get one of the standard JAXB defined properties above or a provider specific property. Attempting to get an undefined property will result in a PropertyException being thrown. See Supported Properties.

Parameters:

name - the name of the property to retrieve

Returns:

the value of the requested property

Throws:

PropertyException - when there is an error retrieving the given property or value property name

IllegalArgumentException - If the name parameter is null

---

public void setEventHandler(ValidationEventHandler handler) throws JAXBException
允许应用程序注册一个验证事件处理程序。

如果在调用任何编组 API 期间遇到任何验证错误，则 JAXB 提供者将调用验证事件处理程序。如果客户端应用程序没有在调用某个 marshal 方法之前注册验证事件处理程序，则将使用默认事件处理程序处理验证事件，默认处理程序将在遇到第一个错误或致命错误之后将终止编组操作。

调用带有 null 参数的此方法将导致 Marshaller 重新使用默认事件处理程序。

handler	验证事件处理程序
Throws	JAXBException: 如果在设置事件处理程序时发生错误

英文文档：

setEventHandler

void setEventHandler(ValidationEventHandler handler)
                     throws JAXBException

Allow an application to register a validation event handler.

The validation event handler will be called by the JAXB Provider if any validation errors are encountered during calls to any of the marshal API's. If the client application does not register a validation event handler before invoking one of the marshal methods, then validation events will be handled by the default event handler which will terminate the marshal operation after the first error or fatal error is encountered.

Calling this method with a null parameter will cause the Marshaller to revert back to the default default event handler.

Parameters:

handler - the validation event handler

Throws:

JAXBException - if an error was encountered while setting the event handler

---

public ValidationEventHandler getEventHandler() throws JAXBException
当前的事件处理程序；如果没有设置，则返回默认事件处理程序。

return	当前的 ValidationEventHandler；如果没有设置，则返回默认的事件处理程序
Throws	JAXBException: 如果获取当前的事件处理程序时遇到错误

英文文档：

getEventHandler

ValidationEventHandler getEventHandler()
                                       throws JAXBException

Return the current event handler or the default event handler if one hasn't been set.

Returns:

the current ValidationEventHandler or the default event handler if it hasn't been set

Throws:

JAXBException - if an error was encountered while getting the current event handler

---

public void setAdapter(">XmlAdapter adapter)
将已配置的 XmlAdapter 实例与此 marshaller 关联。

这是调用 setAdapter(adapter.getClass(),adapter) 的一个便捷方法。

Throws	IllegalArgumentException: 如果 adapter 参数为 null。
Throws	UnsupportedOperationException: 如果基于 JAXB 1.0 实现调用。
since	JAXB 2.0
See also	setAdapter(Class,XmlAdapter)

英文文档：

setAdapter

void setAdapter(XmlAdapter adapter)

Associates a configured instance of XmlAdapter with this marshaller.

This is a convenience method that invokes setAdapter(adapter.getClass(),adapter);.

Throws:

IllegalArgumentException - if the adapter parameter is null.

UnsupportedOperationException - if invoked agains a JAXB 1.0 implementation.

Since:

JAXB 2.0

See Also:

setAdapter(Class,XmlAdapter)

---

英文文档：

setAdapter

<A extends XmlAdapter> void setAdapter(Class<A> type,
                                       A adapter)

Associates a configured instance of XmlAdapter with this marshaller.

Every marshaller internally maintains a Map<Class,XmlAdapter>, which it uses for marshalling classes whose fields/methods are annotated with XmlJavaTypeAdapter.

This method allows applications to use a configured instance of XmlAdapter. When an instance of an adapter is not given, a marshaller will create one by invoking its default constructor.

Parameters:

type - The type of the adapter. The specified instance will be used when XmlJavaTypeAdapter.value() refers to this type.

adapter - The instance of the adapter to be used. If null, it will un-register the current adapter set for this type.

Throws:

IllegalArgumentException - if the type parameter is null.

UnsupportedOperationException - if invoked agains a JAXB 1.0 implementation.

Since:

JAXB 2.0

---

英文文档：

getAdapter

<A extends XmlAdapter> A getAdapter(Class<A> type)

Gets the adapter associated with the specified type. This is the reverse operation of the setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter) method.

Throws:

IllegalArgumentException - if the type parameter is null.

UnsupportedOperationException - if invoked agains a JAXB 1.0 implementation.

Since:

JAXB 2.0

---

public void setAttachmentMarshaller(AttachmentMarshaller am)

与上下文关联，使 XML 文档内的二进制数据能够以优化的 XML 二进制附件的形式传送。可以使用存储在 xml 文档中的内容 id URI (cid) 从 XML 文档内容模式引用附件。

Throws

IllegalStateException: 如果试图在执行编组操作期间同时调用此方法。

英文文档：

setAttachmentMarshaller

void setAttachmentMarshaller(AttachmentMarshaller am)

Associate a context that enables binary data within an XML document to be transmitted as XML-binary optimized attachment. The attachment is referenced from the XML document content model by content-id URIs(cid) references stored within the xml document.

Throws:

IllegalStateException - if attempt to concurrently call this method during a marshal operation.

---

public AttachmentMarshaller getAttachmentMarshaller()

英文文档：

getAttachmentMarshaller

AttachmentMarshaller getAttachmentMarshaller()

---

public void setSchema(javax.xml.validation.Schema schema)
指定应该用作验证后续编组操作依据的 JAXP 1.3 Schema 对象。向此方法传递 null 将禁用验证。

此方法允许调用者在对已编组的 XML 进行编组时验证它。

最初，此属性被设置为 null。

schema	作为验证编组操作依据的 Schema 对象；为 null 表示禁用验证
Throws	UnsupportedOperationException: 如果对根据引用 JAXB 1.0 映射类的 JAXBContext 而创建的 Marshaller 调用此方法，则抛出该异常
since	JAXB2.0

英文文档：

setSchema

void setSchema(Schema schema)

Specify the JAXP 1.3 Schema object that should be used to validate subsequent marshal operations against. Passing null into this method will disable validation.

This method allows the caller to validate the marshalled XML as it's marshalled.

Initially this property is set to null.

Parameters:

schema - Schema object to validate marshal operations against or null to disable validation

Throws:

UnsupportedOperationException - could be thrown if this method is invoked on an Marshaller created from a JAXBContext referencing JAXB 1.0 mapped classes

Since:

JAXB2.0

---

public javax.xml.validation.Schema getSchema()
获取用于执行编组时验证的 JAXP 1.3 Schema 对象。如果未在 marshaller 上设置 Schema，则此方法将返回 null，指示不执行编组时验证。

return	返回用于执行编组时验证的 Schema 对象；如果该对象不存在，则返回 null。
Throws	UnsupportedOperationException: 如果对根据引用 JAXB 1.0 映射类的 JAXBContext 而创建的 Marshaller 调用此方法，则抛出该异常
since	JAXB2.0

英文文档：

getSchema

Schema getSchema()

Get the JAXP 1.3 Schema object being used to perform marshal-time validation. If there is no Schema set on the marshaller, then this method will return null indicating that marshal-time validation will not be performed.

Returns:

the Schema object being used to perform marshal-time validation or null if not present.

Throws:

UnsupportedOperationException - could be thrown if this method is invoked on an Marshaller created from a JAXBContext referencing JAXB 1.0 mapped classes

Since:

JAXB2.0

---

public void setListener(Marshaller.Listener listener)

向此 Marshaller 注册编组事件回调 Listener。

每个 Marshaller 只有一个 Listener。设置 Listener 将替换以前设置的 Listener。通过将 listener 设置为 null 可注销当前的 Listener。

listener	实现 Listener 的类的实例
since	JAXB2.0

英文文档：

setListener

void setListener(Marshaller.Listener listener)

Register marshal event callback Marshaller.Listener with this Marshaller.

There is only one Listener per Marshaller. Setting a Listener replaces the previous set Listener. One can unregister current Listener by setting listener to null.

Parameters:

listener - an instance of a class that implements Marshaller.Listener

Since:

JAXB2.0

---

public Marshaller.Listener getListener()

返回向此 Marshaller 注册的 Listener。

return	注册的 Listener；如果未向此 Marshaller 注册任何 Listener，则返回 null。
since	JAXB2.0

英文文档：

getListener

Marshaller.Listener getListener()

Return Marshaller.Listener registered with this Marshaller.

Returns:

registered Marshaller.Listener or null if no Listener is registered with this Marshaller.

Since:

JAXB2.0

---

Overview  Package   Class  Tree  Deprecated  Index  Help
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

Submit a bug or feature

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.