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

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

    java.lang.Object
      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.

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

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