Package org.exolab.castor.xml
Class Marshaller
java.lang.Object
org.exolab.castor.xml.Marshaller
A Marshaller that serializes Java Object's to XML
Note: This class is not thread safe, and not intended to be,
so please create a new Marshaller for each thread if it
is to be used in a multithreaded environment.
- Version:
- $Revision: 9147 $ $Date: 2006-04-13 06:47:36 -0600 (Thu, 13 Apr 2006) $
- Author:
- Keith Visco
-
Nested Class Summary
Nested Classes -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
The xml:lang attribute, without the "xml:" prefix.static final String
The xsi:nil attribute, without the "xsi:" prefix.static final String
The xml:space attribute name, without the "xml:" prefix.static final String
The value of 'true'.static final String
The xsi:type attribute name, without the "xsi:" prefix.static final String
The xml:lang attribute name.static final String
The xml:space attribute name.static final String
The XSI Namespace URI.static final String
The xsi:nil attribute.static final String
The name of the no namespace schema location attribute.static final String
The name of the Schema location attribute. -
Constructor Summary
ConstructorsConstructorDescriptionCreates a default instance of Marshaller, where the sink needs to be set separately.Marshaller
(Writer out) Creates a newMarshaller
with the given writer.Marshaller
(XMLEventWriter xmlEventWriter) Creates a newMarshaller
with the givenXMLEventWriter
.Marshaller
(XMLStreamWriter xmlStreamWriter) Creates a newMarshaller
with the givenXMLStreamWriter
.Marshaller
(InternalContext internalContext) The oneMarshaller
constructor that is used byXMLContext
which sets anInternalContext
that comes from outside.Marshaller
(Node node) Creates a newMarshaller
for the given DOMNode
.Marshaller
(ContentHandler contentHandler) Creates a newMarshaller
with the given SAXContentHandler
.Marshaller
(DocumentHandler handler) Creates a newMarshaller
with the given SAXDocumentHandler
. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addProcessingInstruction
(String target, String data) Adds the given processing instruction data to the set of processing instructions to output during marshalling.getCollectionHandler
(Class clazz) Returns the CollectionHandler associated with the given collection, or null if no such handler exists.To get theAbstractInternalContext
to use.To get theJavaNaming
instance to be used.boolean
If True the marshaller will use the 'xsi:type' attribute to marshall a field value that extended the defined field type.boolean
Deprecated.getProperty
(String name) Returns the value of the given Castor XML-specific property.Returns the ClassDescriptorResolver for use during marshallingReturns the name of the root element to useboolean
static boolean
isCollection
(Class clazz) Returns true if the given Class is a considered a collection by the marshalling framework.void
Marshals the given Object as XML using the DocumentHandler for this Marshaller.static void
Marshals the given Object as XML using the given writer.static void
Marshals the given Object as XML using the given DOM Node to send events to.static void
marshal
(Object object, ContentHandler handler) Marshals the given Object as XML using the given ContentHandler to send events to.static void
marshal
(Object object, DocumentHandler handler) Marshals the given Object as XML using the given DocumentHandler to send events to.static boolean
namespaceEquals
(String ns1, String ns2) Compares the given namespaces (as strings) for equality.protected org.exolab.castor.xml.MarshalFramework.InheritanceMatch[]
searchInheritance
(String name, String namespace, XMLClassDescriptor classDesc) Search there is a field descriptor which can accept one of the class descriptor which match the given name and namespace.void
setContentHandler
(ContentHandler contentHandler) To set the SAXContentHandler
which is used as destination at marshalling.void
setDoctype
(String publicId, String systemId) Sets the document type definition for the serializer.void
setDocumentHandler
(DocumentHandler handler) Sets the given SAXDocumentHandler
to 'marshal' into.void
setEncoding
(String encoding) Sets the encoding for the serializer.void
setInternalContext
(InternalContext internalContext) To set theInternalContext
to use, and to initializeMarshaller
properties linked to it.void
setLogWriter
(PrintWriter printWriter) Sets the PrintWriter used for loggingvoid
setMapping
(Mapping mapping) Sets the given mapping to be used by the marshalling Framework.void
setMarshalAsDocument
(boolean asDocument) Sets whether or not to marshal as a document which includes the XML declaration, and if necessary the DOCTYPE declaration.void
setMarshalExtendedType
(boolean marshalExtendedType) If True the marshaller will use the 'xsi:type' attribute to marshall a field value that extended the defined field type.void
setMarshalListener
(MarshalListener listener) Sets an optional MarshalListener to recieve pre and post marshal notification for each Object in the tree.void
setNamespaceMapping
(String nsPrefix, String nsURI) Sets the mapping for the given Namespace prefix.void
Sets the W3CNode
instance to marshal to.void
setNoNamespaceSchemaLocation
(String schemaLocation) Sets the value for the xsi:noNamespaceSchemaLocation attribute.void
setNSPrefixAtRoot
(boolean nsPrefixAtRoot) Deprecated.void
setProperty
(String name, String value) Sets a custom value of a given Castor XML-specific property.void
Sets the ClassDescriptorResolver to use during marshalling.void
Sets theResult
into which the output xml will be written.void
setRootElement
(String rootElement) Sets the name of the root element to use.void
setSchemaLocation
(String schemaLocation) Sets the value for the xsi:schemaLocation attribute.void
setSuppressNamespaces
(boolean suppressNamespaces) Sets whether or not namespaces are output.void
setSuppressXSIType
(boolean suppressXSIType) Sets whether or not the xsi:type attribute should appear on the marshalled document.void
setSupressXMLDeclaration
(boolean supressXMLDeclaration) Sets whether or not to marshal as a document which includes the XML declaration, and if necessary the DOCTYPE declaration.void
setUseXSITypeAtRoot
(boolean useXSITypeAtRoot) Sets whether or not to output the xsi:type at the root element.void
setValidation
(boolean validate) Sets whether or not to validate the object model before marshalling.void
Sets the java.io.Writer to be used during marshalling.void
setXmlEventWriter
(XMLEventWriter xmlEventWriter) Sets theXMLEventWriter
to use.void
setXmlStreamWriter
(XMLStreamWriter xmlStreamWriter) Sets theXMLStreamWriter
to use.
-
Field Details
-
XSI_NAMESPACE
The XSI Namespace URI.- See Also:
-
XSI_SCHEMA_LOCATION
The name of the Schema location attribute.- See Also:
-
XSI_NO_NAMESPACE_SCHEMA_LOCATION
The name of the no namespace schema location attribute.- See Also:
-
XML_LANG_ATTR
The xml:lang attribute name.- See Also:
-
LANG_ATTR
The xml:lang attribute, without the "xml:" prefix.- See Also:
-
NIL_ATTR
The xsi:nil attribute, without the "xsi:" prefix.- See Also:
-
XSI_NIL_ATTR
The xsi:nil attribute.- See Also:
-
XML_SPACE_ATTR
The xml:space attribute name.- See Also:
-
SPACE_ATTR
The xml:space attribute name, without the "xml:" prefix.- See Also:
-
TYPE_ATTR
The xsi:type attribute name, without the "xsi:" prefix.- See Also:
-
TRUE_VALUE
The value of 'true'.- See Also:
-
-
Constructor Details
-
Marshaller
Creates a newMarshaller
with the given SAXDocumentHandler
.- Parameters:
handler
- the SAXDocumentHandler
to "marshal" to.- Throws:
IllegalArgumentException
- if the givenDocumentHandler
is null- See Also:
-
Marshaller
Creates a newMarshaller
with the given SAXContentHandler
.- Parameters:
contentHandler
- theContentHandler
to "marshal" to.- Throws:
IllegalArgumentException
- if the gievnContentHandler
is null- See Also:
-
Marshaller
The oneMarshaller
constructor that is used byXMLContext
which sets anInternalContext
that comes from outside. Writer orContentHandler
have to be set in a second step.- Parameters:
internalContext
- theInternalContext
to initialize theMarshaller
instance with
-
Marshaller
public Marshaller()Creates a default instance of Marshaller, where the sink needs to be set separately. -
Marshaller
Creates a newMarshaller
with the given writer.- Parameters:
out
- theWriter
to serialise to.- Throws:
IllegalArgumentException
- if the givenWriter
is nullIOException
- If the givenWriter
instance cannot be opened.- See Also:
-
Marshaller
Creates a newMarshaller
with the givenXMLStreamWriter
.- Parameters:
xmlStreamWriter
- theXMLStreamWriter
- Throws:
IllegalArgumentException
- if the givenXMLStreamWriter
is null- Since:
- 1.3.3
- See Also:
-
Marshaller
Creates a newMarshaller
with the givenXMLEventWriter
.- Parameters:
xmlEventWriter
- theXMLEventWriter
- Throws:
IllegalArgumentException
- if the givenXMLEventWriter
is null- Since:
- 1.3.3
- See Also:
-
Marshaller
Creates a newMarshaller
for the given DOMNode
.- Parameters:
node
- the DOMNode
to marshal into.- Throws:
IllegalArgumentException
- if node is null- See Also:
-
-
Method Details
-
setDocumentHandler
Sets the given SAXDocumentHandler
to 'marshal' into.- Parameters:
handler
- the SAXDocumentHandler
to "marshal" to.- Throws:
IllegalArgumentException
- if the givenDocumentHandler
is null
-
setWriter
Sets the java.io.Writer to be used during marshalling.- Parameters:
out
- The writer to use for marshalling- Throws:
IllegalArgumentException
- if out is nullIOException
- If there's a problem accessing the java.io.Writer provided
-
setResult
Sets theResult
into which the output xml will be written. Currently this method supportsDOMResult
,SAXResult
andStreamResult
.- Parameters:
result
- theResult
instance to set- Throws:
IllegalArgumentException
- if the result is null or it is not supportedIOException
- Since:
- 1.3.3
-
setNode
Sets the W3CNode
instance to marshal to.- Parameters:
node
- the DOMNode
to marshal into.- Throws:
IllegalArgumentException
- if node is null
-
setXmlStreamWriter
Sets theXMLStreamWriter
to use.- Parameters:
xmlStreamWriter
- theXMLStreamWriter
instance to use- Throws:
IllegalArgumentException
- if the xmlStreamWriter is null- Since:
- 1.3.3
-
setXmlEventWriter
Sets theXMLEventWriter
to use.- Parameters:
xmlEventWriter
- theXMLEventWriter
instance to use- Throws:
IllegalArgumentException
- if the xmlEventReader is null- Since:
- 1.3.3
-
setInternalContext
To set theInternalContext
to use, and to initializeMarshaller
properties linked to it.- Parameters:
internalContext
- theInternalContext
to use
-
addProcessingInstruction
Adds the given processing instruction data to the set of processing instructions to output during marshalling.- Parameters:
target
- the processing instruction targetdata
- the processing instruction data- Throws:
IllegalArgumentException
- if target is null or empty string or data is null
-
setDoctype
Sets the document type definition for the serializer. Note that this method cannot be called if you've passed in your own DocumentHandler.- Parameters:
publicId
- the public identifiersystemId
- the system identifier
-
setSupressXMLDeclaration
public void setSupressXMLDeclaration(boolean supressXMLDeclaration) Sets whether or not to marshal as a document which includes the XML declaration, and if necessary the DOCTYPE declaration. By default the Marshaller will marshal as a well formed XML document including the XML Declaration. If the given boolean is true, the Marshaller will marshal as a well formed XML fragment (no XML declaration or DOCTYPE). This method is basically the same as calling #setMarshalAsDocument(false);- Parameters:
supressXMLDeclaration
- a boolean that when true includes that generated XML should not contain the XML declaration.- See Also:
-
setMarshalAsDocument
public void setMarshalAsDocument(boolean asDocument) Sets whether or not to marshal as a document which includes the XML declaration, and if necessary the DOCTYPE declaration. By default the Marshaller will marshal as a well formed XML document including the XML Declaration. If the given boolean is false, the Marshaller will marshal as a well formed XML fragment (no XML declaration or DOCTYPE). This method is basically the same as calling #setSupressXMLDeclaration(true);- Parameters:
asDocument
- a boolean, when true, indicating to marshal as a complete XML document.- See Also:
-
setMapping
Sets the given mapping to be used by the marshalling Framework. If a resolver exists this mapping will be added to the existing ClassDescriptorResolver. Otherwise a new ClassDescriptorResolver will be created.- Parameters:
mapping
- Mapping to using during marshalling.- Throws:
MappingException
-
setMarshalListener
Sets an optional MarshalListener to recieve pre and post marshal notification for each Object in the tree. MarshalListener is only for complex objects that map into elements, simpleTypes and types that map into attributes do not cause any pre and post event notifications. 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 MarshalListener to set.
-
setNamespaceMapping
Sets the mapping for the given Namespace prefix.- Parameters:
nsPrefix
- the namespace prefixnsURI
- the namespace that the prefix resolves to- Throws:
IllegalArgumentException
- if nsURI is null or empty string
-
setRootElement
Sets the name of the root element to use.- Parameters:
rootElement
- The name of the root element to use.
-
getRootElement
Returns the name of the root element to use- Returns:
- Returns the name of the root element to use
-
setNSPrefixAtRoot
public void setNSPrefixAtRoot(boolean nsPrefixAtRoot) Deprecated.Set to True to declare the given namespace mappings at the root node. Default is False.- Parameters:
nsPrefixAtRoot
-
-
getNSPrefixAtRoot
public boolean getNSPrefixAtRoot()Deprecated.Returns True if the given namespace mappings will be declared at the root node.- Returns:
- Returns True if the given namespace mappings will be declared at the root node.
-
getResolver
Returns the ClassDescriptorResolver for use during marshalling- Returns:
- the ClassDescriptorResolver
- See Also:
-
setResolver
Sets the ClassDescriptorResolver to use during marshalling.
Note: This method will nullify any Mapping currently being used by this Marshaller- Parameters:
cdr
- the ClassDescriptorResolver to use- See Also:
-
setValidation
public void setValidation(boolean validate) Sets whether or not to validate the object model before marshalling. By default validation is enabled. This method is really for debugging. I do not recommend turning off validation, since you could marshal a document, which you can then not unmarshal. If you know the object model is guaranteed to be valid, disabling validation will improve performace.- Parameters:
validate
- the boolean indicating whether or not to validate the object model before marshalling.
-
getValidation
public boolean getValidation() -
setMarshalExtendedType
public void setMarshalExtendedType(boolean marshalExtendedType) If True the marshaller will use the 'xsi:type' attribute to marshall a field value that extended the defined field type. Default is True. -
getMarshalExtendedType
public boolean getMarshalExtendedType()If True the marshaller will use the 'xsi:type' attribute to marshall a field value that extended the defined field type. Default is True.- Returns:
- If True the marshaller will use the 'xsi:type' attribute to marshall a field value that extended the defined field type. Default is True.
-
marshal
Marshals the given Object as XML using the given writer.- Parameters:
object
- The Object to marshal.out
- The writer to marshal to.- Throws:
MarshalException
ValidationException
-
marshal
public static void marshal(Object object, DocumentHandler handler) throws MarshalException, ValidationException Marshals the given Object as XML using the given DocumentHandler to send events to.- Parameters:
object
- The Object to marshal.handler
- The DocumentHandler to marshal to.- Throws:
MarshalException
ValidationException
-
marshal
public static void marshal(Object object, ContentHandler handler) throws MarshalException, ValidationException Marshals the given Object as XML using the given ContentHandler to send events to.- Parameters:
object
- The Object to marshal.handler
- The ContentHandler to marshal to.- Throws:
MarshalException
ValidationException
-
marshal
Marshals the given Object as XML using the given DOM Node to send events to.- Parameters:
object
- The Object to marshal.node
- The DOM Node to marshal to.- Throws:
MarshalException
ValidationException
-
marshal
Marshals the given Object as XML using the DocumentHandler for this Marshaller.- Parameters:
object
- The Object to marshal.- Throws:
MarshalException
ValidationException
-
setLogWriter
Sets the PrintWriter used for logging- Parameters:
printWriter
- the PrintWriter to use for logging
-
setEncoding
Sets the encoding for the serializer. Note that this method cannot be called if you've passed in your own DocumentHandler.- Parameters:
encoding
- the encoding to set
-
setNoNamespaceSchemaLocation
Sets the value for the xsi:noNamespaceSchemaLocation attribute. When set, this attribute will appear on the root element of the marshalled document.- Parameters:
schemaLocation
- the URI location of the schema to which the marshalled document is an instance of.
-
setSchemaLocation
Sets the value for the xsi:schemaLocation attribute. When set, this attribute will appear on the root element of the marshalled document.- Parameters:
schemaLocation
- the URI location of the schema to which the marshalled document is an instance of.
-
setSuppressNamespaces
public void setSuppressNamespaces(boolean suppressNamespaces) Sets whether or not namespaces are output. By default the Marshaller will output namespace declarations and prefix elements and attributes with their respective namespace prefix. This method can be used to prevent the usage of namespaces.- Parameters:
suppressNamespaces
- a boolean that when true will prevent namespaces from being output.
-
setSuppressXSIType
public void setSuppressXSIType(boolean suppressXSIType) Sets whether or not the xsi:type attribute should appear on the marshalled document.- Parameters:
suppressXSIType
- a boolean that when true will prevent xsi:type attribute from being used in the marshalling process.
-
setUseXSITypeAtRoot
public void setUseXSITypeAtRoot(boolean useXSITypeAtRoot) Sets whether or not to output the xsi:type at the root element. This is usually needed when the root element type cannot be determined by the element name alone. By default xsi:type will not be output on the root element.- Parameters:
useXSITypeAtRoot
- a boolean that when true indicates that the xsi:type should be output on the root element.
-
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
-
setContentHandler
To set the SAXContentHandler
which is used as destination at marshalling.- Parameters:
contentHandler
- the SAXContentHandler
to use as destination at marshalling
-
getJavaNaming
To get theJavaNaming
instance to be used.- Returns:
- the JavaNaming to be used
-
getInternalContext
To get theAbstractInternalContext
to use.- Returns:
- the
AbstractInternalContext
to use
-
isCollection
Returns true if the given Class is a considered a collection by the marshalling framework.- Parameters:
clazz
- the Class to check- Returns:
- true if the given Class is considered a collection. TODO: joachim: this code exists somewhere else too!!
-
getCollectionHandler
Returns the CollectionHandler associated with the given collection, or null if no such handler exists.- Parameters:
clazz
- the Class to check- Returns:
- the CollectionHandler for the associated type.
-
namespaceEquals
Compares the given namespaces (as strings) for equality. null and empty values are considered equal.- Parameters:
ns1
- the namespace to compare to argument ns2ns2
- the namespace to compare to argument ns1- Returns:
- true if the namespaces are considert equal TODO: joachim put it into XMLNaming!
-
searchInheritance
protected org.exolab.castor.xml.MarshalFramework.InheritanceMatch[] searchInheritance(String name, String namespace, XMLClassDescriptor classDesc) throws MarshalException Search there is a field descriptor which can accept one of the class descriptor which match the given name and namespace.- Parameters:
name
- XML name of the fieldnamespace
- namespace of the fieldclassDesc
- the class descriptor to match againstcdResolver
- the class descriptor resolver to use- Returns:
- An array of InheritanceMatch.
- Throws:
MarshalException
- if the resolver called fails fatally
-