|
ContactCenters V. 0.9.9. |
||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
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. |
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.
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.
Entity | Escaped character |
< | < |
> | > |
" | " |
& | & |
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.
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");
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.
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.
<?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. |
||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |