javax.xml.bind

Interface Marshaller

Known Subinterfaces:
JMMarshaller
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
java.io.OutputStream
marshal(Object, java.io.OutputStream)
A character stream
java.io.Writer
marshal(Object, java.io.Writer)
Author:
JSR-31
Since:
JAXB1.0

Field Summary

static String
JAXB_ENCODING
Name of the property that allows to choose the encoding.
static 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 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 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.
Node
getNode(Object pObject)
Returns a DOM view of the given JAXB object.
Object
getProperty(String pName)
Returns the value of the marshaller property pName.
void
marshal(Object pObject, ContentHandler pTarget)
Marshals the given JAXB object by emitting SAX events into into the given SAX org.xml.sax.ContentHandler.
void
marshal(Object pObject, Node pTarget)
Marshals the given JAXB object by creating a DOM tree below the given node.
void
marshal(Object pObject, OutputStream pTarget)
Marshals the given JAXB object pObject and serializes it into the byte stream pTarget.
void
marshal(Object pObject, Result pTarget)
Marshals the given JAXB object pObject to the javax.xml.transform.Result pTarget.
void
marshal(Object pObject, 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(String pName, Object pValue)
Sets the marshaller property pName to the value pValue.

Field Details

JAXB_ENCODING

public static final String JAXB_ENCODING
Name of the property that allows to choose the encoding. The encoding applies when marshalling to an java.io.OutputStream, to a java.io.Writer, or to a javax.xml.transform.stream.StreamResult. It is ignored, if the target is a org.xml.sax.ContentHandler, a DOM org.w3c.dom.Node, or another flavour of javax.xml.transform.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)

JAXB_FORMATTED_OUTPUT

public static final 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 org.xml.sax.ContentHandler, a DOM org.w3c.dom.Node, or an instance of javax.xml.transform.Result, the exception being a javax.xml.transform.stream.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)

JAXB_NO_NAMESPACE_SCHEMA_LOCATION

public static final 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.

JAXB_SCHEMA_LOCATION

public static final 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.

Method Details

getEventHandler

public 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.

getNode

public Node getNode(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:
JAXBException - An unexpected problem occurred. This may be used, for example, to throw a nested org.w3c.dom.DOMException.

getProperty

public Object getProperty(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.

marshal

public void marshal(Object pObject,
                    ContentHandler pTarget)
            throws JAXBException
Marshals the given JAXB object by emitting SAX events into into the given SAX org.xml.sax.ContentHandler. This includes the events org.xml.sax.ContentHandler.startDocument() and org.xml.sax.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 org.xml.sax.SAXException.

marshal

public void marshal(Object pObject,
                    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 org.w3c.dom.Document, a org.w3c.dom.DocumentFragment, or an org.w3c.dom.Element.
Throws:
JAXBException - An unexpected problem occurred. This may be used, for example, to throw a nested org.w3c.dom.DOMException.

marshal

public void marshal(Object pObject,
                    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 java.io.IOException.

marshal

public void marshal(Object pObject,
                    Result pTarget)
            throws JAXBException
Marshals the given JAXB object pObject to the javax.xml.transform.Result pTarget. All JAXB provider must support javax.xml.transform.dom.DOMResult, javax.xml.transform.sax.SAXResult, and javax.xml.transform.stream.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 javax.xml.transform.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 java.io.IOException.

marshal

public void marshal(Object pObject,
                    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 java.io.IOException.

setEventHandler

public 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.

setProperty

public void setProperty(String pName,
                        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.