Class UnmarshalHandler

  • All Implemented Interfaces:
    org.xml.sax.ContentHandler, org.xml.sax.DocumentHandler, org.xml.sax.ErrorHandler

    public final class UnmarshalHandler
    extends MarshalFramework
    implements org.xml.sax.ContentHandler, org.xml.sax.DocumentHandler, org.xml.sax.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 Detail

      • LOG

        static final org.apache.commons.logging.Log LOG
        Logger from commons-logging.
      • resourceBundle

        protected static java.util.ResourceBundle resourceBundle
        resource bundle
      • XML_SPACE_WITH_PREFIX

        static final java.lang.String XML_SPACE_WITH_PREFIX
        See Also:
        Constant Field Values
    • 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​(java.lang.Class<?> topClass)
        Creates a new UnmarshalHandler.
        Parameters:
        topClass - the Class to create the UnmarshalHandler for
      • UnmarshalHandler

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

      • addNamespaceToPackageMapping

        public void addNamespaceToPackageMapping​(java.lang.String nsURI,
                                                 java.lang.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 java.lang.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 java.lang.Object getObject()
        Returns the "root" Object (ie. the entire object model) being unmarshalled.
        Returns:
        the root Object being unmarshalled.
      • setClassLoader

        public void setClassLoader​(java.lang.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​(java.io.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​(java.lang.Object root)
        Sets the root (top-level) object to use for unmarshalling into.
        Parameters:
        root - the instance to unmarshal into.
      • 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 org.xml.sax.SAXException
        Specified by:
        characters in interface org.xml.sax.ContentHandler
        Specified by:
        characters in interface org.xml.sax.DocumentHandler
        Throws:
        org.xml.sax.SAXException
      • endDocument

        public void endDocument()
                         throws org.xml.sax.SAXException
        Specified by:
        endDocument in interface org.xml.sax.ContentHandler
        Specified by:
        endDocument in interface org.xml.sax.DocumentHandler
        Throws:
        org.xml.sax.SAXException
      • endElement

        public void endElement​(java.lang.String name)
                        throws org.xml.sax.SAXException
        Specified by:
        endElement in interface org.xml.sax.DocumentHandler
        Throws:
        org.xml.sax.SAXException
      • decodeBinaryData

        byte[] decodeBinaryData​(XMLFieldDescriptor descriptor,
                                java.lang.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​(java.lang.String namespaceURI,
                               java.lang.String localName,
                               java.lang.String qName)
                        throws org.xml.sax.SAXException

        ContentHandler#endElement

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

        public void endPrefixMapping​(java.lang.String prefix)
                              throws org.xml.sax.SAXException
        Signals to end the namespace prefix mapping
        Specified by:
        endPrefixMapping in interface org.xml.sax.ContentHandler
        Parameters:
        prefix - the namespace prefix
        Throws:
        org.xml.sax.SAXException
      • ignorableWhitespace

        public void ignorableWhitespace​(char[] ch,
                                        int start,
                                        int length)
                                 throws org.xml.sax.SAXException
        Specified by:
        ignorableWhitespace in interface org.xml.sax.ContentHandler
        Specified by:
        ignorableWhitespace in interface org.xml.sax.DocumentHandler
        Throws:
        org.xml.sax.SAXException
      • processingInstruction

        public void processingInstruction​(java.lang.String target,
                                          java.lang.String data)
                                   throws org.xml.sax.SAXException
        Specified by:
        processingInstruction in interface org.xml.sax.ContentHandler
        Specified by:
        processingInstruction in interface org.xml.sax.DocumentHandler
        Throws:
        org.xml.sax.SAXException
      • setDocumentLocator

        public void setDocumentLocator​(org.xml.sax.Locator locator)
        Specified by:
        setDocumentLocator in interface org.xml.sax.ContentHandler
        Specified by:
        setDocumentLocator in interface org.xml.sax.DocumentHandler
      • getDocumentLocator

        public org.xml.sax.Locator getDocumentLocator()
      • skippedEntity

        public void skippedEntity​(java.lang.String name)
                           throws org.xml.sax.SAXException
        Signals that an entity was skipped by the parser
        Specified by:
        skippedEntity in interface org.xml.sax.ContentHandler
        Parameters:
        name - the skipped entity's name
        Throws:
        org.xml.sax.SAXException
      • startDocument

        public void startDocument()
                           throws org.xml.sax.SAXException
        Signals the start of a new document
        Specified by:
        startDocument in interface org.xml.sax.ContentHandler
        Specified by:
        startDocument in interface org.xml.sax.DocumentHandler
        Throws:
        org.xml.sax.SAXException
      • startElement

        public void startElement​(java.lang.String namespaceURI,
                                 java.lang.String localName,
                                 java.lang.String qName,
                                 org.xml.sax.Attributes atts)
                          throws org.xml.sax.SAXException

        ContentHandler#startElement

        Signals the start of element.
        Specified by:
        startElement in interface org.xml.sax.ContentHandler
        Parameters:
        localName - The name of the element.
        atts - The AttributeList containing the associated attributes for the element.
        Throws:
        org.xml.sax.SAXException
      • startElement

        public void startElement​(java.lang.String name,
                                 org.xml.sax.AttributeList attList)
                          throws org.xml.sax.SAXException
        Deprecated.

        DocumentHandler#startElement

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

        void startElementProcessing​(java.lang.String name,
                                    java.lang.String namespace,
                                    AttributeSet atts)
                             throws org.xml.sax.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:
        org.xml.sax.SAXException
      • processFirstElement

        void processFirstElement​(java.lang.String name,
                                 java.lang.String namespace,
                                 AttributeSet atts,
                                 java.lang.String xmlSpace)
                          throws org.xml.sax.SAXException
        Throws:
        org.xml.sax.SAXException
      • isValidating

        boolean isValidating()
        Indicates whether validation is enabled or not.
        Returns:
        True if validation is enabled.
      • startPrefixMapping

        public void startPrefixMapping​(java.lang.String prefix,
                                       java.lang.String uri)
                                throws org.xml.sax.SAXException
        Signals to start the namespace - prefix mapping
        Specified by:
        startPrefixMapping in interface org.xml.sax.ContentHandler
        Parameters:
        prefix - the namespace prefix to map
        uri - the namespace URI
        Throws:
        org.xml.sax.SAXException
      • error

        public void error​(org.xml.sax.SAXParseException exception)
                   throws org.xml.sax.SAXException
        Specified by:
        error in interface org.xml.sax.ErrorHandler
        Throws:
        org.xml.sax.SAXException
      • fatalError

        public void fatalError​(org.xml.sax.SAXParseException exception)
                        throws org.xml.sax.SAXException
        Specified by:
        fatalError in interface org.xml.sax.ErrorHandler
        Throws:
        org.xml.sax.SAXException
      • warning

        public void warning​(org.xml.sax.SAXParseException exception)
                     throws org.xml.sax.SAXException
        Specified by:
        warning in interface org.xml.sax.ErrorHandler
        Throws:
        org.xml.sax.SAXException
      • addReference

        void addReference​(java.lang.String idRef,
                          java.lang.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

        java.lang.Object createInstance​(java.lang.Class<?> type,
                                        UnmarshalHandler.Arguments args)
                                 throws org.xml.sax.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:
        org.xml.sax.SAXException
      • getInstanceType

        java.lang.String getInstanceType​(AttributeSet atts,
                                         java.lang.String currentPackage)
                                  throws org.xml.sax.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:
        org.xml.sax.SAXException
      • processAttributes

        void processAttributes​(AttributeSet atts,
                               XMLClassDescriptor classDesc)
                        throws org.xml.sax.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:
        org.xml.sax.SAXException
      • processWrapperAttributes

        void processWrapperAttributes​(AttributeSet atts)
                               throws org.xml.sax.SAXException
        Processes the given AttributeSet for wrapper elements.
        Parameters:
        atts - the AttributeSet to process
        Throws:
        org.xml.sax.SAXException - If the AttributeSet cannot be processed
      • processConstructorArgs

        UnmarshalHandler.Arguments processConstructorArgs​(AttributeSet atts,
                                                          XMLClassDescriptor classDesc)
                                                   throws org.xml.sax.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:
        org.xml.sax.SAXException - If there's a problem creating the constructor argument set.
      • processIDREF

        boolean processIDREF​(java.lang.String idRef,
                             XMLFieldDescriptor descriptor,
                             java.lang.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​(java.lang.Class<?> cls)
                                       throws org.xml.sax.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:
        org.xml.sax.SAXException
      • getClassDescriptor

        XMLClassDescriptor getClassDescriptor​(java.lang.String className,
                                              java.lang.ClassLoader loader)
                                       throws org.xml.sax.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:
        org.xml.sax.SAXException
      • resolveByXMLName

        XMLClassDescriptor resolveByXMLName​(java.lang.String name,
                                            java.lang.String namespace,
                                            java.lang.ClassLoader loader)
                                     throws org.xml.sax.SAXException
        Returns the XMLClassLoader
        Throws:
        org.xml.sax.SAXException
      • getJavaPackage

        java.lang.String getJavaPackage​(java.lang.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

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

        static boolean isWhitespace​(java.lang.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

        java.lang.Class<?> loadClass​(java.lang.String className,
                                     java.lang.ClassLoader loader)
                              throws java.lang.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:
        java.lang.ClassNotFoundException
      • toPrimitiveObject

        java.lang.Object toPrimitiveObject​(java.lang.Class<?> type,
                                           java.lang.String value,
                                           XMLFieldDescriptor fieldDesc)
                                    throws org.xml.sax.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:
        org.xml.sax.SAXException - If the String cannot be converted to a primitive object type
      • toPrimitiveObject

        public static java.lang.Object toPrimitiveObject​(java.lang.Class<?> type,
                                                         java.lang.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
      • getClassLoader

        public java.lang.ClassLoader getClassLoader()
        Returns the current ClassLoader in use.
        Returns:
        The ClassLoader 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 java.util.Hashtable<java.lang.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.