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.
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(Class clazz)
A constructor which sets the root class.
Internally calls constructor Unmarshaller(InternalContext, Class) with
an instance of BackwardCompatibilityContext as context.
clazz
- root class for unmarshalling
Unmarshaller
public Unmarshaller(Object root)
Creates a new Unmarshaller with the given Object.
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)
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.
Unmarshaller
public Unmarshaller(InternalContext internalContext,
Class c)
Creates a new Unmarshaller with the given Class.
internalContext
- the InternalContext
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.
Unmarshaller
public Unmarshaller(InternalContext internalContext,
Class c,
ClassLoader loader)
Creates a new Unmarshaller with the given Class.
internalContext
- the context 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(InternalContext internalContext,
Object root)
Creates a new Unmarshaller with the given Object.
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.
Unmarshaller
public Unmarshaller(InternalContext internalContext,
Mapping mapping)
throws MappingException
Creates a new Unmarshaller with the given Mapping.
internalContext
- the internal context to usemapping
- The Mapping 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.
mapping
- The Mapping to use.
addNamespaceToPackageMapping
public void addNamespaceToPackageMapping(String nsURI,
String packageName)
Adds a mapping from the given namespace URI to the given
package name.
nsURI
- the namespace URI to map frompackageName
- the package name to map to
createHandler
public UnmarshalHandler createHandler()
Creates and initalizes an UnmarshalHandler
getContentHandler
public static ContentHandler getContentHandler(UnmarshalHandler handler)
throws SAXException
Returns a ContentHandler for the given UnmarshalHandler
getInternalContext
public InternalContext getInternalContext()
To get the internal XML Context that is in use.
getProperty
public String getProperty(String name)
Returns the value of the given Castor XML-specific property.
name
- Qualified name of the CASTOR XML-specific property.
- The current value of the given property.
isValidating
public boolean isValidating()
Indicates whether or not validation should be performed during umarshalling.
- True if validation is performed during umarshalling.
setClass
public void setClass(Class clazz)
Sets the 'expected' Class
instance on the Unmarshaller.
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.
setClassLoader
public void setClassLoader(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.
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.
clear
- the boolean value that when true indicates
collections should be cleared upon first use.
setDebug
public void setDebug(boolean debug)
Custom debugging is replaced with commons-logging
setEntityResolver
public void setEntityResolver(EntityResolver entityResolver)
Sets the EntityResolver to use when resolving system and
public ids with respect to entites and Document Type.
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.
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.
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.
ignoreExtraElements
- a boolean that when true will
allow non-matched elements to simply be ignored.
setInternalContext
public void setInternalContext(InternalContext internalContext)
To set the internal XML Context to be used.
internalContext
- the context to be used
setLogWriter
public void setLogWriter(PrintWriter printWriter)
Logging is replaced with commons-logging.
printWriter
- the PrintWriter to use for logging
setMapping
public void setMapping(Mapping mapping)
throws MappingException
Sets the Mapping to use during unmarshalling. If the Mapping has a ClassLoader it
will be used during unmarshalling.
mapping
- Mapping to use during unmarshalling.
setObject
public void setObject(Object root)
Sets the 'expected' Object
instance on the Unmarshaller, into
which will be unmarshalled.
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.
setObjectFactory
public void setObjectFactory(ObjectFactory objectFactory)
Set an object factory for the unmarshaller. This factory will be used to
construct the objects being unmarshalled.
objectFactory
- Factory used for constructing objects during unmarshalling.
setProperty
public void setProperty(String name,
String value)
Sets a custom value of a given Castor XML-specific property.
name
- Name of the Castor XML propertyvalue
- Custom value to set.
setResolver
public void setResolver(XMLClassDescriptorResolver xmlClassDescriptorResolver)
Sets the XMLClassDescriptorResolver to use during unmarshalling
xmlClassDescriptorResolver
- the XMLClassDescriptorResolver to use
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.
reuse
- the boolean indicating whether or not
to re-use existing objects in the object model.
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 appliction
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.
setValidation
public void setValidation(boolean validate)
Sets the flag for validation.
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".
preserve
- a boolean that when true enables
whitespace preserving by default.
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.
c
- the Class to create a new instance ofsource
- the InputSource to read the XML from
unmarshal
public static Object unmarshal(Class c,
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.
c
- The Class to create a new instance of.node
- The DOM Node to read the XML from.
unmarshal
public static Object unmarshal(Class c,
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.
c
- the Class to create a new instance ofreader
- the Reader to read the XML from
unmarshal
public Object unmarshal(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.
source
- the InputSource to read the XML from
unmarshal
public Object unmarshal(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.
node
- the DOM node to read the XML from
unmarshal
public Object unmarshal(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.
reader
- the Reader to read the XML from
unmarshal
public Object unmarshal(EventProducer eventProducer)
throws MarshalException,
ValidationException
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.
eventProducer
- the EventProducer which produces
the SAX events
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.
eventProducer
- the SAX2EventProducer instance which produces
the SAX 2 events