Class Unmarshaller


  • public class Unmarshaller
    extends java.lang.Object
    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: 8659 $ $Date: 2006-02-23 14:16:51 -0700 (Thu, 23 Feb 2006) $
    Author:
    Keith Visco
    • Field Summary

      Fields 
      Modifier and Type Field Description
      (package private) org.xml.sax.EntityResolver entityResolver
      The EntityResolver used for resolving entities
    • Constructor Summary

      Constructors 
      Constructor Description
      Unmarshaller()
      An empty default constructor which: - sets the internal context to the backward compatibility context - all other flags to defaults Internally the Unmarshaller(Class) constructor is called.
      Unmarshaller​(java.lang.Class clazz)
      A constructor which sets the root class.
      Unmarshaller​(java.lang.Object root)
      Creates a new Unmarshaller with the given Object.
      Unmarshaller​(InternalContext internalContext)
      Creates a new basic Unmarshaller.
      Unmarshaller​(InternalContext internalContext, java.lang.Class c)
      Creates a new Unmarshaller with the given Class.
      Unmarshaller​(InternalContext internalContext, java.lang.Class c, java.lang.ClassLoader loader)
      Creates a new Unmarshaller with the given Class.
      Unmarshaller​(InternalContext internalContext, java.lang.Object root)
      Creates a new Unmarshaller with the given Object.
      Unmarshaller​(InternalContext internalContext, Mapping mapping)
      Creates a new Unmarshaller with the given Mapping.
      Unmarshaller​(Mapping mapping)
      Creates a new Unmarshaller with the given Mapping.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void addNamespaceToPackageMapping​(java.lang.String nsURI, java.lang.String packageName)
      Adds a mapping from the given namespace URI to the given package name.
      UnmarshalHandler createHandler()
      Creates and initalizes an UnmarshalHandler
      static org.xml.sax.ContentHandler getContentHandler​(UnmarshalHandler handler)
      Returns a ContentHandler for the given UnmarshalHandler
      InternalContext getInternalContext()
      To get the internal XML Context that is in use.
      java.lang.String getProperty​(java.lang.String name)
      Returns the value of the given Castor XML-specific property.
      boolean isValidating()
      Indicates whether or not validation should be performed during umarshalling.
      void setClass​(java.lang.Class clazz)
      Sets the 'expected' Class instance on the Unmarshaller.
      void setClassLoader​(java.lang.ClassLoader loader)
      Sets the ClassLoader to use when loading new classes.
      void 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 setEntityResolver​(org.xml.sax.EntityResolver entityResolver)
      Sets the EntityResolver to use when resolving system and public ids with respect to entites and Document Type.
      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 ignoreExtraElements)
      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 the internal XML Context to be used.
      void setLogWriter​(java.io.PrintWriter printWriter)
      Deprecated. 
      void setMapping​(Mapping mapping)
      Sets the Mapping to use during unmarshalling.
      void setObject​(java.lang.Object root)
      Sets the 'expected' Object instance on the Unmarshaller, into which will be unmarshalled.
      void setObjectFactory​(ObjectFactory objectFactory)
      Set an object factory for the unmarshaller.
      void setProperty​(java.lang.String name, java.lang.String value)
      Sets a custom value of a given Castor XML-specific property.
      void setResolver​(XMLClassDescriptorResolver xmlClassDescriptorResolver)
      Sets the XMLClassDescriptorResolver to use during unmarshalling
      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 setUnmarshalListener​(UnmarshalListener listener)
      Sets an optional UnmarshalListener to receive pre and post unmarshal notification for each Object in the tree.
      void setUnmarshalListener​(UnmarshalListener listener)
      Deprecated.
      replaced by UnmarshalListener
      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.
      java.lang.Object unmarshal​(java.io.Reader reader)
      Unmarshals Objects of this Unmarshaller's Class type.
      static java.lang.Object unmarshal​(java.lang.Class c, java.io.Reader reader)
      Unmarshals Objects of the given Class type.
      static java.lang.Object unmarshal​(java.lang.Class c, org.w3c.dom.Node node)
      Unmarshals Objects of the given Class type.
      static java.lang.Object unmarshal​(java.lang.Class c, org.xml.sax.InputSource source)
      Unmarshals Objects of the given Class type.
      java.lang.Object unmarshal​(javax.xml.stream.XMLEventReader eventReader)
      Unmarshals objects of this Unmarshaller's class type.
      java.lang.Object unmarshal​(javax.xml.stream.XMLStreamReader streamReader)
      Unmarshals objects of this Unmarshaller's class type.
      java.lang.Object unmarshal​(AnyNode anyNode)
      Unmarshals objects of this Unmarshaller's Class type from an AnyNode instance.
      java.lang.Object unmarshal​(EventProducer eventProducer)
      Deprecated.
      please use @see #unmarshal(SAX2EventProducer) instead.
      java.lang.Object unmarshal​(SAX2EventAndErrorProducer eventProducer)
      Unmarshals objects of this Unmarshaller's class type.
      java.lang.Object unmarshal​(SAX2EventProducer eventProducer)
      Unmarshals Objects of this Unmarshaller's Class type.
      java.lang.Object unmarshal​(org.w3c.dom.Node node)
      Unmarshals Objects of this Unmarshaller's Class type.
      java.lang.Object unmarshal​(org.xml.sax.InputSource source)
      Unmarshals Objects of this Unmarshaller's Class type.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • entityResolver

        org.xml.sax.EntityResolver entityResolver
        The EntityResolver used for resolving entities
    • Constructor Detail

      • Unmarshaller

        public Unmarshaller()
        An empty default constructor which: - sets the internal context to the backward compatibility context - all other flags to defaults Internally the Unmarshaller(Class) constructor is called.
      • Unmarshaller

        public Unmarshaller​(java.lang.Class clazz)
        A constructor which sets the root class. Internally calls constructor Unmarshaller(InternalContext, Class) with an instance of BackwardCompatibilityContext as context.
        Parameters:
        clazz - root class for unmarshalling
      • Unmarshaller

        public Unmarshaller​(InternalContext internalContext)
        Creates a new basic Unmarshaller. When using this constructor it will most likely be necessary to use a mapping file or ClassDescriptorResolver So that the Unmarshaller can find the classes during the unmarshalling process.
        Parameters:
        internalContext - the InternalContext to use
      • Unmarshaller

        public Unmarshaller​(InternalContext internalContext,
                            java.lang.Class c)
        Creates a new Unmarshaller with the given Class.
        Parameters:
        internalContext - the InternalContext to use
        c - the Class to create the Unmarshaller for, this may be null, if the Unmarshaller#setMapping is called to load a mapping for the root element of xml document.
      • Unmarshaller

        public Unmarshaller​(InternalContext internalContext,
                            java.lang.Class c,
                            java.lang.ClassLoader loader)
        Creates a new Unmarshaller with the given Class.
        Parameters:
        internalContext - the InternalContext to be used, for config, and such...
        c - the Class to create the Unmarshaller for, this may be null, if the Unmarshaller#setMapping is called to load a mapping for the root element of xml document.
        loader - The ClassLoader to use.
      • Unmarshaller

        public Unmarshaller​(Mapping mapping)
                     throws MappingException
        Creates a new Unmarshaller with the given Mapping. An instance of BackwardsCompatibilityContext is used as InternalContext.
        Parameters:
        mapping - The Mapping to use.
        Throws:
        MappingException - in case that Unmarshaller fails to be instantiated
      • Unmarshaller

        public Unmarshaller​(InternalContext internalContext,
                            Mapping mapping)
                     throws MappingException
        Creates a new Unmarshaller with the given Mapping.
        Parameters:
        internalContext - the internal context to use
        mapping - The Mapping to use.
        Throws:
        MappingException - in case that Unmarshaller fails to be instantiated
      • Unmarshaller

        public Unmarshaller​(java.lang.Object root)
        Creates a new Unmarshaller with the given Object.
        Parameters:
        root - the instance to unmarshal into. This may be null, if the Unmarshaller#setMapping is called to load a mapping for the root element of xml document.
      • Unmarshaller

        public Unmarshaller​(InternalContext internalContext,
                            java.lang.Object root)
        Creates a new Unmarshaller with the given Object.
        Parameters:
        internalContext - the internal context to use
        root - the instance to unmarshal into. This may be null, if the Unmarshaller#setMapping is called to load a mapping for the root element of xml document.
    • 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
      • createHandler

        public UnmarshalHandler createHandler()
        Creates and initalizes an UnmarshalHandler
        Returns:
        the new UnmarshalHandler
      • isValidating

        public boolean isValidating()
        Indicates whether or not validation should be performed during umarshalling.
        Returns:
        True if validation is performed during umarshalling.
      • setClass

        public void setClass​(java.lang.Class clazz)
        Sets the 'expected' Class instance on the Unmarshaller.
        Parameters:
        clazz - the Class to create the Unmarshaller for, this may be null, if the Unmarshaller#setMapping is called to load a mapping for the root element of xml document.
      • setObject

        public void setObject​(java.lang.Object root)
        Sets the 'expected' Object instance on the Unmarshaller, into which will be unmarshalled.
        Parameters:
        root - the instance to unmarshal into. This may be null, if the Unmarshaller#setMapping is called to load a mapping for the root element of xml document.
      • setClassLoader

        public void setClassLoader​(java.lang.ClassLoader loader)
        Sets the ClassLoader to use when loading new classes.
        Note:This ClassLoader is used for classes loaded by the unmarshaller only. If a Mapping has been set, the Mapping has it's own ClassLoader and may also need to be set propertly.
        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.
        Custom debugging is replaced with commons-logging
      • setEntityResolver

        public void setEntityResolver​(org.xml.sax.EntityResolver entityResolver)
        Sets the EntityResolver to use when resolving system and public ids with respect to entites and Document Type.
        Parameters:
        entityResolver - the EntityResolver to use when resolving System and Public ids.
      • 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 ignoreExtraElements)
        Sets whether or not elements that do not match a specific field should simply be ignored or reported as an error. By default, extra elements are flagged as an error.
        Parameters:
        ignoreExtraElements - a boolean that when true will allow non-matched elements to simply be ignored.
      • setLogWriter

        public void setLogWriter​(java.io.PrintWriter printWriter)
        Deprecated.
        Logging is replaced with commons-logging.
        Parameters:
        printWriter - the PrintWriter to use for 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.
      • setUnmarshalListener

        public void setUnmarshalListener​(UnmarshalListener listener)
        Deprecated.
        replaced by UnmarshalListener
        Sets an optional UnmarshalListener to receive pre and post unmarshal notification for each Object in the tree. An UnmarshalListener is often used to allow objects to appropriately initialize themselves by taking application specific behavior as they are unloaded. Current only one (1) listener is allowed. If you need register multiple listeners, you will have to create your own master listener that will forward the event notifications and manage the multiple listeners.
        The deprecated listener set with this method will be wrapped by an adapter.
        Parameters:
        listener - the UnmarshalListener to set.
      • setUnmarshalListener

        public void setUnmarshalListener​(UnmarshalListener listener)
        Sets an optional UnmarshalListener to receive pre and post unmarshal notification for each Object in the tree. An UnmarshalListener is often used to allow objects to appropriately initialize themselves by taking application specific behavior as they are unloaded. Current only one (1) listener is allowed. If you need register multiple listeners, you will have to create your own master listener that will forward the event notifications and manage the multiple listeners.
        Parameters:
        listener - the UnmarshalListener to set.
      • 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.
      • unmarshal

        public java.lang.Object unmarshal​(java.io.Reader reader)
                                   throws MarshalException,
                                          ValidationException
        Unmarshals Objects of this Unmarshaller's Class type. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.
        Parameters:
        reader - the Reader to read the XML from
        Throws:
        MarshalException - when there is an error during the unmarshalling process
        ValidationException - when there is a validation error
      • unmarshal

        public java.lang.Object unmarshal​(EventProducer eventProducer)
                                   throws MarshalException,
                                          ValidationException
        Deprecated.
        please use @see #unmarshal(SAX2EventProducer) instead.
        Unmarshals Objects of this Unmarshaller's Class type. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.
        Parameters:
        eventProducer - the EventProducer which produces the SAX events
        Throws:
        MarshalException - when there is an error during the unmarshalling process
        ValidationException - when there is a validation error
      • unmarshal

        public java.lang.Object unmarshal​(SAX2EventProducer eventProducer)
                                   throws MarshalException,
                                          ValidationException
        Unmarshals Objects of this Unmarshaller's Class type. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.
        Parameters:
        eventProducer - the SAX2EventProducer instance which produces the SAX 2 events
        Throws:
        MarshalException - when there is an error during the unmarshalling process
        ValidationException - when there is a validation error
        Since:
        1.0M3
      • unmarshal

        public java.lang.Object unmarshal​(AnyNode anyNode)
                                   throws MarshalException
        Unmarshals objects of this Unmarshaller's Class type from an AnyNode instance. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.
        Parameters:
        anyNode - AnyNode instance to be unmarshalled from
        Returns:
        The Object instance that is a result of unmarshalling.
        Throws:
        MarshalException - when there is an error during the unmarshalling process
      • unmarshal

        public java.lang.Object unmarshal​(org.xml.sax.InputSource source)
                                   throws MarshalException,
                                          ValidationException
        Unmarshals Objects of this Unmarshaller's Class type. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.
        Parameters:
        source - the InputSource to read the XML from
        Throws:
        MarshalException - when there is an error during the unmarshalling process
        ValidationException - when there is a validation error
      • unmarshal

        public java.lang.Object unmarshal​(org.w3c.dom.Node node)
                                   throws MarshalException,
                                          ValidationException
        Unmarshals Objects of this Unmarshaller's Class type. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.
        Parameters:
        node - the DOM node to read the XML from
        Throws:
        MarshalException - when there is an error during the unmarshalling process
        ValidationException - when there is a validation error
      • unmarshal

        public java.lang.Object unmarshal​(javax.xml.stream.XMLEventReader eventReader)
                                   throws MarshalException,
                                          ValidationException
        Unmarshals objects of this Unmarshaller's class type. The class must specify the proper access methods (setters/getters) in order for instances of the class to be properly unmarshalled.
        Parameters:
        eventReader - the StaX XMLEventReader to read XML from.
        Throws:
        MarshalException - indicates a general problem during the unmarshalling process.
        ValidationException - indicates a problem related to validation.
        Since:
        1.3.2
      • unmarshal

        public java.lang.Object unmarshal​(javax.xml.stream.XMLStreamReader streamReader)
                                   throws MarshalException,
                                          ValidationException
        Unmarshals objects of this Unmarshaller's class type. The class must specify the proper access methods (setters/getters) in order for instances of the class to be properly unmarshalled.
        Parameters:
        streamReader - the STaX XMLStreamReader to read XML from.
        Throws:
        MarshalException - indicates a general problem during the unmarshalling process.
        ValidationException - indicates a problem related to validation.
        Since:
        1.3.2
      • getContentHandler

        public static org.xml.sax.ContentHandler getContentHandler​(UnmarshalHandler handler)
                                                            throws org.xml.sax.SAXException
        Returns a ContentHandler for the given UnmarshalHandler
        Returns:
        the ContentHandler
        Throws:
        org.xml.sax.SAXException
      • unmarshal

        public static java.lang.Object unmarshal​(java.lang.Class c,
                                                 java.io.Reader reader)
                                          throws MarshalException,
                                                 ValidationException
        Unmarshals Objects of the given Class type. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.

        Note:This is a *static* method, any mapping files set on a particular Unmarshaller instance, and any changes made via setters will be unavailable to this method.

        Parameters:
        c - the Class to create a new instance of
        reader - the Reader to read the XML from
        Throws:
        MarshalException - when there is an error during the unmarshalling process
        ValidationException - when there is a validation error
      • unmarshal

        public static java.lang.Object unmarshal​(java.lang.Class c,
                                                 org.xml.sax.InputSource source)
                                          throws MarshalException,
                                                 ValidationException
        Unmarshals Objects of the given Class type. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.

        Note:This is a *static* method, any mapping files set on a particular Unmarshaller instance, and any changes made via setters will be unavailable to this method.

        Parameters:
        c - the Class to create a new instance of
        source - the InputSource to read the XML from
        Throws:
        MarshalException - when there is an error during the unmarshalling process
        ValidationException - when there is a validation error
      • unmarshal

        public static java.lang.Object unmarshal​(java.lang.Class c,
                                                 org.w3c.dom.Node node)
                                          throws MarshalException,
                                                 ValidationException
        Unmarshals Objects of the given Class type. The Class must specify the proper access methods (setters/getters) in order for instances of the Class to be properly unmarshalled.

        Note:This is a *static* method, any mapping files set on a particular Unmarshaller instance, and any changes made via setters will be unavailable to this method.

        Parameters:
        c - The Class to create a new instance of.
        node - The DOM Node to read the XML from.
        Throws:
        MarshalException - When there is an error during the unmarshalling process.
        ValidationException - When there is a validation error.
      • setObjectFactory

        public void setObjectFactory​(ObjectFactory objectFactory)
        Set an object factory for the unmarshaller. This factory will be used to construct the objects being unmarshalled.
        Parameters:
        objectFactory - Factory used for constructing objects during unmarshalling.
      • getProperty

        public java.lang.String getProperty​(java.lang.String name)
        Returns the value of the given Castor XML-specific property.
        Parameters:
        name - Qualified name of the CASTOR XML-specific property.
        Returns:
        The current value of the given property.
        Since:
        1.1.2
      • setProperty

        public void setProperty​(java.lang.String name,
                                java.lang.String value)
        Sets a custom value of a given Castor XML-specific property.
        Parameters:
        name - Name of the Castor XML property
        value - Custom value to set.
        Since:
        1.1.2
      • setInternalContext

        public void setInternalContext​(InternalContext internalContext)
        To set the internal XML Context to be used.
        Parameters:
        internalContext - the context to be used
      • getInternalContext

        public InternalContext getInternalContext()
        To get the internal XML Context that is in use.
        Returns:
        the InternalContext in use