javax.xml.bind
Class Unmarshaller

java.lang.Object
  |
  +--javax.xml.bind.Unmarshaller

public final class Unmarshaller

extends Object

An unmarshaller governs the process of unmarshalling an XML document into a newly-created content tree, validating the tree as it is constructed. It encapsulates the dispatcher, scanner, and validator objects used during an unmarshalling operation, and it provides the basic unmarshalling methods.

The process of unmarshalling a content tree begins when one of the unmarshal methods of a Dispatcher object is invoked. (An unmarshalling operation may also be initiated by invoking one of the static methods in each marshallable root element class generated by the schema compiler.) These methods examine the given scanner's current state, if necessary, in order to locate the element class to be unmarshalled. They then create a new unmarshaller from the dispatcher, the given scanner, and a new validator. Finally, the new unmarshaller's unmarshal(Class) method is invoked, passing the element class. After this method returns the validator is used to resolve any pending identifier references and check any global constraints.

The unmarshalling process makes the same guarantees as the validation process. If unmarshalling completes successfully then the validation propositions are guaranteed to hold for every member of the resulting content tree. It is also guaranteed that the target of every identifier reference exists.

This class does not have any public or protected constructors; it is intended only for use by the unmarshalling process.

Version:

1.11, 01/05/31

See Also:

Dispatcher, Validator, XMLScanner

Method Summary

XMLScanner	scanner() Returns the scanner to be used during this unmarshalling operation.
MarshallableObject	unmarshal() Unmarshals the next element in this unmarshaller's scanner and validates the resulting instance subtree.
MarshallableObject	unmarshal(Class mobClass) Unmarshals the next element in this unmarshaller's scanner, using the given schema-derived marshallable-object class, and validates the resulting subtree.
Validator	validator() Returns the validator to be used during this unmarshalling operation.

Methods inherited from class java.lang.Object

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

Method Detail

scanner

public XMLScanner scanner()

Returns the scanner to be used during this unmarshalling operation.

Returns:

The scanner

unmarshal

public MarshallableObject unmarshal()
                             throws UnmarshalException

Unmarshals the next element in this unmarshaller's scanner and validates the resulting instance subtree.

This method examines the scanner's current start tag, uses the dispatcher to map it to a marshallable-object class, and then passes the resulting class to the unmarshal(Class) method.

Returns:

A valid, unmarshalled object

Throws:

InvalidContentException - If the scanner is not currently positioned at a start tag, or if some other invalid content is later encountered

UnrecognizedElementNameException - If the element name in the current start tag is not registered in this unmarshaller's dispatcher, or if some other unrecognized element name is later encountered

ScanIOException - If an I/O error occurs

ScanException - If the input document is not well-formed

ValidationException - If the input document violates the constraints expressed in the source schema, or some other validation error is detected

unmarshal

public MarshallableObject unmarshal(Class mobClass)
                             throws UnmarshalException

Unmarshals the next element in this unmarshaller's scanner, using the given schema-derived marshallable-object class, and validates the resulting subtree.

This method applies the dispatcher's class map to the given marshallable class and creates an instance of the resulting class. It then invokes the unmarshal(Unmarshaller) method of the new instance, passing this unmarshaller in order to unmarshal recursively the element and its subelements, if any. Once the new instance has been unmarshalled it is locally validated by invoking its validateThis() method. If the instance implements the IdentifiableElement interface and has an identifier then the validator is updated with that identifier value.

Returns:

A valid, unmarshalled object

Throws:

NonInitialObjectException - If the instantiated class modified the instance in any way during its initialization

InvalidContentException - If the scanner is not currently positioned at a start tag, or if some other invalid content is later encountered

UnrecognizedElementNameException - If the element name in the current start tag is not the element name handled by the given class, or if some other unrecognized element name is later encountered

ScanIOException - If an I/O error occurs

ScanException - If the input document is not well-formed

ValidationException - If the input document violates the constraints expressed in the source schema, or some other validation error is detected

validator

public Validator validator()

Returns the validator to be used during this unmarshalling operation.

Returns:

The validator