Package 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$ $Date: 2006-05-25 06:41:12 -0600 (Thu, 25 May 2006) $
- Author:
- Keith Visco
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
A class for handling Arrays during unmarshalling. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
The xml:lang attribute, without the "xml:" prefix.static final String
The xsi:nil attribute, without the "xsi:" prefix.protected static ResourceBundle
resource bundlestatic final String
The xml:space attribute name, without the "xml:" prefix.static final String
The value of 'true'.static final String
The xsi:type attribute name, without the "xsi:" prefix.static final String
The xml:lang attribute name.static final String
The xml:space attribute name.static final String
The XSI Namespace URI.static final String
The xsi:nil attribute.static final String
The name of the no namespace schema location attribute.static final String
The name of the Schema location attribute. -
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 namevoid
characters
(char[] ch, int start, int length) 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.Returns the currentClassLoader
in use.getCollectionHandler
(Class clazz) Returns the CollectionHandler associated with the given collection, or null if no such handler exists.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
instanceTo get theAbstractInternalContext
to use.To get theJavaNaming
instance to be used.Returns 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.static boolean
isCollection
(Class clazz) Returns true if the given Class is a considered a collection by the marshalling framework.boolean
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 org.exolab.castor.xml.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 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
setInternalContext
(InternalContext internalContext) To set theAbstractInternalContext
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) 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.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.void
warning
(SAXParseException exception) 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
-
resourceBundle
resource bundle -
XSI_NAMESPACE
-
XSI_SCHEMA_LOCATION
-
XSI_NO_NAMESPACE_SCHEMA_LOCATION
The name of the no namespace schema location attribute.- See Also:
-
XML_LANG_ATTR
-
LANG_ATTR
-
NIL_ATTR
-
XSI_NIL_ATTR
-
XML_SPACE_ATTR
-
SPACE_ATTR
The xml:space attribute name, without the "xml:" prefix.- See Also:
-
TYPE_ATTR
The xsi:type attribute name, without the "xsi:" prefix.- See Also:
-
TRUE_VALUE
-
-
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
-
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
-
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
-
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
-
toPrimitiveObject
-
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
-
getAnyNode
-
setAnyNode
-
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
To get theJavaNaming
instance to be used.- Returns:
- the JavaNaming to be used
-
getInternalContext
To get theAbstractInternalContext
to use.- Returns:
- the
AbstractInternalContext
to use
-
setInternalContext
To set theAbstractInternalContext
to use.- Parameters:
internalContext
- theAbstractInternalContext
to use
-
isCollection
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
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
Compares the given namespaces (as strings) for equality. null and empty values are considered equal.- Parameters:
ns1
- the namespace to compare to argument ns2ns2
- the namespace to compare to argument ns1- Returns:
- true if the namespaces are considert equal TODO: joachim put it into XMLNaming!
-
searchInheritance
protected org.exolab.castor.xml.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 fieldnamespace
- namespace of the fieldclassDesc
- the class descriptor to match againstcdResolver
- the class descriptor resolver to use- Returns:
- An array of InheritanceMatch.
- Throws:
MarshalException
- if the resolver called fails fatally
-
UnmarshalListener
interface