| javax.xml.bind.Marshaller
All known Subclasses: javax.xml.bind.helpers.AbstractMarshallerImpl,
Marshaller | public interface Marshaller (Code) | |
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
Marshaller.setProperty(String,Object) 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,
javax.xml.bind.helpers.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:
-
Marshaller.marshal(Object,org.xml.sax.ContentHandler) marshal(Object,ContentHandler) - the Marshaller won't
invoke
org.xml.sax.ContentHandler.startDocument and
org.xml.sax.ContentHandler.endDocument .
-
Marshaller.marshal(Object,org.w3c.dom.Node) marshal(Object,Node) - the property has no effect on this
API.
-
Marshaller.marshal(Object,java.io.OutputStream) marshal(Object,OutputStream) - the Marshaller won't
generate an xml declaration.
-
Marshaller.marshal(Object,java.io.Writer) marshal(Object,Writer) - the Marshaller won't
generate an xml declaration.
-
Marshaller.marshal(Object,javax.xml.transform.Result) marshal(Object,Result) - depends on the kind of
Result object, see semantics for Node, ContentHandler, and Stream APIs
-
Marshaller.marshal(Object,javax.xml.stream.XMLEventWriter) marshal(Object,XMLEventWriter) - the
Marshaller will not generate
javax.xml.stream.events.XMLEvent.START_DOCUMENT and
javax.xml.stream.events.XMLEvent.END_DOCUMENT events.
-
Marshaller.marshal(Object,javax.xml.stream.XMLStreamWriter) marshal(Object,XMLStreamWriter) - the
Marshaller will not generate
javax.xml.stream.events.XMLEvent.START_DOCUMENT and
javax.xml.stream.events.XMLEvent.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);
// Invoked by Marshaller after it has marshalled all properties of this object.
void afterMmarshal(Marshaller);
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
Listener
instance with a
Marshaller.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
Listener.beforeMarshal(Object) and
Listener.afterMarshal(Object) .
An event callback method throwing an exception terminates the current marshal process.
author: - Kohsuke Kawaguchi, Sun Microsystems, Inc.
- Ryan Shoemaker, Sun Microsystems, Inc.
- Joe Fialli, Sun Microsystems, Inc.
version: $Revision: 1.21 $ $Date: 2006/08/28 17:56:41 $ See Also: JAXBContext See Also: Validator See Also: Unmarshaller since: JAXB1.0 |
Inner Class :abstract public static class Listener | |
Field Summary | |
final public static String | JAXB_ENCODING The name of the property used to specify the output encoding in
the marshalled XML data. | final public 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. | final public 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). | final public 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. | final public 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 | |
public A | getAdapter(Class<A> type) Gets the adapter associated with the specified type. | AttachmentMarshaller | getAttachmentMarshaller() | public ValidationEventHandler | getEventHandler() Return the current event handler or the default event handler if one
hasn't been set. | public Listener | getListener() Return
Listener registered with this
Marshaller . | public org.w3c.dom.Node | getNode(java.lang.Object contentTree) 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. | public Object | getProperty(String name) Get the particular property in the underlying implementation of
Marshaller. | public Schema | getSchema() Get the JAXP 1.3
javax.xml.validation.Schema Schema object
being used to perform marshal-time validation. | public void | marshal(Object jaxbElement, javax.xml.transform.Result result) Marshal the content tree rooted at jaxbElement into the specified
javax.xml.transform.Result.
All JAXB Providers must at least support
javax.xml.transform.dom.DOMResult ,
javax.xml.transform.sax.SAXResult , and
javax.xml.transform.stream.StreamResult . | public void | marshal(Object jaxbElement, java.io.OutputStream os) Marshal the content tree rooted at jaxbElement into an output stream.
Parameters: jaxbElement - The root of content tree to be marshalled. | public void | marshal(Object jaxbElement, File output) Marshal the content tree rooted at jaxbElement into a file.
Parameters: jaxbElement - The root of content tree to be marshalled. Parameters: output - File to be written. | public void | marshal(Object jaxbElement, java.io.Writer writer) Marshal the content tree rooted at jaxbElement into a Writer.
Parameters: jaxbElement - The root of content tree to be marshalled. | public void | marshal(Object jaxbElement, org.xml.sax.ContentHandler handler) Marshal the content tree rooted at jaxbElement into SAX2 events.
Parameters: jaxbElement - The root of content tree to be marshalled. | public void | marshal(Object jaxbElement, org.w3c.dom.Node node) Marshal the content tree rooted at jaxbElement into a DOM tree.
Parameters: jaxbElement - The content tree to be marshalled. | public void | marshal(Object jaxbElement, javax.xml.stream.XMLStreamWriter writer) Marshal the content tree rooted at jaxbElement into a
javax.xml.stream.XMLStreamWriter .
Parameters: jaxbElement - The content tree to be marshalled. | public void | marshal(Object jaxbElement, javax.xml.stream.XMLEventWriter writer) Marshal the content tree rooted at jaxbElement into a
javax.xml.stream.XMLEventWriter .
Parameters: jaxbElement - The content tree rooted at jaxbElement to be marshalled. | public void | setAdapter(XmlAdapter adapter) Associates a configured instance of
XmlAdapter with this marshaller. | public void | setAdapter(Class<A> type, A adapter) Associates a configured instance of
XmlAdapter with this marshaller.
Every marshaller internally maintains a
java.util.Map <
Class ,
XmlAdapter >,
which it uses for marshalling classes whose fields/methods are annotated
with
javax.xml.bind.annotation.adapters.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. | void | setAttachmentMarshaller(AttachmentMarshaller am) Associate a context that enables binary data within an XML document
to be transmitted as XML-binary optimized attachment. | public void | setEventHandler(ValidationEventHandler handler) 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. | public void | setListener(Listener listener)
Register marshal event callback
Listener with this
Marshaller .
There is only one Listener per Marshaller. | public void | setProperty(String name, Object value) Set the particular property in the underlying implementation of
Marshaller. | public void | setSchema(Schema schema) Specify the JAXP 1.3
javax.xml.validation.Schema Schema object that should be used to validate subsequent marshal operations
against. |
JAXB_ENCODING | final public static String JAXB_ENCODING(Code) | | The name of the property used to specify the output encoding in
the marshalled XML data.
|
JAXB_FORMATTED_OUTPUT | final public static String JAXB_FORMATTED_OUTPUT(Code) | | The name of the property used to specify whether or not the marshalled
XML data is formatted with linefeeds and indentation.
|
JAXB_FRAGMENT | final public static String JAXB_FRAGMENT(Code) | | The name of the property used to specify whether or not the marshaller
will generate document level events (ie calling startDocument or endDocument).
|
JAXB_NO_NAMESPACE_SCHEMA_LOCATION | final public static String JAXB_NO_NAMESPACE_SCHEMA_LOCATION(Code) | | The name of the property used to specify the
xsi:noNamespaceSchemaLocation attribute value to place in the marshalled
XML output.
|
JAXB_SCHEMA_LOCATION | final public static String JAXB_SCHEMA_LOCATION(Code) | | The name of the property used to specify the xsi:schemaLocation
attribute value to place in the marshalled XML output.
|
getEventHandler | public ValidationEventHandler getEventHandler() throws JAXBException(Code) | | Return the current event handler or the default event handler if one
hasn't been set.
the current ValidationEventHandler or the default event handlerif it hasn't been set throws: JAXBException - if an error was encountered while getting the current event handler |
getListener | public Listener getListener()(Code) | | Return
Listener registered with this
Marshaller .
registered Listener or null if no Listener is registered with this Marshaller. since: JAXB2.0 |
getProperty | public Object getProperty(String name) throws PropertyException(Code) | | 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 the value of the requested property throws: PropertyException - when there is an error retrieving the given property or valueproperty name throws: IllegalArgumentException - If the name parameter is null |
getSchema | public Schema getSchema()(Code) | | Get the JAXP 1.3
javax.xml.validation.Schema 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.
the Schema object being used to perform marshal-timevalidation or null if not present. throws: UnsupportedOperationException - could be thrown if this method isinvoked on an Marshaller created from a JAXBContext referencingJAXB 1.0 mapped classes since: JAXB2.0 |
marshal | public void marshal(Object jaxbElement, File output) throws JAXBException(Code) | | Marshal the content tree rooted at jaxbElement into a file.
Parameters: jaxbElement - The root of content tree to be marshalled. Parameters: output - File to be written. If this file already exists, it will be overwritten. throws: JAXBException - If any unexpected problem occurs during the marshalling. throws: MarshalException - If the ValidationEventHandler ValidationEventHandlerreturns false from its handleEvent method or theMarshaller is unable to marshal obj (or anyobject reachable from obj). See Marshalling a JAXB element. throws: IllegalArgumentException - If any of the method parameters are null since: JAXB2.1 |
setAttachmentMarshaller | void setAttachmentMarshaller(AttachmentMarshaller am)(Code) | | 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 thismethod during a marshal operation. |
setEventHandler | public void setEventHandler(ValidationEventHandler handler) throws JAXBException(Code) | | 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 theevent handler |
setListener | public void setListener(Listener listener)(Code) | |
Register marshal event callback
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 Listener since: JAXB2.0 |
setProperty | public void setProperty(String name, Object value) throws PropertyException(Code) | | 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 eitherbe specified using one of the constant fields or a user supplied string. Parameters: value - the value of the property to be set throws: PropertyException - when there is an error processing the givenproperty or value throws: IllegalArgumentException - If the name parameter is null |
setSchema | public void setSchema(Schema schema)(Code) | | Specify the JAXP 1.3
javax.xml.validation.Schema 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 isinvoked on an Marshaller created from a JAXBContext referencingJAXB 1.0 mapped classes since: JAXB2.0 |
|
|