org.exolab.castor.xml

Class Marshaller


public class Marshaller
extends MarshalFramework

A Marshaller that serializes Java Object's to XML Note: This class is not thread safe, and not intended to be, so please create a new Marshaller for each thread if it is to be used in a multithreaded environment.
Version:
$Revision: 6368 $ $Date: 2006-04-13 06:47:36 -0600 (Thu, 13 Apr 2006) $
Author:
Keith Visco

Nested Class Summary

(package private) static class
Marshaller.MarshalState
static class
Marshaller.NilObject
A wrapper for a "Nil" object
(package private) static class
Marshaller.WrapperInfo
Inner-class used for handling wrapper elements and locations

Nested classes/interfaces inherited from class org.exolab.castor.xml.MarshalFramework

MarshalFramework.InheritanceMatch, MarshalFramework.InternalXMLClassDescriptor

Field Summary

(package private) int
depth
The depth of the sub tree, 0 denotes document level

Fields inherited from class org.exolab.castor.xml.MarshalFramework

INTERNAL_XML_NAME, JAVA_PREFIX, LANG_ATTR, NIL_ATTR, NO_FIELD_DESCRIPTORS, QNAME_NAME, SPACE_ATTR, TRUE_VALUE, TYPE_ATTR, XML_LANG_ATTR, XML_SPACE_ATTR, XSI_NAMESPACE, XSI_NIL_ATTR, XSI_NO_NAMESPACE_SCHEMA_LOCATION, XSI_SCHEMA_LOCATION

Constructor Summary

Marshaller()
Creates a default instance of Marshaller, where the sink needs to be set separately.
Marshaller(ContentHandler handler)
Creates a new Marshaller with the given SAX ContentHandler.
Marshaller(DocumentHandler handler)
Creates a new Marshaller with the given DocumentHandler.
Marshaller(Node node)
Creates a new Marshaller for the given DOM Node.
Marshaller(Writer out)
Creates a new Marshaller with the given writer.

Method Summary

void
addProcessingInstruction(String target, String data)
Adds the given processing instruction data to the set of processing instructions to output during marshalling.
boolean
getMarshalExtendedType()
If True the marshaller will use the 'xsi:type' attribute to marshall a field value that extended the defined field type.
boolean
getNSPrefixAtRoot()
Deprecated.
ClassDescriptorResolver
getResolver()
Returns the ClassDescriptorResolver for use during marshalling
String
getRootElement()
Returns the name of the root element to use
void
marshal(Object object)
Marshals the given Object as XML using the DocumentHandler for this Marshaller.
static void
marshal(Object object, ContentHandler handler)
Marshals the given Object as XML using the given ContentHandler to send events to.
static void
marshal(Object object, DocumentHandler handler)
Marshals the given Object as XML using the given DocumentHandler to send events to.
static void
marshal(Object object, Node node)
Marshals the given Object as XML using the given DOM Node to send events to.
static void
marshal(Object object, Writer out)
Marshals the given Object as XML using the given writer.
void
setDoctype(String publicId, String systemId)
Sets the document type definition for the serializer.
void
setEncoding(String encoding)
Sets the encoding for the serializer.
void
setLogWriter(PrintWriter printWriter)
Sets the PrintWriter used for logging
void
setMapping(Mapping mapping)
Sets the given mapping to be used by the marshalling Framework.
void
setMarshalAsDocument(boolean asDocument)
Sets whether or not to marshal as a document which includes the XML declaration, and if necessary the DOCTYPE declaration.
void
setMarshalExtendedType(boolean marshalExtendedType)
If True the marshaller will use the 'xsi:type' attribute to marshall a field value that extended the defined field type.
void
setMarshalListener(MarshalListener listener)
Sets an optional MarshalListener to recieve pre and post marshal notification for each Object in the tree.
void
setNSPrefixAtRoot(boolean nsPrefixAtRoot)
Deprecated.
void
setNamespaceMapping(String nsPrefix, String nsURI)
Sets the mapping for the given Namespace prefix
void
setNoNamespaceSchemaLocation(String schemaLocation)
Sets the value for the xsi:noNamespaceSchemaLocation attribute.
void
setResolver(XMLClassDescriptorResolver cdr)
Sets the ClassDescriptorResolver to use during marshalling
Note: This method will nullify any Mapping currently being used by this Marshaller
void
setRootElement(String rootElement)
Sets the name of the root element to use.
void
setSchemaLocation(String schemaLocation)
Sets the value for the xsi:schemaLocation attribute.
void
setSuppressNamespaces(boolean suppressNamespaces)
Sets whether or not namespaces are output.
void
setSuppressXSIType(boolean suppressXSIType)
Sets whether or not the xsi:type attribute should appear on the marshalled document.
void
setSupressXMLDeclaration(boolean supressXMLDeclaration)
Sets whether or not to marshal as a document which includes the XML declaration, and if necessary the DOCTYPE declaration.
void
setUseXSITypeAtRoot(boolean useXSITypeAtRoot)
Sets whether or not to output the xsi:type at the root element.
void
setValidation(boolean validate)
Sets whether or not to validate the object model before marshalling.
void
setWriter(Writer out)
Sets the java.io.Writer to be used during marshalling.

Methods inherited from class org.exolab.castor.xml.MarshalFramework

getCollectionHandler, hasFieldsAtLocation, isCollection, isPrimitive, namespaceEquals, primitiveOrWrapperEquals, searchInheritance

Field Details

depth

(package private)  int depth
The depth of the sub tree, 0 denotes document level

Constructor Details

Marshaller

public Marshaller()
Creates a default instance of Marshaller, where the sink needs to be set separately.

Marshaller

public Marshaller(ContentHandler handler)
            throws IOException
Creates a new Marshaller with the given SAX ContentHandler.
Parameters:
handler - the ContentHandler to "marshal" to.

Marshaller

public Marshaller(DocumentHandler handler)
Creates a new Marshaller with the given DocumentHandler.
Parameters:
handler - the DocumentHandler to "marshal" to.

Marshaller

public Marshaller(Node node)
Creates a new Marshaller for the given DOM Node.
Parameters:
node - the DOM node to marshal into.

Marshaller

public Marshaller(Writer out)
            throws IOException
Creates a new Marshaller with the given writer.
Parameters:
out - the Writer to serialize to

Method Details

addProcessingInstruction

public void addProcessingInstruction(String target,
                                     String data)
Adds the given processing instruction data to the set of processing instructions to output during marshalling.
Parameters:
target - the processing instruction target
data - the processing instruction data

getMarshalExtendedType

public boolean getMarshalExtendedType()
If True the marshaller will use the 'xsi:type' attribute to marshall a field value that extended the defined field type. Default is True.
Returns:
If True the marshaller will use the 'xsi:type' attribute to marshall a field value that extended the defined field type. Default is True.

getNSPrefixAtRoot

public boolean getNSPrefixAtRoot()

Deprecated.

Returns True if the given namespace mappings will be declared at the root node.
Returns:
Returns True if the given namespace mappings will be declared at the root node.

getResolver

public ClassDescriptorResolver getResolver()
Returns the ClassDescriptorResolver for use during marshalling
Returns:
the ClassDescriptorResolver

getRootElement

public String getRootElement()
Returns the name of the root element to use
Returns:
Returns the name of the root element to use

marshal

public void marshal(Object object)
            throws MarshalException,
                   ValidationException
Marshals the given Object as XML using the DocumentHandler for this Marshaller.
Parameters:
object - The Object to marshal.

marshal

public static void marshal(Object object,
                           ContentHandler handler)
            throws MarshalException,
                   ValidationException,
                   IOException
Marshals the given Object as XML using the given ContentHandler to send events to.
Parameters:
object - The Object to marshal.
handler - The ContentHandler to marshal to.

marshal

public static void marshal(Object object,
                           DocumentHandler handler)
            throws MarshalException,
                   ValidationException
Marshals the given Object as XML using the given DocumentHandler to send events to.
Parameters:
object - The Object to marshal.
handler - The DocumentHandler to marshal to.

marshal

public static void marshal(Object object,
                           Node node)
            throws MarshalException,
                   ValidationException
Marshals the given Object as XML using the given DOM Node to send events to.
Parameters:
object - The Object to marshal.
node - The DOM Node to marshal to.

marshal

public static void marshal(Object object,
                           Writer out)
            throws MarshalException,
                   ValidationException
Marshals the given Object as XML using the given writer.
Parameters:
object - The Object to marshal.
out - The writer to marshal to.

setDoctype

public void setDoctype(String publicId,
                       String systemId)
Sets the document type definition for the serializer. Note that this method cannot be called if you've passed in your own DocumentHandler.
Parameters:
publicId - the public identifier
systemId - the system identifier

setEncoding

public void setEncoding(String encoding)
Sets the encoding for the serializer. Note that this method cannot be called if you've passed in your own DocumentHandler.
Parameters:
encoding - the encoding to set

setLogWriter

public void setLogWriter(PrintWriter printWriter)
Sets the PrintWriter used for logging
Parameters:
printWriter - the PrintWriter to use for logging

setMapping

public void setMapping(Mapping mapping)
            throws MappingException
Sets the given mapping to be used by the marshalling Framework. If a resolver exists this mapping will be added to the existing ClassDescriptorResolver. Otherwise a new ClassDescriptorResolver will be created.
Parameters:
mapping - Mapping to using during marshalling.

setMarshalAsDocument

public void setMarshalAsDocument(boolean asDocument)
Sets whether or not to marshal as a document which includes the XML declaration, and if necessary the DOCTYPE declaration. By default the Marshaller will marshal as a well formed XML document including the XML Declaration. If the given boolean is false, the Marshaller will marshal as a well formed XML fragment (no XML declaration or DOCTYPE). This method is basically the same as calling #setSupressXMLDeclaration(true);
Parameters:
asDocument - a boolean, when true, indicating to marshal as a complete XML document.

setMarshalExtendedType

public void setMarshalExtendedType(boolean marshalExtendedType)
If True the marshaller will use the 'xsi:type' attribute to marshall a field value that extended the defined field type. Default is True.

setMarshalListener

public void setMarshalListener(MarshalListener listener)
Sets an optional MarshalListener to recieve pre and post marshal notification for each Object in the tree. MarshalListener is only for complex objects that map into elements, simpleTypes and types that map into attributes do not cause any pre and post event notifications. Current only one (1) listener is allowed. If you need register multiple listeners, you will have to create your own master listener that will forward the event notifications and manage the multiple listeners.
Parameters:
listener - the MarshalListener to set.

setNSPrefixAtRoot

public void setNSPrefixAtRoot(boolean nsPrefixAtRoot)

Deprecated.

Set to True to declare the given namespace mappings at the root node. Default is False.
Parameters:
nsPrefixAtRoot -

setNamespaceMapping

public void setNamespaceMapping(String nsPrefix,
                                String nsURI)
Sets the mapping for the given Namespace prefix
Parameters:
nsPrefix - the namespace prefix
nsURI - the namespace that the prefix resolves to

setNoNamespaceSchemaLocation

public void setNoNamespaceSchemaLocation(String schemaLocation)
Sets the value for the xsi:noNamespaceSchemaLocation attribute. When set, this attribute will appear on the root element of the marshalled document.
Parameters:
schemaLocation - the URI location of the schema to which the marshalled document is an instance of.

setResolver

public void setResolver(XMLClassDescriptorResolver cdr)
Sets the ClassDescriptorResolver to use during marshalling
Note: This method will nullify any Mapping currently being used by this Marshaller
Parameters:
cdr - the ClassDescriptorResolver to use

setRootElement

public void setRootElement(String rootElement)
Sets the name of the root element to use.
Parameters:
rootElement - The name of the root element to use.

setSchemaLocation

public void setSchemaLocation(String schemaLocation)
Sets the value for the xsi:schemaLocation attribute. When set, this attribute will appear on the root element of the marshalled document.
Parameters:
schemaLocation - the URI location of the schema to which the marshalled document is an instance of.

setSuppressNamespaces

public void setSuppressNamespaces(boolean suppressNamespaces)
Sets whether or not namespaces are output. By default the Marshaller will output namespace declarations and prefix elements and attributes with their respective namespace prefix. This method can be used to prevent the usage of namespaces.
Parameters:
suppressNamespaces - a boolean that when true will prevent namespaces from being output.

setSuppressXSIType

public void setSuppressXSIType(boolean suppressXSIType)
Sets whether or not the xsi:type attribute should appear on the marshalled document.
Parameters:
suppressXSIType - a boolean that when true will prevent xsi:type attribute from being used in the marshalling process.

setSupressXMLDeclaration

public void setSupressXMLDeclaration(boolean supressXMLDeclaration)
Sets whether or not to marshal as a document which includes the XML declaration, and if necessary the DOCTYPE declaration. By default the Marshaller will marshal as a well formed XML document including the XML Declaration. If the given boolean is true, the Marshaller will marshal as a well formed XML fragment (no XML declaration or DOCTYPE). This method is basically the same as calling #setMarshalAsDocument(false);
Parameters:
supressXMLDeclaration - a boolean that when true includes that generated XML should not contain the XML declaration.

setUseXSITypeAtRoot

public void setUseXSITypeAtRoot(boolean useXSITypeAtRoot)
Sets whether or not to output the xsi:type at the root element. This is usually needed when the root element type cannot be determined by the element name alone. By default xsi:type will not be output on the root element.
Parameters:
useXSITypeAtRoot - a boolean that when true indicates that the xsi:type should be output on the root element.

setValidation

public void setValidation(boolean validate)
Sets whether or not to validate the object model before marshalling. By default validation is enabled. This method is really for debugging. I do not recommend turning off validation, since you could marshal a document, which you can then not unmarshal. If you know the object model is guaranteed to be valid, disabling validation will improve performace.
Parameters:
validate - the boolean indicating whether or not to validate the object model before marshalling.

setWriter

public void setWriter(Writer out)
            throws IOException
Sets the java.io.Writer to be used during marshalling.
Parameters:
out - The writer to use for marshalling

Intalio Inc. (C) 1999-2006. All rights reserved http://www.intalio.com