org.exolab.castor.xml

Class Marshaller

public class Marshaller extends MarshalFramework

A Marshaller to allowing serializing 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: 1.4 $ $Date: 2003/05/30 02:20:25 $

Author: Keith Visco

Field Summary
intdepth
The depth of the sub tree, 0 denotes document level
static booleanenableDebug
A static flag used to enable debugging when using the static marshal methods.
Constructor Summary
Marshaller(DocumentHandler handler)
Creates a new Marshaller with the given DocumentHandler.
Marshaller(ContentHandler handler)
Creates a new Marshaller with the given SAX ContentHandler.
Marshaller(Writer out)
Creates a new Marshaller with the given writer.
Marshaller(Node node)
Creates a new Marshaller for the given DOM Node.
Method Summary
voidaddProcessingInstruction(String target, String data)
Adds the given processing instruction data to the set of processing instructions to output during marshalling.
booleangetMarshalExtendedType()
If True the marshaller will use the 'xsi:type' attribute to marshall a field value that extended the defined field type.
booleangetNSPrefixAtRoot()
Returns True if the given namespace mappings will be declared at the root node.
StringgetRootElement()
Returns the name of the root element to use
static voidmarshal(Object object, Writer out)
Marshals the given Object as XML using the given writer
static voidmarshal(Object object, DocumentHandler handler)
Marshals the given Object as XML using the given DocumentHandler to send events to.
static voidmarshal(Object object, ContentHandler handler)
Marshals the given Object as XML using the given ContentHandler to send events to.
static voidmarshal(Object object, Node node)
Marshals the given Object as XML using the given DOM Node to send events to.
voidmarshal(Object object)
Marshals the given Object as XML using the DocumentHandler for this Marshaller.
voidsetDebug(boolean debug)
Sets the flag to turn on and off debugging
voidsetDoctype(String publicId, String systemId)
Sets the document type definition for the serializer.
voidsetEncoding(String encoding)
Sets the encoding for the serializer.
voidsetLogWriter(PrintWriter printWriter)
Sets the PrintWriter used for logging
voidsetMapping(Mapping mapping)
Sets the given mapping to be used by the marshalling Framework.
voidsetMarshalAsDocument(boolean asDocument)
Sets whether or not to marshal as a document which includes the XML declaration, and if necessary the DOCTYPE declaration.
voidsetMarshalExtendedType(boolean marshalExtendedType)
If True the marshaller will use the 'xsi:type' attribute to marshall a field value that extended the defined field type.
voidsetMarshalListener(MarshalListener listener)
Sets an optional MarshalListener to recieve pre and post marshal notification for each Object in the tree.
voidsetNamespaceMapping(String nsPrefix, String nsURI)
Sets the mapping for the given Namespace prefix
voidsetNoNamespaceSchemaLocation(String schemaLocation)
Sets the value for the xsi:noNamespaceSchemaLocation attribute.
voidsetNSPrefixAtRoot(boolean nsPrefixAtRoot)
Set to True to declare the given namespace mappings at the root node.
voidsetResolver(ClassDescriptorResolver cdr)
Sets the ClassDescriptorResolver to use during unmarshalling
voidsetRootElement(String rootElement)
Sets the name of the root element to use
voidsetSchemaLocation(String schemaLocation)
Sets the value for the xsi:schemaLocation attribute.
voidsetSuppressXSIType(boolean suppressXSIType)
Sets whether or not the xsi:type attribute should appear on the marshalled document.
voidsetValidation(boolean validate)
Sets whether or not to validate the object model before marshalling.

Field Detail

depth

int depth
The depth of the sub tree, 0 denotes document level

enableDebug

public static boolean enableDebug
A static flag used to enable debugging when using the static marshal methods.

Constructor Detail

Marshaller

public Marshaller(DocumentHandler handler)
Creates a new Marshaller with the given DocumentHandler.

Parameters: handler the DocumentHandler to "marshal" to.

Marshaller

public Marshaller(ContentHandler handler)
Creates a new Marshaller with the given SAX ContentHandler.

Parameters: handler the ContentHandler to "marshal" to.

Marshaller

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

Parameters: out the Writer to serialize to

Marshaller

public Marshaller(Node node)
Creates a new Marshaller for the given DOM Node.

Parameters: node the DOM node to marshal into.

Method Detail

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.

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 static void marshal(Object object, Writer out)
Marshals the given Object as XML using the given writer

Parameters: obj the Object to marshal out the writer to marshal to

Throws: org.exolab.castor.xml.MarshalException org.exolab.castor.xml.ValidationException

marshal

public static void marshal(Object object, DocumentHandler handler)
Marshals the given Object as XML using the given DocumentHandler to send events to.

Parameters: obj the Object to marshal handler the DocumentHandler to marshal to

Throws: org.exolab.castor.xml.MarshalException org.exolab.castor.xml.ValidationException

marshal

public static void marshal(Object object, ContentHandler handler)
Marshals the given Object as XML using the given ContentHandler to send events to.

Parameters: obj the Object to marshal handler the ContentHandler to marshal to

Throws: org.exolab.castor.xml.MarshalException org.exolab.castor.xml.ValidationException

marshal

public static void marshal(Object object, Node node)
Marshals the given Object as XML using the given DOM Node to send events to.

Parameters: obj the Object to marshal node the DOM Node to marshal to

Throws: org.exolab.castor.xml.MarshalException org.exolab.castor.xml.ValidationException

marshal

public void marshal(Object object)
Marshals the given Object as XML using the DocumentHandler for this Marshaller.

Parameters: obj the Object to marshal

Throws: org.exolab.castor.xml.MarshalException org.exolab.castor.xml.ValidationException

setDebug

public void setDebug(boolean debug)
Sets the flag to turn on and off debugging

Parameters: debug the flag indicating whether or not debug information should be generated

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)
Sets the given mapping to be used by the marshalling Framework. If a ClassDescriptorResolver exists This mapping will be added to the existing Resolver. Otherwise a new ClassDescriptorResolver will be created.

Parameters: mapping the 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 fragment (no XML declaration or DOCTYPE).

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.

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.

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

setResolver

public void setResolver(ClassDescriptorResolver cdr)
Sets the ClassDescriptorResolver to use during unmarshalling

Parameters: cdr the ClassDescriptorResolver to use

See Also:
Note: This method will nullify any Mapping currently being used by this Marshaller

setRootElement

public void setRootElement(String rootElement)
Sets the name of the root element to use

Parameters: 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.

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.

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.

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