org.exolab.castor.xml

Class UnmarshalHandler

public final class UnmarshalHandler extends MarshalFramework implements ContentHandler, DocumentHandler, 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.51 $ $Date: 2005/08/05 19:58:33 $

Author: Keith Visco

Nested Class Summary
classUnmarshalHandler.Arguments
Internal class used for passing constructor argument information
static classUnmarshalHandler.ArrayHandler
A class for handling Arrays during unmarshalling.
classUnmarshalHandler.ElementInfo
A utility class for keeping track of the qName and how the SAX parser passed attributes
classUnmarshalHandler.IDResolverImpl
Local IDResolver
classUnmarshalHandler.ReferenceInfo
Internal class used to save state for reference resolving
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(Class _class)
Creates a new UnmarshalHandler
Method Summary
voidaddNamespaceToPackageMapping(String nsURI, String packageName)
Adds a mapping from the given namespace URI to the given package name
voidcharacters(char[] ch, int start, int length)
voidendDocument()
voidendElement(String name)
voidendElement(String namespaceURI, String localName, String qName)

ContentHandler#endElement

Signals the end of an element
voidendPrefixMapping(String prefix)
Signals to end the namespace prefix mapping
voiderror(SAXParseException exception)
voidfatalError(SAXParseException exception)
ObjectgetCurrentObject()
Returns the Object that the UnmarshalHandler is currently handling (within the object model), or null if the current element is a simpleType.
LocatorgetDocumentLocator()
ObjectgetObject()
Returns the "root" Object (ie. the entire object model) being unmarshalled.
voidignorableWhitespace(char[] ch, int start, int length)
voidprocessingInstruction(String target, String data)
voidsetClassLoader(ClassLoader loader)
Sets the ClassLoader to use when loading classes
voidsetClearCollections(boolean clear)
Sets whether or not to clear collections (including arrays) upon first use to remove default values.
protected voidsetConfiguration(Configuration config)
Sets the current Castor configuration.
voidsetDebug(boolean debug)
Turns debuging on or off.
voidsetDocumentLocator(Locator locator)
voidsetIDResolver(IDResolver idResolver)
Sets the IDResolver to use when resolving IDREFs for which no associated element may exist in XML document.
voidsetIgnoreExtraAttributes(boolean ignoreExtraAtts)
Sets whether or not attributes that do not match a specific field should simply be ignored or reported as an error.
voidsetIgnoreExtraElements(boolean ignoreExtraElems)
Sets whether or not elements that do not match a specific field should simply be ignored or reported as an error.
voidsetLogWriter(PrintWriter printWriter)
Sets the PrintWriter used for printing log messages
voidsetResolver(ClassDescriptorResolver cdResolver)
Sets the ClassDescriptorResolver to use for loading and resolving ClassDescriptors
voidsetReuseObjects(boolean reuse)
Sets a boolean that when true indicates that objects contained within the object model should be re-used where appropriate.
voidsetRootObject(Object root)
Sets the root (top-level) object to use for unmarshalling into.
voidsetUnmarshalListener(UnmarshalListener listener)
voidsetValidation(boolean validate)
Sets the flag for validation
voidsetWhitespacePreserve(boolean preserve)
Sets the top-level whitespace (xml:space) to either preserving or non preserving.
voidskippedEntity(String name)
Signals that an entity was skipped by the parser
voidstartDocument()
Signals the start of a new document
voidstartElement(String namespaceURI, String localName, String qName, Attributes atts)

ContentHandler#startElement

Signals the start of element
voidstartElement(String name, AttributeList attList)

DocumentHandler#startElement

Signals the start of element
voidstartPrefixMapping(String prefix, String uri)
Signals to start the namespace - prefix mapping
static ObjecttoPrimitiveObject(Class type, String value)
Converts a String to the given primitive object type
voidwarning(SAXParseException exception)

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

Parameters: _class the Class to create the UnmarshalHandler for

Method Detail

addNamespaceToPackageMapping

public void addNamespaceToPackageMapping(String nsURI, 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

characters

public void characters(char[] ch, int start, int length)

endDocument

public void endDocument()

endElement

public void endElement(String name)

endElement

public void endElement(String namespaceURI, String localName, String qName)

ContentHandler#endElement

Signals the end of an element

Parameters: name the name of the element

endPrefixMapping

public void endPrefixMapping(String prefix)
Signals to end the namespace prefix mapping

Parameters: prefix the namespace prefix

error

public void error(SAXParseException exception)

fatalError

public void fatalError(SAXParseException exception)

getCurrentObject

public 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.

getDocumentLocator

public Locator getDocumentLocator()

getObject

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

Returns: the root Object being unmarshalled.

ignorableWhitespace

public void ignorableWhitespace(char[] ch, int start, int length)

processingInstruction

public void processingInstruction(String target, String data)

setClassLoader

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

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.

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: UnmarshalHandler

setDocumentLocator

public void setDocumentLocator(Locator locator)

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(PrintWriter printWriter)
Sets the PrintWriter used for printing log messages

Parameters: printWriter the PrintWriter to use when printing log messages

setResolver

public void setResolver(ClassDescriptorResolver cdResolver)
Sets the ClassDescriptorResolver to use for loading and resolving ClassDescriptors

Parameters: cdResolver the ClassDescriptorResolver to use

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

skippedEntity

public void skippedEntity(String name)
Signals that an entity was skipped by the parser

Parameters: name the skipped entity's name

startDocument

public void startDocument()
Signals the start of a new document

startElement

public void startElement(String namespaceURI, String localName, String qName, Attributes atts)

ContentHandler#startElement

Signals the start of element

Parameters: name the name of the element atts the AttributeList containing the associated attributes for the element

startElement

public void startElement(String name, AttributeList attList)

DocumentHandler#startElement

Signals the start of element

Parameters: name the name of the element atts the AttributeList containing the associated attributes for the element

startPrefixMapping

public void startPrefixMapping(String prefix, String uri)
Signals to start the namespace - prefix mapping

Parameters: prefix the namespace prefix to map uri the namespace URI

toPrimitiveObject

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

warning

public void warning(SAXParseException exception)
Intalio Inc. (C) 1999-2004. All rights reserved http://www.intalio.com