ContactCenters
V. 0.9.9.

umontreal.iro.lecuyer.xmlbind
Class ParamReadHelper

java.lang.Object
  extended by umontreal.iro.lecuyer.xmlbind.ParamReadHelper

public class ParamReadHelper
extends Object

Defines methods that can be used to construct Java objects from some parameter objects whose classes are derived by the JAXB binding compiler. Objects from JAXB-derived classes have behavior; they contain data only. This class provides methods to convert some complex parameter objects representing maps of properties, database connections, and probability distributions to more useful Java and SSJ objects. It complements the ArrayConverter class which is specialized for 2D arrays.


Constructor Summary
ParamReadHelper()
           
 
Method Summary
static Distribution createBasicDistribution(RandomVariateGenParams rvgp)
          Constructs and returns an object representing the distribution based on the parameters in rvgp.
static Connection createConnection(DBConnectionParams dbParams)
          Creates a database connection from the parameters stored in the given dbParams object.
static RandomVariateGen createGenerator(RandomVariateGenParams rvgp, RandomStream stream)
          Constructs and returns a random variate generator from the parameters given by rvgp, and the random stream stream.
static RandomVariateGen createGenerator(RandomVariateGenParams rvgp, RandomStream stream, Distribution dist)
          Constructs and returns a random variate generator from the parameters given in rvgp, the random stream stream, and the probability distribution dist.
static TruncatedDist createTruncatedDist(Distribution dist, RandomVariateGenParams rvgp)
          Constructs and returns a truncated distribution object from distribution dist, and parameters tp.
static boolean estimateParameters(RandomVariateGenParams rvgp)
          Replaces the array of observations returned by RandomVariateGenParams.getParams() with an array obtained by parameter estimation.
static double getMean(RandomVariateGenParams rvgp)
          Determines the mean of the distribution corresponding to the parameters given by rvgp.
static Properties getProperties(Map<String,Object> prop)
          Converts the given map of properties to a Java Properties object.
static double getVariance(RandomVariateGenParams rvgp)
          Determines the variance of the distribution corresponding to the parameters given by rvgp.
static PropertiesParams marshalProperties(Map<String,Object> prop)
          Marshals the given map into a PropertiesParams object.
static boolean sameGenerators(RandomVariateGenParams rvgp1, RandomVariateGenParams rvgp2, double tol)
          Determines if rvgp1 and rvgp2 describe two equivalent random variate generators.
static Map<String,Object> unmarshalProperties(PropertiesParams prop)
          Constructs and returns a map containing the properties stored into the given PropertiesParams object prop which can be considered as a list of properties.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ParamReadHelper

public ParamReadHelper()
Method Detail

unmarshalProperties

public static Map<String,Object> unmarshalProperties(PropertiesParams prop)
Constructs and returns a map containing the properties stored into the given PropertiesParams object prop which can be considered as a list of properties. For each AbstractProperty stored in prop, this method adds an entry to the returned map. The name of the new entry is the name of the property while the value of the entry is the value of the property. The null value is used for properties with no values. The type of the value is determined by the concrete subclass of AbstractProperty. The supported types are Boolean, String, Integer, Double, Duration, Date, and arrays of these preceding types except Integer[], Double[], and Date[]. Arrays of numbers are converted to int[], and double[] instead.

This method returns an empty map if prop is null.

Parameters:
prop - the properties in the XML file.
Returns:
the Java Properties object.
Throws:
IllegalArgumentException - if more than one property with the same name was found.

getProperties

public static Properties getProperties(Map<String,Object> prop)
Converts the given map of properties to a Java Properties object. This method accepts a map that is usually created by unmarshalProperties(PropertiesParams), and turns it into a Properties object by converting each of its non-null values to strings, with the Object.toString() method. A null reference as a property value results in a null reference in the returned map.

This method returns an empty property set if its argument is null.

Parameters:
prop - the properties represented as a map.
Returns:
the properties represented as a Properties object.

marshalProperties

public static PropertiesParams marshalProperties(Map<String,Object> prop)
Marshals the given map into a PropertiesParams object. The result of this method can be associated directly with a JAXB element of type PropertiesParams. Each entry of the given map is converted into an object whose class extends AbstractProperty, the exact subclass depending on the class of the value. This method supports the same property types as unmarshalProperties(PropertiesParams). If a property in prop has a value with an unsupported non-array type, the value is turned into a string using its toString method. Unsupported array types are converted to strings using a mechanism similar to Arrays.deepToString(Object[]) but working for objects and primitive types.

This method returns null if its argument is null.

Parameters:
prop - the Java Properties.
Returns:
the Properties parameters.

createConnection

public static Connection createConnection(DBConnectionParams dbParams)
                                   throws SQLException
Creates a database connection from the parameters stored in the given dbParams object. This method first constructs a Properties object from the properties in dbParams with the help of the unmarshalProperties(PropertiesParams), and getProperties(Map) methods. It then checks attributes in dbParams to decide the way the connection is established. More specifically, if a JNDI name is specified, i.e., DBConnectionParams.isSetJndiDataSourceName() returns true, the properties are used as an environment to create an InitialContext for JNDI, the constructed context is used to look for a JDBC DataSource, and the connection is obtained. Otherwise, the driver is loaded if its class is not null, and the connection is established using the URI and properties.

Parameters:
dbParams - the parameters of the connection.
Returns:
the reference to an object representing the established database connection.
Throws:
SQLException - if a connection error occurred.

createBasicDistribution

public static Distribution createBasicDistribution(RandomVariateGenParams rvgp)
                                            throws DistributionCreationException
Constructs and returns an object representing the distribution based on the parameters in rvgp. This method first resolves the class name given by RandomVariateGenParams.getDistributionClass(). The creation of the distribution object then depends on whether data or parameters are specified in rvgp, which is determined using RandomVariateGenParams.isEstimateParameters(). The constructed distribution does not take account of the truncation bounds RandomVariateGenParams.getLowerBound(), and RandomVariateGenParams.getUpperBound(); this is considered in RandomVariateGenParams). Moreover, the shift returned by RandomVariateGenParams.getShift() is only used for parameter estimation; it is considered by RandomStream).

If RandomVariateGenParams.isEstimateParameters() returns true, the result of RandomVariateGenParams.getParams() is considered as an array of observations, and parameter estimation is performed. For this, the array is copied into an array of double-precision values. If a shift is specified using RandomVariateGenParams.getShift(), it is added to each observation in the intermediate array. If the distribution class corresponds to EmpiricalDist or PiecewiseLinearEmpiricalDist, the observations are sorted, and used to construct the distribution directly. Otherwise, parameter estimation is performed by using DistributionFactory.getDistributionMLE(Class,double[],int). In the case of discrete distributions over the integers, each double-precision observation is rounded to the nearest integer, and used for parameter estimation by the method DistributionFactory.getDistributionMLE(Class,int[],int).

If RandomVariateGenParams.isEstimateParameters() returns false, the array returned by RandomVariateGenParams.getParams() represents parameters. This method then looks for a constructor, in the selected distribution class, taking an array of double-precision values, and calls that constructor if it exists. If such a constructor cannot be found, it searches for a constructor taking n numerical parameters, where n is the number of parameters given. A distribution-creation exception is thrown if no suitable constructor can be found.

Parameters:
rvgp - the parameters of the random variate generator.
Returns:
a reference to the object representing the distribution.
Throws:
DistributionCreationException - if an exception occurred during the creation of the distribution.

estimateParameters

public static boolean estimateParameters(RandomVariateGenParams rvgp)
                                  throws DistributionCreationException
Replaces the array of observations returned by RandomVariateGenParams.getParams() with an array obtained by parameter estimation. Parameters are estimated a way similar to createBasicDistribution(RandomVariateGenParams), and copied into the array returned by RandomVariateGenParams.getParams(). However, instead of using DistributionFactory, this method calls the getMaximumLikelohoodEstimate or getMLE static methods directly to get the array of parameters. After this method returns, the array of estimated parameters can be obtained using RandomVariateGenParams.getParams() while the array of observations is lost, and RandomVariateGenParams.isEstimateParameters() returns false. This method does nothing if RandomVariateGenParams.isEstimateParameters() returns false for the given rvgp object.

Parameters:
rvgp - the random variate generator parameters.
Returns:
true if and only if the data is replaced by estimated parameters.
Throws:
DistributionCreationException - if an exception occurred when getting the distribution class.

getMean

public static double getMean(RandomVariateGenParams rvgp)
                      throws DistributionCreationException
Determines the mean of the distribution corresponding to the parameters given by rvgp. This method creates the distribution, and uses Distribution.getMean() to obtain the mean. It also applies the shift given by RandomVariateGenParams.getShift().

Parameters:
rvgp - the parameters of the random variate generator.
Returns:
the mean.
Throws:
DistributionCreationException - if a problem occurred while creating the distribution.

getVariance

public static double getVariance(RandomVariateGenParams rvgp)
                          throws DistributionCreationException
Determines the variance of the distribution corresponding to the parameters given by rvgp. This method creates the distribution, and uses Distribution.getVariance() to obtain the variance.

Parameters:
rvgp - the parameters of the random variate generator.
Returns:
the variance.
Throws:
DistributionCreationException - if a problem occurred while creating the distribution.

createTruncatedDist

public static TruncatedDist createTruncatedDist(Distribution dist,
                                                RandomVariateGenParams rvgp)
                                         throws DistributionCreationException
Constructs and returns a truncated distribution object from distribution dist, and parameters tp. This method throws a distribution-creation exception if the given distribution is not continuous, or if parameters are invalid.

Parameters:
dist - the distribution to truncate.
rvgp - the parameters of the random variate generator.
Returns:
the truncated distribution.
Throws:
DistributionCreationException - if an error occurs during the construction of the distribution.

createGenerator

public static RandomVariateGen createGenerator(RandomVariateGenParams rvgp,
                                               RandomStream stream)
                                        throws DistributionCreationException,
                                               GeneratorCreationException
Constructs and returns a random variate generator from the parameters given by rvgp, and the random stream stream. This method uses createBasicDistribution(RandomVariateGenParams) to create the basic distribution, and createGenerator(RandomVariateGenParams,RandomStream,Distribution) to create the random variate generator.

Parameters:
rvgp - the parameters of the generator.
stream - the random stream.
Returns:
the random variate generator.
Throws:
DistributionCreationException - if an eror occurred during the creation of the distribution.
GeneratorCreationException - if an error occurred during the creation of the generator.

createGenerator

public static RandomVariateGen createGenerator(RandomVariateGenParams rvgp,
                                               RandomStream stream,
                                               Distribution dist)
                                        throws DistributionCreationException,
                                               GeneratorCreationException
Constructs and returns a random variate generator from the parameters given in rvgp, the random stream stream, and the probability distribution dist. First, if truncation parameters are specified, this method uses RandomVariateGenParams) to construct the truncated distribution, and creates a random variate generator using inversion. Otherwise, the method creates a generator from the class given by RandomVariateGenParams.getGeneratorClass(). If no generator class is specified, a RandomVariateGen is used for any distribution, except discrete distributions over the integers for which the method uses RandomVariateGenInt. This results in using inversion if no random variate generator was specified. The constructed generator is finally wrapped around a RandomVariateGenWithShift instance if a shift was defined in rvgp.

Parameters:
rvgp - the random variate generator parameters.
stream - the random stream.
dist - the probability distribution.
Returns:
the random variate generator.
Throws:
DistributionCreationException - if an exception occurred during construction of the truncated distribution.
GeneratorCreationException - if an exception occurred when constructing the generator.

sameGenerators

public static boolean sameGenerators(RandomVariateGenParams rvgp1,
                                     RandomVariateGenParams rvgp2,
                                     double tol)
Determines if rvgp1 and rvgp2 describe two equivalent random variate generators. That is, if they have the same distribution, generation method, and same parameters within tolerance tol. Numerical parameters are compared as follows by this method: parameters a and b are equal if and only if | b - a| < tol.

Parameters:
rvgp1 - the first random variate generator.
rvgp2 - the second random variate generator.
tol - the tolerance for comparing numbers.
Returns:
true if and only if the generators are considered to be equivalent.

ContactCenters
V. 0.9.9.

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