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
  • 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
      Parameters:
      listener - the UnmarshalListener to use with this instance of the UnmarshalHandler.
    • setUnmarshalListener

      public void setUnmarshalListener(UnmarshalListener listener)
      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
    • decodeBinaryData

      byte[] decodeBinaryData(XMLFieldDescriptor descriptor, String binaryData)
      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

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

      void startElementProcessing(String name, String namespace, AttributeSet atts) throws SAXException
      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

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

      void addReference(String idRef, Object parent, XMLFieldDescriptor descriptor)
      Adds the given reference to the "queue" until the referenced object has been unmarshalled.
      Parameters:
      idRef - the ID being referenced
      parent - the target/parent object for the field
      descriptor - the XMLFieldDescriptor for the field
    • createInstance

      Object createInstance(Class<?> type, UnmarshalHandler.Arguments args) throws SAXException
      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 instantiation
      args - (Optional) arguments to be used during instantiation
      Throws:
      SAXException
    • getInstanceType

      String getInstanceType(AttributeSet atts, String currentPackage) throws SAXException
      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

      void processAttributes(AttributeSet atts, XMLClassDescriptor classDesc) throws SAXException
      Processes the given attribute list, and attempts to add each Attributes to the current Object on the stack.
      Parameters:
      atts - the AttributeSet to process
      classDesc - the classDesc to use during processing
      Throws:
      SAXException
    • processWrapperAttributes

      void processWrapperAttributes(AttributeSet atts) throws SAXException
      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 process
      classDesc - 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

      boolean processIDREF(String idRef, XMLFieldDescriptor descriptor, Object parent)
      Processes the given IDREF.
      Parameters:
      idRef - the ID of the object in which to reference
      descriptor - the current FieldDescriptor
      parent - the current parent object
      Returns:
      true if the ID was found and resolved properly
    • getClassDescriptor

      XMLClassDescriptor getClassDescriptor(Class<?> cls) throws SAXException
      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

      XMLClassDescriptor getClassDescriptor(String className, ClassLoader loader) throws SAXException
      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

      String getJavaPackage(Class<?> type)
      Returns the package for the given Class
      Parameters:
      type - the Class to return the package of
      Returns:
      the package for the given Class
    • className

      String className(Class<?> type)
      Returns the name of a class, handles array types
      Returns:
      the name of a class, handles array types
    • isWhitespace

      static boolean isWhitespace(StringBuffer sb)
      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

      Class<?> loadClass(String className, ClassLoader loader) throws ClassNotFoundException
      Loads and returns the class with the given class name using the given loader.
      Parameters:
      className - the name of the class to load
      loader - 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 to
      value - the String to convert to a primitive
      fieldDesc - 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

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