Overview | Package | Class | Tree | Deprecated | Index | Help
| ContactCenters V. 0.9.9.
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## Package umontreal.iro.lecuyer.xmlconfig

Provides some facilities to extract and verify parameters read from data files in XML format.

See:
Description

Interface Summary
Param | Marks an object as a parameter object.
SourceArray2D | Represents a 2D array obtained from a data source such a text file, or a database.
StorableParam | Represents a parameter object providing the capability to be converted back to a DOM element.

Class Summary
AbstractParam | Provides common attributes for parameter objects.
ArrayParam | Represents a parameter object containing an array of parameters.
ArrayParam.RowParam | For internal use only.
ArrayParam2D | Represents a parameter object containing a 2D array or a matrix of parameters.
ArrayParam2D.MatrixRowParam | For internal use only.
CSVSourceArray2D | Represents a source array whose contents is read from a CSV-formatted text file.
DBConnectionParam | Represents the parameters for a database connection established using JDBC.
DBSourceArray2D | Represents a source array whose data is extracted from a database using JDBC.
DOMUtils | Provides utility methods to build indented DOM documents intended to be converted to XML files.
ExcelSourceArray2D | Represents a source array whose contents is read from a Microsoft Excel workbook.
ParamReader | Constructs a parameter object from an XML document parsed using a DOM parser.
ParamReader.MethodComparator | Comparator for sorting the methods returned by `Introspection.getMethods(java.lang.Class)`.
ParamWithSourceArray | Represents a parameter object whose contents can be extracted from a source subset created from a source array.
PropertyParam | Represents a property, i.e., a name-value pair.
RandomVariateGenParam | Stores the parameters of a probability distribution to create the distribution object or a matching random variate generator at a later time.
SourceSubset2D | Represents a source subset obtained from a source array.
TimeParam | Represents a time duration or a rate parameter expressed in a time unit.

Exception Summary
DistributionCreationException | This exception is thrown when a problem occurs during the construction of a distribution object by `RandomVariateGenParam.createDistribution()` or `RandomVariateGenParam.createDistributionInt()`, or during the parsing of the nested text containing a distribution XML element.
GeneratorCreationException | This exception is thrown when a problem occurs during the construction of a random variate generator by `RandomVariateGenParam.createGenerator(umontreal.iro.lecuyer.rng.RandomStream)` or `RandomVariateGenParam.createGeneratorInt(umontreal.iro.lecuyer.rng.RandomStream)`.
ParamReadException | This exception is thrown when a problem happens when converting a DOM document into a tree of parameter objects.

## Package umontreal.iro.lecuyer.xmlconfig Description

Provides some facilities to extract and verify parameters read from data files in XML format. Parameter reading is often tedious and clutters the application code with repetitive statements. Read parameters must be converted from string to useful types, checked for validity and processed in many ways before they can be used by an application program. By using XML [21], one can take advantage of a standardized file format syntax and already implemented and robust parsers providing error checking. However, even when a validating parser, which is able to ensure that an XML file satisfy predefined structural constraints, is used, the parameters must be extracted from a parse tree and converted from string.

This package provides facilities to extract and convert values from a Document Object Model (DOM) document constructed using the Java API for XML (JAXP) or any other API implementing DOM Level 2 [16] or above. It uses a design-patterns oriented technique strongly inspired from Apache Ant [5] task building but extended to be used in a more general context.

### Format of parameter files

This section briefly introduces the XML format as used by the parameter files. See [21] for the full XML specification. The first line of an XML file is optional and contains an header specifying the version of the format and the encoding. This line is like the following one:

    <?xml version="1.0" encoding="iso-8859-1"?>

If this line is not given, the UTF-8 character encoding is assumed. Specifying the encoding can be useful to allow accented characters to appear in the input when the used editor does not support UTF-8.

In an XML file, an element is a container with a name and possibly some attributes. It is represented by a starting marker and an ending marker. The text between these markers is called the contents of the element. For example, `<element>contents</element>` declares an element with name `element` and contents `contents`. An element with no contents can be formatted as `<element/>`. This is called a self-closing element. The whole XML document is contained into a special element called the root element.

An attribute is a key-value pair associated with an element. An element can have zero or more attributes. For example, `<element attribute="value"/>` declares a self-closing element `element` with attribute `attribute` having value `value`. The order of an element's attributes is not important in any XML document.

The nested contents can be simple or complex. Simple contents is composed of only character data, i.e., text with no XML markers. If such characters are required for some reasons, they must be escaped by using entities. Entities are sequences of characters automatically substituted with character data by an XML parser. For the user, they act similarly to macros. Table 5 shows the entities used to escape reserved characters.

Table 5: XML entities used to escape reserved characters
Entity | Escaped character
`&lt;` | `<`
`&gt;` | `>`
`&quot;` | `"`
`&amp;` | `&`

Complex contents is composed of character data and other elements. Some XML document types specify an order in which the elements need to be presented. For the parameter reader, the order of elements is not important.

At any point in the XML file, comments of the form `<!-- comment -->` can be added. These comments are ignored by the parameter reader and can be used to document the parameter files.

Processing instructions can be used to communicate with specific XML processors. The parameter reading facility implemented in this package supports the `import` processing instruction which can be used to import packages when referring to class names in parameter files. The `import` processing instruction works the same way as the Java `import` statement. For example, `<?import java.util.*?>` imports all classes in the `java.util` package.

### Extracting parameters

For an XML document to be converted into a parameter object, an instance of `ParamReader` is needed. The root element name must be bound to a parameter object class, by modifying the `elements` map. For example, the following code associates the `myparams` root element with the class `MyParams`.

       ParamReader reader = new ParamReader();
       reader.elements.put ("myparams", MyParams.class);

After the binding is done, the reading method can be invoked. The `read` method accepts a `Document` implementation or an XML file name and turns it into a parameter object. In the preceding example, the general format of the XML file would be

       <myparams>
          ...
       </myparams>

The following call would read the XML file and creates a `MyParams` instance.

       MyParams par = (MyParams)reader.read ("file.xml");

### Converting back to XML

To be converted back to XML, a parameter object needs to provide a write method specified in the `StorableParam` interface. This method turns the parameter object into a DOM document. The DOM document can then be converted to an XML file. The `AbstractParam` class provides a `write` method capable of converting the storable parameter object to an XML file.

For example, if `MyParams` implements `StorableParam`, the following code can write the parameter object `par` to an XML file.

       AbstractParam.write (new ClassFinder(), "file.xml",
                            par, "myparams", 3);

The class finder is used to convert `Class` objects to simple class names, taking the import declarations into account. The name of the root element, `myparams`, must be given, as well as the number of spaces for each indentation level.

### Creating new parameter object classes

A parameter object can come from any class implementing the `Param` interface, providing a no-argument constructor, and supplying setter, adder, or creater methods that will be mapped to XML attributes and nested elements. Setter methods are used to notify the parameter object about the value of attributes whereas adder and creater methods are used to notify nested elements.

For attribute attr, the setter method `set` Attr is called and the string contents of the attribute is converted to the target class by `StringConvert`. The `id` attribute has a special meaning for the parameter reader; it assigns a name to an element. When the `xref` attribute is associated with an element, the element's contents is expected to be empty and the only allowed attribute is `xref`. The parameter reader replaces such a reference element's attributes and contents with the element having the matching `id` attribute.

Nested XML elements are recursively turned into parameter objects by adder and creater methods. An adder method has the form `add` Element whereas a creater method has the form `create` Element. For simple contents, the adder method can accept a class that can be converted by `StringConvert`. For complex contents to be represented, another parameter object must be used.

For a parameter object to become storable, it must implement the `StorableParam` subinterface of `Param`. This interface specifies a writing method responsible for the conversion. The `DOMUtils` class contains helper methods that can be used during the conversion of any parameter object to a DOM tree.

#### Example of a parameter file.

The following example shows how the parameters from a sample file are handled and converted.

    <?xml version="1.0"?>

    <myparams id="test">
       <numtypes>3</numtypes>
       <numgroups>2</numgroups>
       <arrivalrates>2, 4, 2</arrivalrates>
    </myparams>

We define a class `MyParams` implementing `Param` and providing a no-argument constructor and the following methods. The methods do not need to be public.

       class MyParams implements Param {
          void setId (String id) { ... }
          void addNumtypes (int n) { ... }
          void addNumgroups (int n) { ... }
          ArrayParam createArrivalrates() {
             return new ArrayParam (double.class);
          }
          addArrivalrates (ArrayParam rates) { r = rates.getDoubleValues(); }
       }

After the parameter object is constructed, the parameter reader calls `setId` with the string `test`. All other attributes are mapped to a corresponding setter method.

The parameter reader then calls `addNumtypes` with integer `3`. The same process happens for the `numgroups` nested element.

When the `arrivalrates` element is found, the `createArrivalrates` method is called to create a parameter object. This creater method is necessary because the `ArrayParam` class does not provide a no-argument constructor since the user needs to specify the component class for the array. The parameter reader constructs the array parameter object and pass it back to `addArrivalrates` when the configuration is done. The `getDoubleValues` method can be used to get an array of double-precision elements when the array component class is numeric. Note that there is a similar class for 2D arrays called `ArrayParam2D`.

Overview | Package | Class | Tree | Deprecated | Index | Help
| ContactCenters V. 0.9.9.
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

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