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();
编组文件:
OutputStream os = new FileOutputStream( "nosferatu.xml" ); m.marshal( element, os );
编组到SAX ContentHandler:
// assume MyContentHandler instanceof ContentHandler m.marshal( element, new MyContentHandler() );
编组到DOM节点:
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 );
The first parameter of the overloaded Marshaller.marshal(java.lang.Object, ...) methods must be a JAXB element as computed byJAXBIntrospector.isElement(java.lang.Object)
; otherwise, a Marshaller.marshal method must throw aMarshalException
. 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 aJAXBElement
, 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
.
编码
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.
验证和成型
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.
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 invokeContentHandler.startDocument()
andContentHandler.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 APIsmarshal(Object,XMLEventWriter)
- the Marshaller will not generateXMLStreamConstants.START_DOCUMENT
andXMLStreamConstants.END_DOCUMENT
events.marshal(Object,XMLStreamWriter)
- the Marshaller will not generateXMLStreamConstants.START_DOCUMENT
andXMLStreamConstants.END_DOCUMENT
events.
"TheMarshaller
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:
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.// Invoked by Marshaller after it has created an instance of this object. boolean beforeMarshal(Marshaller); // Invoked by Marshaller after it has marshalled all properties of this object. void afterMarshal(Marshaller);The external listener callback mechanism enables the registration of a
Marshaller.Listener
instance with asetListener(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)
andMarshaller.Listener.afterMarshal(Object)
.An event callback method throwing an exception terminates the current marshal process.
JAXBContext
, Validator
, Unmarshaller
Modifier and Type | Interface and Description |
---|---|
static class |
Marshaller.Listener
使用 Marshaller 注册此类的实现的实例 ,以外部监听元帅事件。
|
Modifier and Type | Field and Description |
---|---|
static String |
JAXB_ENCODING
用于在编组的XML数据中指定输出编码的属性的名称。
|
static String |
JAXB_FORMATTED_OUTPUT
用于指定编组的XML数据是否使用换行符和缩进格式化的属性的名称。
|
static String |
JAXB_FRAGMENT
用于指定编组器是否生成文档级事件(即调用startDocument或endDocument)的属性的名称。
|
static String |
JAXB_NO_NAMESPACE_SCHEMA_LOCATION
用于指定要排列在编组XML输出中的xsi:noNamespaceSchemaLocation属性值的属性名称。
|
static String |
JAXB_SCHEMA_LOCATION
用于指定要排列在编组XML输出中的xsi:schemaLocation属性值的属性名称。
|
Modifier and Type | Method and Description |
---|---|
<A extends XmlAdapter> |
getAdapter(类<A> type)
获取与指定类型相关联的适配器。
|
AttachmentMarshaller |
getAttachmentMarshaller() |
ValidationEventHandler |
getEventHandler()
返回当前事件处理程序或默认事件处理程序(如果尚未设置)。
|
Marshaller.Listener |
getListener()
|
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, File output)
将根源于
jaxbElement的内容树
组织成一个文件。
|
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的内容树
组织成一个作家。
|
void |
marshal(Object jaxbElement, XMLEventWriter writer)
将根据jaxbElement的内容树组织成一个 XMLEventWriter 。
|
void |
marshal(Object jaxbElement, XMLStreamWriter writer)
将根据jaxbElement的内容树组织成一个 XMLStreamWriter 。
|
<A extends XmlAdapter> |
setAdapter(类<A> type, A adapter)
相关联的配置实例 XmlAdapter 这个编组。
|
void |
setAdapter(XmlAdapter adapter)
相关联的配置实例 XmlAdapter 这个编组。
|
void |
setAttachmentMarshaller(AttachmentMarshaller am)
关联使XML文档中的二进制数据能够以XML二进制优化的附件传输的上下文。
|
void |
setEventHandler(ValidationEventHandler handler)
允许应用程序注册验证事件处理程序。
|
void |
setListener(Marshaller.Listener listener)
注册元帅事件回调 Marshaller.Listener 与这Marshaller 。
|
void |
setProperty(String name, Object value)
在底层实现中设置特定的属性
Marshaller 。
|
void |
setSchema(Schema schema)
|
static final String JAXB_ENCODING
static final String JAXB_FORMATTED_OUTPUT
static final String JAXB_SCHEMA_LOCATION
static final String JAXB_NO_NAMESPACE_SCHEMA_LOCATION
static final String JAXB_FRAGMENT
void marshal(Object jaxbElement, Result result) throws JAXBException
所有JAXB提供者必须至少支持DOMResult
, SAXResult
和StreamResult
。 它也可以支持Result的其他派生类。
jaxbElement
- 要编组的内容树的根。
result
- 将会将XML发送到此结果
JAXBException
- 如果编组期间出现意外问题。
MarshalException
- 如果ValidationEventHandler
从其handleEvent方法返回false,或者Marshaller无法组织obj (或任何可从obj可访问的对象)。
见Marshalling a JAXB element 。
IllegalArgumentException
- 如果任何方法参数为空
void marshal(Object jaxbElement, OutputStream os) throws JAXBException
jaxbElement
- 要编组的内容树的根。
os
- XML将被添加到此流。
JAXBException
- 如果编组期间出现意外问题。
MarshalException
- 如果ValidationEventHandler
从其handleEvent方法返回false,或者Marshaller无法组织obj (或任何可从obj访问的对象)。
见Marshalling a JAXB element 。
IllegalArgumentException
- 如果任何方法参数为空
void marshal(Object jaxbElement, File output) throws JAXBException
jaxbElement
- 要编组的内容树的根。
output
- 要写入的文件。
如果这个文件已经存在,它将被覆盖。
JAXBException
- 如果在编组过程中发生意外问题。
MarshalException
- 如果ValidationEventHandler
从其handleEvent方法返回false,或者Marshaller无法组合obj (或任何可从obj可访问的对象)。
见Marshalling a JAXB element 。
IllegalArgumentException
- 如果任何方法参数为空
void marshal(Object jaxbElement, Writer writer) throws JAXBException
jaxbElement
- 要编组的内容树的根。
writer
- XML将被发送到这个作者。
JAXBException
- 如果编组期间出现意外问题。
MarshalException
- 如果ValidationEventHandler
从其handleEvent方法返回false,或者Marshaller无法组织obj (或任何可从obj访问的对象)。
见Marshalling a JAXB element 。
IllegalArgumentException
- 如果任何方法参数为空
void marshal(Object jaxbElement, ContentHandler handler) throws JAXBException
jaxbElement
- 要编组的内容树的根。
handler
- XML将作为SAX2事件发送到此处理程序。
JAXBException
- 如果在编组过程中发生意外问题。
MarshalException
- 如果ValidationEventHandler
从其handleEvent方法返回false,或者Marshaller无法组织obj (或任何可从obj可访问的对象)。
见Marshalling a JAXB element 。
IllegalArgumentException
- 如果任何方法参数为空
void marshal(Object jaxbElement, Node node) throws JAXBException
jaxbElement
- 要编组的内容树。
node
- 将作为此节点的子节点添加DOM节点。
此参数必须是一个可接受子(节点Document
, DocumentFragment
,或Element
)
JAXBException
- 如果编组期间出现意外问题。
MarshalException
- 如果ValidationEventHandler
从其handleEvent方法返回false,或者Marshaller无法组织jaxbElement (或任何可从jaxbElement可访问的对象)。
见Marshalling a JAXB element 。
IllegalArgumentException
- 如果任何方法参数为空
void marshal(Object jaxbElement, XMLStreamWriter writer) throws JAXBException
XMLStreamWriter
。
jaxbElement
- 要编组的内容树。
writer
- XML将被发送到这个作者。
JAXBException
- 如果在编组过程中发生意外问题。
MarshalException
- 如果ValidationEventHandler
从其handleEvent方法返回false,或者Marshaller无法组合obj (或任何可从obj访问的对象)。
参见Marshalling a JAXB element 。
IllegalArgumentException
- 如果任何方法参数为空
void marshal(Object jaxbElement, XMLEventWriter writer) throws JAXBException
XMLEventWriter
。
jaxbElement
- 根据要编组的jaxbElement的内容树。
writer
- XML将被发送给作者。
JAXBException
- 如果在编组过程中出现意外问题。
MarshalException
- 如果ValidationEventHandler
从其handleEvent方法返回false,或者Marshaller无法组织obj (或任何可从obj可访问的对象)。
见Marshalling a JAXB element 。
IllegalArgumentException
- 如果任何方法参数为空
Node getNode(Object contentTree) throws JAXBException
contentTree
- - JAXB XML内容的Java表示
UnsupportedOperationException
- 如果JAXB提供程序实现不支持内容树的DOM视图
IllegalArgumentException
- 如果任何方法参数为空
JAXBException
- 如果发生意外问题
void setProperty(String name, Object value) throws PropertyException
name
- 要设置的属性的名称。
可以使用常量字段或用户提供的字符串指定此值。
value
- 要设置的属性的值
PropertyException
- 处理给定属性或值时出错
IllegalArgumentException
- 如果name参数为空
Object getProperty(String name) throws PropertyException
name
- 要检索的属性的名称
PropertyException
- 检索给定属性或值属性名称时出现错误
IllegalArgumentException
- 如果name参数为null
void setEventHandler(ValidationEventHandler handler) throws JAXBException
如果在任何元帅API的调用期间遇到任何验证错误,JAXB提供者将调用验证事件处理程序。 如果客户端应用程序在调用其中一个元数据方法之前没有注册验证事件处理程序,则验证事件将由默认事件处理程序处理,该事件处理程序将在遇到第一个错误或致命错误后终止元组操作。
使用null参数调用此方法将导致Marshaller恢复为默认的默认事件处理程序。
handler
- 验证事件处理程序
JAXBException
- 如果在设置事件处理程序时遇到错误
ValidationEventHandler getEventHandler() throws JAXBException
JAXBException
- 如果在获取当前事件处理程序时遇到错误
void setAdapter(XmlAdapter adapter)
XmlAdapter
这个编组。
这是调用setAdapter(adapter.getClass(),adapter);
的方便方法。
IllegalArgumentException
- 如果适配器参数为空。
UnsupportedOperationException
- 如果
UnsupportedOperationException
调用JAXB 1.0实现。
setAdapter(Class,XmlAdapter)
<A extends XmlAdapter> void setAdapter(类<A> type, A adapter)
XmlAdapter
这个编组。
每编组内部维护一个Map
< 类
, XmlAdapter
>,它使用用于编组类,它们的字段/方法的注解为XmlJavaTypeAdapter
。
此方法允许应用程序使用的一个配置实例XmlAdapter
。 当没有给出适配器的实例时,编组者将通过调用其默认构造函数来创建一个。
type
- 适配器的类型。
当XmlJavaTypeAdapter.value()
引用此类型时,将使用指定的实例。
adapter
- 要使用的适配器的实例。
如果为空,它将取消注册此类型的当前适配器集。
IllegalArgumentException
- 如果type参数为null。
UnsupportedOperationException
- 如果
UnsupportedOperationException
调用JAXB 1.0实现。
<A extends XmlAdapter> A getAdapter(类<A> type)
setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter)
方法的反向操作。
IllegalArgumentException
- 如果type参数为null。
UnsupportedOperationException
- 如果
UnsupportedOperationException
调用JAXB 1.0实现。
void setAttachmentMarshaller(AttachmentMarshaller am)
关联使XML文档中的二进制数据能够以XML二进制优化的附件传输的上下文。 附件由XML文档内容模型通过存储在xml文档中的content-id URI(cid)引用引用。
IllegalStateException
- 如果在组织操作期间尝试同时调用此方法。
AttachmentMarshaller getAttachmentMarshaller()
void setSchema(Schema schema)
schema
- 用于验证
schema
模式对象或null以禁用验证
UnsupportedOperationException
- 如果在引用JAXB 1.0映射类的JAXBContext创建的Marshaller上调用此方法,则可能会抛出
Schema getSchema()
Schema
对象。
如果在编组器中没有设置Schema,则该方法将返回null,表示将不执行组织时间验证。
UnsupportedOperationException
- 如果在引用JAXB 1.0映射类的JAXBContext创建的Marshaller上调用此方法,则可能会抛出
void setListener(Marshaller.Listener listener)
注册元帅事件回调Marshaller.Listener
与这Marshaller
。
每个Marshaller只有一个监听器。 设置侦听器将替换以前设置的侦听器。 可以通过将侦听器设置为null来取消注册当前侦听器。
listener
-实现一个类的实例Marshaller.Listener
Marshaller.Listener getListener()
返回Marshaller.Listener
注册了这个Marshaller
。
Marshaller.Listener
或null
如果没有监听器注册此Marshaller。