ContactCenters
V. 0.9.9.

umontreal.iro.lecuyer.xmlbind
Class JAXBParamsConverter<T>

java.lang.Object
  extended by umontreal.iro.lecuyer.xmlbind.JAXBParamsConverter<T>
Type Parameters:
T - the type of objects processed by the converter.
Direct Known Subclasses:
CallCenterParamsConverter, ContactCenterEvalResultsConverter, SimParamsConverter

public abstract class JAXBParamsConverter<T>
extends Object

Convenience base class to marshal and unmarshal objects of a specific class using JAXB. When using JAXB directly, one must create a context, use that context to get an unmarshaller or a marshaller, convert the unmarshalled JAXB element into a value object, or wrap a value object into a JAXB element for marshalling. This class can help in performing these tasks. It also manages the association of a schema to unmarshallers, and marshallers in order to perform validation. It also implements a mechanism to replace JAXB-generated namespace prefixes by user-defined prefixes while marshalling. This does not affect the validity of marshalled XML, but it can increase the readability of the output files.

The methods unmarshal(File), and File) can be used to marshal and unmarshal objects. Alternatively, simple console applications may use unmarshalOrExit(File), and File) which prints a detailed message and exits in case of an error while the regular methods throw exceptions.

This class must be extended with a specific type of parameter object to be used. This type can be any class derived by the JAXB-provided xjc compiler from a XML Schema. It must be passed as a type parameter when creating this class. More specifically, any concrete subclass must implement the getContext() method used to create the JAXB context as well as the getSchema() method to get the schema object used for validation.

For example, suppose that we have a Schema describing parameters of call centers, with a root element of type CallCenterParams. The JAXB compiler produces a class named CallCenterParams. The user-defined converter class then extends the base class JAXBParamsConverter<CallCenterParams>, and provides an implementation for the two mandatory methods.


Constructor Summary
JAXBParamsConverter(Class<T> objClass)
          Constructs a new converter manipulating objects of class objClass.
 
Method Summary
abstract  JAXBContext getContext()
          Constructs and returns the JAXB context used to read parameters.
 ValidationEventHandler getEventHandler()
          Returns the validation event handler associated with marshallers and unmarshallers used by this converter.
 Object getJAXBObject(Object value)
          Constructs and returns a JAXB element with value as a value.
abstract  Map<String,String> getNamespacePrefixes()
          Returns a map associating prefixes with namespace URI.
abstract  Schema getSchema()
          Constructs and returns a schema for the document type represented by a concrete subclass.
 T getValue(Object jaxbElement)
          Converts the JAXB element returned by an unmarshaller into an instance of class T.
static boolean hasErrors(ValidationEvent... evs)
          Similar to hasWarnings(ValidationEvent[]) for errors instead of warnings.
static boolean hasFatalErrors(ValidationEvent... evs)
          Similar to hasWarnings(ValidationEvent[]) for fatal errors instead of warnings.
static boolean hasWarnings(ValidationEvent... evs)
          Determines if the given list of validation events contains at least one event representing a warning.
 void initMarshaller(Marshaller m)
          Initializes the marshaller before it is used by this object.
 void initUnmarshaller(Unmarshaller um)
          Initializes the unmarshaller before it is used by this object.
 boolean isValidating()
          Determines if this converter is validating unmarshalled and marshalled instances.
static String locatorToString(ValidationEventLocator locator)
          Formats the given locator locator into a string.
 void marshal(T object, ContentHandler handler1)
          Marshals the given object by generating SAX events and sending them to the given content handler.
 void marshal(T object, File res)
          Marshals the given value object into the given output file.
 void marshal(T object, Node node)
          Similar to File), for a DOM node.
 void marshal(T object, Result res)
          Marshals the given object object to the target set by res.
 void marshalAndGZip(T object, File res)
          Marshals the given object to the given file, and gzips the marshalled contents.
 void marshalAndGZipOrExit(T object, File file)
          Similar to File), except that the method File) is called instead of File).
 void marshalOrExit(T object, File file)
          Marshals the object object to the file file, using the File) method, but if an error occurs, this method prints messages on the standard error output, and exits the VM using System.exit(int).
 Schema readSchema()
          Tries to use getSchema() to obtain the schema.
 void setEventHandler(ValidationEventHandler handler)
          Sets the validation event handler to handler.
 void setValidating(boolean validating)
          Sets the status of the validating indicator to validating.
 T unmarshal(File file)
          Unmarshals the given input file to an object.
 T unmarshal(Node node)
          Unmarshals the given node into a JAXB object, and returns the constructed object.
 T unmarshal(Source source)
          Unmarshals the given source into an object, and returns the constructed object.
 T unmarshal(URL url)
          Unmarshals the given URL into an object, and returns the constructed object.
 T unmarshalGZipped(File file)
          Reads the given input file as a GZipped file, using GZIPInputStream, and unmarshals the uncompressed XML data.
 T unmarshalGZipped(URL url)
          Similar to unmarshalGZipped(File), for a URL instead of a file.
 T unmarshalOrExit(File file)
          Unmarshals the given file using unmarshalGZipped(File), but if an error occurs, messages are printed on the standard error output, and the method exits the VM using System.exit(int).
static String validationEventsToString(ValidationEvent... evs)
          Formats and returns a string containing a description for each validation event in the given list.
static String validationEventToString(ValidationEvent ev)
          Constructs and returns a string representing the validation event ev.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JAXBParamsConverter

public JAXBParamsConverter(Class<T> objClass)
Constructs a new converter manipulating objects of class objClass.

Parameters:
objClass - the class of objects.
Method Detail

getContext

public abstract JAXBContext getContext()
                                throws JAXBException
Constructs and returns the JAXB context used to read parameters. This method should create and return a static instance of the JAXB context since the creation of the context is costly.

Any concrete subclass should define a static field of type JAXBContext. If the field is non-null, the method returns its value. Otherwise, it initializes the field using JAXBContext.newInstance(String), and returns the resulting context. The arguments given to JAXB depends on the JAXB-derived class associated with the concrete subclass.

Returns:
the JAXB context to be used.
Throws:
JAXBException - if an error occurs while creating the JAXB context.

getSchema

public abstract Schema getSchema()
                          throws SAXException
Constructs and returns a schema for the document type represented by a concrete subclass. If no schema is used, this method should return null. If an error occurs when reading or parsing the schema, this method should throws a SAX exception.

It is recommended to use SchemaFactory to create the Schema object, and to store it in a static variable for future use, because loading and parsing the schema might be costly. If the schema is stored at the same location as class files, Class.getResourceAsStream(String) can be used to obtain a stream for the schema.

Returns:
the schema object, or null.
Throws:
SAXException - if an error occurred during reading or parsing.

getNamespacePrefixes

public abstract Map<String,String> getNamespacePrefixes()
Returns a map associating prefixes with namespace URI. Each key of the returned map corresponds to a prefix while each value denotes a URI. This map is used while marshalling in order to assign meaningful prefixes to namespace URI rather than the default prefixes. An empty map can be used to disable namespace prefix mapping.

When using namespaces, each XML element and attribute can be qualified with a namespace URI which is referred to, in the XML document, using a prefix. These prefixes, which are not unique in contrast with URIs, can be chosen arbitrarily, but they should be human-readable for clearer documents. However, by default, JAXB generates its own prefix each time it finds a new namespace URI during marshalling; there is no standard way to impose prefixes. This map can be used to bind user-defined prefixes to the URIs used by the XML document. When this method returns a non-empty map, the marshalling mechanism of this class uses the RemappingContentHandler to perform the namespace prefix mapping in a way independent from the JAXB implementation.

Returns:
the map associating namsepace prefixes to URIs.

readSchema

public Schema readSchema()
Tries to use getSchema() to obtain the schema. If this method throws a SAX exception, the exception is logged, validation is disabled, and this method returns null. Otherwise, the schema object is returned. This can be used to work around bugs in some Java implementations preventing valid schemas to be read; parsing will then continue, without validation.

Returns:
the schema object, or null.

initUnmarshaller

public void initUnmarshaller(Unmarshaller um)
                      throws JAXBException
Initializes the unmarshaller before it is used by this object. By default, this method installs the event handler returned by getEventHandler(). It can be overridden to perform custom initialization such as setting properties.

Parameters:
um - the unmarshaller being initialized.
Throws:
JAXBException

initMarshaller

public void initMarshaller(Marshaller m)
                    throws JAXBException
Initializes the marshaller before it is used by this object. By default, this method associates the event handler returned by getEventHandler() to the marshaller, and activates the Marshaller.JAXB_FORMATTED_OUTPUT property. It can be overridden to perform custom initialization such as setting properties.

Parameters:
m - the marshaller being initialized.
Throws:
JAXBException

isValidating

public boolean isValidating()
Determines if this converter is validating unmarshalled and marshalled instances. The default value is true, which activates validation. However, validation is disabled if no schema is specified, or if the schema cannot be initialized.

Returns:
the status of the validating indicator.

setValidating

public void setValidating(boolean validating)
Sets the status of the validating indicator to validating.

Parameters:
validating - the new value of the indicator.

getEventHandler

public ValidationEventHandler getEventHandler()
Returns the validation event handler associated with marshallers and unmarshallers used by this converter. This returns null if no handler was set (the default).

Returns:
the validation event handler, or null.

setEventHandler

public void setEventHandler(ValidationEventHandler handler)
Sets the validation event handler to handler.

Parameters:
handler - the new validation event handler.

getValue

public T getValue(Object jaxbElement)
           throws JAXBException
Converts the JAXB element returned by an unmarshaller into an instance of class T. This uses the JAXBIntrospector.getValue(Object) to obtain the object, and casts it to an instance of class T.

Parameters:
jaxbElement - the JAXB element.
Returns:
the cast object.
Throws:
JAXBException - if an error occurs during conversion.

getJAXBObject

public Object getJAXBObject(Object value)
                     throws JAXBException
Constructs and returns a JAXB element with value as a value. The returned object can be given to a JAXB Marshaller in order to be serialized to XML.

This method first uses JAXBIntrospector.isElement(Object) to test if the given value is an element, and returns the value if the test succeeds. Otherwise, this method looks for an ObjectFactory class in the package of the class of the given value. If such a factory is found, the method searches a factory method in this factory taking an object corresponding to the type of the given value, and calls this method to get a JAXB element encapsulating the value.

Parameters:
value - the value to encapsulate.
Returns:
the JAXB element corresponding to the value.
Throws:
JAXBException - if an error occurs during the process.

unmarshal

public T unmarshal(File file)
            throws JAXBException
Unmarshals the given input file to an object.

This method first calls getContext() to obtain a JAXB context. It then uses the obtained JAXB context to create an unmarshaller, sets its schema to the value returned by readSchema(), and initializes it by calling initUnmarshaller(Unmarshaller). It then uses the unmarshaller to process the given file, and calls getValue(Object) to obtain the value of the resulting JAXB element.

Parameters:
file - the input file.
Returns:
the unmarshalled object.
Throws:
JAXBException - if an error occurs during unmarshalling.

unmarshal

public T unmarshal(URL url)
            throws JAXBException
Unmarshals the given URL into an object, and returns the constructed object. This is simular to unmarshal(File), for a URL.

Parameters:
url - the URL of the input.
Returns:
the output object.
Throws:
JAXBException - if an error occurs during unmarshalling.

unmarshalGZipped

public T unmarshalGZipped(File file)
                   throws JAXBException
Reads the given input file as a GZipped file, using GZIPInputStream, and unmarshals the uncompressed XML data. If the given file is not in GZIP format, this method calls unmarshal(File) to unmarshal a plain text file.

Parameters:
file - the file to be read.
Returns:
the unmarshalled object.
Throws:
JAXBException - if an error occurs during file reading.

unmarshalGZipped

public T unmarshalGZipped(URL url)
                   throws JAXBException
Similar to unmarshalGZipped(File), for a URL instead of a file.

Parameters:
url - the URL pointing to the XML data.
Returns:
the unmarshalled object.
Throws:
JAXBException - if an error occurs during the unmarshalling process.

unmarshal

public T unmarshal(Node node)
            throws JAXBException
Unmarshals the given node into a JAXB object, and returns the constructed object. This is similar to unmarshal(File), for a DOM node.

Parameters:
node - the DOM node to be unmarshalled.
Returns:
the resulting object.
Throws:
JAXBException - if an error occurs during unmarshalling.

unmarshal

public T unmarshal(Source source)
            throws JAXBException
Unmarshals the given source into an object, and returns the constructed object. This is similar to unmarshal(File), for a source.

Parameters:
source - the source to be unmarshalled.
Returns:
the constructed object.
Throws:
JAXBException - if an error occurs during unmarshalling.

unmarshalOrExit

public T unmarshalOrExit(File file)
Unmarshals the given file using unmarshalGZipped(File), but if an error occurs, messages are printed on the standard error output, and the method exits the VM using System.exit(int). This method is intended to be used in main methods of command-line programs.

Parameters:
file - the input file.
Returns:
the parameter object.

marshal

public void marshal(T object,
                    ContentHandler handler1)
             throws JAXBException
Marshals the given object by generating SAX events and sending them to the given content handler.

This method calls getJAXBObject(Object) on the given object to convert it into a JAXB object. It then creates a marshaller using the context returned by getContext(), sets its schema to the value returned by readSchema(), initializes it with initMarshaller(Marshaller), and gives it the JAXB object obtained from the given value. If getNamespacePrefixes() returns a non-empty map, the supplied handler is wrapped around a RemappingContentHandler in order to take namespace prefixes into account, and wrapped handler is passed to the marshaller. Otherwise, the content handler is passed directly to the marshaller.

Parameters:
object - the object to marshal.
handler1 - the content handler.
Throws:
JAXBException - if an exception occurs during marshalling.

marshal

public void marshal(T object,
                    Result res)
             throws JAXBException
Marshals the given object object to the target set by res.

This method calls getJAXBObject(Object) to turn the given object into a JAXB object. If getNamespacePrefixes() returns an empty map, this method creates a marshaller the same way as ContentHandler), and uses it directly to marshal the JAXB object. Otherwise, it creates a TransformerHandler, and gives it to ContentHandler).

Parameters:
object - the object to marshal.
res - the result object.
Throws:
JAXBException - if an error occurs during marshalling.

marshal

public void marshal(T object,
                    File res)
             throws JAXBException
Marshals the given value object into the given output file. This creates a new StreamResult with the given file object, and calls Result) to performing marshalling.

Parameters:
object - the value to marshal.
res - the output file.
Throws:
JAXBException - if an error occurs during marshalling.

marshalAndGZip

public void marshalAndGZip(T object,
                           File res)
                    throws JAXBException
Marshals the given object to the given file, and gzips the marshalled contents.

Parameters:
object - the object to be marshalled.
res - the target file.
Throws:
JAXBException - if an error occurs during marshalling.

marshal

public void marshal(T object,
                    Node node)
             throws JAXBException
Similar to File), for a DOM node.

Parameters:
object - the value object to marshal.
node - the output node.
Throws:
JAXBException - if an error occurs during marshalling.

marshalOrExit

public void marshalOrExit(T object,
                          File file)
Marshals the object object to the file file, using the File) method, but if an error occurs, this method prints messages on the standard error output, and exits the VM using System.exit(int). This method is intended to be used in main methods of command-line programs.

Parameters:
object - the object to marshal.
file - the output file.

marshalAndGZipOrExit

public void marshalAndGZipOrExit(T object,
                                 File file)
Similar to File), except that the method File) is called instead of File).

Parameters:
object - the object to be marshalled.
file - the output file.

hasWarnings

public static boolean hasWarnings(ValidationEvent... evs)
Determines if the given list of validation events contains at least one event representing a warning. This method tests each event of the given list for their severity returned by ValidationEvent.getSeverity(), and returns true as soon as one event with severity ValidationEvent.WARNING is found. This returns false if the list is empty, or if it contains only events representing errors or fatal errors.

Parameters:
evs - the tested list.
Returns:
true if and only if the given list contains at least one warning event.

hasErrors

public static boolean hasErrors(ValidationEvent... evs)
Similar to hasWarnings(ValidationEvent[]) for errors instead of warnings.

Parameters:
evs - the tested list.
Returns:
true if and only if the given list contains at least one error event.

hasFatalErrors

public static boolean hasFatalErrors(ValidationEvent... evs)
Similar to hasWarnings(ValidationEvent[]) for fatal errors instead of warnings.

Parameters:
evs - the tested list.
Returns:
true if and only if the given list contains at least one fatal error event.

validationEventsToString

public static String validationEventsToString(ValidationEvent... evs)
Formats and returns a string containing a description for each validation event in the given list. For each event, this method formats a string using validationEventToString(ValidationEvent), and separates each event with two newlines.

Parameters:
evs - the list of validation events.
Returns:
the formatted string.

validationEventToString

public static String validationEventToString(ValidationEvent ev)
Constructs and returns a string representing the validation event ev. This string contains the severity (warning, error, or fatal error) of the event, and its descriptive message. It also contains the result of locatorToString(ValidationEventLocator) which converts the location information into a string.

Parameters:
ev - the validation event being formatted.
Returns:
the formatted string.

locatorToString

public static String locatorToString(ValidationEventLocator locator)
Formats the given locator locator into a string. If the locator specifies a URL, this method returns the URL as well as the line and column. If it contains an object, it returns the result of its toString method. If it specifies a DOM node, the node is formatted to an XPath-like expression. Otherwise, Unknown location is returned.

Parameters:
locator -
Returns:
the string representation of the locator.

ContactCenters
V. 0.9.9.

To submit a bug or ask questions, send an e-mail to Richard Simard.