Class Marshaller

java.lang.Object
org.exolab.castor.xml.Marshaller
public class Marshaller extends Object
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

  • Field Details

  • Constructor Details

  • Method Details

    • setDocumentHandler

      public void setDocumentHandler(DocumentHandler handler)
      Sets the given SAX DocumentHandler to 'marshal' into.
      Parameters:
      handler - the SAX DocumentHandler to "marshal" to.
      Throws:
      IllegalArgumentException - if the given DocumentHandler is null

    • setWriter

      public void setWriter(Writer out) throws IOException
      Sets the java.io.Writer to be used during marshalling.
      Parameters:
      out - The writer to use for marshalling
      Throws:
      IllegalArgumentException - if out is null
      IOException - If there's a problem accessing the java.io.Writer provided

    • setResult

      public void setResult(Result result) throws IOException
      Sets the Result into which the output xml will be written. Currently this method supports DOMResult, SAXResult and StreamResult.
      Parameters:
      result - the Result instance to set
      Throws:
      IllegalArgumentException - if the result is null or it is not supported
      IOException
      Since:
      1.3.3

    • setNode

      public void setNode(Node node)
      Sets the W3C Node instance to marshal to.
      Parameters:
      node - the DOM Node to marshal into.
      Throws:
      IllegalArgumentException - if node is null

    • setXmlStreamWriter

      public void setXmlStreamWriter(XMLStreamWriter xmlStreamWriter)
      Sets the XMLStreamWriter to use.
      Parameters:
      xmlStreamWriter - the XMLStreamWriter instance to use
      Throws:
      IllegalArgumentException - if the xmlStreamWriter is null
      Since:
      1.3.3

    • setXmlEventWriter

      public void setXmlEventWriter(XMLEventWriter xmlEventWriter)
      Sets the XMLEventWriter to use.
      Parameters:
      xmlEventWriter - the XMLEventWriter instance to use
      Throws:
      IllegalArgumentException - if the xmlEventReader is null
      Since:
      1.3.3

    • setInternalContext

      public void setInternalContext(InternalContext internalContext)
      To set the InternalContext to use, and to initialize Marshaller properties linked to it.
      Parameters:
      internalContext - the InternalContext to use

    • addProcessingInstruction

      public void addProcessingInstruction(String target, String data)
      Adds the given processing instruction data to the set of processing instructions to output during marshalling.
      Parameters:
      target - the processing instruction target
      data - the processing instruction data
      Throws:
      IllegalArgumentException - if target is null or empty string or data is null

    • setDoctype

      public void setDoctype(String publicId, String systemId)
      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 identifier
      systemId - 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

      public void setMapping(Mapping mapping) throws MappingException
      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

      public void setMarshalListener(MarshalListener listener)
      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

      public void setNamespaceMapping(String nsPrefix, String nsURI)
      Sets the mapping for the given Namespace prefix.
      Parameters:
      nsPrefix - the namespace prefix
      nsURI - the namespace that the prefix resolves to
      Throws:
      IllegalArgumentException - if nsURI is null or empty string

    • setRootElement

      public void setRootElement(String rootElement)
      Sets the name of the root element to use.
      Parameters:
      rootElement - The name of the root element to use.

    • getRootElement

      public String 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

      public XMLClassDescriptorResolver getResolver()
      Returns the ClassDescriptorResolver for use during marshalling
      Returns:
      the ClassDescriptorResolver
      See Also:

    • setResolver

      public void setResolver(XMLClassDescriptorResolver cdr)
      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

      public static void marshal(Object object, Writer out) throws MarshalException, ValidationException
      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

      public static void marshal(Object object, Node node) throws MarshalException, ValidationException
      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

      public void marshal(Object object) throws MarshalException, ValidationException
      Marshals the given Object as XML using the DocumentHandler for this Marshaller.
      Parameters:
      object - The Object to marshal.
      Throws:
      MarshalException
      ValidationException

    • setLogWriter

      public void setLogWriter(PrintWriter printWriter)
      Sets the PrintWriter used for logging
      Parameters:
      printWriter - the PrintWriter to use for logging

    • setEncoding

      public void setEncoding(String encoding)
      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

      public void setNoNamespaceSchemaLocation(String schemaLocation)
      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

      public void setSchemaLocation(String schemaLocation)
      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

      public String getProperty(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(String name, 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

    • setContentHandler

      public void setContentHandler(ContentHandler contentHandler)
      To set the SAX ContentHandler which is used as destination at marshalling.
      Parameters:
      contentHandler - the SAX ContentHandler to use as destination at marshalling

    • getJavaNaming

      public JavaNaming getJavaNaming()
      To get the JavaNaming instance to be used.
      Returns:
      the JavaNaming to be used

    • getInternalContext

      public InternalContext getInternalContext()
      To get the AbstractInternalContext to use.
      Returns:
      the AbstractInternalContext to use

    • isCollection

      public static boolean isCollection(Class clazz)
      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

      public CollectionHandler getCollectionHandler(Class clazz)
      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

      public static boolean namespaceEquals(String ns1, String ns2)
      Compares the given namespaces (as strings) for equality. null and empty values are considered equal.
      Parameters:
      ns1 - the namespace to compare to argument ns2
      ns2 - 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 field
      namespace - namespace of the field
      classDesc - the class descriptor to match against
      cdResolver - the class descriptor resolver to use
      Returns:
      An array of InheritanceMatch.
      Throws:
      MarshalException - if the resolver called fails fatally