Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

de.ispsoft.jaxme.jaxb
Interface Marshaller

All Known Implementing Classes:
MarshallerImpl
Deprecated. Soon to be replaced with javax.xml.bind.Marshaller

public interface Marshaller

The Marshaller class is responsible for governing the process of serializing Java content trees back into XML data. It provides the basic marshalling methods:

(assume that obj is an instance of a schema derived interface from package com.acme.foo)

TODO: finish sample code fragments

Marshalling to a File: 

       OutputStream os = new OutputStream( new FileOutputStream( "nosferatu.xml" ) );
       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Marshaller m = jc.createMarshaller();
       m.marshal( obj, os );

Marshalling to a SAX ContentHandler: 

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Marshaller m = jc.createMarshaller();
       m.marshal( obj, ... );

Marshalling to a DOM Node: 

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Marshaller m = jc.createMarshaller();
       m.marshal( obj, ... );

Marshalling to a java.io.OutputStream: 

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Marshaller m = jc.createMarshaller();
       m.marshal( obj, ... );

Marshalling to a java.io.Writer: 

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Marshaller m = jc.createMarshaller();
       m.marshal( obj, ... );

Marshalling to a javax.xml.transform.Result: 

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Marshaller m = jc.createMarshaller();
       m.marshal( obj, ... );

Marshalling java.lang.Object Objects

Although each of the marshal methods accepts a java.lang.Object as its first parameter, JAXB Providers are not required to be able to marshal any arbitrary java.lang.Object. If the JAXBContext object that was used to create this Marshaller does not have enough information to know how to marshal the object parameter (or any objects reachable from it), then the marshal operation will throw a MarshalException. Eventhough JAXB Providers are not required to be able to marshal arbitrary java.lang.Object objects, some providers may allow it.

Encoding

By default, the Marshaller will use UTF-8 encoding when generating XML data to a java.io.File, java.io.OutputStream, and java.io.Writer. Use the setEncoding API to change the ouput encoding used during these marshal operations.

Validation and Well-Formedness

Client applications are not required to validate the Java content tree prior to calling one of the marshal API's. Furthermore, there is no requirement that the Java content tree be valid with respect to its original schema in order to marshal it back into XML data. Different JAXB Providers will support marshalling invalid Java content trees at varying levels, however all JAXB Providers must be able to marshal a valid content tree back to XML data. A JAXB Provider must throw a MarshalException when it is unable to complete the marshal operation due to invalid content. Some JAXB Providers will fully allow marshalling invalid content, others will fail on the first validation error.

Supported Properties

TODO: Need feedback on properties we should support
jaxb.encoding
output encoding
jaxb.formatted.output
true - human readable indented xml data, false - unformatted xml data

Since:
JAXB1.0
Version:
$Revision: 1.4 $ $Date: 2003/07/04 00:21:00 $
Author:
See Also:
JAXBContext, Validator, Unmarshaller

Method Summary
 java.lang.String getEncoding()
          Deprecated. Get the current encoding used when marshalling to java.io.File, java.io.OutputStream, and java.io.Writer.
 java.lang.Object getProperty(java.lang.String name)
          Deprecated. Get the particular property in the underlying implementation of Marshaller.
 void marshal(java.lang.Object obj, org.xml.sax.ContentHandler handler)
          Deprecated. Marshal the content tree rooted at obj into SAX2 events.
 void marshal(java.lang.Object obj, org.w3c.dom.Node node)
          Deprecated. Marshal the content tree rooted at obj into a DOM tree.
 void marshal(java.lang.Object obj, java.io.OutputStream os)
          Deprecated. Marshal the content tree rooted at obj into an output stream.
 void marshal(java.lang.Object obj, javax.xml.transform.Result result)
          Deprecated. Marshal the content tree rooted at obj into the specified javax.xml.transform.Result.
 void marshal(java.lang.Object obj, java.io.Writer writer)
          Deprecated. Marshal the content tree rooted at obj into a Writer.
 void setEncoding(java.lang.String encoding)
          Deprecated. Set the output encoding used when marshalling to a java.io.File, java.io.OutputStream, and java.io.Writer.
 void setProperty(java.lang.String name, java.lang.Object value)
          Deprecated. Set the particular property in the underlying implementation of Marshaller.
 

Method Detail

marshal

public void marshal(java.lang.Object obj,
                    javax.xml.transform.Result result)
             throws JAXBException
Deprecated. 
Marshal the content tree rooted at obj into the specified javax.xml.transform.Result.

All JAXB Providers must at least support DOMResult, SAXResult, and StreamResult. It can support other derived classes of Result as well.

Parameters:
obj - The content tree to be marshalled.
result - XML will be sent to this Result
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If obj (or any object reachable from obj) can not be marshalled. See Marshalling objects.

marshal

public void marshal(java.lang.Object obj,
                    java.io.OutputStream os)
             throws JAXBException
Deprecated. 
Marshal the content tree rooted at obj into an output stream.

Parameters:
obj - The content tree to be marshalled.
os - XML will be added to this stream.
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If obj (or any object reachable from obj) can not be marshalled. See Marshalling objects.

marshal

public void marshal(java.lang.Object obj,
                    java.io.Writer writer)
             throws JAXBException
Deprecated. 
Marshal the content tree rooted at obj into a Writer.

Parameters:
obj - The content tree to be marshalled.
writer - XML will be sent to this writer.
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If obj (or any object reachable from obj) can not be marshalled. See Marshalling objects.

marshal

public void marshal(java.lang.Object obj,
                    org.xml.sax.ContentHandler handler)
             throws JAXBException
Deprecated. 
Marshal the content tree rooted at obj into SAX2 events.

Parameters:
obj - The content tree to be marshalled.
handler - XML will be sent to this handler as SAX2 events.
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If obj (or any object reachable from obj) can not be marshalled. See Marshalling objects.

marshal

public void marshal(java.lang.Object obj,
                    org.w3c.dom.Node node)
             throws JAXBException
Deprecated. 
Marshal the content tree rooted at obj into a DOM tree.

Parameters:
obj - The content tree to be marshalled.
node - DOM nodes will be added as children of this node. This parameter must be a Node that accepts children (Document, DocumentFragment, or Element)
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If obj (or any object reachable from obj) can not be marshalled. See Marshalling objects.

setEncoding

public void setEncoding(java.lang.String encoding)
                 throws JAXBException,
                        java.io.UnsupportedEncodingException
Deprecated. 
Set the output encoding used when marshalling to a java.io.File, java.io.OutputStream, and java.io.Writer.

JAXB Providers must convert the encoding parameter to its canonical form as defined by the IANA Charset Registry. Some character sets have a historical name that is defined for compatibility with previous versions of the Java platform. These historical names must not be used since they may violate the W3C XML v1.0 Recommendation requirements for valid encoding names. In some cases, the historical name is the same as the canonical name, but not always. The client application should be allowed to specify the encoding using any of the available aliases for that charset (For example, "UTF8" and "UTF-8" should both resolve to the canonical name for this encoding which is "UTF-8". However, the historical name is "UTF8", which should not be used by providers).

Please refer to the javadocs for java.nio.charset.Charset for more details.

Parameters:
encoding - the desired output encoding
Throws:
JAXBException - If any unexpected problems occur while setting the ecoding
java.io.UnsupportedEncodingException - If the supplied encoding is unsupported

getEncoding

public java.lang.String getEncoding()
Deprecated. 
Get the current encoding used when marshalling to java.io.File, java.io.OutputStream, and java.io.Writer.

This method returns the canonical name of the charset specified by the current encoding.

Returns:
The current encoding or "UTF-8" if it has not been specified

setProperty

public void setProperty(java.lang.String name,
                        java.lang.Object value)
                 throws JAXBException,
                        UnrecognizedPropertyException,
                        UnsupportedPropertyException
Deprecated. 
Set the particular property in the underlying implementation of Marshaller. See Supported Properties .

Parameters:
name - the name of the property to be set
value - the value of the property to be set
Throws:
UnrecognizedPropertyException - when the underlying Marshaller does not recognize the property name
UnsupportedPropertyException - when the underlying Marshaller recognizes the property name, but does not support it
JAXBException - if any other errors are encountered while setting the property

getProperty

public java.lang.Object getProperty(java.lang.String name)
                             throws JAXBException,
                                    UnrecognizedPropertyException,
                                    UnsupportedPropertyException
Deprecated. 
Get the particular property in the underlying implementation of Marshaller. See Supported Properties .

Parameters:
name - the name of the property to retrieve
Returns:
the value of the requested property
Throws:
UnrecognizedPropertyException - when the underlying Marshaller does not recognize the property name
UnsupportedPropertyException - when the underlying Marshaller recognizes the property name, but does not support it
JAXBException - if any other errors are encountered while setting the property
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD