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 ParamReadHelper

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

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.