ContactCenters
V. 0.9.9.

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 setAttr 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 addElement whereas a creater method has the form createElement. 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.


ContactCenters
V. 0.9.9.

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