接口 Marshaller
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，此属性具有不同的含义：
marshal(Object,ContentHandler)：Marshaller 不会调用ContentHandler.startDocument()和ContentHandler.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 不会生成XMLStreamConstants.START_DOCUMENT和XMLStreamConstants.END_DOCUMENT事件。marshal(Object,XMLStreamWriter)：Marshaller 不会生成XMLStreamConstants.START_DOCUMENT和XMLStreamConstants.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);外部侦听器回调机制支持
Marshaller.Listener实例使用setListener(Listener)的注册。外部侦听器接收所有回调事件，从而允许用比逐个类地定义回调方法更为集中的方式处理事件。“类定义的”事件回调方法和外部侦听器事件回调方法相互独立，可以对一个事件同时调用。两种侦听器回调方法都存在时，按照
Marshaller.Listener.beforeMarshal(Object)和Marshaller.Listener.afterMarshal(Object)中定义的顺序对它们进行调用。抛出异常的事件回调方法会终止当前的编组进程。
- 从以下版本开始：
- JAXB 1.0
- 另请参见：
-
JAXBContext,Validator,Unmarshaller
| 嵌套类摘要 | |
|---|---|
static class |
Marshaller.Listener向 |
| 字段摘要 | |
|---|---|
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 属性值的属性名称。 |
| 方法摘要 | ||
|---|---|---|
|
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 中。 |
|
|
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