JAXB
v2.0

javax.xml.bind
Interface Marshaller

All Known Implementing Classes:
AbstractMarshallerImpl

public interface Marshaller

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 in all following code fragments:

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

Marshalling to a File:

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

Marshalling to a SAX ContentHandler:

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

Marshalling to a DOM Node:

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

       m.marshal( obj, doc );
    

Marshalling to a java.io.OutputStream:

       m.marshal( obj, System.out );
    

Marshalling to a java.io.Writer:

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

Marshalling to a javax.xml.transform.SAXResult:

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

       m.marshal( obj, result );
    

Marshalling to a javax.xml.transform.DOMResult:

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

Marshalling to a javax.xml.transform.StreamResult:

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

Marshalling to a javax.xml.stream.XMLStreamWriter:

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

Marshalling to a javax.xml.stream.XMLEventWriter:

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

Marshalling java.lang.Object Objects

Although each of the marshal methods accepts a java.lang.Object as its first parameter, JAXB Providers are not required to be able to marshal any arbitrary java.lang.Object. If the JAXBContext object that was used to create this Marshaller does not have enough information to know how to marshal the object parameter (or any objects reachable from it), then the marshal operation will throw a MarshalException. Even though JAXB Providers are not required to be able to marshal arbitrary java.lang.Object objects, some providers may allow it.

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.

Although there is no way to enable validation during the marshal operation, it is possible that certain types of validation events will be detected during the operation. These 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 the default event handler which will terminate the marshal operation after encountering the first error or fatal error.

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:

Since:
JAXB1.0
Version:
$Revision: 1.7 $ $Date: 2005/06/16 17:15:59 $
Author:
See Also:
JAXBContext, Validator, Unmarshaller

Field Summary
static java.lang.String JAXB_ENCODING
          The name of the property used to specify the output encoding in the marshalled XML data.
static java.lang.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 java.lang.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 java.lang.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 java.lang.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(java.lang.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.
 org.w3c.dom.Node getNode(java.lang.Object contentTree)
          Get a DOM tree view of the content tree(Optional).
 java.lang.Object getProperty(java.lang.String name)
          Get the particular property in the underlying implementation of Marshaller.
 javax.xml.validation.Schema getSchema()
          Get the JAXP 1.3 Schema object being used to perform marshal-time validation.
 void marshal(java.lang.Object obj, org.xml.sax.ContentHandler handler)
          Marshal the content tree rooted at obj into SAX2 events.
 void marshal(java.lang.Object obj, org.w3c.dom.Node node)
          Marshal the content tree rooted at obj into a DOM tree.
 void marshal(java.lang.Object obj, java.io.OutputStream os)
          Marshal the content tree rooted at obj into an output stream.
 void marshal(java.lang.Object obj, javax.xml.transform.Result result)
          Marshal the content tree rooted at obj into the specified javax.xml.transform.Result.
 void marshal(java.lang.Object obj, java.io.Writer writer)
          Marshal the content tree rooted at obj into a Writer.
 void marshal(java.lang.Object obj, javax.xml.stream.XMLEventWriter writer)
          Marshal the content tree rooted at obj into a XMLEventWriter.
 void marshal(java.lang.Object obj, javax.xml.stream.XMLStreamWriter writer)
          Marshal the content tree rooted at obj into a XMLStreamWriter.
<A extends XmlAdapter>
void
setAdapter(java.lang.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 setProperty(java.lang.String name, java.lang.Object value)
          Set the particular property in the underlying implementation of Marshaller.
 void setSchema(javax.xml.validation.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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

marshal

void marshal(java.lang.Object obj,
             javax.xml.transform.Result result)
             throws JAXBException
Marshal the content tree rooted at obj 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:
obj - The 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 objects.
java.lang.IllegalArgumentException - If any of the method parameters are null

marshal

void marshal(java.lang.Object obj,
             java.io.OutputStream os)
             throws JAXBException
Marshal the content tree rooted at obj into an output stream.

Parameters:
obj - The 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 objects.
java.lang.IllegalArgumentException - If any of the method parameters are null

marshal

void marshal(java.lang.Object obj,
             java.io.Writer writer)
             throws JAXBException
Marshal the content tree rooted at obj into a Writer.

Parameters:
obj - 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 objects.
java.lang.IllegalArgumentException - If any of the method parameters are null

marshal

void marshal(java.lang.Object obj,
             org.xml.sax.ContentHandler handler)
             throws JAXBException
Marshal the content tree rooted at obj into SAX2 events.

Parameters:
obj - The 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 objects.
java.lang.IllegalArgumentException - If any of the method parameters are null

marshal

void marshal(java.lang.Object obj,
             org.w3c.dom.Node node)
             throws JAXBException
Marshal the content tree rooted at obj into a DOM tree.

Parameters:
obj - 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 obj (or any object reachable from obj). See Marshalling objects.
java.lang.IllegalArgumentException - If any of the method parameters are null

marshal

void marshal(java.lang.Object obj,
             javax.xml.stream.XMLStreamWriter writer)
             throws JAXBException
Marshal the content tree rooted at obj into a XMLStreamWriter.

Parameters:
obj - 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 objects.
java.lang.IllegalArgumentException - If any of the method parameters are null
Since:
JAXB 2.0

marshal

void marshal(java.lang.Object obj,
             javax.xml.stream.XMLEventWriter writer)
             throws JAXBException
Marshal the content tree rooted at obj into a XMLEventWriter.

Parameters:
obj - 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 objects.
java.lang.IllegalArgumentException - If any of the method parameters are null
Since:
JAXB 2.0

getNode

org.w3c.dom.Node getNode(java.lang.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:
java.lang.UnsupportedOperationException - If the JAXB provider implementation does not support a DOM view of the content tree
java.lang.IllegalArgumentException - If any of the method parameters are null
JAXBException - If any unexpected problem occurs

setProperty

void setProperty(java.lang.String name,
                 java.lang.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
java.lang.IllegalArgumentException - If the name parameter is null

getProperty

java.lang.Object getProperty(java.lang.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
java.lang.IllegalArgumentException - If the name parameter is null

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

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

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:
java.lang.IllegalArgumentException - if the adapter parameter is null.
java.lang.UnsupportedOperationException - if invoked agains a JAXB 1.0 implementation.
Since:
JAXB 2.0
See Also:
setAdapter(Class,XmlAdapter)

setAdapter

<A extends XmlAdapter> void setAdapter(java.lang.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:
java.lang.IllegalArgumentException - if the type parameter is null.
java.lang.UnsupportedOperationException - if invoked agains a JAXB 1.0 implementation.
Since:
JAXB 2.0

getAdapter

<A extends XmlAdapter> A getAdapter(java.lang.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:
java.lang.IllegalArgumentException - if the type parameter is null.
java.lang.UnsupportedOperationException - if invoked agains a JAXB 1.0 implementation.
Since:
JAXB 2.0

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:
java.lang.IllegalStateException - if attempt to concurrently call this method during a marshal operation.

getAttachmentMarshaller

AttachmentMarshaller getAttachmentMarshaller()

setSchema

void setSchema(javax.xml.validation.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:
java.lang.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

getSchema

javax.xml.validation.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:
java.lang.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

JAXB 2.0 PD Specification License


Comments to: spec-comments@jsr222.dev.java.net
More information at: http://java.sun.com/xml/jaxb

Copyright © 2004 by Sun Microsystems, Inc., 901 San Antonio Road,
Palo Alto, California, 94303, U.S.A. All Rights Reserved.