Marshaller (Castor JavaDoc)

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: 8820 $ $Date: 2006-04-13 06:47:36 -0600 (Thu, 13 Apr 2006) $

Author:

Keith Visco

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`(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
- 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

Constructors
Constructor	Description
`Marshaller()`	Creates a default instance of Marshaller, where the sink needs to be set separately.
`Marshaller(java.io.Writer out)`	Creates a new Marshaller with the given writer.
`Marshaller(InternalContext internalContext)`	The one `Marshaller` constructor that is used by `XMLContext` which sets an `InternalContext` that comes from outside.
`Marshaller(org.w3c.dom.Node node)`	Creates a new `Marshaller` for the given DOM `Node`.
`Marshaller(org.xml.sax.ContentHandler contentHandler)`	Creates a new `Marshaller` with the given SAX `ContentHandler`.
`Marshaller(org.xml.sax.DocumentHandler handler)`	Creates a new `Marshaller` with the given SAX `DocumentHandler`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method	Description
`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.
`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
`boolean`	`getValidation()`
`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, java.io.Writer out)`	Marshals the given Object as XML using the given writer.
`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, 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.
`void`	`setContentHandler(org.xml.sax.ContentHandler contentHandler)`	To set the SAX `ContentHandler` 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`	`setDocumentHandler(org.xml.sax.DocumentHandler handler)`	Sets the given SAX `DocumentHandler` to 'marshal' into.
`void`	`setEncoding(java.lang.String encoding)`	Sets the encoding for the serializer.
`void`	`setInternalContext(InternalContext internalContext)`	To set the `InternalContext` to use, and to initialize `Marshaller` properties linked to it.
`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`	`setNode(org.w3c.dom.Node node)`	Sets the W3C `Node` instance to marshal to.
`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 org.exolab.castor.xml.MarshalFramework
getCollectionHandler, getInternalContext, getJavaNaming, hasFieldsAtLocation, isCollection, isEnum, isPrimitive, namespaceEquals, primitiveOrWrapperEquals, searchInheritance

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Marshaller
```
public Marshaller(org.xml.sax.DocumentHandler handler)
```
    Creates a new Marshaller with the given SAX DocumentHandler.
    
    Parameters:
    
    handler - the SAX DocumentHandler to "marshal" to.
    
    See Also:
    
    XMLContext
  - Marshaller
```
public Marshaller(org.xml.sax.ContentHandler contentHandler)
```
    Creates a new Marshaller with the given SAX ContentHandler.
    
    Parameters:
    
    contentHandler - the ContentHandler to "marshal" to.
    
    See Also:
    
    XMLContext
  - Marshaller
```
public Marshaller(InternalContext internalContext)
```
    The one Marshaller constructor that is used by XMLContext which sets an InternalContext that comes from outside. Writer or ContentHandler have to be set in a second step.
    
    Parameters:
    
    internalContext - the InternalContext to initialize the Marshaller instance with
  - 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
    
    Throws:
    
    java.io.IOException - If the given Writer instance cannot be opened.
    
    See Also:
    
    XMLContext
  - 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.
    
    See Also:
    
    XMLContext
- Method Detail
  - setDocumentHandler
```
public void setDocumentHandler(org.xml.sax.DocumentHandler handler)
```
    Sets the given SAX DocumentHandler to 'marshal' into.
    
    Parameters:
    
    handler - the SAX DocumentHandler to "marshal" to.
  - 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
  - setNode
```
public void setNode(org.w3c.dom.Node node)
```
    Sets the W3C Node instance to marshal to.
    
    Parameters:
    
    node - the DOM Node to marshal into.
  - setInternalContext
```
public void setInternalContext(InternalContext internalContext)
```
    To set the InternalContext to use, and to initialize Marshaller properties linked to it.
    
    Overrides:
    
    setInternalContext in class MarshalFramework
    
    Parameters:
    
    internalContext - the InternalContext to use
  - 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.
  - getValidation
```
public boolean getValidation()
```
  - 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 SAX ContentHandler which is used as destination at marshalling.
    
    Parameters:
    
    contentHandler - the SAX ContentHandler to use as destination at marshalling

Class Marshaller

Nested Class Summary

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

Field Summary

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

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Constructor Detail

Marshaller

Marshaller

Marshaller

Marshaller

Marshaller

Marshaller

Method Detail

setDocumentHandler

setWriter

setNode

setInternalContext

addProcessingInstruction

setDoctype

setSupressXMLDeclaration

setMarshalAsDocument

setMapping

setMarshalListener

setNamespaceMapping

setRootElement

getRootElement

setNSPrefixAtRoot

getNSPrefixAtRoot

getResolver

setResolver

setValidation

getValidation

setMarshalExtendedType

getMarshalExtendedType

marshal

marshal

marshal

marshal

marshal

setLogWriter

setEncoding

setNoNamespaceSchemaLocation

setSchemaLocation

setSuppressNamespaces

setSuppressXSIType

setUseXSITypeAtRoot

getProperty

setProperty

setContentHandler