org.exolab.castor.xml
Class UnmarshalHandler

java.lang.Object
  org.exolab.castor.xml.UnmarshalHandler

All Implemented Interfaces:

ContentHandler, DocumentHandler, ErrorHandler

public final class UnmarshalHandler
extends Object
implements ContentHandler, DocumentHandler, ErrorHandler

An unmarshaller to allowing unmarshaling 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 unmarshaled.

Version:

$Revision: 9086 $ $Date: 2006-05-25 06:41:12 -0600 (Thu, 25 May 2006) $

Author:

Keith Visco

Nested Class Summary

static class	MarshalFramework.InheritanceMatch Used to store the information when we find a possible inheritance.
static class	UnmarshalHandler.ArrayHandler A class for handling Arrays during unmarshalling.

Field Summary

static String	LANG_ATTR The xml:lang attribute, without the "xml:" prefix.
static String	NIL_ATTR The xsi:nil attribute, without the "xsi:" prefix.
protected static ResourceBundle	resourceBundle resource bundle
static String	SPACE_ATTR The xml:space attribute name, without the "xml:" prefix.
static String	TRUE_VALUE The value of 'true'.
static String	TYPE_ATTR The xsi:type attribute name, without the "xsi:" prefix.
static String	XML_LANG_ATTR The xml:lang attribute name.
static String	XML_SPACE_ATTR The xml:space attribute name.
static String	XSI_NAMESPACE The XSI Namespace URI.
static String	XSI_NIL_ATTR The xsi:nil attribute.
static String	XSI_NO_NAMESPACE_SCHEMA_LOCATION The name of the no namespace schema location attribute.
static String	XSI_SCHEMA_LOCATION The name of the Schema location attribute.

Constructor Summary

protected	UnmarshalHandler() Creates a new UnmarshalHandler The "root" class will be obtained by looking into the mapping for a descriptor that matches the root element.
protected	UnmarshalHandler(Class<?> topClass) Creates a new UnmarshalHandler.
protected	UnmarshalHandler(InternalContext internalContext, Class<?> topClass) Creates a new UnmarshalHandler.

Method Summary

void	addNamespaceToPackageMapping(String nsURI, String packageName) Adds a mapping from the given namespace URI to the given package name
void	characters(char[] ch, int start, int length)
void	endDocument()
void	endElement(String name)
void	endElement(String namespaceURI, String localName, String qName) ContentHandler#endElement Signals the end of an element
void	endPrefixMapping(String prefix) Signals to end the namespace prefix mapping
void	error(SAXParseException exception)
void	fatalError(SAXParseException exception)
AnyNode	getAnyNode() returns the AnyNode (if any).
AnyNodeUnmarshalHandler	getAnyNodeHandler() Returns the currently used AnyNodeUnmarshalHandler instance.
ClassLoader	getClassLoader() Returns the current ClassLoader in use.
CollectionHandler	getCollectionHandler(Class clazz) Returns the CollectionHandler associated with the given collection, or null if no such handler exists.
Object	getCurrentObject() Returns the Object that the UnmarshalHandler is currently handling (within the object model), or null if the current element is a simpleType.
UnmarshalListenerDelegate	getDelegateUnmarshalListener() Returns the currently active UnmarshalListenerDelegate instance
Locator	getDocumentLocator()
InternalContext	getInternalContext() To get the AbstractInternalContext to use.
JavaNaming	getJavaNaming() To get the JavaNaming instance to be used.
NamespaceHandling	getNamespaceHandling() Returns the NamespaceHandling in use.
Object	getObject() Returns the "root" Object (ie. the entire object model) being unmarshalled.
ObjectFactory	getObjectFactory() Returns the ObjectFactory instance in use.
Hashtable<String,org.exolab.castor.xml.ReferenceInfo>	getResolveTable() Hashtable to store idReference and ReferenceInfo
UnmarshalStateStack	getStateStack() Returnss a refrence to the UnmarshalStateStack instance currently in use.
StrictElementHandler	getStrictElementHandler() Returns the StrictElementHandler in use.
UnmarshalState	getTopState() Returns the top UnmarshalState instance from the UnmarshalStateStack.
void	ignorableWhitespace(char[] ch, int start, int length)
boolean	isClearCollections() Indicates whether it's necessary to clear any collection or not.
static boolean	isCollection(Class clazz) Returns true if the given Class is a considered a collection by the marshalling framework.
boolean	isReuseObjects() Indicats whether Object instances should be re-used.
static boolean	namespaceEquals(String ns1, String ns2) Compares the given namespaces (as strings) for equality.
void	processingInstruction(String target, String data)
protected MarshalFramework.InheritanceMatch[]	searchInheritance(String name, 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	setAnyNode(AnyNode node) sets the AnyNode
void	setClassLoader(ClassLoader loader) Sets the ClassLoader to use when loading classes
void	setClearCollections(boolean clear) Sets whether or not to clear collections (including arrays) upon first use to remove default values.
void	setDebug(boolean debug) Deprecated.
void	setDocumentLocator(Locator locator)
void	setIDResolver(IDResolver idResolver) Sets the IDResolver to use when resolving IDREFs for which no associated element may exist in XML document.
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.
void	setIgnoreExtraElements(boolean ignoreExtraElems) Sets whether or not elements that do not match a specific field should simply be ignored or reported as an error.
void	setInternalContext(InternalContext internalContext) To set the AbstractInternalContext to use.
void	setLogWriter(PrintWriter printWriter) Deprecated.
void	setObjectFactory(ObjectFactory objectFactory) Sets a (custom) ObjectFactory instance.
void	setReuseObjects(boolean reuse) Sets a boolean that when true indicates that objects contained within the object model should be re-used where appropriate.
void	setRootObject(Object root) Sets the root (top-level) object to use for unmarshalling into.
void	setUnmarshalListener(UnmarshalListener listener) Deprecated. please move to the new UnmarshalListener interface
void	setUnmarshalListener(UnmarshalListener listener) Sets an UnmarshalListener.
void	setValidation(boolean validate) Sets the flag for validation.
void	setWhitespacePreserve(boolean preserve) Sets the top-level whitespace (xml:space) to either preserving or non preserving.
void	skippedEntity(String name) Signals that an entity was skipped by the parser
void	startDocument() Signals the start of a new document
void	startElement(String name, AttributeList attList) Deprecated.
void	startElement(String namespaceURI, String localName, String qName, Attributes atts) ContentHandler#startElement Signals the start of element.
void	startPrefixMapping(String prefix, String uri) Signals to start the namespace - prefix mapping
static Object	toPrimitiveObject(Class<?> type, String value) Converts a String to the given primitive object type.
void	warning(SAXParseException exception)

Methods inherited from class java.lang.Object

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

Field Detail

resourceBundle

protected static ResourceBundle resourceBundle

resource bundle

XSI_NAMESPACE

public static final String XSI_NAMESPACE

The XSI Namespace URI.

See Also:

Constant Field Values

XSI_SCHEMA_LOCATION

public static final String XSI_SCHEMA_LOCATION

The name of the Schema location attribute.

See Also:

Constant Field Values

XSI_NO_NAMESPACE_SCHEMA_LOCATION

public static final 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 String XML_LANG_ATTR

The xml:lang attribute name.

See Also:

Constant Field Values

LANG_ATTR

public static final String LANG_ATTR

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

See Also:

Constant Field Values

NIL_ATTR

public static final String NIL_ATTR

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

See Also:

Constant Field Values

XSI_NIL_ATTR

public static final String XSI_NIL_ATTR

The xsi:nil attribute.

See Also:

Constant Field Values

XML_SPACE_ATTR

public static final String XML_SPACE_ATTR

The xml:space attribute name.

See Also:

Constant Field Values

SPACE_ATTR

public static final String SPACE_ATTR

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

See Also:

Constant Field Values

TYPE_ATTR

public static final String TYPE_ATTR

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

See Also:

Constant Field Values

TRUE_VALUE

public static final String TRUE_VALUE

The value of 'true'.

See Also:

Constant Field Values

Constructor Detail

UnmarshalHandler

protected UnmarshalHandler()

Creates a new UnmarshalHandler The "root" class will be obtained by looking into the mapping for a descriptor that matches the root element.

UnmarshalHandler

protected UnmarshalHandler(Class<?> topClass)

Creates a new UnmarshalHandler.

Parameters:

topClass - the Class to create the UnmarshalHandler for

UnmarshalHandler

protected UnmarshalHandler(InternalContext internalContext,
                           Class<?> topClass)

Creates a new UnmarshalHandler.

Parameters:

internalContext - the InternalContext to use

topClass - the Class to work for

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

getCurrentObject

public Object getCurrentObject()

Returns the Object that the UnmarshalHandler is currently handling (within the object model), or null if the current element is a simpleType.

Returns:

the Object currently being unmarshalled, or null if the current element is a simpleType.

getObject

public Object getObject()

Returns the "root" Object (ie. the entire object model) being unmarshalled.

Returns:

the root Object being unmarshalled.

setClassLoader

public void setClassLoader(ClassLoader loader)

Sets the ClassLoader to use when loading classes

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)

Deprecated.

Included for backward compatibility. Debug is replaced with commons-logging.

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 ignoreExtraElems)

Sets whether or not elements that do not match a specific field should simply be ignored or reported as an error. By default, extra attributes are ignored.

Parameters:

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

setLogWriter

public void setLogWriter(PrintWriter printWriter)

Deprecated.

Custom logging replaced with commons-logging.

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.

setRootObject

public void setRootObject(Object root)

Sets the root (top-level) object to use for unmarshalling into.

Parameters:

root - the instance to unmarshal into.

setUnmarshalListener

public void setUnmarshalListener(UnmarshalListener listener)

Deprecated. please move to the new UnmarshalListener interface

Sets an UnmarshalListener.

Parameters:

listener - the UnmarshalListener to use with this instance of the UnmarshalHandler.

setUnmarshalListener

public void setUnmarshalListener(UnmarshalListener listener)

Sets an UnmarshalListener.

Parameters:

listener - the UnmarshalListener to use with this instance of the UnmarshalHandler.

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.

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws SAXException

Specified by:

characters in interface ContentHandler

Specified by:

characters in interface DocumentHandler

Throws:

SAXException

endDocument

public void endDocument()
                 throws SAXException

Specified by:

endDocument in interface ContentHandler

Specified by:

endDocument in interface DocumentHandler

Throws:

SAXException

endElement

public void endElement(String name)
                throws SAXException

Specified by:

endElement in interface DocumentHandler

Throws:

SAXException

endElement

public void endElement(String namespaceURI,
                       String localName,
                       String qName)
                throws SAXException

ContentHandler#endElement

Signals the end of an element

Specified by:

endElement in interface ContentHandler

Parameters:

localName - The name of the element.

Throws:

SAXException

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException

Signals to end the namespace prefix mapping

Specified by:

endPrefixMapping in interface ContentHandler

Parameters:

prefix - the namespace prefix

Throws:

SAXException

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws SAXException

Specified by:

ignorableWhitespace in interface ContentHandler

Specified by:

ignorableWhitespace in interface DocumentHandler

Throws:

SAXException

processingInstruction

public void processingInstruction(String target,
                                  String data)
                           throws SAXException

Specified by:

processingInstruction in interface ContentHandler

Specified by:

processingInstruction in interface DocumentHandler

Throws:

SAXException

setDocumentLocator

public void setDocumentLocator(Locator locator)

Specified by:

setDocumentLocator in interface ContentHandler

Specified by:

setDocumentLocator in interface DocumentHandler

getDocumentLocator

public Locator getDocumentLocator()

skippedEntity

public void skippedEntity(String name)
                   throws SAXException

Signals that an entity was skipped by the parser

Specified by:

skippedEntity in interface ContentHandler

Parameters:

name - the skipped entity's name

Throws:

SAXException

startDocument

public void startDocument()
                   throws SAXException

Signals the start of a new document

Specified by:

startDocument in interface ContentHandler

Specified by:

startDocument in interface DocumentHandler

Throws:

SAXException

startElement

public void startElement(String namespaceURI,
                         String localName,
                         String qName,
                         Attributes atts)
                  throws SAXException

ContentHandler#startElement

Signals the start of element.

Specified by:

startElement in interface ContentHandler

Parameters:

localName - The name of the element.

atts - The AttributeList containing the associated attributes for the element.

Throws:

SAXException

startElement

public void startElement(String name,
                         AttributeList attList)
                  throws SAXException

Deprecated.

DocumentHandler#startElement

Signals the start of element.

Specified by:

startElement in interface DocumentHandler

Parameters:

name - The name of the element.

attList - The AttributeList containing the associated attributes for the element.

Throws:

SAXException

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String uri)
                        throws SAXException

Signals to start the namespace - prefix mapping

Specified by:

startPrefixMapping in interface ContentHandler

Parameters:

prefix - the namespace prefix to map

uri - the namespace URI

Throws:

SAXException

error

public void error(SAXParseException exception)
           throws SAXException

Specified by:

error in interface ErrorHandler

Throws:

SAXException

fatalError

public void fatalError(SAXParseException exception)
                throws SAXException

Specified by:

fatalError in interface ErrorHandler

Throws:

SAXException

warning

public void warning(SAXParseException exception)
             throws SAXException

Specified by:

warning in interface ErrorHandler

Throws:

SAXException

toPrimitiveObject

public static Object toPrimitiveObject(Class<?> type,
                                       String value)

Converts a String to the given primitive object type.

Parameters:

type - the class type of the primitive in which to convert the String to

value - the String to convert to a primitive

Returns:

the new primitive Object

getObjectFactory

public ObjectFactory getObjectFactory()

Returns the ObjectFactory instance in use.

Returns:

the ObjectFactory instance in use.

setObjectFactory

public void setObjectFactory(ObjectFactory objectFactory)

Sets a (custom) ObjectFactory instance.

Parameters:

objectFactory - A (custom) ObjectFactory instance

getStateStack

public UnmarshalStateStack getStateStack()

Returnss a refrence to the UnmarshalStateStack instance currently in use.

Returns:

The UnmarshalStateStack in use.

getTopState

public UnmarshalState getTopState()

Returns the top UnmarshalState instance from the UnmarshalStateStack.

Returns:

The top UnmarshalState instance.

getStrictElementHandler

public StrictElementHandler getStrictElementHandler()

Returns the StrictElementHandler in use.

Returns:

The StrictElementHandler in use.

getNamespaceHandling

public NamespaceHandling getNamespaceHandling()

Returns the NamespaceHandling in use.

Returns:

The currently active NamespaceHandling instance.

getClassLoader

public ClassLoader getClassLoader()

Returns the current ClassLoader in use.

Returns:

The ClassLoader in use.

getAnyNodeHandler

public AnyNodeUnmarshalHandler getAnyNodeHandler()

Returns the currently used AnyNodeUnmarshalHandler instance.

Returns:

The AnyNodeUnmarshalHandler in use.

getDelegateUnmarshalListener

public UnmarshalListenerDelegate getDelegateUnmarshalListener()

Returns the currently active UnmarshalListenerDelegate instance

Returns:

The active UnmarshalListenerDelegate in use.

isReuseObjects

public boolean isReuseObjects()

Indicats whether Object instances should be re-used.

Returns:

True if object instances should be re-used.

getResolveTable

public Hashtable<String,org.exolab.castor.xml.ReferenceInfo> getResolveTable()

Hashtable to store idReference and ReferenceInfo

Returns:

Hashtable

getAnyNode

public AnyNode getAnyNode()

returns the AnyNode (if any).

Returns:

AnyNode, could be null

setAnyNode

public void setAnyNode(AnyNode node)

sets the AnyNode

Parameters:

node - AnyNode

isClearCollections

public boolean isClearCollections()

Indicates whether it's necessary to clear any collection or not.

Returns:

True if it's necessary to clear any collection.

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(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(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.

namespaceEquals

public static boolean namespaceEquals(String ns1,
                                      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!

searchInheritance

protected MarshalFramework.InheritanceMatch[] searchInheritance(String name,
                                                                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

cdResolver - the class descriptor resolver to use

Returns:

An array of InheritanceMatch.

Throws:

MarshalException - if the resolver called fails fatally