Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
public interface Marshaller
Marshaller
may be obtained by the
JAXB user to serialize JAXB objects to various flavours of XML.
The created XML may be:
A byte streamjava.io.OutputStream | marshal(Object, java.io.OutputStream) |
---|---|
A character streamjava.io.Writer | marshal(Object, java.io.Writer) |
Field Summary | |
static String |
|
static String |
|
static String |
|
static String |
|
Method Summary | |
ValidationEventHandler |
|
Node |
|
Object |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
public static final String JAXB_ENCODING
Name of the property that allows to choose the encoding. The encoding applies when marshalling to anjava.io.OutputStream
, to ajava.io.Writer
, or to ajavax.xml.transform.stream.StreamResult
. It is ignored, if the target is aorg.xml.sax.ContentHandler
, a DOMorg.w3c.dom.Node
, or another flavour ofjavax.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 theMarshaller
as well.
- See Also:
marshal(Object, java.io.OutputStream)
,marshal(Object, java.io.Writer)
,marshal(Object, javax.xml.transform.Result)
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 ofBoolean
, by defaultBoolean.TRUE
. The formatting property is supported when marshalling to a character or byte stream. It is ignored, if the target is aorg.xml.sax.ContentHandler
, a DOMorg.w3c.dom.Node
, or an instance ofjavax.xml.transform.Result
, the exception being ajavax.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)
public static final String JAXB_NO_NAMESPACE_SCHEMA_LOCATION
If this property is set to another value than null, then theMarshaller
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
public static final String JAXB_SCHEMA_LOCATION
If this property is set to another value than null, then theMarshaller
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
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 aValidator
.
- 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.
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 nestedorg.w3c.dom.DOMException
.
public Object getProperty(String pName) throws PropertyException
Returns the value of the marshaller propertypName
. Note, that the value type depends on the property being set. For example, the propertyJAXB_ENCODING
requires a string, but the propertyJAXB_FORMATTED_OUTPUT
requires aBoolean
.
- Parameters:
pName
- The property name.
- Throws:
PropertyException
- An error occurred while processing the property.
public void marshal(Object pObject, ContentHandler pTarget) throws JAXBException
Marshals the given JAXB object by emitting SAX events into into the given SAXorg.xml.sax.ContentHandler
. This includes the eventsorg.xml.sax.ContentHandler.startDocument()
andorg.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 nestedorg.xml.sax.SAXException
.
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 aorg.w3c.dom.Document
, aorg.w3c.dom.DocumentFragment
, or anorg.w3c.dom.Element
.
- Throws:
JAXBException
- An unexpected problem occurred. This may be used, for example, to throw a nestedorg.w3c.dom.DOMException
.
public void marshal(Object pObject, OutputStream pTarget) throws JAXBException
Marshals the given JAXB objectpObject
and serializes it into the byte streampTarget
. Note, that serialization into a byte stream demands the use of an encoding. It may be required to set the parameterJAXB_ENCODING
. By default the created output is formatted, which may be turned off usingJAXB_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 nestedjava.io.IOException
.
public void marshal(Object pObject, Result pTarget) throws JAXBException
Marshals the given JAXB objectpObject
to thejavax.xml.transform.Result
pTarget
. All JAXB provider must supportjavax.xml.transform.dom.DOMResult
,javax.xml.transform.sax.SAXResult
, andjavax.xml.transform.stream.StreamResult
, which can easily be mapped tomarshal(Object, org.w3c.dom.Node)
,marshal(Object, org.xml.sax.ContentHandler)
,marshal(Object,java.io.OutputStream)
, ormarshal(Object,java.io.Writer)
. The use of ajavax.xml.transform.Result
as a target isn't portable beyond these subinterfaces.
- Parameters:
pObject
- The JAXB object being marshalled.pTarget
- TheResult
being created.
- Throws:
JAXBException
- An unexcpected problem occurred. This may be used, for example, to throw a nestedjava.io.IOException
.
public void marshal(Object pObject, Writer pTarget) throws JAXBException
Marshals the given JAXB objectpObject
and serializes it into the character streampTarget
. Unlike serialization to a byte stream, an encoding is not required, but aMarshaller
may use the encoding whether to escape a character or not. Use of theJAXB_ENCODING
property is still recommended. By default the created output is formatted, which may be turned off usingJAXB_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 nestedjava.io.IOException
.
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 aValidator
.
- 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.
public void setProperty(String pName, Object pValue) throws PropertyException
Sets the marshaller propertypName
to the valuepValue
. Note, that the value type depends on the property being set. For example, the propertyJAXB_ENCODING
requires a string, but the propertyJAXB_FORMATTED_OUTPUT
requires aBoolean
.
- Parameters:
pName
- The property name.
- Throws:
PropertyException
- An error occurred while processing the property.