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.contactcenters.contact
Class ContactArrivalProcess

    java.lang.Object
      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, {(t), t≥0}, is given by taking (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 [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 [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

  λ(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 e≤s.

  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

  [λ(t)]dt/(e - s).

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

  This method returns 0 if e≤s.

  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.

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.