org.exolab.castor.xml
Class Marshaller

java.lang.Object
  org.exolab.castor.xml.MarshalFramework
      org.exolab.castor.xml.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: 7398 $ $Date: 2006-04-13 06:47:36 -0600 (Thu, 13 Apr 2006) $

Author:

Keith Visco

Nested Class Summary

static class	MarshalFramework.InheritanceMatch Used to store the information when we find a possible inheritance.
(package private) class	MarshalFramework.InternalXMLClassDescriptor An internal implementation of XMLClassDescriptor used by the Unmarshaller and Marshaller...
(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

Field Summary

(package private) int	depth The depth of the sub tree, 0 denotes document level
(package private) static java.lang.String	INTERNAL_XML_NAME A constant to indicate a wrong name without setting null.
(package private) static java.lang.String	JAVA_PREFIX The default prefix used for specifying the xsi:type as a classname instead of a schema name.
static java.lang.String	LANG_ATTR The xml:lang attribute, without the "xml:" prefix.
static java.lang.String	NIL_ATTR The xsi:nil attribute, without the "xsi:" prefix.
(package private) static XMLFieldDescriptor[]	NO_FIELD_DESCRIPTORS An empty array of field descriptors.
(package private) static java.lang.String	QNAME_NAME The name of the QName type.
static java.lang.String	SPACE_ATTR The xml:space attribute name, without the "xml:" prefix.
static java.lang.String	TRUE_VALUE The value of 'true'.
static java.lang.String	TYPE_ATTR The xsi:type attribute name, without the "xsi:" prefix.
static java.lang.String	XML_LANG_ATTR The xml:lang attribute name.
static java.lang.String	XML_SPACE_ATTR The xml:space attribute name.
static java.lang.String	XSI_NAMESPACE The XSI Namespace URI.
static java.lang.String	XSI_NIL_ATTR The xsi:nil attribute.
static java.lang.String	XSI_NO_NAMESPACE_SCHEMA_LOCATION The name of the no namespace schema location attribute.
static java.lang.String	XSI_SCHEMA_LOCATION The name of the Schema location attribute.

Constructor Summary

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

Marshaller(org.xml.sax.ContentHandler handler)
Creates a new Marshaller with the given SAX ContentHandler.

Marshaller(org.xml.sax.DocumentHandler handler)
Creates a new Marshaller with the given DocumentHandler.

Marshaller(org.w3c.dom.Node node)
Creates a new Marshaller for the given DOM Node.

Marshaller(java.io.Writer out)
Creates a new Marshaller with the given writer.

Method Summary

void	addProcessingInstruction(java.lang.String target, java.lang.String data) Adds the given processing instruction data to the set of processing instructions to output during marshalling.
CollectionHandler	getCollectionHandler(java.lang.Class clazz) Returns the CollectionHandler associated with the given collection, or null if no such handler exists.
InternalContext	getInternalContext() To get the AbstractInternalContext to use.
JavaNaming	getJavaNaming() To get the JavaNaming instance to be used.
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.
java.lang.String	getProperty(java.lang.String name) Returns the value of the given Castor XML-specific property.
XMLClassDescriptorResolver	getResolver() Returns the ClassDescriptorResolver for use during marshalling
java.lang.String	getRootElement() Returns the name of the root element to use
(package private) static boolean	hasFieldsAtLocation(java.lang.String location, XMLClassDescriptor classDesc) Returns true if any of the fields associated with the given XMLClassDescriptor are located at, or beneath, the given location.
static boolean	isCollection(java.lang.Class clazz) Returns true if the given Class is a considered a collection by the marshalling framework.
(package private) static boolean	isEnum(java.lang.Class type) Returns true if the given class should be treated as an enum type.
(package private) static boolean	isPrimitive(java.lang.Class type) Returns true if the given class should be treated as a primitive type.
void	marshal(java.lang.Object object) Marshals the given Object as XML using the DocumentHandler for this Marshaller.
static void	marshal(java.lang.Object object, org.xml.sax.ContentHandler handler) Marshals the given Object as XML using the given ContentHandler to send events to.
static void	marshal(java.lang.Object object, org.xml.sax.DocumentHandler handler) Marshals the given Object as XML using the given DocumentHandler to send events to.
static void	marshal(java.lang.Object object, org.w3c.dom.Node node) Marshals the given Object as XML using the given DOM Node to send events to.
static void	marshal(java.lang.Object object, java.io.Writer out) Marshals the given Object as XML using the given writer.
static boolean	namespaceEquals(java.lang.String ns1, java.lang.String ns2) Compares the given namespaces (as strings) for equality.
(package private) static boolean	primitiveOrWrapperEquals(java.lang.Class a, java.lang.Class b) Returns true if the given classes are both the same primitive or primitive wrapper class.
protected MarshalFramework.InheritanceMatch[]	searchInheritance(java.lang.String name, java.lang.String namespace, XMLClassDescriptor classDesc) Search there is a field descriptor which can accept one of the class descriptor which match the given name and namespace.
void	setContentHandler(org.xml.sax.ContentHandler contentHandler) To set the content handler which is used as destination at marshalling.
void	setDoctype(java.lang.String publicId, java.lang.String systemId) Sets the document type definition for the serializer.
void	setEncoding(java.lang.String encoding) Sets the encoding for the serializer.
void	setInternalContext(InternalContext internalContext) To set the AbstractInternalContext to use.
void	setLogWriter(java.io.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	setNamespaceMapping(java.lang.String nsPrefix, java.lang.String nsURI) Sets the mapping for the given Namespace prefix
void	setNoNamespaceSchemaLocation(java.lang.String schemaLocation) Sets the value for the xsi:noNamespaceSchemaLocation attribute.
void	setNSPrefixAtRoot(boolean nsPrefixAtRoot) Deprecated.
void	setProperty(java.lang.String name, java.lang.String value) Sets a custom value of a given Castor XML-specific property.
void	setResolver(XMLClassDescriptorResolver cdr) Sets the ClassDescriptorResolver to use during marshalling.
void	setRootElement(java.lang.String rootElement) Sets the name of the root element to use.
void	setSchemaLocation(java.lang.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(java.io.Writer out) Sets the java.io.Writer to be used during marshalling.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

depth

int depth

The depth of the sub tree, 0 denotes document level

XSI_NAMESPACE

public static final java.lang.String XSI_NAMESPACE

The XSI Namespace URI.

See Also:

Constant Field Values

XSI_SCHEMA_LOCATION

public static final java.lang.String XSI_SCHEMA_LOCATION

The name of the Schema location attribute.

See Also:

Constant Field Values

XSI_NO_NAMESPACE_SCHEMA_LOCATION

public static final java.lang.String XSI_NO_NAMESPACE_SCHEMA_LOCATION

The name of the no namespace schema location attribute.

See Also:

Constant Field Values

XML_LANG_ATTR

public static final java.lang.String XML_LANG_ATTR

The xml:lang attribute name.

See Also:

Constant Field Values

LANG_ATTR

public static final java.lang.String LANG_ATTR

The xml:lang attribute, without the "xml:" prefix.

See Also:

Constant Field Values

NIL_ATTR

public static final java.lang.String NIL_ATTR

The xsi:nil attribute, without the "xsi:" prefix.

See Also:

Constant Field Values

XSI_NIL_ATTR

public static final java.lang.String XSI_NIL_ATTR

The xsi:nil attribute.

See Also:

Constant Field Values

XML_SPACE_ATTR

public static final java.lang.String XML_SPACE_ATTR

The xml:space attribute name.

See Also:

Constant Field Values

SPACE_ATTR

public static final java.lang.String SPACE_ATTR

The xml:space attribute name, without the "xml:" prefix.

See Also:

Constant Field Values

TYPE_ATTR

public static final java.lang.String TYPE_ATTR

The xsi:type attribute name, without the "xsi:" prefix.

See Also:

Constant Field Values

TRUE_VALUE

public static final java.lang.String TRUE_VALUE

The value of 'true'.

See Also:

Constant Field Values

INTERNAL_XML_NAME

static final java.lang.String INTERNAL_XML_NAME

A constant to indicate a wrong name without setting null.

See Also:

Constant Field Values

JAVA_PREFIX

static final java.lang.String JAVA_PREFIX

The default prefix used for specifying the xsi:type as a classname instead of a schema name. This is a Castor specific hack.

See Also:

Constant Field Values

QNAME_NAME

static final java.lang.String QNAME_NAME

The name of the QName type.

See Also:

Constant Field Values

NO_FIELD_DESCRIPTORS

static final XMLFieldDescriptor[] NO_FIELD_DESCRIPTORS

An empty array of field descriptors.

Constructor Detail

Marshaller

public Marshaller(org.xml.sax.DocumentHandler handler)

Creates a new Marshaller with the given DocumentHandler.

Parameters:

handler - the DocumentHandler to "marshal" to.

Marshaller

public Marshaller(org.xml.sax.ContentHandler handler)
           throws java.io.IOException

Creates a new Marshaller with the given SAX ContentHandler.

Parameters:

handler - the ContentHandler to "marshal" to.

Marshaller

public Marshaller()

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

Marshaller

public Marshaller(java.io.Writer out)
           throws java.io.IOException

Creates a new Marshaller with the given writer.

Parameters:

out - the Writer to serialize to

Marshaller

public Marshaller(org.w3c.dom.Node node)

Creates a new Marshaller for the given DOM Node.

Parameters:

node - the DOM node to marshal into.

Method Detail

setWriter

public void setWriter(java.io.Writer out)
               throws java.io.IOException

Sets the java.io.Writer to be used during marshalling.

Parameters:

out - The writer to use for marshalling

Throws:

java.io.IOException - If there's a problem accessing the java.io.Writer provided

addProcessingInstruction

public void addProcessingInstruction(java.lang.String target,
                                     java.lang.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

setDoctype

public void setDoctype(java.lang.String publicId,
                       java.lang.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

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.

See Also:

setMarshalAsDocument(boolean)

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.

See Also:

setSupressXMLDeclaration(boolean)

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.

Throws:

MappingException

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.

setNamespaceMapping

public void setNamespaceMapping(java.lang.String nsPrefix,
                                java.lang.String nsURI)

Sets the mapping for the given Namespace prefix

Parameters:

nsPrefix - the namespace prefix

nsURI - the namespace that the prefix resolves to

setRootElement

public void setRootElement(java.lang.String rootElement)

Sets the name of the root element to use.

Parameters:

rootElement - The name of the root element to use.

getRootElement

public java.lang.String getRootElement()

Returns the name of the root element to use

Returns:

Returns the name of the root element to use

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 -

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 XMLClassDescriptorResolver getResolver()

Returns the ClassDescriptorResolver for use during marshalling

Returns:

the ClassDescriptorResolver

See Also:

setResolver(org.exolab.castor.xml.XMLClassDescriptorResolver)

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

See Also:

setMapping(org.exolab.castor.mapping.Mapping), getResolver()

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.

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.

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.

marshal

public static void marshal(java.lang.Object object,
                           java.io.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.

Throws:

MarshalException

ValidationException

marshal

public static void marshal(java.lang.Object object,
                           org.xml.sax.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.

Throws:

MarshalException

ValidationException

marshal

public static void marshal(java.lang.Object object,
                           org.xml.sax.ContentHandler handler)
                    throws MarshalException,
                           ValidationException,
                           java.io.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.

Throws:

MarshalException

ValidationException

java.io.IOException

marshal

public static void marshal(java.lang.Object object,
                           org.w3c.dom.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.

Throws:

MarshalException

ValidationException

marshal

public void marshal(java.lang.Object object)
             throws MarshalException,
                    ValidationException

Marshals the given Object as XML using the DocumentHandler for this Marshaller.

Parameters:

object - The Object to marshal.

Throws:

MarshalException

ValidationException

setLogWriter

public void setLogWriter(java.io.PrintWriter printWriter)

Sets the PrintWriter used for logging

Parameters:

printWriter - the PrintWriter to use for logging

setEncoding

public void setEncoding(java.lang.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

setNoNamespaceSchemaLocation

public void setNoNamespaceSchemaLocation(java.lang.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.

setSchemaLocation

public void setSchemaLocation(java.lang.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.

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.

getProperty

public java.lang.String getProperty(java.lang.String name)

Returns the value of the given Castor XML-specific property.

Parameters:

name - Qualified name of the CASTOR XML-specific property.

Returns:

The current value of the given property.

Since:

1.1.2

setProperty

public void setProperty(java.lang.String name,
                        java.lang.String value)

Sets a custom value of a given Castor XML-specific property.

Parameters:

name - Name of the Castor XML property

value - Custom value to set.

Since:

1.1.2

setContentHandler

public void setContentHandler(org.xml.sax.ContentHandler contentHandler)

To set the content handler which is used as destination at marshalling.

Parameters:

contentHandler - the content handler to use as destination at marshalling

getJavaNaming

public JavaNaming getJavaNaming()

To get the JavaNaming instance to be used.

Returns:

the JavaNaming to be used

getInternalContext

public InternalContext getInternalContext()

To get the AbstractInternalContext to use.

Returns:

the AbstractInternalContext to use

setInternalContext

public void setInternalContext(InternalContext internalContext)

To set the AbstractInternalContext to use.

Parameters:

internalContext - the AbstractInternalContext to use

isCollection

public static boolean isCollection(java.lang.Class clazz)

Returns true if the given Class is a considered a collection by the marshalling framework.

Parameters:

clazz - the Class to check

Returns:

true if the given Class is considered a collection. TODO: joachim: this code exists somewhere else too!!

getCollectionHandler

public CollectionHandler getCollectionHandler(java.lang.Class clazz)

Returns the CollectionHandler associated with the given collection, or null if no such handler exists.

Parameters:

clazz - the Class to check

Returns:

the CollectionHandler for the associated type.

isPrimitive

static boolean isPrimitive(java.lang.Class type)

Returns true if the given class should be treated as a primitive type. This method will return true for all Java primitive types, the set of primitive object wrappers, as well as Strings.

Parameters:

type - the Class to check

Returns:

true if the given class should be treated as a primitive type TODO: joachim: this code exists somewhere else too!!

isEnum

static boolean isEnum(java.lang.Class type)

Returns true if the given class should be treated as an enum type. This method will return true for all Java 5 (or later) enums, and for enum-style classes.

Parameters:

type - the Class to check

Returns:

true if the given class should be treated as an enum

hasFieldsAtLocation

static final boolean hasFieldsAtLocation(java.lang.String location,
                                         XMLClassDescriptor classDesc)

Returns true if any of the fields associated with the given XMLClassDescriptor are located at, or beneath, the given location.

Parameters:

location - the location to compare against

classDesc - the XMLClassDescriptor in which to check the field locations

Returns:

true if any of the fields has a location associated

namespaceEquals

public static boolean namespaceEquals(java.lang.String ns1,
                                      java.lang.String ns2)

Compares the given namespaces (as strings) for equality. null and empty values are considered equal.

Parameters:

ns1 - the namespace to compare to argument ns2

ns2 - the namespace to compare to argument ns1

Returns:

true if the namespaces are considert equal TODO: joachim put it into XMLNaming!

primitiveOrWrapperEquals

static boolean primitiveOrWrapperEquals(java.lang.Class a,
                                        java.lang.Class b)

Returns true if the given classes are both the same primitive or primitive wrapper class. For exmaple, if class "a" is an int (Integer.TYPE) and class "b" is either an int or Integer.class then true will be returned, otherwise false.

Parameters:

a - compare a with b

b - compare a with b

Returns:

true if both a and b are considered equal

searchInheritance

protected MarshalFramework.InheritanceMatch[] searchInheritance(java.lang.String name,
                                                                java.lang.String namespace,
                                                                XMLClassDescriptor classDesc)
                                                         throws MarshalException

Search there is a field descriptor which can accept one of the class descriptor which match the given name and namespace.

Parameters:

name - XML name of the field

namespace - namespace of the field

classDesc - the class descriptor to match against

Returns:

An array of InheritanceMatch.

Throws:

MarshalException - if the resolver called fails fatally