Package org.exolab.castor.xml
Class UnmarshalHandler
java.lang.Object
org.exolab.castor.xml.MarshalFramework
org.exolab.castor.xml.UnmarshalHandler
- All Implemented Interfaces:
ContentHandler
,DocumentHandler
,ErrorHandler
public final class UnmarshalHandler
extends MarshalFramework
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: 8802 $ $Date: 2006-05-25 06:41:12 -0600 (Thu, 25 May 2006) $
- Author:
- Keith Visco
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) class
Internal class used for passing constructor argument information.static class
A class for handling Arrays during unmarshalling.Nested classes/interfaces inherited from class org.exolab.castor.xml.MarshalFramework
MarshalFramework.InheritanceMatch, MarshalFramework.InternalXMLClassDescriptor
-
Field Summary
FieldsModifier and TypeFieldDescription(package private) static final org.apache.commons.logging.Log
Logger from commons-logging.(package private) static final String
protected static ResourceBundle
resource bundle(package private) static final String
(package private) static final String
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
ConstructorsModifierConstructorDescriptionprotected
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
Modifier and TypeMethodDescriptionvoid
addNamespaceToPackageMapping
(String nsURI, String packageName) Adds a mapping from the given namespace URI to the given package name(package private) void
addReference
(String idRef, Object parent, XMLFieldDescriptor descriptor) Adds the given reference to the "queue" until the referenced object has been unmarshalled.void
characters
(char[] ch, int start, int length) (package private) String
Returns the name of a class, handles array types(package private) Object
createInstance
(Class<?> type, UnmarshalHandler.Arguments args) Creates an instance of the given class /type, using the arguments provided (if there are any).(package private) byte[]
decodeBinaryData
(XMLFieldDescriptor descriptor, String binaryData) Decode binary data and return decoded value.void
void
endElement
(String name) void
endElement
(String namespaceURI, String localName, String qName) ContentHandler#endElementvoid
endPrefixMapping
(String prefix) Signals to end the namespace prefix mappingvoid
error
(SAXParseException exception) void
fatalError
(SAXParseException exception) returns the AnyNode (if any).Returns the currently usedAnyNodeUnmarshalHandler
instance.(package private) XMLClassDescriptor
getClassDescriptor
(Class<?> cls) Finds and returns an XMLClassDescriptor for the given class.(package private) XMLClassDescriptor
getClassDescriptor
(String className, ClassLoader loader) Finds and returns a ClassDescriptor for the given class.Returns the currentClassLoader
in use.Returns the Object that the UnmarshalHandler is currently handling (within the object model), or null if the current element is a simpleType.Returns the currently activeUnmarshalListenerDelegate
instance(package private) String
getInstanceType
(AttributeSet atts, String currentPackage) Returns the resolved instance type attribute (xsi:type).(package private) String
getJavaPackage
(Class<?> type) Returns the package for the given ClassReturns theNamespaceHandling
in use.Returns the "root" Object (ie.Returns the ObjectFactory instance in use.Hashtable to store idReference and ReferenceInfoReturnss a refrence to theUnmarshalStateStack
instance currently in use.Returns theStrictElementHandler
in use.Returns the topUnmarshalState
instance from theUnmarshalStateStack
.void
ignorableWhitespace
(char[] ch, int start, int length) boolean
Indicates whether it's necessary to clear any collection or not.boolean
Indicats whether Object instances should be re-used.(package private) boolean
Indicates whether validation is enabled or not.(package private) static boolean
Checks the given StringBuffer to determine if it only contains whitespace.(package private) Class
<?> loadClass
(String className, ClassLoader loader) Loads and returns the class with the given class name using the given loader.(package private) void
processAttributes
(AttributeSet atts, XMLClassDescriptor classDesc) Processes the given attribute list, and attempts to add eachAttributes
to the currentObject
on the stack.(package private) UnmarshalHandler.Arguments
processConstructorArgs
(AttributeSet atts, XMLClassDescriptor classDesc) Processes the given attribute set, and creates the constructor arguments.(package private) void
processFirstElement
(String name, String namespace, AttributeSet atts, String xmlSpace) (package private) boolean
processIDREF
(String idRef, XMLFieldDescriptor descriptor, Object parent) Processes the given IDREF.void
processingInstruction
(String target, String data) (package private) void
Processes the given AttributeSet for wrapper elements.(package private) XMLClassDescriptor
resolveByXMLName
(String name, String namespace, ClassLoader loader) Returns the XMLClassLoadervoid
setAnyNode
(AnyNode node) sets the AnyNodevoid
setClassLoader
(ClassLoader loader) Sets the ClassLoader to use when loading classesvoid
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
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) Sets anUnmarshalListener
.void
setUnmarshalListener
(UnmarshalListener listener) Deprecated.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 parservoid
Signals the start of a new documentvoid
startElement
(String namespaceURI, String localName, String qName, Attributes atts) ContentHandler#startElementvoid
startElement
(String name, AttributeList attList) Deprecated.(package private) void
startElementProcessing
(String name, String namespace, AttributeSet atts) Signals the start of an element with the given name.void
startPrefixMapping
(String prefix, String uri) Signals to start the namespace - prefix mappingstatic Object
toPrimitiveObject
(Class<?> type, String value) Converts aString
to the given primitive object type.(package private) Object
toPrimitiveObject
(Class<?> type, String value, XMLFieldDescriptor fieldDesc) Converts a String to the given primitive object type.void
warning
(SAXParseException exception) Methods inherited from class org.exolab.castor.xml.MarshalFramework
getCollectionHandler, getInternalContext, getJavaNaming, hasFieldsAtLocation, isCollection, isEnum, isPrimitive, namespaceEquals, primitiveOrWrapperEquals, searchInheritance, setInternalContext
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.xml.sax.ContentHandler
declaration
-
Field Details
-
LOG
static final org.apache.commons.logging.Log LOGLogger from commons-logging. -
resourceBundle
resource bundle -
XML_SPACE
- See Also:
-
XML_SPACE_WITH_PREFIX
- See Also:
-
PRESERVE
- See Also:
-
-
Constructor Details
-
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
Creates a new UnmarshalHandler.- Parameters:
topClass
- the Class to create the UnmarshalHandler for
-
UnmarshalHandler
Creates a new UnmarshalHandler.- Parameters:
internalContext
- theInternalContext
to usetopClass
- the Class to work for
-
-
Method Details
-
addNamespaceToPackageMapping
Adds a mapping from the given namespace URI to the given package name- Parameters:
nsURI
- the namespace URI to map frompackageName
- the package name to map to
-
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
Returns the "root" Object (ie. the entire object model) being unmarshalled.- Returns:
- the root Object being unmarshalled.
-
setClassLoader
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
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
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
Sets the root (top-level) object to use for unmarshalling into.- Parameters:
root
- the instance to unmarshal into.
-
setUnmarshalListener
Deprecated.please move to the newUnmarshalListener
interfaceSets anUnmarshalListener
.- Parameters:
listener
- theUnmarshalListener
to use with this instance of the UnmarshalHandler.
-
setUnmarshalListener
Sets anUnmarshalListener
.- Parameters:
listener
- theUnmarshalListener
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
- Specified by:
characters
in interfaceContentHandler
- Specified by:
characters
in interfaceDocumentHandler
- Throws:
SAXException
-
endDocument
- Specified by:
endDocument
in interfaceContentHandler
- Specified by:
endDocument
in interfaceDocumentHandler
- Throws:
SAXException
-
endElement
- Specified by:
endElement
in interfaceDocumentHandler
- Throws:
SAXException
-
decodeBinaryData
Decode binary data and return decoded value.- Parameters:
descriptor
-XMLFieldDescriptor
instance for the field whose value requires decoding.binaryData
- The binary data value to be decoded- Returns:
- Decode data.
-
endElement
ContentHandler#endElement
Signals the end of an element- Specified by:
endElement
in interfaceContentHandler
- Parameters:
localName
- The name of the element.- Throws:
SAXException
-
endPrefixMapping
Signals to end the namespace prefix mapping- Specified by:
endPrefixMapping
in interfaceContentHandler
- Parameters:
prefix
- the namespace prefix- Throws:
SAXException
-
ignorableWhitespace
- Specified by:
ignorableWhitespace
in interfaceContentHandler
- Specified by:
ignorableWhitespace
in interfaceDocumentHandler
- Throws:
SAXException
-
processingInstruction
- Specified by:
processingInstruction
in interfaceContentHandler
- Specified by:
processingInstruction
in interfaceDocumentHandler
- Throws:
SAXException
-
setDocumentLocator
- Specified by:
setDocumentLocator
in interfaceContentHandler
- Specified by:
setDocumentLocator
in interfaceDocumentHandler
-
getDocumentLocator
-
skippedEntity
Signals that an entity was skipped by the parser- Specified by:
skippedEntity
in interfaceContentHandler
- Parameters:
name
- the skipped entity's name- Throws:
SAXException
-
startDocument
Signals the start of a new document- Specified by:
startDocument
in interfaceContentHandler
- Specified by:
startDocument
in interfaceDocumentHandler
- 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 interfaceContentHandler
- Parameters:
localName
- The name of the element.atts
- The AttributeList containing the associated attributes for the element.- Throws:
SAXException
-
startElement
Deprecated.DocumentHandler#startElement
Signals the start of element.- Specified by:
startElement
in interfaceDocumentHandler
- Parameters:
name
- The name of the element.attList
- The AttributeList containing the associated attributes for the element.- Throws:
SAXException
-
startElementProcessing
Signals the start of an element with the given name.- Parameters:
name
- the NCName of the element. It is an error if the name is a QName (ie. contains a prefix).namespace
- the namespace of the element. This may be null. Note: A null namespace is not the same as the default namespace unless the default namespace is also null.atts
- the AttributeSet containing the attributes associated with the element.- Throws:
SAXException
-
processFirstElement
void processFirstElement(String name, String namespace, AttributeSet atts, String xmlSpace) throws SAXException - Throws:
SAXException
-
isValidating
boolean isValidating()Indicates whether validation is enabled or not.- Returns:
- True if validation is enabled.
-
startPrefixMapping
Signals to start the namespace - prefix mapping- Specified by:
startPrefixMapping
in interfaceContentHandler
- Parameters:
prefix
- the namespace prefix to mapuri
- the namespace URI- Throws:
SAXException
-
error
- Specified by:
error
in interfaceErrorHandler
- Throws:
SAXException
-
fatalError
- Specified by:
fatalError
in interfaceErrorHandler
- Throws:
SAXException
-
warning
- Specified by:
warning
in interfaceErrorHandler
- Throws:
SAXException
-
addReference
Adds the given reference to the "queue" until the referenced object has been unmarshalled.- Parameters:
idRef
- the ID being referencedparent
- the target/parent object for the fielddescriptor
- the XMLFieldDescriptor for the field
-
createInstance
Creates an instance of the given class /type, using the arguments provided (if there are any).- Parameters:
type
- The class type to be used during instantiationargs
- (Optional) arguments to be used during instantiation- Throws:
SAXException
-
getInstanceType
Returns the resolved instance type attribute (xsi:type). If present the instance type attribute is resolved into a java class name and then returned.- Parameters:
atts
- the AttributeList to search for the instance type attribute.- Returns:
- the java class name corresponding to the value of the instance type attribute, or null if no instance type attribute exists in the given AttributeList.
- Throws:
SAXException
-
processAttributes
Processes the given attribute list, and attempts to add eachAttributes
to the currentObject
on the stack.- Parameters:
atts
- the AttributeSet to processclassDesc
- the classDesc to use during processing- Throws:
SAXException
-
processWrapperAttributes
Processes the given AttributeSet for wrapper elements.- Parameters:
atts
- the AttributeSet to process- Throws:
SAXException
- If the AttributeSet cannot be processed
-
processConstructorArgs
UnmarshalHandler.Arguments processConstructorArgs(AttributeSet atts, XMLClassDescriptor classDesc) throws SAXException Processes the given attribute set, and creates the constructor arguments.- Parameters:
atts
- the AttributeSet to processclassDesc
- the XMLClassDescriptor of the objec- Returns:
- the array of constructor argument values.
- Throws:
SAXException
- If there's a problem creating the constructor argument set.
-
processIDREF
Processes the given IDREF.- Parameters:
idRef
- the ID of the object in which to referencedescriptor
- the current FieldDescriptorparent
- the current parent object- Returns:
- true if the ID was found and resolved properly
-
getClassDescriptor
Finds and returns an XMLClassDescriptor for the given class. If a ClassDescriptor could not be found one will attempt to be generated.- Parameters:
cls
- the Class to get the ClassDescriptor for- Throws:
SAXException
-
getClassDescriptor
Finds and returns a ClassDescriptor for the given class. If a ClassDescriptor could not be found one will attempt to be generated.- Parameters:
className
- the name of the class to get the Descriptor for- Throws:
SAXException
-
resolveByXMLName
XMLClassDescriptor resolveByXMLName(String name, String namespace, ClassLoader loader) throws SAXException Returns the XMLClassLoader- Throws:
SAXException
-
getJavaPackage
Returns the package for the given Class- Parameters:
type
- the Class to return the package of- Returns:
- the package for the given Class
-
className
Returns the name of a class, handles array types- Returns:
- the name of a class, handles array types
-
isWhitespace
Checks the given StringBuffer to determine if it only contains whitespace.- Parameters:
sb
- the StringBuffer to check- Returns:
- true if the only whitespace characters were found in the given StringBuffer
-
loadClass
Loads and returns the class with the given class name using the given loader.- Parameters:
className
- the name of the class to loadloader
- the ClassLoader to use, this may be null.- Throws:
ClassNotFoundException
-
toPrimitiveObject
Object toPrimitiveObject(Class<?> type, String value, XMLFieldDescriptor fieldDesc) throws SAXException Converts a String to the given primitive object type.- Parameters:
type
- the class type of the primitive in which to convert the String tovalue
- the String to convert to a primitivefieldDesc
- Descriptor for the given field (value)- Returns:
- the new primitive Object
- Throws:
SAXException
- If the String cannot be converted to a primitive object type
-
toPrimitiveObject
Converts aString
to the given primitive object type. -
getObjectFactory
Returns the ObjectFactory instance in use.- Returns:
- the ObjectFactory instance in use.
-
setObjectFactory
Sets a (custom) ObjectFactory instance.- Parameters:
objectFactory
- A (custom) ObjectFactory instance
-
getStateStack
Returnss a refrence to theUnmarshalStateStack
instance currently in use.- Returns:
- The
UnmarshalStateStack
in use.
-
getTopState
Returns the topUnmarshalState
instance from theUnmarshalStateStack
.- Returns:
- The top
UnmarshalState
instance.
-
getStrictElementHandler
Returns theStrictElementHandler
in use.- Returns:
- The
StrictElementHandler
in use.
-
getNamespaceHandling
Returns theNamespaceHandling
in use.- Returns:
- The currently active
NamespaceHandling
instance.
-
getClassLoader
Returns the currentClassLoader
in use.- Returns:
- The
ClassLoader
in use.
-
getAnyNodeHandler
Returns the currently usedAnyNodeUnmarshalHandler
instance.- Returns:
- The
AnyNodeUnmarshalHandler
in use.
-
getDelegateUnmarshalListener
Returns the currently activeUnmarshalListenerDelegate
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
Hashtable to store idReference and ReferenceInfo- Returns:
- Hashtable
-
getAnyNode
returns the AnyNode (if any).- Returns:
- AnyNode, could be null
-
setAnyNode
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.
-
UnmarshalListener
interface