Package org.exolab.castor.xml
Class Unmarshaller
java.lang.Object
org.exolab.castor.xml.Unmarshaller
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: 9164 $ $Date: 2006-02-23 14:16:51 -0700 (Thu, 23 Feb 2006) $
- Author:
- Keith Visco
-
Constructor Summary
ConstructorsConstructorDescriptionAn 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
(Class clazz) A constructor which sets the root class.Unmarshaller
(Object root) Creates a new Unmarshaller with the given Object.Unmarshaller
(InternalContext internalContext) Creates a new basic Unmarshaller.Unmarshaller
(InternalContext internalContext, Class c) Creates a new Unmarshaller with the given Class.Unmarshaller
(InternalContext internalContext, Class c, ClassLoader loader) Creates a newUnmarshaller
with the given Class.Unmarshaller
(InternalContext internalContext, 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
Modifier and TypeMethodDescriptionvoid
addNamespaceToPackageMapping
(String nsURI, String packageName) Adds a mapping from the given namespace URI to the given package name.Creates and initalizes an UnmarshalHandlerstatic ContentHandler
getContentHandler
(UnmarshalHandler handler) Returns a ContentHandler for the given UnmarshalHandlerTo get the internal XML Context that is in use.getProperty
(String name) Returns the value of the given Castor XML-specific property.boolean
Indicates whether or not validation should be performed during umarshalling.void
Sets the 'expected'Class
instance on the Unmarshaller.void
setClassLoader
(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
(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
(PrintWriter printWriter) Deprecated.void
setMapping
(Mapping mapping) Sets the Mapping to use during unmarshalling.void
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
(String name, String value) Sets a custom value of a given Castor XML-specific property.void
setResolver
(XMLClassDescriptorResolver xmlClassDescriptorResolver) Sets the XMLClassDescriptorResolver to use during unmarshallingvoid
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 optionalUnmarshalListener
to receive pre and post unmarshal notification for each Object in the tree.void
setUnmarshalListener
(UnmarshalListener listener) Deprecated.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.Unmarshals Objects of this Unmarshaller's Class type.static Object
Unmarshals Objects of the given Class type.static Object
Unmarshals Objects of the given Class type.static Object
unmarshal
(Class c, InputSource source) Unmarshals Objects of the given Class type.unmarshal
(XMLEventReader eventReader) Unmarshals objects of thisUnmarshaller
's class type.unmarshal
(XMLStreamReader streamReader) Unmarshals objects of thisUnmarshaller
's class type.Unmarshals ths givenSource
instance.Unmarshals objects of thisUnmarshaller
's Class type from anAnyNode
instance.unmarshal
(EventProducer eventProducer) Deprecated.please use @see #unmarshal(SAX2EventProducer) instead.unmarshal
(SAX2EventAndErrorProducer eventProducer) Unmarshals objects of thisUnmarshaller
's class type.unmarshal
(SAX2EventProducer eventProducer) Unmarshals Objects of this Unmarshaller's Class type.Unmarshals Objects of this Unmarshaller's Class type.unmarshal
(InputSource source) Unmarshals Objects of this Unmarshaller's Class type.
-
Constructor Details
-
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
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
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
- theInternalContext
to use- Throws:
IllegalArgumentException
- if internalContext is null
-
Unmarshaller
Creates a new Unmarshaller with the given Class.- Parameters:
internalContext
- theInternalContext
to usec
- 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.- Throws:
IllegalArgumentException
- if internalContext is null
-
Unmarshaller
Creates a newUnmarshaller
with the given Class.- Parameters:
internalContext
- theInternalContext
to be used, for config, and such...c
- theClass
to create theUnmarshaller
for, this may be null, if the Unmarshaller#setMapping is called to load a mapping for the root element of xml document.loader
- TheClassLoader
to use.- Throws:
IllegalArgumentException
- if internalContext is null
-
Unmarshaller
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
Creates a new Unmarshaller with the given Mapping.- Parameters:
internalContext
- the internal context to usemapping
- The Mapping to use.- Throws:
MappingException
- in case that Unmarshaller fails to be instantiatedIllegalArgumentException
- if internalContext is null
-
Unmarshaller
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
Creates a new Unmarshaller with the given Object.- Parameters:
internalContext
- the internal context to useroot
- 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.- Throws:
IllegalArgumentException
- if internalContext is null
-
-
Method Details
-
addNamespaceToPackageMapping
Adds a mapping from the given namespace URI to the given package name.- Parameters:
nsURI
- the namespace URI to map frompackageName
- the package name to map to
-
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
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
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
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
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
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
Deprecated.Logging is replaced with commons-logging.- Parameters:
printWriter
- the PrintWriter to use for logging
-
setMapping
Sets the Mapping to use during unmarshalling. If the Mapping has a ClassLoader it will be used during unmarshalling.- Parameters:
mapping
- Mapping to use during unmarshalling.- Throws:
MappingException
- See Also:
-
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
Deprecated.replaced byUnmarshalListener
Sets an optionalUnmarshalListener
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
- theUnmarshalListener
to set.
-
setUnmarshalListener
Sets an optionalUnmarshalListener
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
- theUnmarshalListener
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
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 processValidationException
- when there is a validation error
-
unmarshal
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 processValidationException
- when there is a validation error
-
unmarshal
public 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 processValidationException
- when there is a validation error- Since:
- 1.0M3
-
unmarshal
Unmarshals objects of thisUnmarshaller
's Class type from anAnyNode
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
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 processValidationException
- when there is a validation error
-
unmarshal
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 processValidationException
- when there is a validation error
-
unmarshal
Unmarshals objects of thisUnmarshaller
'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 StaXXMLEventReader
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
Unmarshals objects of thisUnmarshaller
'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 STaXXMLStreamReader
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 Object unmarshal(SAX2EventAndErrorProducer eventProducer) throws MarshalException, ValidationException Unmarshals objects of thisUnmarshaller
's class type.
The class must specify the proper access methods (setters/getters) in order for instances of the class to be properly unmarshalled. invalid input: '<'/br/>- Parameters:
eventProducer
- theSAX2EventAndErrorProducer
instance which produces the SAX 2 events and handles SAX 2 errors.- Throws:
MarshalException
- indiactes a general error during the unmarshalling process.ValidationException
- indicates a validation error.- Since:
- 1.3.2
-
unmarshal
Unmarshals ths givenSource
instance. Currently this method will support fallowing classesDOMSource
,SAXSource
andStreamSource
.- Parameters:
source
- the source to unmarshal- Returns:
- the unmarshalled object instance
- Throws:
IllegalArgumentException
- if the given source is null or it is unsupportedMarshalException
- indiactes a general error during the unmarshalling process.ValidationException
- indicates a validation error.
-
getContentHandler
Returns a ContentHandler for the given UnmarshalHandler- Returns:
- the ContentHandler
- Throws:
SAXException
-
unmarshal
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 ofreader
- the Reader to read the XML from- Throws:
MarshalException
- when there is an error during the unmarshalling processValidationException
- when there is a validation error
-
unmarshal
public static Object unmarshal(Class c, 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 ofsource
- the InputSource to read the XML from- Throws:
MarshalException
- when there is an error during the unmarshalling processValidationException
- when there is a validation error
-
unmarshal
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
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
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
Sets a custom value of a given Castor XML-specific property.- Parameters:
name
- Name of the Castor XML propertyvalue
- Custom value to set.- Since:
- 1.1.2
-
setInternalContext
To set the internal XML Context to be used.- Parameters:
internalContext
- the context to be used
-
getInternalContext
To get the internal XML Context that is in use.- Returns:
- the
InternalContext
in use
-
setResolver
Sets the XMLClassDescriptorResolver to use during unmarshalling- Parameters:
xmlClassDescriptorResolver
- the XMLClassDescriptorResolver to use- See Also:
-
UnmarshalListener