javax.xml.bind
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
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 |
static String | JAXB_SCHEMA_LOCATION If this property is set to another value than null,
then the |
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 |
void | marshal(Object pObject, Result pTarget) Marshals the given JAXB object |
void | marshal(Object pObject, OutputStream pTarget) Marshals the given JAXB object |
void | marshal(Object pObject, Writer pTarget) Marshals the given JAXB object |
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 | setEventHandler(ValidationEventHandler pHandler) Allows the application to set an event handler. |
void | setProperty(String pName, Object pValue) Sets the marshaller property |
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
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
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
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
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.
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.
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.
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
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
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
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
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
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.
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.