javax.xml.bind

Interface Marshaller

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
Marshaller
A character stream
java.io.Writer
Marshaller

Since: JAXB1.0

Author: JSR-31

Field Summary
static StringJAXB_ENCODING

Name of the property that allows to choose the encoding.

static StringJAXB_FORMATTED_OUTPUT

Name of the property that allows to choose whether the generated XML should be formatted (human readable, indented) or not.

static StringJAXB_NO_NAMESPACE_SCHEMA_LOCATION

If this property is set to another value than null, then the Marshaller will create an attribute xsi:noNamespaceSchemaLocation.

static StringJAXB_SCHEMA_LOCATION

If this property is set to another value than null, then the Marshaller will create an attribute xsi:schemaLocation.

Method Summary
ValidationEventHandlergetEventHandler()

Returns an event handler previously registered by the application.

NodegetNode(Object pObject)

Returns a DOM view of the given JAXB object.

ObjectgetProperty(String pName)

Returns the value of the marshaller property pName.

voidmarshal(Object pObject, Result pTarget)

Marshals the given JAXB object pObject to the javax.xml.transform.Result pTarget.

voidmarshal(Object pObject, OutputStream pTarget)

Marshals the given JAXB object pObject and serializes it into the byte stream pTarget.

voidmarshal(Object pObject, Writer pTarget)

Marshals the given JAXB object pObject and serializes it into the character stream pTarget.

voidmarshal(Object pObject, ContentHandler pTarget)

Marshals the given JAXB object by emitting SAX events into into the given SAX org.xml.sax.ContentHandler.

voidmarshal(Object pObject, Node pTarget)

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

voidsetEventHandler(ValidationEventHandler pHandler)

Allows the application to set an event handler.

voidsetProperty(String pName, Object pValue)

Sets the marshaller property pName to the value pValue.

Field Detail

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: Marshaller Marshaller Marshaller

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: Marshaller Marshaller Marshaller

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.

See Also: JAXB_SCHEMA_LOCATION

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.

See Also: JAXB_NO_NAMESPACE_SCHEMA_LOCATION

Method Detail

getEventHandler

public ValidationEventHandler getEventHandler()

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)

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: UnsupportedOperationException The JAXB provider does not support DOM views. JAXBException An unexpected problem occurred. This may be used, for example, to throw a nested org.w3c.dom.DOMException. IllegalArgumentException The parameter was null.

getProperty

public Object getProperty(String pName)

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. IllegalArgumentException The name parameter was null.

marshal

public void marshal(Object pObject, Result pTarget)

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 Marshaller, Marshaller, marshal, or marshal. 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. MarshalException Whereever possible, one should throw a MarshalException, and not a JAXBException. IllegalArgumentException Any of the parameters was null.

See Also: JAXB_SCHEMA_LOCATION JAXB_NO_NAMESPACE_SCHEMA_LOCATION

marshal

public void marshal(Object pObject, OutputStream pTarget)

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. MarshalException Whereever possible, one should prefer the MarshalException over the JAXBException. IllegalArgumentException Any of the parameters was null.

See Also: JAXB_ENCODING JAXB_FORMATTED_OUTPUT JAXB_NO_NAMESPACE_SCHEMA_LOCATION JAXB_SCHEMA_LOCATION

marshal

public void marshal(Object pObject, Writer pTarget)

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. MarshalException Whereever possible, one should prefer the MarshalException over the JAXBException. IllegalArgumentException Any of the parameters was null.

See Also: JAXB_ENCODING JAXB_FORMATTED_OUTPUT JAXB_NO_NAMESPACE_SCHEMA_LOCATION JAXB_SCHEMA_LOCATION

marshal

public void marshal(Object pObject, ContentHandler pTarget)

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. MarshalException Whereever possible, one should prefer the MarshalException over the JAXBException. IllegalArgumentException Any of the parameters was null.

See Also: JAXB_NO_NAMESPACE_SCHEMA_LOCATION JAXB_SCHEMA_LOCATION

marshal

public void marshal(Object pObject, Node pTarget)

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. MarshalException Whereever possible, one should prefer the MarshalException over the JAXBException. IllegalArgumentException Any of the parameters was null.

See Also: JAXB_NO_NAMESPACE_SCHEMA_LOCATION JAXB_SCHEMA_LOCATION

setEventHandler

public void setEventHandler(ValidationEventHandler pHandler)

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)

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. IllegalArgumentException The name parameter was null.