org.exolab.castor.xml
Class UnmarshalHandler

java.lang.Object
  extended by 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 java.lang.Object
implements org.xml.sax.ContentHandler, org.xml.sax.DocumentHandler, org.xml.sax.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: 8057 $ $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 java.lang.String LANG_ATTR
          The xml:lang attribute, without the "xml:" prefix.
static java.lang.String NIL_ATTR
          The xsi:nil attribute, without the "xsi:" prefix.
static java.lang.String SPACE_ATTR
          The xml:space attribute name, without the "xml:" prefix.
static java.lang.String TRUE_VALUE
          The value of 'true'.
static java.lang.String TYPE_ATTR
          The xsi:type attribute name, without the "xsi:" prefix.
static java.lang.String XML_LANG_ATTR
          The xml:lang attribute name.
static java.lang.String XML_SPACE_ATTR
          The xml:space attribute name.
static java.lang.String XSI_NAMESPACE
          The XSI Namespace URI.
static java.lang.String XSI_NIL_ATTR
          The xsi:nil attribute.
static java.lang.String XSI_NO_NAMESPACE_SCHEMA_LOCATION
          The name of the no namespace schema location attribute.
static java.lang.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(java.lang.Class<?> topClass)
          Creates a new UnmarshalHandler.
protected UnmarshalHandler(InternalContext internalContext, java.lang.Class<?> topClass)
          Creates a new UnmarshalHandler.
 
Method Summary
 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)
           
 CollectionHandler getCollectionHandler(java.lang.Class clazz)
          Returns the CollectionHandler associated with the given collection, or null if no such handler exists.
 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()
           
 InternalContext getInternalContext()
          To get the AbstractInternalContext to use.
 JavaNaming getJavaNaming()
          To get the JavaNaming instance to be used.
 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)
           
static boolean isCollection(java.lang.Class clazz)
          Returns true if the given Class is a considered a collection by the marshalling framework.
static boolean namespaceEquals(java.lang.String ns1, java.lang.String ns2)
          Compares the given namespaces (as strings) for equality.
 void processingInstruction(java.lang.String target, java.lang.String data)
           
protected  MarshalFramework.InheritanceMatch[] searchInheritance(java.lang.String name, java.lang.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 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.
 void setDebug(boolean debug)
          Deprecated.  
 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 setInternalContext(InternalContext internalContext)
          To set the AbstractInternalContext to use.
 void setLogWriter(java.io.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(java.lang.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(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 java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

XSI_NAMESPACE

public static final java.lang.String XSI_NAMESPACE
The XSI Namespace URI.

See Also:
Constant Field Values

XSI_SCHEMA_LOCATION

public static final java.lang.String XSI_SCHEMA_LOCATION
The name of the Schema location attribute.

See Also:
Constant Field Values

XSI_NO_NAMESPACE_SCHEMA_LOCATION

public static final java.lang.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 java.lang.String XML_LANG_ATTR
The xml:lang attribute name.

See Also:
Constant Field Values

LANG_ATTR

public static final java.lang.String LANG_ATTR
The xml:lang attribute, without the "xml:" prefix.

See Also:
Constant Field Values

NIL_ATTR

public static final java.lang.String NIL_ATTR
The xsi:nil attribute, without the "xsi:" prefix.

See Also:
Constant Field Values

XSI_NIL_ATTR

public static final java.lang.String XSI_NIL_ATTR
The xsi:nil attribute.

See Also:
Constant Field Values

XML_SPACE_ATTR

public static final java.lang.String XML_SPACE_ATTR
The xml:space attribute name.

See Also:
Constant Field Values

SPACE_ATTR

public static final java.lang.String SPACE_ATTR
The xml:space attribute name, without the "xml:" prefix.

See Also:
Constant Field Values

TYPE_ATTR

public static final java.lang.String TYPE_ATTR
The xsi:type attribute name, without the "xsi:" prefix.

See Also:
Constant Field Values

TRUE_VALUE

public static final java.lang.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(java.lang.Class<?> topClass)
Creates a new UnmarshalHandler.

Parameters:
topClass - the Class to create the UnmarshalHandler for

UnmarshalHandler

protected UnmarshalHandler(InternalContext internalContext,
                           java.lang.Class<?> topClass)
Creates a new UnmarshalHandler.

Parameters:
internalContext - the InternalContext to use
topClass - the Class to work 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)
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(java.io.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(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)
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 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

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

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(java.lang.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(java.lang.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(java.lang.String ns1,
                                      java.lang.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(java.lang.String name,
                                                                java.lang.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


Copyright © 2011. All Rights Reserved.