org.exolab.castor.xml
Class UnmarshalHandler

java.lang.Object
  extended byorg.exolab.castor.xml.MarshalFramework
      extended byorg.exolab.castor.xml.UnmarshalHandler
All Implemented Interfaces:
org.xml.sax.DocumentHandler, org.xml.sax.ErrorHandler

public final class UnmarshalHandler
extends MarshalFramework
implements 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: 1.8 $ $Date: 2003/05/28 08:10:07 $
Author:
Keith Visco

Nested Class Summary
static class MarshalFramework.InheritanceMatch
          Used to store the information when we find a possible inheritance.
(package private)  class MarshalFramework.InternalXMLClassDescriptor
          An internal implementation of XMLClassDescriptor used by the Unmarshaller and Marshaller...
(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.IDResolverImpl
          Local IDResolver
(package private)  class UnmarshalHandler.ReferenceInfo
          Internal class used to save state for reference resolving
 
Field Summary
(package private) static java.lang.String JAVA_PREFIX
          The default prefix used for specifying the xsi:type as a classname instead of a schema name.
(package private) static java.lang.String QNAME_NAME
          The name of the QName type
static java.lang.String XSI_NAMESPACE
          The XSI Namespace URI
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 _class)
          Creates a new UnmarshalHandler
 
Method Summary
 void characters(char[] ch, int start, int length)
           
 void endDocument()
           
 void endElement(java.lang.String name)
           
 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()
           
 java.lang.Object getObject()
          Returns the "root" Object (ie.
(package private) static boolean hasFieldsAtLocation(java.lang.String location, XMLClassDescriptor classDesc)
          Returns true if any of the fields associated with the given XMLClassDescriptor are located at, or beneath, the given location.
 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.
(package private) static boolean isPrimitive(java.lang.Class type)
          Returns true if the given class should be treated as a primitive type.
static boolean namespaceEquals(java.lang.String ns1, java.lang.String ns2)
          Compares the given namespaces (as strings) for equality.
(package private) static boolean primitiveOrWrapperEquals(java.lang.Class a, java.lang.Class b)
          Returns true if the given classes are both the same primitive or primitive wrapper class.
 void processingInstruction(java.lang.String target, java.lang.String data)
           
static MarshalFramework.InheritanceMatch[] searchInheritance(java.lang.String name, java.lang.String namespace, XMLClassDescriptor classDesc, ClassDescriptorResolver cdResolver)
          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.
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 setResolver(ClassDescriptorResolver 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 startDocument()
           
 void startElement(java.lang.String name, org.xml.sax.AttributeList attList)
           
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

JAVA_PREFIX

static final java.lang.String JAVA_PREFIX
The default prefix used for specifying the xsi:type as a classname instead of a schema name. This is a Castor specific hack.

See Also:
Constant Field Values

QNAME_NAME

static final java.lang.String QNAME_NAME
The name of the QName type

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 _class)
Creates a new UnmarshalHandler

Parameters:
_class - the Class to create the UnmarshalHandler for
Method Detail

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


characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws org.xml.sax.SAXException
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.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

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws org.xml.sax.SAXException
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.DocumentHandler
Throws:
org.xml.sax.SAXException

setDocumentLocator

public void setDocumentLocator(org.xml.sax.Locator locator)
Specified by:
setDocumentLocator in interface org.xml.sax.DocumentHandler

getDocumentLocator

public org.xml.sax.Locator getDocumentLocator()

startDocument

public void startDocument()
                   throws org.xml.sax.SAXException
Specified by:
startDocument in interface org.xml.sax.DocumentHandler
Throws:
org.xml.sax.SAXException

startElement

public void startElement(java.lang.String name,
                         org.xml.sax.AttributeList attList)
                  throws org.xml.sax.SAXException
Specified by:
startElement in interface org.xml.sax.DocumentHandler
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

isCollection

public static boolean isCollection(java.lang.Class clazz)
Returns true if the given Class is a considered a collection by the marshalling framework.

Returns:
true if the given Class is considered a collection.

getCollectionHandler

public CollectionHandler getCollectionHandler(java.lang.Class clazz)
Returns the CollectionHandler associated with the given collection, or null if no such handler exists.

Returns:
the CollectionHandler for the associated type.

isPrimitive

static boolean isPrimitive(java.lang.Class type)
Returns true if the given class should be treated as a primitive type. This method will return true for all Java primitive types, the set of primitive object wrappers, as well as Strings.

Returns:
true if the given class should be treated as a primitive type

hasFieldsAtLocation

static final boolean hasFieldsAtLocation(java.lang.String location,
                                         XMLClassDescriptor classDesc)
Returns true if any of the fields associated with the given XMLClassDescriptor are located at, or beneath, the given location.

Parameters:
location - the location to compare against
classDesc - the XMLClassDescriptor in which to check the field locations

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

primitiveOrWrapperEquals

static boolean primitiveOrWrapperEquals(java.lang.Class a,
                                        java.lang.Class b)
Returns true if the given classes are both the same primitive or primitive wrapper class. For exmaple, if class "a" is an int (Integer.TYPE) and class "b" is either an int or Integer.class then true will be returned, otherwise false.

Returns:
true if both a and b are considered equal

searchInheritance

public static MarshalFramework.InheritanceMatch[] searchInheritance(java.lang.String name,
                                                                    java.lang.String namespace,
                                                                    XMLClassDescriptor classDesc,
                                                                    ClassDescriptorResolver cdResolver)
Search there is a field descriptor which can accept one of the class descriptor which match the given name and namespace.



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