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 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 );
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或专件)。
|
static String |
JAXB_NO_NAMESPACE_SCHEMA_LOCATION
使用指定的XSI的属性的名称:nonamespaceschemalocation属性值放在整理XML输出。
|
static String |
JAXB_SCHEMA_LOCATION
使用指定的XSI的属性的名称:schemaLocation属性值放在整理XML输出。
|
Modifier and Type | Method and Description |
---|---|
<A extends XmlAdapter> |
getAdapter(类<A> type)
获取与指定类型关联的适配器。
|
AttachmentMarshaller |
getAttachmentMarshaller() |
ValidationEventHandler |
getEventHandler()
如果一个没有被设置,返回当前事件处理程序或默认事件处理程序。
|
Marshaller.Listener |
getListener()
返回
Marshaller.Listener 注册这个
Marshaller 。
|
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 登记事件回调
Marshaller.Listener 元帅。
|
void |
setProperty(String name, Object value)
在
Marshaller底层实现设置特定的属性。
|
void |
setSchema(Schema schema)
指定JAXP 1.3
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
所有的API提供商必须至少支持DOMResult
,SAXResult
,和StreamResult
。它可以支持Result以及其他派生类。
jaxbElement
-内容整理根树。
result
XML将被发送到这个结果
JAXBException
-如果在编组发生任何意外的问题。
MarshalException
-如果
ValidationEventHandler
返回false其
handleEvent法或
Marshaller无法
obj元帅(或任何物体可从
obj)。看到
Marshalling a JAXB element。
IllegalArgumentException
-如果任何方法的参数是空的
void marshal(Object jaxbElement, OutputStream os) throws JAXBException
jaxbElement
-内容整理根树。
os
XML将被添加到该流。
JAXBException
-如果在编组发生任何意外的问题。
MarshalException
-如果
ValidationEventHandler
返回false其
handleEvent法或
Marshaller无法
obj元帅(或任何物体可从
obj)。看到
Marshalling a JAXB element。
IllegalArgumentException
-如果任何方法的参数是空的
void marshal(Object jaxbElement, File output) throws JAXBException
jaxbElement
-内容整理根树。
output
文件被写入。如果该文件已经存在,它将被覆盖。
JAXBException
-如果在编组发生任何意外的问题。
MarshalException
-如果
ValidationEventHandler
返回false其
handleEvent法或
Marshaller无法
obj元帅(或任何物体可从
obj)。看到
Marshalling a JAXB element。
IllegalArgumentException
-如果任何方法的参数是空的
void marshal(Object jaxbElement, Writer writer) throws JAXBException
jaxbElement
-内容整理根树。
writer
XML将被发送到这个作家。
JAXBException
-如果在编组发生任何意外的问题。
MarshalException
-如果
ValidationEventHandler
返回false其
handleEvent法或
Marshaller无法
obj元帅(或任何物体可从
obj)。看到
Marshalling a JAXB element。
IllegalArgumentException
-如果任何方法的参数是空的
void marshal(Object jaxbElement, ContentHandler handler) throws JAXBException
jaxbElement
-内容整理根树。
handler
XML将被发送到这个处理SAX2事件。
JAXBException
-如果在编组发生任何意外的问题。
MarshalException
-如果
ValidationEventHandler
返回false其
handleEvent法或
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
返回false其
handleEvent法或
Marshaller无法
jaxbElement元帅(或任何物体可从
jaxbElement)。看到
Marshalling a JAXB element。
IllegalArgumentException
-如果任何方法的参数是空的
void marshal(Object jaxbElement, XMLStreamWriter writer) throws JAXBException
XMLStreamWriter
。
jaxbElement
-内容被整理。
writer
XML将被发送到这个作家。
JAXBException
-如果在编组发生任何意外的问题。
MarshalException
-如果
ValidationEventHandler
返回false其
handleEvent法或
Marshaller无法
obj元帅(或任何物体可从
obj)。看到
Marshalling a JAXB element。
IllegalArgumentException
-如果任何方法的参数是空的
void marshal(Object jaxbElement, XMLEventWriter writer) throws JAXBException
XMLEventWriter
。
jaxbElement
内容-树在jaxbelement被整理。
writer
XML将被发送到这个作家。
JAXBException
-如果在编组发生任何意外的问题。
MarshalException
-如果
ValidationEventHandler
返回false其
handleEvent法或
Marshaller无法
obj元帅(或任何物体可从
obj)。看到
Marshalling a JAXB element。
IllegalArgumentException
-如果任何方法的参数是空的
Node getNode(Object contentTree) throws JAXBException
marshal(Object, org.w3c.dom.Node)
迫使内容树深拷贝到一个DOM表示。
contentTree
- JAXB java的XML表示的内容
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参数为空
void setEventHandler(ValidationEventHandler handler) throws JAXBException
验证事件处理程序将被JAXB提供者如果任何验证期间遇到错误调用任何元帅的API的。如果客户端应用程序不登记验证事件处理程序调用一个元帅的方法之前,然后验证事件将被默认的事件处理程序将后遇到的第一个错误或致命错误终止元帅作业处理。
使用null参数调用此方法将导致指挥恢复到默认的默认事件处理程序。
handler
-验证事件处理程序
JAXBException
如果同时设置事件处理程序时出错
ValidationEventHandler getEventHandler() throws JAXBException
JAXBException
-如果在当前的事件处理程序时出错
void setAdapter(XmlAdapter adapter)
XmlAdapter
这个指挥。
这是一个方便的方法调用setAdapter(adapter.getClass(),adapter);
。
IllegalArgumentException
-如果适配器参数为空。
UnsupportedOperationException
对JAXB 1实施。
setAdapter(Class,XmlAdapter)
<A extends XmlAdapter> void setAdapter(类<A> type, A adapter)
XmlAdapter
这个指挥。
每一个指挥内部保持Map
< 类
,XmlAdapter
>,它使用编组的字段/方法注释的XmlJavaTypeAdapter
类。
这种方法允许应用程序使用的配置实例XmlAdapter
。当适配器的实例是不给,一个指挥将创建一个通过调用其默认构造函数。
type
-适配器的类型。指定的实例时将使用
XmlJavaTypeAdapter.value()
指的是这种类型。
adapter
-适配器要使用的实例。如果为空,它将不为这种类型的当前适配器设置。
IllegalArgumentException
-如果类型参数为空。
UnsupportedOperationException
对JAXB 1实施。
<A extends XmlAdapter> A getAdapter(类<A> type)
setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter)
反向操作的方法。
IllegalArgumentException
-如果类型参数为空。
UnsupportedOperationException
对JAXB 1实施。
void setAttachmentMarshaller(AttachmentMarshaller am)
将一个可在XML文档中的二进制数据作为XML二进制优化附件传输的上下文关联。附件是引用XML文档的内容模型的内容ID URI(CID)存储在XML文档中的引用。
IllegalStateException
如果试图同时调用此方法一个元帅在运行。
AttachmentMarshaller getAttachmentMarshaller()
void setSchema(Schema schema)
schema
架构对象验证元帅打击或空禁用验证
UnsupportedOperationException
可以如果这个方法是从送引用JAXB 1映射的类创建了一个指挥调用抛出
Schema getSchema()
Schema
对象被用来执行元帅的时间验证。如果没有模式设置在指挥,那么这个方法将返回null表示元帅时间验证将不会执行。
UnsupportedOperationException
可以如果这个方法是从送引用JAXB 1映射的类创建了一个指挥调用抛出
void setListener(Marshaller.Listener listener)
这Marshaller
登记事件回调Marshaller.Listener
元帅。
有每指挥只有一个听众。设置一个侦听器替换前一个侦听器。一个可以注销当前听众通过设置监听器null。
listener
-一个类实现
Marshaller.Listener
实例
Marshaller.Listener getListener()
Marshaller.Listener
或
null
如果没有监听器注册这个指挥。
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.