javax.xml.bind
Class Dispatcher

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

public final class Dispatcher

extends Object

A dispatcher is used to map element names to class names, and to initiate the unmarshalling process.

A dispatcher contains two maps, an element-name map and a class map. The element-name map maps element names to marshallable-object classes; the class map maps marshallable-object classes to user-defined subclasses.

New mappings may be registered in each map. Each map may also be frozen in order to guard against unwanted concurrent modification. The unmarshalling process always freezes both maps of the dispatcher that it uses.

Version:

1.10, 01/05/31

See Also:

MarshallableObject, Unmarshaller, Validator, XMLScanner

Constructor Summary

Dispatcher()
Constructs a new, empty dispatcher.

Method Summary

void	freezeClassMap() Freezes this dispatcher's class map.
void	freezeElementNameMap() Freezes this dispatcher's element-name map.
Class	lookup(Class mobClass) Applies the class map to the given marshallable-object class.
Class	lookup(String elementName) Determines the class to be used when unmarshalling the given element name.
void	register(Class mobClass, Class userClass) Registers the given user class so that it will be used in place of the given schema-derived marshallable-object class during unmarshalling.
void	register(String elementName, Class elementClass) Registers the given element name so that it will be unmarshalled into an instance of the given element class.
RootElement	unmarshal(InputStream in) Unmarshals and validates a content tree from the given input stream.
RootElement	unmarshal(XMLScanner xs) Unmarshals and validates a content tree using the given scanner.
RootElement	unmarshal(XMLScanner xs, Class rootClass) Unmarshals and validates a content tree using the given scanner and root element class.

Methods inherited from class java.lang.Object

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

Constructor Detail

Dispatcher

public Dispatcher()

Constructs a new, empty dispatcher.

Method Detail

freezeClassMap

public void freezeClassMap()

Freezes this dispatcher's class map. Further attempts to register user subclasses of schema-derived marshallable-object classes will result in an IllegalStateException being thrown.

freezeElementNameMap

public void freezeElementNameMap()

Freezes this dispatcher's element-name map. Further attempts to register element names will result in an IllegalStateException being thrown.

lookup

public Class lookup(Class mobClass)

Applies the class map to the given marshallable-object class.

Returns:

The user class to which the given class is mapped, or the given class if it has not been mapped

lookup

public Class lookup(String elementName)
             throws UnrecognizedElementNameException

Determines the class to be used when unmarshalling the given element name. The class to be used is computed by applying the element-name map to the given name and then applying the class map to the resulting class.

Parameters:

elementName - The non-colonized element name being looked up; must not be the empty string

Returns:

The class to which the given element name is mapped

Throws:

UnrecognizedElementNameException - If no class for the given element name can be found

register

public void register(Class mobClass,
                     Class userClass)

Registers the given user class so that it will be used in place of the given schema-derived marshallable-object class during unmarshalling. Requires that this dispatcher's class map is not frozen.

This method is provided primarily so that user subclasses of schema-derived element classes may be defined and used.

Parameters:

mobClass - A schema-derived subclass of MarshallableObject for which no class mapping has yet been defined

userClass - The user-defined subclass of mobClass, for which no class mapping has been defined, to be used in place of that class during unmarshalling

Throws:

IllegalStateException - If this dispatcher's class map is frozen

register

public void register(String elementName,
                     Class elementClass)

Registers the given element name so that it will be unmarshalled into an instance of the given element class. Requires that this dispatcher's element-name map is not frozen.

Parameters:

elementName - The non-colonized element name being registered; must not be the empty string

elementClass - The class to be used to unmarshal elements with the given name; must extend MarshallableObject and implement the Element interface

Throws:

ElementNameRegisteredException - If the element name has already been registered

IllegalStateException - If this dispatcher's element-name map is frozen

unmarshal

public RootElement unmarshal(InputStream in)
                      throws UnmarshalException

Unmarshals and validates a content tree from the given input stream. An invocation of this convenience method behaves in the same manner as the expression

 unmarshal(XMLScanner.open(java.io.InputStream)(in))

Parameters:

in - The input stream from which data will be unmarshalled

Returns:

The root element object of a valid, unmarshalled content tree

Throws:

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 RootElement unmarshal(XMLScanner xs)
                      throws UnmarshalException

Unmarshals and validates a content tree using the given scanner. After freezing both the element-name and class maps, this method examines the scanner's current start tag, maps it to a marshallable-object class via the lookup method, and then invokes the unmarshal(XMLScanner, Class) method, passing the scanner and the class.

Parameters:

xs - The scanner from which data will be unmarshalled

Returns:

The root element object of a valid, unmarshalled content tree

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, or if some other unrecognized element name is encountered

InvalidAttributeException - If an attribute that is not permitted for the current element is scanned

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 RootElement unmarshal(XMLScanner xs,
                             Class rootClass)
                      throws UnmarshalException

Unmarshals and validates a content tree using the given scanner and root element class. After freezing both the element-name and class maps, this method instantiates a new Unmarshaller with this dispatcher and the given scanner. It then uses the unmarshaller to unmarshal an instance of the given class and validate the resulting content tree. This method closes the given scanner when it terminates, whether normally or by throwing an exception.

Parameters:

xs - The scanner from which data will be unmarshalled

rootClass - The root marshallable-object class to be instantiated

Returns:

The root element object of a valid, unmarshalled content tree

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 the element name handled by the given class, or if some other unrecognized element name is later encountered

InvalidAttributeException - If an attribute that is not permitted for the current element is scanned

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