org.exolab.castor.xml

Class UnmarshalHandler

java.lang.Object

org.exolab.castor.xml.MarshalFramework

org.exolab.castor.xml.UnmarshalHandler

All Implemented Interfaces:

org.xml.sax.ContentHandler, org.xml.sax.DocumentHandler, org.xml.sax.ErrorHandler

public final class UnmarshalHandler
extends MarshalFramework
implements org.xml.sax.ContentHandler, org.xml.sax.DocumentHandler, org.xml.sax.ErrorHandler

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-05-25 06:41:12 -0600 (Thu, 25 May 2006) $

Author:

Keith Visco

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) class	UnmarshalHandler.Arguments Internal class used for passing constructor argument information
static class	UnmarshalHandler.ArrayHandler A class for handling Arrays during unmarshalling.
(package private) class	UnmarshalHandler.ElementInfo A utility class for keeping track of the qName and how the SAX parser passed attributes
(package private) class	UnmarshalHandler.IDResolverImpl Local IDResolver
(package private) class	UnmarshalHandler.ReferenceInfo Internal class used to save state for reference resolving

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

Modifier	Constructor and Description
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(java.lang.Class _class) Creates a new UnmarshalHandler

Method Summary

Modifier and Type	Method and Description
void	addNamespaceToPackageMapping(java.lang.String nsURI, java.lang.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(java.lang.String name)
void	endElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName) ContentHandler#endElement
void	endPrefixMapping(java.lang.String prefix) Signals to end the namespace prefix mapping
void	error(org.xml.sax.SAXParseException exception)
void	fatalError(org.xml.sax.SAXParseException exception)
java.lang.Object	getCurrentObject() Returns the Object that the UnmarshalHandler is currently handling (within the object model), or null if the current element is a simpleType.
org.xml.sax.Locator	getDocumentLocator()
java.lang.Object	getObject() Returns the "root" Object (ie.
ObjectFactory	getObjectFactory() Returns the ObjectFactory instance in use.
void	ignorableWhitespace(char[] ch, int start, int length)
void	processingInstruction(java.lang.String target, java.lang.String data)
void	setClassLoader(java.lang.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.
protected void	setConfiguration(Configuration config) Sets the current Castor configuration.
void	setDebug(boolean debug) Turns debuging on or off.
void	setDocumentLocator(org.xml.sax.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	setLogWriter(java.io.PrintWriter printWriter) Sets the PrintWriter used for printing log messages
void	setObjectFactory(ObjectFactory objectFactory) Sets a (custom) ObjectFactory instance.
void	setResolver(XMLClassDescriptorResolver cdResolver) Sets the ClassDescriptorResolver to use for loading and resolving ClassDescriptors
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(java.lang.Object root) Sets the root (top-level) object to use for unmarshalling into.
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(java.lang.String name) Signals that an entity was skipped by the parser
void	startDocument() Signals the start of a new document
void	startElement(java.lang.String name, org.xml.sax.AttributeList attList) DocumentHandler#startElement
void	startElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts) ContentHandler#startElement
void	startPrefixMapping(java.lang.String prefix, java.lang.String uri) Signals to start the namespace - prefix mapping
static java.lang.Object	toPrimitiveObject(java.lang.Class type, java.lang.String value) Converts a String to the given primitive object type
void	warning(org.xml.sax.SAXParseException exception)

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

getCollectionHandler, hasFieldsAtLocation, isCollection, isPrimitive, namespaceEquals, primitiveOrWrapperEquals, searchInheritance

Methods inherited from class java.lang.Object

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

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(java.lang.Class _class)

Creates a new UnmarshalHandler

Parameters:

_class - the Class to create the UnmarshalHandler for

Method Detail

addNamespaceToPackageMapping

public void addNamespaceToPackageMapping(java.lang.String nsURI,
                                         java.lang.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 java.lang.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 java.lang.Object getObject()

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

Returns:

the root Object being unmarshalled.

setClassLoader

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

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:

setLogWriter(java.io.PrintWriter)

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(java.io.PrintWriter printWriter)

Sets the PrintWriter used for printing log messages

Parameters:

printWriter - the PrintWriter to use when printing log messages

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.

setResolver

public void setResolver(XMLClassDescriptorResolver cdResolver)

Sets the ClassDescriptorResolver to use for loading and resolving ClassDescriptors

Parameters:

cdResolver - the ClassDescriptorResolver to use

setRootObject

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

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 org.xml.sax.SAXException

Specified by:

characters in interface org.xml.sax.ContentHandler

Specified by:

characters in interface org.xml.sax.DocumentHandler

Throws:

org.xml.sax.SAXException

endDocument

public void endDocument()
                 throws org.xml.sax.SAXException

Specified by:

endDocument in interface org.xml.sax.ContentHandler

Specified by:

endDocument in interface org.xml.sax.DocumentHandler

Throws:

org.xml.sax.SAXException

endElement

public void endElement(java.lang.String name)
                throws org.xml.sax.SAXException

Specified by:

endElement in interface org.xml.sax.DocumentHandler

Throws:

org.xml.sax.SAXException

endElement

public void endElement(java.lang.String namespaceURI,
                       java.lang.String localName,
                       java.lang.String qName)
                throws org.xml.sax.SAXException

ContentHandler#endElement

Signals the end of an element

Specified by:

endElement in interface org.xml.sax.ContentHandler

Parameters:

localName - The name of the element.

Throws:

org.xml.sax.SAXException

endPrefixMapping

public void endPrefixMapping(java.lang.String prefix)
                      throws org.xml.sax.SAXException

Signals to end the namespace prefix mapping

Specified by:

endPrefixMapping in interface org.xml.sax.ContentHandler

Parameters:

prefix - the namespace prefix

Throws:

org.xml.sax.SAXException

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws org.xml.sax.SAXException

Specified by:

ignorableWhitespace in interface org.xml.sax.ContentHandler

Specified by:

ignorableWhitespace in interface org.xml.sax.DocumentHandler

Throws:

org.xml.sax.SAXException

processingInstruction

public void processingInstruction(java.lang.String target,
                                  java.lang.String data)
                           throws org.xml.sax.SAXException

Specified by:

processingInstruction in interface org.xml.sax.ContentHandler

Specified by:

processingInstruction in interface org.xml.sax.DocumentHandler

Throws:

org.xml.sax.SAXException

setDocumentLocator

public void setDocumentLocator(org.xml.sax.Locator locator)

Specified by:

setDocumentLocator in interface org.xml.sax.ContentHandler

Specified by:

setDocumentLocator in interface org.xml.sax.DocumentHandler

getDocumentLocator

public org.xml.sax.Locator getDocumentLocator()

skippedEntity

public void skippedEntity(java.lang.String name)
                   throws org.xml.sax.SAXException

Signals that an entity was skipped by the parser

Specified by:

skippedEntity in interface org.xml.sax.ContentHandler

Parameters:

name - the skipped entity's name

Throws:

org.xml.sax.SAXException

startDocument

public void startDocument()
                   throws org.xml.sax.SAXException

Signals the start of a new document

Specified by:

startDocument in interface org.xml.sax.ContentHandler

Specified by:

startDocument in interface org.xml.sax.DocumentHandler

Throws:

org.xml.sax.SAXException

startElement

public void startElement(java.lang.String namespaceURI,
                         java.lang.String localName,
                         java.lang.String qName,
                         org.xml.sax.Attributes atts)
                  throws org.xml.sax.SAXException

ContentHandler#startElement

Signals the start of element.

Specified by:

startElement in interface org.xml.sax.ContentHandler

Parameters:

localName - The name of the element.

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

Throws:

org.xml.sax.SAXException

startElement

public void startElement(java.lang.String name,
                         org.xml.sax.AttributeList attList)
                  throws org.xml.sax.SAXException

DocumentHandler#startElement

Signals the start of element.

Specified by:

startElement in interface org.xml.sax.DocumentHandler

Parameters:

name - The name of the element.

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

Throws:

org.xml.sax.SAXException

startPrefixMapping

public void startPrefixMapping(java.lang.String prefix,
                               java.lang.String uri)
                        throws org.xml.sax.SAXException

Signals to start the namespace - prefix mapping

Specified by:

startPrefixMapping in interface org.xml.sax.ContentHandler

Parameters:

prefix - the namespace prefix to map

uri - the namespace URI

Throws:

org.xml.sax.SAXException

error

public void error(org.xml.sax.SAXParseException exception)
           throws org.xml.sax.SAXException

Specified by:

error in interface org.xml.sax.ErrorHandler

Throws:

org.xml.sax.SAXException

fatalError

public void fatalError(org.xml.sax.SAXParseException exception)
                throws org.xml.sax.SAXException

Specified by:

fatalError in interface org.xml.sax.ErrorHandler

Throws:

org.xml.sax.SAXException

warning

public void warning(org.xml.sax.SAXParseException exception)
             throws org.xml.sax.SAXException

Specified by:

warning in interface org.xml.sax.ErrorHandler

Throws:

org.xml.sax.SAXException

setConfiguration

protected void setConfiguration(Configuration config)

Sets the current Castor configuration. Currently this Configuration is only used during Validation (which is why this method is currently protected, since it has no effect at this point on the actual configuration of the unmarshaller) Currently, this method should only be called by the Unmarshaller.

toPrimitiveObject

public static java.lang.Object toPrimitiveObject(java.lang.Class type,
                                                 java.lang.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