javax.xml.bind
Class MarshallableRootElement

java.lang.Object
  |
  +--javax.xml.bind.ValidatableObject
        |
        +--javax.xml.bind.MarshallableObject
              |
              +--javax.xml.bind.MarshallableRootElement

All Implemented Interfaces:

Element, RootElement

public abstract class MarshallableRootElement

extends MarshallableObject

implements RootElement

Abstract base class for root element objects that can be marshalled and unmarshalled. The marshalling methods in this class, in conjunction with the unmarshalling methods defined in the Dispatcher class and in every schema-derived marshallable root element class, are the primary entry points for the marshalling and unmarshalling processes.

Both marshalling and unmarshalling are optional operations because in some applications only one or the other operation is of interest. If a particular operation is not supported then an UnsupportedOperationException is thrown when the corresponding method is invoked.

Static methods in marshallable root element classes

This class only defines marshalling methods. The unmarshalling methods associated with a specific root class, as well as the method for creating a default dispatcher, must be static methods. The Java programming language does not support abstract static methods, however, so the schema compiler generates four static methods in each marshallable root element class. For a root element class Foo the primary unmarshalling method has the signature

 public static Foo unmarshal(javax.xml.marshal.XMLScanner xs,
                                    Dispatcher d)
     throws UnmarshalException;

and behaves exactly the same as the expression

 (Foo)(d.unmarshal(xs, Foo.class))

The other two static unmarshalling methods are simply convenience methods that use a dispatcher obtained from the static newDispatcher method and, in the last case, also create a new scanner from the given input stream:

 public static Foo unmarshal(javax.xml.marshal.XMLScanner xs)
     throws UnmarshalException;
 public static Foo unmarshal(java.io.InputStream in)
     throws UnmarshalException;

Finally, the static method for creating a new default dispatcher has the signature

 public static Dispatcher newDispatcher();

This method creates a new dispatcher and initializes it to map each element name defined in the source schema from which the root element class was derived to the corresponding marshallable root element class. After being initialized the element-name map is frozen. User subclasses of schema-derived marshallable-object classes may then be registered if desired.

Version:

1.8, 01/05/31

Constructor Summary

protected

MarshallableRootElement() Initializes a new marshallable root element object.

Method Summary

void	marshal(OutputStream out) Marshals the content tree rooted at this object to the given output stream (optional operation).
void	marshal(XMLWriter xw) Marshals the content tree rooted at this object using the given XML writer (optional operation).

Methods inherited from class javax.xml.bind.MarshallableObject

marshal, unmarshal

Methods inherited from class javax.xml.bind.ValidatableObject

invalidate, validate, validate, validateThis

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface javax.xml.bind.RootElement

validate

Methods inherited from interface javax.xml.bind.Element

validateThis

Constructor Detail

MarshallableRootElement

protected MarshallableRootElement()

Initializes a new marshallable root element object.

Method Detail

marshal

public final void marshal(OutputStream out)
                   throws IOException

Marshals the content tree rooted at this object to the given output stream (optional operation). This convenience method behaves in exactly the same way as the expression marshal(new XMLWriter(out)).

Parameters:

xw - The XML writer to be used

Throws:

IOException - If an I/O error occurs

ValidationRequiredException - If the content tree requires validation

UnsupportedOperationException - If some object in the content tree does not support marshalling

marshal

public final void marshal(XMLWriter xw)
                   throws IOException

Marshals the content tree rooted at this object using the given XML writer (optional operation).

This method creates a new Marshaller based upon the given writer, invokes its marshal(MarshallableObject) method, passing this object, and then flushes the writer.

Parameters:

xw - The XML writer to be used

Throws:

IOException - If an I/O error occurs

ValidationRequiredException - If the content tree requires validation

UnsupportedOperationException - If some object in the content tree does not support marshalling