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: 9086 $ $Date: 2006-05-25 06:41:12 -0600 (Thu, 25 May 2006) $
Author:
Keith Visco

  • Field Details

  • 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

      protected UnmarshalHandler(Class<?> topClass)
      Creates a new UnmarshalHandler.
      Parameters:
      topClass - the Class to create the UnmarshalHandler for

    • UnmarshalHandler

      protected UnmarshalHandler(InternalContext internalContext, Class<?> topClass)
      Creates a new UnmarshalHandler.
      Parameters:
      internalContext - the InternalContext to use
      topClass - the Class to work for

  • Method Details

    • 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

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

    • getObject

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

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

    • 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(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(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 SAXException
      Specified by:
      characters in interface ContentHandler
      Specified by:
      characters in interface DocumentHandler
      Throws:
      SAXException

    • endDocument

      public void endDocument() throws SAXException
      Specified by:
      endDocument in interface ContentHandler
      Specified by:
      endDocument in interface DocumentHandler
      Throws:
      SAXException

    • endElement

      public void endElement(String name) throws SAXException
      Specified by:
      endElement in interface DocumentHandler
      Throws:
      SAXException

    • endElement

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

      ContentHandler#endElement

      Signals the end of an element
      Specified by:
      endElement in interface ContentHandler
      Parameters:
      localName - The name of the element.
      Throws:
      SAXException

    • endPrefixMapping

      public void endPrefixMapping(String prefix) throws SAXException
      Signals to end the namespace prefix mapping
      Specified by:
      endPrefixMapping in interface ContentHandler
      Parameters:
      prefix - the namespace prefix
      Throws:
      SAXException

    • ignorableWhitespace

      public void ignorableWhitespace(char[] ch, int start, int length) throws SAXException
      Specified by:
      ignorableWhitespace in interface ContentHandler
      Specified by:
      ignorableWhitespace in interface DocumentHandler
      Throws:
      SAXException

    • processingInstruction

      public void processingInstruction(String target, String data) throws SAXException
      Specified by:
      processingInstruction in interface ContentHandler
      Specified by:
      processingInstruction in interface DocumentHandler
      Throws:
      SAXException

    • setDocumentLocator

      public void setDocumentLocator(Locator locator)
      Specified by:
      setDocumentLocator in interface ContentHandler
      Specified by:
      setDocumentLocator in interface DocumentHandler

    • getDocumentLocator

      public Locator getDocumentLocator()

    • skippedEntity

      public void skippedEntity(String name) throws SAXException
      Signals that an entity was skipped by the parser
      Specified by:
      skippedEntity in interface ContentHandler
      Parameters:
      name - the skipped entity's name
      Throws:
      SAXException

    • startDocument

      public void startDocument() throws SAXException
      Signals the start of a new document
      Specified by:
      startDocument in interface ContentHandler
      Specified by:
      startDocument in interface DocumentHandler
      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 interface ContentHandler
      Parameters:
      localName - The name of the element.
      atts - The AttributeList containing the associated attributes for the element.
      Throws:
      SAXException

    • startElement

      public void startElement(String name, AttributeList attList) throws SAXException
      Deprecated.

      DocumentHandler#startElement

      Signals the start of element.
      Specified by:
      startElement in interface DocumentHandler
      Parameters:
      name - The name of the element.
      attList - The AttributeList containing the associated attributes for the element.
      Throws:
      SAXException

    • startPrefixMapping

      public void startPrefixMapping(String prefix, String uri) throws SAXException
      Signals to start the namespace - prefix mapping
      Specified by:
      startPrefixMapping in interface ContentHandler
      Parameters:
      prefix - the namespace prefix to map
      uri - the namespace URI
      Throws:
      SAXException

    • error

      public void error(SAXParseException exception) throws SAXException
      Specified by:
      error in interface ErrorHandler
      Throws:
      SAXException

    • fatalError

      public void fatalError(SAXParseException exception) throws SAXException
      Specified by:
      fatalError in interface ErrorHandler
      Throws:
      SAXException

    • warning

      public void warning(SAXParseException exception) throws SAXException
      Specified by:
      warning in interface ErrorHandler
      Throws:
      SAXException

    • 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

    • 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

    • getStateStack

      public UnmarshalStateStack getStateStack()
      Returnss a refrence to the UnmarshalStateStack instance currently in use.
      Returns:
      The UnmarshalStateStack in use.

    • getTopState

      public UnmarshalState getTopState()
      Returns the top UnmarshalState instance from the UnmarshalStateStack.
      Returns:
      The top UnmarshalState instance.

    • getStrictElementHandler

      public StrictElementHandler getStrictElementHandler()
      Returns the StrictElementHandler in use.
      Returns:
      The StrictElementHandler in use.

    • getNamespaceHandling

      public NamespaceHandling getNamespaceHandling()
      Returns the NamespaceHandling in use.
      Returns:
      The currently active NamespaceHandling instance.

    • getClassLoader

      public ClassLoader getClassLoader()
      Returns the current ClassLoader in use.
      Returns:
      The ClassLoader in use.

    • getAnyNodeHandler

      public AnyNodeUnmarshalHandler getAnyNodeHandler()
      Returns the currently used AnyNodeUnmarshalHandler instance.
      Returns:
      The AnyNodeUnmarshalHandler in use.

    • getDelegateUnmarshalListener

      public UnmarshalListenerDelegate getDelegateUnmarshalListener()
      Returns the currently active UnmarshalListenerDelegate 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

      public Hashtable<String,org.exolab.castor.xml.ReferenceInfo> getResolveTable()
      Hashtable to store idReference and ReferenceInfo
      Returns:
      Hashtable

    • getAnyNode

      public AnyNode getAnyNode()
      returns the AnyNode (if any).
      Returns:
      AnyNode, could be null

    • setAnyNode

      public void setAnyNode(AnyNode node)
      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.

    • 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(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(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(String ns1, 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 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 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