cz.zcu.fav.kiv.jsim.random
Class JSimUserObjectStream

java.lang.Object
  cz.zcu.fav.kiv.jsim.random.JSimUserObjectStream

public class JSimUserObjectStream
extends java.lang.Object

A stream generating user-defined objects according to their corresponding user-defined absolute rates. The probability that a certain object will be returned by the getNext() method is equal to the ratio its_absolute_rate / sum_of_all_absolute_rates. All objects specified by the user must be non-null, all absolute rates must be non-negative. An initial seed can be specified, which allows you to generate the same sequence of user objects several times.

Since:

J-Sim version 0.3.0

Version:

J-Sim version 0.6.0

Author:

Jarda KAČER

Field Summary

private double[]	cumulativeRates Cumulative rates of object occurence.
private java.lang.Object[]	objects The objects specified by the user and returned by getNext().
private double[]	rates The absolute rates of object occurence.
protected java.util.Random	stream An internal stream from which random numbers are taken to compute an object.
private double	sumOfRates The sum of all rates.

Constructor Summary

JSimUserObjectStream(java.lang.Object[] objects, double[] rates)
Creates a new user object stream.

JSimUserObjectStream(java.lang.Object[] objects, double[] rates, long seed)
Creates a new user object stream.

Method Summary

java.lang.Object	getNext() Returns a randomly selected user object.
java.lang.Object[]	getObjects() Returns a copy of user objects returned by getNext().
double[]	getRates() Returns a copy of rates used by the generator.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

stream

protected java.util.Random stream

An internal stream from which random numbers are taken to compute an object.

objects

private java.lang.Object[] objects

The objects specified by the user and returned by getNext().

rates

private double[] rates

The absolute rates of object occurence. The bigger the i^th rate is, the bigger probability that the i^th object will be returned by getNext().

cumulativeRates

private double[] cumulativeRates

Cumulative rates of object occurence.

sumOfRates

private double sumOfRates

The sum of all rates.

Constructor Detail

JSimUserObjectStream

public JSimUserObjectStream(java.lang.Object[] objects,
                            double[] rates)
                     throws JSimInvalidParametersException

Creates a new user object stream. A pseudo-randomly generated seed will be used. Both arrays are copied so any subsequent changes do not affect the generator functionality. However, in the case of user objects, just a shallow copy is performed, so any subsequent change of an object to be returned does possibly affect the return value of getNext().

Parameters:

objects - User objects to be returned by getNext(). No object of the array can be null. The length of the array must be positive and equal to the lenght of rates.

rates - The absolute rates of occurence of user-defined objects. Every rate must be non-negative. The length of the array must be positive and equal to the lenght of objects.

Throws:

JSimInvalidParametersException - This exception is thrown out if the arrays of objects and rates are null, have zero length, have different lengths, or an item of the arrays is null or less than zero, respectively.

JSimUserObjectStream

public JSimUserObjectStream(java.lang.Object[] objects,
                            double[] rates,
                            long seed)
                     throws JSimInvalidParametersException

Creates a new user object stream. The seed given as the third argument will be used. Both arrays are copied so any subsequent changes do not affect the generator functionality. However, in the case of user objects, just a shallow copy is performed, so any subsequent change of an object to be returned does possibly affect the return value of getNext().

Parameters:

objects - User objects to be returned by getNext(). No object of the array can be null. The length of the array must be positive and equal to the lenght of rates.

rates - The absolute rates of occurence of user-defined objects. Every rate must be non-negative. The length of the array must be positive and equal to the lenght of objects.

seed - A seed that will initialize the generator.

Throws:

JSimInvalidParametersException - This exception is thrown out if the arrays of objects and rates are null, have zero length, have different lengths, or an item of the arrays is null or less than zero, respectively.

Method Detail

getNext

public java.lang.Object getNext()

Returns a randomly selected user object. The probability that a certain object is returned is equal to the ratio between its rate and the sum of all rates.

Returns:

A randomly selected user object.

getObjects

public java.lang.Object[] getObjects()

Returns a copy of user objects returned by getNext(). Subsequent changes to the return value (an array of Object instances) does not affect the generator but any change to an item of the returned array does affect it.

Returns:

A copy of user objects returned by getNext().

getRates

public double[] getRates()

Returns a copy of rates used by the generator. Subsequent changes to the return value (an array of doubles) does not affect the generator.

Returns:

A copy of rates used by the generator.