ContactCenters
V. 0.9.9.

umontreal.iro.lecuyer.contactcenters.contact
Class ContactArrivalProcess

java.lang.Object
  extended by umontreal.iro.lecuyer.contactcenters.contact.ContactArrivalProcess
All Implemented Interfaces:
ContactSource, Initializable, Named, ToggleElement
Direct Known Subclasses:
PoissonArrivalProcess, PoissonUniformArrivalProcess, StationaryContactArrivalProcess

public abstract class ContactArrivalProcess
extends Object
implements ContactSource

Represents a contact arrival process modeling the arrival of inbound contacts. Such a process schedules an event for each new contact, and broadcasts the arrival to any registered new-contact listeners. More specifically, a single simulation event manages arrivals as follows: upon an arrival, a new contact is instantiated using the associated contact factory, the contact is broadcast to any registered listener, and the next arrival is scheduled. The interarrival times are computed using the nextTime() method which needs to be implemented in a concrete subclass. This abstract class also takes care of new-contact listeners registration and notification. Subclasses only needs to define nextTime() and optionally init() which initializes the arrival process at the beginning of the simulation. It is also possible to access the scheduled new-contact event to reschedule or cancel it as needed. Implementing getArrivalRate(int), and getExpectedArrivalRate(int) is recommended to allow programs to get the arrival rate and expected arrival rate.

Each arrival process has an associated simulator which is an instance of the Simulator class. This simulator is used to schedule the event managing the arrival process. It is also assumed that the user-defined contact factory attaches this simulator to each new contact. Failing to meet this condition might lead to unexpected behavior, and will trigger a failed assertion if assertion checking is turned on during execution.

The arrival process can be inflated or deflated by a busyness factor denoted B, a random variable with mean 1, and usually generated once for a day. Any arrival process can be defined as {N(t), t≥0}, where N(t) is the number of arrivals during the time interval [0, t). The process affected by the busyness, {$ \tilde{N}$(t), t≥0}, is given by taking $ \tilde{N}$(t) = round(BN(t)), where round(⋅) rounds its argument to the nearest integer. The exact way to take account of the busyness factor depends on the specific arrival process. For example, for Poisson processes, the busyness is used to inflate or deflate the λ arrival rate.

The busyness factor must be set externally, because the value of B for this arrival process is often correlated with B for other arrival processes. The recommended way to set B is using init(double). The current value of B might be obtained using getBusynessFactor(). By default, it is assumed that $ \E$[B] = 1. If this is not true for a particular model, one should call setExpectedBusynessFactor(double) to set the expectation of the factor.

Note: the NewContactListener implementations are notified in the order of the list returned by getNewContactListeners(), and a new-contact listener modifying the list of listeners by using addNewContactListener(NewContactListener) or removeNewContactListener(NewContactListener) could result in unpredictable behavior.


Field Summary
protected  Event contactEvent
          Event representing the arrival of a new contact.
 
Constructor Summary
ContactArrivalProcess(ContactFactory factory)
          Constructs a new contact arrival process creating contacts using the given factory.
ContactArrivalProcess(Simulator sim, ContactFactory factory)
          Equivalent to ContactArrivalProcess(ContactFactory), with a user-defined simulator sim.
 
Method Summary
 void addNewContactListener(NewContactListener listener)
          Adds the listener listener to be notified when a new contact is produced.
 void clearNewContactListeners()
          Clears the list of new-contact listeners associated with this contact source.
 double getArrivalRate(double st, double et)
          Determines the mean arrival rate in time interval [s, e].
 double getArrivalRate(int p)
          Determines the arrival rate in period p for this arrival process.
 void getArrivalRates(double[] rates)
          Fills the given array rates with the arrival rate for each period.
 double getBusynessFactor()
          Returns the currently used busyness factor B, which must be greater than or equal to 0, and defaults to 1.
 ContactFactory getContactFactory()
          Returns a reference to the associated contact factory.
 double getExpectedArrivalRate(double st, double et)
          Determines the expected mean arrival rate in time interval [s, e] for this arrival process assuming that the expected value of the busyness factor is 1.
 double getExpectedArrivalRate(int p)
          Determines the expected arrival rate in period p for this arrival process assuming that the expected value of the busyness factor is 1.
 double getExpectedArrivalRateB(double st, double et)
          Returns the expected mean arrival rate considering the current expected busyness factor.
 double getExpectedArrivalRateB(int p)
          Returns the expected arrival rate considering the current expected busyness factor.
 void getExpectedArrivalRates(double[] rates)
          Fills the given array rates with the expected arrival rate for each period.
 void getExpectedArrivalRatesB(double[] rates)
          Fills the given array rates with the expected arrival rate for each period.
 double getExpectedBusynessFactor()
          Returns the expected value of the busyness factor for this arrival process.
 String getName()
          Returns the name associated with this object.
 List<NewContactListener> getNewContactListeners()
          Returns an unmodifiable list containing all the new-contact listeners registered with this contact source.
 double getNextArrivalTime()
          Returns the simulation time of the next arrival currently scheduled by this arrival process.
 void init()
          Initializes the new arrival process.
 void init(double b)
          Initializes this process with a specific busyness factor B = b.
 boolean isStarted()
          Determines if the element is enabled or disabled.
abstract  double nextTime()
          Computes and returns the time before the next contact arrival is simulated by this object.
 void notifyNewContact(Contact contact)
          Notifies the contact contact to every registered listener.
 void removeNewContactListener(NewContactListener listener)
          Removes the new-contact listener listener from the list associated with this contact source.
 void setBusynessFactor(double b)
          Sets the busyness factor to b.
 void setContactFactory(ContactFactory factory)
          Sets the contact factory to factory.
 void setExpectedBusynessFactor(double bMean)
          Sets the expected busyness factor for this arrival process to bMean.
 void setName(String name)
          Sets the name of this object to name.
 void setSimulator(Simulator sim)
          Sets the simulator attached to this contact source to sim.
 Simulator simulator()
          Returns a reference to the simulator associated with this contact source.
 void start()
          Enables the element represented by this object.
 void start(double delay)
          Starts this arrival process and schedules the first arrival to happen after delay simulation time units, independently of how nextTime() is implemented.
 void startStationary()
          Setup the arrival process to be stationary, and starts it using the start() method.
 void stop()
          Disables the element represented by this object.
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

contactEvent

protected final Event contactEvent
Event representing the arrival of a new contact. Subclasses can cancel or reschedule this event to adjust it when a parameter change occurs.

Constructor Detail

ContactArrivalProcess

public ContactArrivalProcess(ContactFactory factory)
Constructs a new contact arrival process creating contacts using the given factory.

Parameters:
factory - the factory creating contacts for this arrival process.
Throws:
NullPointerException - if factory is null.

ContactArrivalProcess

public ContactArrivalProcess(Simulator sim,
                             ContactFactory factory)
Equivalent to ContactArrivalProcess(ContactFactory), with a user-defined simulator sim.

Parameters:
sim - the simulator attached to this arrival process.
factory - the factory creating contacts for this arrival process.
Throws:
NullPointerException - if sim or factory are null.
Method Detail

simulator

public Simulator simulator()
Description copied from interface: ContactSource
Returns a reference to the simulator associated with this contact source. The simulator is used to schedule any event required by the contact source to produce contacts.

Any implementation of this interface should provide a constructor accepting the simulator as an argument. Constructors not receiving a simulator should use the default simulator returned by Simulator.getDefaultSimulator().

Specified by:
simulator in interface ContactSource
Returns:
the associated simulator.

setSimulator

public void setSimulator(Simulator sim)
Description copied from interface: ContactSource
Sets the simulator attached to this contact source to sim. This method should not be called while the contact source is started.

Specified by:
setSimulator in interface ContactSource
Parameters:
sim - the new simulator.

getName

public String getName()
Description copied from interface: Named
Returns the name associated with this object. If no name was set, this must return an empty string, not null.

Specified by:
getName in interface Named
Returns:
the name of this object.

setName

public void setName(String name)
Description copied from interface: Named
Sets the name of this object to name. The given name cannot be null and the implementation can throw an UnsupportedOperationException if the name is read-only.

Specified by:
setName in interface Named
Parameters:
name - the new name of the object.

nextTime

public abstract double nextTime()
Computes and returns the time before the next contact arrival is simulated by this object. If this method returns Double.POSITIVE_INFINITY, no more arrival events will be scheduled until the arrival process is reinitialized.

Returns:
the time before the next arrival.

getBusynessFactor

public double getBusynessFactor()
Returns the currently used busyness factor B, which must be greater than or equal to 0, and defaults to 1.

Returns:
the current busyness factor.

setBusynessFactor

public void setBusynessFactor(double b)
Sets the busyness factor to b. This method should be called before init() is called, or one should use init(double).

Parameters:
b - the new busyness factor.
Throws:
IllegalArgumentException - if b is negative.

getExpectedBusynessFactor

public double getExpectedBusynessFactor()
Returns the expected value of the busyness factor for this arrival process.

Returns:
the expected value of the busyness factor.

setExpectedBusynessFactor

public void setExpectedBusynessFactor(double bMean)
Sets the expected busyness factor for this arrival process to bMean.

Parameters:
bMean - the new value of the expectation.
Throws:
IllegalArgumentException - if bMean is negative.

init

public void init(double b)
Initializes this process with a specific busyness factor B = b. By default, this method simply calls setBusynessFactor(double) followed by init().

Parameters:
b - the value of the busyness factor.
Throws:
IllegalArgumentException - if b ≤ 0.

init

public void init()
Initializes the new arrival process. If this method is overridden by a subclass, it is important to call super.init() in order to ensure that everything is initialized correctly.

Specified by:
init in interface ContactSource
Specified by:
init in interface Initializable

getContactFactory

public ContactFactory getContactFactory()
Returns a reference to the associated contact factory. This factory is used to instantiate contact objects.

Returns:
the associated contact factory.

setContactFactory

public void setContactFactory(ContactFactory factory)
Sets the contact factory to factory. This new contact factory will be used to instantiate future contact objects.

Parameters:
factory - the new contact factory.
Throws:
NullPointerException - if the given contact factory is null.

addNewContactListener

public void addNewContactListener(NewContactListener listener)
Description copied from interface: ContactSource
Adds the listener listener to be notified when a new contact is produced. If the listener was already registered, nothing happens, because the listener cannot be notified more than once.

Specified by:
addNewContactListener in interface ContactSource
Parameters:
listener - the new-contact listener being added.

removeNewContactListener

public void removeNewContactListener(NewContactListener listener)
Description copied from interface: ContactSource
Removes the new-contact listener listener from the list associated with this contact source. If the listener was not previously registered with this contact source, nothing happens.

Specified by:
removeNewContactListener in interface ContactSource
Parameters:
listener - the new-contact listener being removed.

clearNewContactListeners

public void clearNewContactListeners()
Description copied from interface: ContactSource
Clears the list of new-contact listeners associated with this contact source.

Specified by:
clearNewContactListeners in interface ContactSource

getNewContactListeners

public List<NewContactListener> getNewContactListeners()
Description copied from interface: ContactSource
Returns an unmodifiable list containing all the new-contact listeners registered with this contact source.

Specified by:
getNewContactListeners in interface ContactSource
Returns:
the list of all registered new-contact listeners.

start

public void start()
Description copied from interface: ToggleElement
Enables the element represented by this object. This method throws an IllegalStateException if the element is already enabled.

Specified by:
start in interface ToggleElement

startStationary

public void startStationary()
Setup the arrival process to be stationary, and starts it using the start() method. When an arrival process is started using this method, its parameters do not evolve with time. This can be useful, e.g., to simulate a single period as if it was infinite in the model. If the arrival process does not support stationary mode, this method throws an unsupported-operation exception. The default behavior of this method is to throw this exception.


start

public void start(double delay)
Starts this arrival process and schedules the first arrival to happen after delay simulation time units, independently of how nextTime() is implemented. If delay is set to Double.POSITIVE_INFINITY, no arrival is scheduled. Any subsequent inter-arrival times will be generated with nextTime() as usual.

Parameters:
delay - the first inter-arrival time.

stop

public void stop()
Description copied from interface: ToggleElement
Disables the element represented by this object. This method throws an IllegalStateException if the element is already disabled.

Specified by:
stop in interface ToggleElement

isStarted

public boolean isStarted()
Description copied from interface: ToggleElement
Determines if the element is enabled or disabled. Returns true if the element is enabled, false otherwise.

Specified by:
isStarted in interface ToggleElement
Returns:
the current state of the element.

getNextArrivalTime

public double getNextArrivalTime()
Returns the simulation time of the next arrival currently scheduled by this arrival process. If the arrival process is stopped or no arrival is scheduled, this returns a negative number.

Returns:
the arrival time of the next contact.

getArrivalRate

public double getArrivalRate(int p)
Determines the arrival rate in period p for this arrival process. The arrival rate corresponds to the expected number of arrivals per simulation time unit during the specified period; one must multiply the rate by the period duration to get the expected number of arrivals during the period.

If arrival rate is random, this returns the arrival rate for the current replication. One should use getExpectedArrivalRate(int) or getExpectedArrivalRateB(int) to get the expected arrival rate.

If the arrival rate is not available, throws an UnsupportedOperationException.

Parameters:
p - the queried period index.
Returns:
the arrival rate in that period.

getArrivalRates

public void getArrivalRates(double[] rates)
Fills the given array rates with the arrival rate for each period. After this method returns, element rates[p] corresponds to the value returned by getArrivalRate (p).

Parameters:
rates - the array filled with rates.

getExpectedArrivalRate

public double getExpectedArrivalRate(int p)
Determines the expected arrival rate in period p for this arrival process assuming that the expected value of the busyness factor is 1. The arrival rate corresponds to the expected number of arrivals per simulation time unit during the specified period; one must multiply the rate by the period duration to get the expected number of arrivals during the period. If arrival rates are deterministic, this returns the same value as getArrivalRate(int).

If $ \E$[B]≠1, one should use getExpectedArrivalRateB(int) which takes the expectation of the busyness factor into account.

If the expected arrival rate is not available, throws an UnsupportedOperationException. This is the default behavior of this method if not overridden by a subclass.

Parameters:
p - the queried period index.
Returns:
the expected arrival rate in that period.

getExpectedArrivalRates

public void getExpectedArrivalRates(double[] rates)
Fills the given array rates with the expected arrival rate for each period. After this method returns, element rates[p] corresponds to the value returned by getExpectedArrivalRate (p).

Parameters:
rates - the array filled with rates.

getExpectedArrivalRateB

public double getExpectedArrivalRateB(int p)
Returns the expected arrival rate considering the current expected busyness factor. This corresponds to the product of the value returned by getExpectedArrivalRate(int), and the value returned by getExpectedBusynessFactor().

Parameters:
p - the tested period.
Returns:
the tested arrival rate.

getExpectedArrivalRatesB

public void getExpectedArrivalRatesB(double[] rates)
Fills the given array rates with the expected arrival rate for each period. After this method returns, element rates[p] corresponds to the value returned by getExpectedArrivalRateB (p).

Parameters:
rates - the array filled with rates.

getArrivalRate

public double getArrivalRate(double st,
                             double et)
Determines the mean arrival rate in time interval [s, e]. The arrival rate corresponds to the expected number of arrivals per simulation time unit during the specified interval; one must multiply the rate by the interval length to get the expected number of arrivals during the interval. If λ(t) is the arrival rate at time t, this method returns the result of

$\displaystyle \htint_{s}^{e}$λ(t)dt/(e - s).

If arrival rate is random, this returns the arrival rate for the current replication. One should use getExpectedArrivalRate(double,double) or getExpectedArrivalRateB(double,double) to get the expected arrival rate.

This method returns 0 if es.

If the arrival rate is not available, throws an UnsupportedOperationException. This is the default behavior of this method if not overridden by a subclass.

Parameters:
st - the starting time s.
et - the ending time e.
Returns:
the arrival rate in the given time interval.

getExpectedArrivalRate

public double getExpectedArrivalRate(double st,
                                     double et)
Determines the expected mean arrival rate in time interval [s, e] for this arrival process assuming that the expected value of the busyness factor is 1. The arrival rate corresponds to the expected number of arrivals per simulation time unit during the specified interval; one must multiply the rate by the interval length to get the expected number of arrivals during the interval. If arrival rates are deterministic, this returns the same value as getArrivalRate(double,double). If λ(t) is the arrival rate at time t, this method returns

$\displaystyle \htint_{s}^{e}$$\displaystyle \E$[λ(t)]dt/(e - s).

If $ \E$[B]≠1, one should use getExpectedArrivalRateB(double,double) which takes the expectation of the busyness factor into account.

This method returns 0 if es.

If the expected arrival rate is not available, throws an UnsupportedOperationException. This is the default behavior of this method if not overridden by a subclass.

Parameters:
st - the starting time s.
et - the ending time e.
Returns:
the expected arrival rate in the given time interval.

getExpectedArrivalRateB

public double getExpectedArrivalRateB(double st,
                                      double et)
Returns the expected mean arrival rate considering the current expected busyness factor. This corresponds to the product of the value returned by getExpectedArrivalRate(double,double), and the value returned by getExpectedBusynessFactor().

Parameters:
st - the starting time s.
et - the ending time e.
Returns:
the expected arrival rate in the given time interval.

toString

public String toString()
Overrides:
toString in class Object

notifyNewContact

public void notifyNewContact(Contact contact)
Notifies the contact contact to every registered listener.

Parameters:
contact - the contact to be notified.

ContactCenters
V. 0.9.9.

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