javax.xml.bind
Interface Marshaller

All Known Subinterfaces:

JMMarshaller

All Known Implementing Classes:

AbstractMarshallerImpl, JMMarshallerImpl

public interface Marshaller

An instance of Marshaller may be obtained by the JAXB user to serialize JAXB objects to various flavours of XML. The created XML may be:

A byte stream OutputStream	marshal(Object, java.io.OutputStream)
A character stream Writer	marshal(Object, java.io.Writer)

Since:

JAXB1.0

Author:

JSR-31

Field Summary

static java.lang.String	JAXB_ENCODING Name of the property that allows to choose the encoding.
static java.lang.String	JAXB_FORMATTED_OUTPUT Name of the property that allows to choose whether the generated XML should be formatted (human readable, indented) or not.
static java.lang.String	JAXB_NO_NAMESPACE_SCHEMA_LOCATION If this property is set to another value than null, then the Marshaller will create an attribute xsi:noNamespaceSchemaLocation.
static java.lang.String	JAXB_SCHEMA_LOCATION If this property is set to another value than null, then the Marshaller will create an attribute xsi:schemaLocation.

Method Summary

ValidationEventHandler	getEventHandler() Returns an event handler previously registered by the application.
org.w3c.dom.Node	getNode(java.lang.Object pObject) Returns a DOM view of the given JAXB object.
java.lang.Object	getProperty(java.lang.String pName) Returns the value of the marshaller property pName.
void	marshal(java.lang.Object pObject, org.xml.sax.ContentHandler pTarget) Marshals the given JAXB object by emitting SAX events into into the given SAX ContentHandler.
void	marshal(java.lang.Object pObject, org.w3c.dom.Node pTarget) Marshals the given JAXB object by creating a DOM tree below the given node.
void	marshal(java.lang.Object pObject, java.io.OutputStream pTarget) Marshals the given JAXB object pObject and serializes it into the byte stream pTarget.
void	marshal(java.lang.Object pObject, javax.xml.transform.Result pTarget) Marshals the given JAXB object pObject to the Result pTarget.
void	marshal(java.lang.Object pObject, java.io.Writer pTarget) Marshals the given JAXB object pObject and serializes it into the character stream pTarget.
void	setEventHandler(ValidationEventHandler pHandler) Allows the application to set an event handler.
void	setProperty(java.lang.String pName, java.lang.Object pValue) Sets the marshaller property pName to the value pValue.

Field Detail

JAXB_ENCODING

static final java.lang.String JAXB_ENCODING

Name of the property that allows to choose the encoding. The encoding applies when marshalling to an OutputStream, to a Writer, or to a StreamResult. It is ignored, if the target is a ContentHandler, a DOM Node, or another flavour of Result.

The encoding may be used both to choose the characters being escaped (as &#ddd;) or to convert characters into byte sequences.

The property value is the encoding name, for example UTF-8, which is the default. Note, that a JAXB implementation need not support other encodings than UTF-8, UTF-16, and US-ASCII. Usually you may expect that the encodings supported by the JVM itself will work for the Marshaller as well.

See Also:

marshal(Object, java.io.OutputStream), marshal(Object, java.io.Writer), marshal(Object, javax.xml.transform.Result), Constant Field Values

JAXB_FORMATTED_OUTPUT

static final java.lang.String JAXB_FORMATTED_OUTPUT

Name of the property that allows to choose whether the generated XML should be formatted (human readable, indented) or not. By default the generated XML is formatted. The property value is an instance of Boolean, by default Boolean.TRUE.

The formatting property is supported when marshalling to a character or byte stream. It is ignored, if the target is a ContentHandler, a DOM Node, or an instance of Result, the exception being a StreamResult, which is in fact a character or byte stream.

See Also:

marshal(Object, java.io.OutputStream), marshal(Object, java.io.Writer), marshal(Object, javax.xml.transform.Result), Constant Field Values

JAXB_SCHEMA_LOCATION

static final java.lang.String JAXB_SCHEMA_LOCATION

If this property is set to another value than null, then the Marshaller will create an attribute xsi:schemaLocation. The attribute value is the property value. By default the property is set to null and no such attribute is generated.

See Also:

JAXB_NO_NAMESPACE_SCHEMA_LOCATION, Constant Field Values

JAXB_NO_NAMESPACE_SCHEMA_LOCATION

static final java.lang.String JAXB_NO_NAMESPACE_SCHEMA_LOCATION

If this property is set to another value than null, then the Marshaller will create an attribute xsi:noNamespaceSchemaLocation. The attribute value is the property value. By default the property is set to null and no such attribute is generated.

See Also:

JAXB_SCHEMA_LOCATION, Constant Field Values

Method Detail

marshal

void marshal(java.lang.Object pObject,
             javax.xml.transform.Result pTarget)
             throws JAXBException

Marshals the given JAXB object pObject to the Result pTarget. All JAXB provider must support DOMResult, SAXResult, and StreamResult, which can easily be mapped to marshal(Object, org.w3c.dom.Node), marshal(Object, org.xml.sax.ContentHandler), marshal(Object,java.io.OutputStream), or marshal(Object,java.io.Writer). The use of a Result as a target isn't portable beyond these subinterfaces.

Parameters:

pObject - The JAXB object being marshalled.

pTarget - The Result being created.

Throws:

JAXBException - An unexcpected problem occurred. This may be used, for example, to throw a nested IOException.

MarshalException - Whereever possible, one should throw a MarshalException, and not a JAXBException.

java.lang.IllegalArgumentException - Any of the parameters was null.

See Also:

JAXB_SCHEMA_LOCATION, JAXB_NO_NAMESPACE_SCHEMA_LOCATION

marshal

void marshal(java.lang.Object pObject,
             java.io.OutputStream pTarget)
             throws JAXBException

Marshals the given JAXB object pObject and serializes it into the byte stream pTarget. Note, that serialization into a byte stream demands the use of an encoding. It may be required to set the parameter JAXB_ENCODING. By default the created output is formatted, which may be turned off using JAXB_FORMATTED_OUTPUT.

Parameters:

pObject - The JAXB object being marshalled.

pTarget - The output byte stream.

Throws:

JAXBException - An unexpected problem occurred. This may be used, for example, to throw a nested IOException.

MarshalException - Whereever possible, one should prefer the MarshalException over the JAXBException.

java.lang.IllegalArgumentException - Any of the parameters was null.

See Also:

JAXB_ENCODING, JAXB_FORMATTED_OUTPUT, JAXB_NO_NAMESPACE_SCHEMA_LOCATION, JAXB_SCHEMA_LOCATION

marshal

void marshal(java.lang.Object pObject,
             java.io.Writer pTarget)
             throws JAXBException

Marshals the given JAXB object pObject and serializes it into the character stream pTarget. Unlike serialization to a byte stream, an encoding is not required, but a Marshaller may use the encoding whether to escape a character or not. Use of the JAXB_ENCODING property is still recommended. By default the created output is formatted, which may be turned off using JAXB_FORMATTED_OUTPUT.

Parameters:

pObject - The JAXB object being marshalled.

pTarget - The output character stream.

Throws:

JAXBException - An unexpected problem occurred. This may be used, for example, to throw a nested IOException.

MarshalException - Whereever possible, one should prefer the MarshalException over the JAXBException.

java.lang.IllegalArgumentException - Any of the parameters was null.

See Also:

JAXB_ENCODING, JAXB_FORMATTED_OUTPUT, JAXB_NO_NAMESPACE_SCHEMA_LOCATION, JAXB_SCHEMA_LOCATION

marshal

void marshal(java.lang.Object pObject,
             org.xml.sax.ContentHandler pTarget)
             throws JAXBException

Marshals the given JAXB object by emitting SAX events into into the given SAX ContentHandler. This includes the events ContentHandler.startDocument() and ContentHandler.endDocument().

Parameters:

pObject - The JAXB Object being marshalled.

pTarget - The target event handler.

Throws:

JAXBException - An unexpected problem occurred. This may be used, for example, to throw a nested SAXException.

MarshalException - Whereever possible, one should prefer the MarshalException over the JAXBException.

java.lang.IllegalArgumentException - Any of the parameters was null.

See Also:

JAXB_NO_NAMESPACE_SCHEMA_LOCATION, JAXB_SCHEMA_LOCATION

marshal

void marshal(java.lang.Object pObject,
             org.w3c.dom.Node pTarget)
             throws JAXBException

Marshals the given JAXB object by creating a DOM tree below the given node.

Parameters:

pObject - The JAXB object being marshalled.

pTarget - The target node. This node must be ready to accept a child element. For example, it may be a Document, a DocumentFragment, or an Element.

Throws:

JAXBException - An unexpected problem occurred. This may be used, for example, to throw a nested DOMException.

MarshalException - Whereever possible, one should prefer the MarshalException over the JAXBException.

java.lang.IllegalArgumentException - Any of the parameters was null.

See Also:

JAXB_NO_NAMESPACE_SCHEMA_LOCATION, JAXB_SCHEMA_LOCATION

getNode

org.w3c.dom.Node getNode(java.lang.Object pObject)
                         throws JAXBException

Returns a DOM view of the given JAXB object. This view is life in the sense that modifications of its DOM tree will trigger updates on the original JAXB object.

Note: This is an optional feature and not supported by all JAXB providers.

Parameters:

pObject - The JAXB object being viewed.

Throws:

java.lang.UnsupportedOperationException - The JAXB provider does not support DOM views.

JAXBException - An unexpected problem occurred. This may be used, for example, to throw a nested DOMException.

java.lang.IllegalArgumentException - The parameter was null.

setProperty

void setProperty(java.lang.String pName,
                 java.lang.Object pValue)
                 throws PropertyException

Sets the marshaller property pName to the value pValue. Note, that the value type depends on the property being set. For example, the property JAXB_ENCODING requires a string, but the property JAXB_FORMATTED_OUTPUT requires a Boolean.

Parameters:

pName - The property name.

Throws:

PropertyException - An error occurred while processing the property.

java.lang.IllegalArgumentException - The name parameter was null.

getProperty

java.lang.Object getProperty(java.lang.String pName)
                             throws PropertyException

Returns the value of the marshaller property pName. Note, that the value type depends on the property being set. For example, the property JAXB_ENCODING requires a string, but the property JAXB_FORMATTED_OUTPUT requires a Boolean.

Parameters:

pName - The property name.

Throws:

PropertyException - An error occurred while processing the property.

java.lang.IllegalArgumentException - The name parameter was null.

setEventHandler

void setEventHandler(ValidationEventHandler pHandler)
                     throws JAXBException

Allows the application to set an event handler. The event handler will be invoked in case of a validation event.

Note: The ability to register an event handler does not indicate that a JAXB provider is required to validate the objects being marshalled. If you want to ensure, that only valid objects are marshalled, you should perform an explicit validation using a Validator.

Parameters:

pHandler - An application specific event handler or null to revert to the default event handler. The default handler is throwing an exception in case of errors.

Throws:

JAXBException

getEventHandler

ValidationEventHandler getEventHandler()
                                       throws JAXBException

Returns an event handler previously registered by the application. The event handler will be invoked in case of a validation event.

Note: The ability to register an event handler does not indicate that a JAXB provider is required to validate the objects being marshalled. If you want to ensure, that only valid objects are marshalled, you should perform an explicit validation using a Validator.

Returns:

An event handler previously set by the application or the default event handler. The default handler is simply throwing exceptions.

Throws:

JAXBException - An error occurred while getting the event handler.