org.exolab.castor.xml

Class Unmarshaller

public class Unmarshaller extends Object

An unmarshaller to allowing unmarshalling of XML documents to Java Objects. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.

Version: $Revision: 6392 $ $Date: 2006-02-23 14:16:51 -0700 (Thu, 23 Feb 2006) $

Author: Keith Visco

Field Summary
EntityResolverentityResolver
The EntityResolver used for resolving entities
Constructor Summary
Unmarshaller()
Creates a new basic Unmarshaller When using this constructor it will most likely be necessary to use a mapping file or ClassDescriptorResolver So that the Unmarshaller can find the classes during the unmarshalling process.
Unmarshaller(Class c)
Creates a new Unmarshaller with the given Class
Unmarshaller(Class c, ClassLoader loader)
Creates a new Unmarshaller with the given Class
Unmarshaller(Mapping mapping)
Creates a new Unmarshaller with the given Mapping
Unmarshaller(Object root)
Creates a new Unmarshaller with the given Object
Method Summary
voidaddNamespaceToPackageMapping(String nsURI, String packageName)
Adds a mapping from the given namespace URI to the given package name
UnmarshalHandlercreateHandler()
Creates and initalizes an UnmarshalHandler
static ContentHandlergetContentHandler(UnmarshalHandler handler)
Returns a ContentHandler for the given UnmarshalHandler
voidsetClassLoader(ClassLoader loader)
Sets the ClassLoader to use when loading new classes.
voidsetClearCollections(boolean clear)
Sets whether or not to clear collections (including arrays) upon first use to remove default values.
voidsetDebug(boolean debug)
Turns debuging on or off.
voidsetEntityResolver(EntityResolver entityResolver)
Sets the EntityResolver to use when resolving system and public ids with respect to entites and Document Type.
voidsetIDResolver(IDResolver idResolver)
Sets the IDResolver to use when resolving IDREFs for which no associated element may exist in XML document.
voidsetIgnoreExtraAttributes(boolean ignoreExtraAtts)
Sets whether or not attributes that do not match a specific field should simply be ignored or reported as an error.
voidsetIgnoreExtraElements(boolean ignoreExtraElements)
Sets whether or not elements that do not match a specific field should simply be ignored or reported as an error.
voidsetLogWriter(PrintWriter printWriter)
Sets the PrintWriter used for logging
voidsetMapping(Mapping mapping)
Sets the Mapping to use during unmarshalling.
voidsetObjectFactory(ObjectFactory objectFactory)
Set an object factory for the unmarshaller.
voidsetResolver(XMLClassDescriptorResolver cdr)
Sets the ClassDescriptorResolver to use during unmarshalling
voidsetReuseObjects(boolean reuse)
Sets a boolean that when true indicates that objects contained within the object model should be re-used where appropriate.
voidsetUnmarshalListener(UnmarshalListener listener)
Sets an optional UnmarshalListener to receive pre and post unmarshal notification for each Object in the tree.
voidsetValidation(boolean validate)
Sets the flag for validation.
voidsetWhitespacePreserve(boolean preserve)
Sets the top-level whitespace (xml:space) to either preserving or non preserving.
Objectunmarshal(Reader reader)
Unmarshals Objects of this Unmarshaller's Class type.
Objectunmarshal(EventProducer eventProducer)
Unmarshals Objects of this Unmarshaller's Class type.
Objectunmarshal(SAX2EventProducer eventProducer)
Unmarshals Objects of this Unmarshaller's Class type.
Objectunmarshal(InputSource source)
Unmarshals Objects of this Unmarshaller's Class type.
Objectunmarshal(Node node)
Unmarshals Objects of this Unmarshaller's Class type.
static Objectunmarshal(Class c, Reader reader)
Unmarshals Objects of the given Class type.
static Objectunmarshal(Class c, InputSource source)
Unmarshals Objects of the given Class type.
static Objectunmarshal(Class c, Node node)
Unmarshals Objects of the given Class type.

Field Detail

entityResolver

EntityResolver entityResolver
The EntityResolver used for resolving entities

Constructor Detail

Unmarshaller

public Unmarshaller()
Creates a new basic Unmarshaller When using this constructor it will most likely be necessary to use a mapping file or ClassDescriptorResolver So that the Unmarshaller can find the classes during the unmarshalling process.

Unmarshaller

public Unmarshaller(Class c)
Creates a new Unmarshaller with the given Class

Parameters: c the Class to create the Unmarshaller for, this may be null, if the Unmarshaller#setMapping is called to load a mapping for the root element of xml document.

Unmarshaller

public Unmarshaller(Class c, ClassLoader loader)
Creates a new Unmarshaller with the given Class

Parameters: c the Class to create the Unmarshaller for, this may be null, if the Unmarshaller#setMapping is called to load a mapping for the root element of xml document. loader The ClassLoader to use.

Unmarshaller

public Unmarshaller(Mapping mapping)
Creates a new Unmarshaller with the given Mapping

Parameters: mapping The Mapping to use.

Unmarshaller

public Unmarshaller(Object root)
Creates a new Unmarshaller with the given Object

Parameters: root the instance to unmarshal into. This may be null, if the Unmarshaller#setMapping is called to load a mapping for the root element of xml document.

Method Detail

addNamespaceToPackageMapping

public void addNamespaceToPackageMapping(String nsURI, String packageName)
Adds a mapping from the given namespace URI to the given package name

Parameters: nsURI the namespace URI to map from packageName the package name to map to

createHandler

public UnmarshalHandler createHandler()
Creates and initalizes an UnmarshalHandler

Returns: the new UnmarshalHandler

getContentHandler

public static ContentHandler getContentHandler(UnmarshalHandler handler)
Returns a ContentHandler for the given UnmarshalHandler

Returns: the ContentHandler

setClassLoader

public void setClassLoader(ClassLoader loader)
Sets the ClassLoader to use when loading new classes.
Note:This ClassLoader is used for classes loaded by the unmarshaller only. If a Mapping has been set, the Mapping has it's own ClassLoader and may also need to be set propertly.

Parameters: loader the ClassLoader to use

setClearCollections

public void setClearCollections(boolean clear)
Sets whether or not to clear collections (including arrays) upon first use to remove default values. By default, and for backward compatibility with previous versions of Castor this value is false, indicating that collections are not cleared before initial use by Castor.

Parameters: clear the boolean value that when true indicates collections should be cleared upon first use.

setDebug

public void setDebug(boolean debug)
Turns debuging on or off. If no Log Writer has been set, then System.out will be used to display debug information

Parameters: debug the flag indicating whether to generate debug information. A value of true, will turn debuggin on.

See Also: Unmarshaller

setEntityResolver

public void setEntityResolver(EntityResolver entityResolver)
Sets the EntityResolver to use when resolving system and public ids with respect to entites and Document Type.

Parameters: entityResolver the EntityResolver to use when resolving System and Public ids.

setIDResolver

public void setIDResolver(IDResolver idResolver)
Sets the IDResolver to use when resolving IDREFs for which no associated element may exist in XML document.

Parameters: idResolver the IDResolver to use when resolving IDREFs for which no associated element may exist in the XML document.

setIgnoreExtraAttributes

public void setIgnoreExtraAttributes(boolean ignoreExtraAtts)
Sets whether or not attributes that do not match a specific field should simply be ignored or reported as an error. By default, extra attributes are ignored.

Parameters: ignoreExtraAtts a boolean that when true will allow non-matched attributes to simply be ignored.

setIgnoreExtraElements

public void setIgnoreExtraElements(boolean ignoreExtraElements)
Sets whether or not elements that do not match a specific field should simply be ignored or reported as an error. By default, extra elements are flagged as an error.

Parameters: ignoreExtraElements a boolean that when true will allow non-matched elements to simply be ignored.

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 Mapping to use during unmarshalling. If the Mapping has a ClassLoader it will be used during unmarshalling.

Parameters: mapping Mapping to use during unmarshalling.

See Also: Unmarshaller

setObjectFactory

public void setObjectFactory(ObjectFactory objectFactory)
Set an object factory for the unmarshaller. This factory will be used to construct the objects being unmarshalled.

Parameters: objectFactory Factory used for constructing objects during unmarshalling.

setResolver

public void setResolver(XMLClassDescriptorResolver 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 Unmarshaller

setReuseObjects

public void setReuseObjects(boolean reuse)
Sets a boolean that when true indicates that objects contained within the object model should be re-used where appropriate. This is only valid when unmarshalling to an existing object.

Parameters: reuse the boolean indicating whether or not to re-use existing objects in the object model.

setUnmarshalListener

public void setUnmarshalListener(UnmarshalListener listener)
Sets an optional UnmarshalListener to receive pre and post unmarshal notification for each Object in the tree. An UnmarshalListener is often used to allow objects to appropriately initialize themselves by taking appliction specific behavior as they are unloaded. 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 UnmarshalListener to set.

setValidation

public void setValidation(boolean validate)
Sets the flag for validation.

Parameters: validate A boolean to indicate whether or not validation should be done during umarshalling.
By default validation will be performed.

setWhitespacePreserve

public void setWhitespacePreserve(boolean preserve)
Sets the top-level whitespace (xml:space) to either preserving or non preserving. The XML document can override this value using xml:space on specific elements.This sets the "default" behavior when xml:space="default".

Parameters: preserve a boolean that when true enables whitespace preserving by default.

unmarshal

public Object unmarshal(Reader reader)
Unmarshals Objects of this Unmarshaller's Class type. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.

Parameters: reader the Reader to read the XML from

Throws: MarshalException when there is an error during the unmarshalling process ValidationException when there is a validation error

unmarshal

public Object unmarshal(EventProducer eventProducer)

Deprecated: please use @see #unmarshal(SAX2EventProducer) instead.

Unmarshals Objects of this Unmarshaller's Class type. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.

Parameters: eventProducer the EventProducer which produces the SAX events

Throws: MarshalException when there is an error during the unmarshalling process ValidationException when there is a validation error

unmarshal

public Object unmarshal(SAX2EventProducer eventProducer)
Unmarshals Objects of this Unmarshaller's Class type. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.

Parameters: eventProducer the SAX2EventProducer instance which produces the SAX 2 events

Throws: MarshalException when there is an error during the unmarshalling process ValidationException when there is a validation error

Since: 1.0M3

unmarshal

public Object unmarshal(InputSource source)
Unmarshals Objects of this Unmarshaller's Class type. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.

Parameters: source the InputSource to read the XML from

Throws: MarshalException when there is an error during the unmarshalling process ValidationException when there is a validation error

unmarshal

public Object unmarshal(Node node)
Unmarshals Objects of this Unmarshaller's Class type. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.

Parameters: node the DOM node to read the XML from

Throws: MarshalException when there is an error during the unmarshalling process ValidationException when there is a validation error

unmarshal

public static Object unmarshal(Class c, Reader reader)
Unmarshals Objects of the given Class type. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.

Note:This is a *static* method, any mapping files set on a particular Unmarshaller instance, and any changes made via setters will be unavailable to this method.

Parameters: c the Class to create a new instance of reader the Reader to read the XML from

Throws: MarshalException when there is an error during the unmarshalling process ValidationException when there is a validation error

unmarshal

public static Object unmarshal(Class c, InputSource source)
Unmarshals Objects of the given Class type. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.

Note:This is a *static* method, any mapping files set on a particular Unmarshaller instance, and any changes made via setters will be unavailable to this method.

Parameters: c the Class to create a new instance of source the InputSource to read the XML from

Throws: MarshalException when there is an error during the unmarshalling process ValidationException when there is a validation error

unmarshal

public static Object unmarshal(Class c, Node node)
Unmarshals Objects of the given Class type. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.

Note:This is a *static* method, any mapping files set on a particular Unmarshaller instance, and any changes made via setters will be unavailable to this method.

Parameters: c The Class to create a new instance of. node The DOM Node to read the XML from.

Throws: MarshalException When there is an error during the unmarshalling process. ValidationException When there is a validation error.

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