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.dialer
Class Dialer

    java.lang.Object
      umontreal.iro.lecuyer.contactcenters.dialer.Dialer

All Implemented Interfaces:
  ContactSource, Initializable, Named, ToggleElement

    public class Dialer

extends Object
implements ContactSource

Represents a predictive dialer making outbound contacts. A predictive dialer is normally used to generate outbound calls. The dialer's policy determines the number of calls to try on each occasion (as a function of the system's state), and supplies a list to extract them from. This list could be produced by a contact factory and is often assumed to be infinite for simplicity. Such lists could also be constructed from customer contacts who left a message, who were disconnected, etc.

For each call extracted from the dialer list, a success test is performed. This test succeeds with a probability being fixed or depending on the tested call, and the state of the system. Successful calls represent right party connects whereas failed calls represent wrong party connects and connection failures. The dialer generates a random delay representing the time between the beginning of dialing and the success or failure. This delay may depend on the success indicator, the call itself, the current time, etc. An event for broadcasting the call to registered listeners is then scheduled to occur at the time of success or failure.

The dialer defines separate lists of new-contact listeners for right party connects, and failed calls. Usually, only right party connects reach the router, but statistical collectors may need to listen to failed calls as well.

Note: the order in which `NewContactListener` implementations are notified is unspecified, and a new-contact listener modifying a list of listeners could result in unpredictable behavior.

Constructor Summary
`Dialer(DialerPolicy policy, RandomStream streamReach, ValueGenerator probReach)` Constructs a new dialer using the dialer policy `policy`, the random stream `streamReach` to determine if a dialed call reaches the right party, and with 0 reach and fail times.
`Dialer(DialerPolicy policy, RandomStream streamReach, ValueGenerator probReach, ValueGenerator reachTimeGen, ValueGenerator failTimeGen)` Constructs a new dialer using the dialer policy `policy`.
`Dialer(Simulator sim, DialerPolicy policy, RandomStream streamReach, ValueGenerator probReach)` Equivalent to `Dialer(DialerPolicy,RandomStream,ValueGenerator)`, with the given user-defined simulator `sim`.
`Dialer(Simulator sim, DialerPolicy policy, RandomStream streamReach, ValueGenerator probReach, ValueGenerator reachTimeGen, ValueGenerator failTimeGen)` Equivalent to `Dialer(DialerPolicy,RandomStream,ValueGenerator,ValueGenerator,ValueGenerator)`, using the given simulator `sim`.

Method Summary
`void` | `addFailListener(NewContactListener listener)` Adds the new-contact listener `listener` which will be notified upon wrong party connects or connection failures.
`void` | `addNewContactListener(NewContactListener listener)` Calls `addReachListener(NewContactListener)`.
`void` | `addReachListener(NewContactListener listener)` Adds the new-contact listener `listener` which will be notified upon right party connects.
`void` | `clearFailListeners()` Removes all new-contact listeners being notified when this dialer fails to make a contact.
`void` | `clearNewContactListeners()` Calls `clearReachListeners()`.
`void` | `clearReachListeners()` Removes all new-contact listeners being notified when this dialer makes a right party connect.
`void` | `dial()` Instructs the dialer to try performing outbound calls.
`Iterator<DialerActionEvent>` | `dialerActionEventsIterator()` Constructs and returns an iterator for the dialer-action events.
`Set<DialerActionEvent>` | `getActionEvents()` Returns a set containing all the currently scheduled `DialerActionEvent` objects.
`DialerPolicy` | `getDialerPolicy()` Returns the dialing policy used by this dialer.
`List<NewContactListener>` | `getFailListeners()` Returns an unmodifiable list containing all the new-contact listeners notified when the dialer fails making a contact.
`ValueGenerator` | `getFailTimeGenerator()` Returns the value generator for the fail times.
`String` | `getName()` Returns the name associated with this object.
`List<NewContactListener>` | `getNewContactListeners()` Returns the result of `getReachListeners()`.
`int` | `getNumActionEvents()` Returns the number of action events currently scheduled by this dialer.
`int` | `getNumActionEvents(int k)`
`ValueGenerator` | `getProbReachGenerator()` Returns the value generator for the probability of a call to be successful, i.e., the probability of right party connect.
`List<NewContactListener>` | `getReachListeners()` Returns an unmodifiable list containing all the new-contact listeners notified when a right-party connect occurs.
`ValueGenerator` | `getReachTimeGenerator()` Returns the value generator for the reach times.
`RandomStream` | `getStreamReach()` Returns the random stream used to determine if a called person is reached or not.
`void` | `init()` Initializes the contact source for a new replication of a simulation.
`boolean` | `isKeepingActionEvents()` Determines if this dialer is keeping the action events.
`boolean` | `isStarted()` Determines if the element is enabled or disabled.
`boolean` | `isSuccessful(Contact contact)` Determines if the call represented by `contact` is a right party connect.
`boolean` | `isUsingNumActionsEvents()` Determines if the `dial()` method subtracts the number of action events returned by `getNumActionEvents()` from the return value of `DialerPolicy.getNumDials(Dialer)` in order to determine the number of calls to dial.
`protected void` | `notifyListeners(Contact contact, boolean success)` Notifies registered new-contact listeners about the success or failure of the contact `contact`.
`void` | `removeFailListener(NewContactListener listener)` Removes the new-contact listener `listener` from the list of listeners being notified upon wrong party connects or connection failures.
`void` | `removeNewContactListener(NewContactListener listener)` Calls `removeReachListener(NewContactListener)`.
`void` | `removeReachListener(NewContactListener listener)` Removes the new-contact listener `listener` from the list of listeners being notified upon right party connects.
`void` | `restore(DialerState state)` Restores the state of this dialer with state information included in `state`.
`DialerState` | `save()` Saves the state of this dialer and returns a state object containing the information.
`void` | `setDialerPolicy(DialerPolicy policy)` Sets the dialing policy to `policy`.
`void` | `setFailTimeGenerator(ValueGenerator failTimeGen)` Sets the value generator for fail times to `failTimeGen`.
`void` | `setKeepingActionEvents(boolean keepActionEvents)` Sets the keep-dial-events indicator to `keepActionEvents`.
`void` | `setName(String name)` Sets the name of this object to `name`.
`void` | `setProbReachGenerator(ValueGenerator probReach)` Sets the value generator for right party connect probabilities to `probReach`.
`void` | `setReachTimeGenerator(ValueGenerator reachTimeGen)` Sets the value generator for reach times to `reachTimeGen`.
`void` | `setSimulator(Simulator sim)` Sets the simulator attached to this contact source to `sim`.
`void` | `setStreamReach(RandomStream streamReach)` Sets the stream used to determine if a called person is reached to `streamReach`.
`void` | `setUsingNumActionEvents(boolean useNumActionEvents)` Sets the flag for taking the number of action events into account while dialing to `useNumActionEvents`.
`Simulator` | `simulator()` Returns a reference to the simulator associated with this contact source.
`void` | `start()` Enables the element represented by this object.
`void` | `startNoDial()` This is the same as `start()`, except that no call to `dial()` is made after the dialer is started.
`void` | `stop()` Disables the element represented by this object.
`void` | `stopDial()` Stops any ongoing dialing of calls.
`String` | `toString()`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### Dialer

    public Dialer(DialerPolicy policy,
                  RandomStream streamReach,
                  ValueGenerator probReach)

  Constructs a new dialer using the dialer policy `policy`, the random stream `streamReach` to determine if a dialed call reaches the right party, and with 0 reach and fail times.

  Parameters:
    `policy` - the dialer's policy being used.
    `streamReach` - the random number stream used to determine the success of a dial.
    `probReach` - the probability of reaching the right party.
  Throws:
    `NullPointerException` - if any argument is `null`.

### Dialer

    public Dialer(Simulator sim,
                  DialerPolicy policy,
                  RandomStream streamReach,
                  ValueGenerator probReach)

  Equivalent to `Dialer(DialerPolicy,RandomStream,ValueGenerator)`, with the given user-defined simulator `sim`.

  Parameters:
    `sim` - the simulator attached to the dialer.
    `policy` - the dialer's policy being used.
    `streamReach` - the random number stream used to determine the success of a dial.
    `probReach` - the probability of reaching the right party.
  Throws:
    `NullPointerException` - if any argument is `null`.

### Dialer

    public Dialer(DialerPolicy policy,
                  RandomStream streamReach,
                  ValueGenerator probReach,
                  ValueGenerator reachTimeGen,
                  ValueGenerator failTimeGen)

  Constructs a new dialer using the dialer policy `policy`. The random stream `streamReach` is used to determine if a call is reached, `reachTimeGen` and `failTimeGen` compute the reach and fail times, respectively, i.e., the simulation time between the call to `dial()` and the notification to the appropriate new-contact listeners.

  Parameters:
    `policy` - the dialer policy being used.
    `streamReach` - the random number stream used to compute the status of a dial.
    `probReach` - the probability of successful contact.
    `reachTimeGen` - the value generator for the time between dialing and reaching.
    `failTimeGen` - the value generator for the time between dialing and failing.
  Throws:
    `NullPointerException` - if any argument is `null`.

### Dialer

    public Dialer(Simulator sim,
                  DialerPolicy policy,
                  RandomStream streamReach,
                  ValueGenerator probReach,
                  ValueGenerator reachTimeGen,
                  ValueGenerator failTimeGen)

  Equivalent to `Dialer(DialerPolicy,RandomStream,ValueGenerator,ValueGenerator,ValueGenerator)`, using the given simulator `sim`.

  Parameters:
    `sim` - the simulator attached to the dialer.
    `policy` - the dialer policy being used.
    `streamReach` - the random number stream used to compute the status of a dial.
    `probReach` - the probability of successful contact.
    `reachTimeGen` - the value generator for the time between dialing and reaching.
    `failTimeGen` - the value generator for the time between dialing and failing.
  Throws:
    `NullPointerException` - if any argument is `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.

### addNewContactListener

    public void addNewContactListener(NewContactListener listener)

  Calls `addReachListener(NewContactListener)`.

  Specified by:
    `addNewContactListener` in interface `ContactSource`
  Parameters:
    `listener` - the new-contact listener being added.
  Throws:
    `NullPointerException` - if `listener` is `null`.

### removeNewContactListener

    public void removeNewContactListener(NewContactListener listener)

  Calls `removeReachListener(NewContactListener)`.

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

### clearNewContactListeners

    public void clearNewContactListeners()

  Calls `clearReachListeners()`.

  Specified by:
    `clearNewContactListeners` in interface `ContactSource`

### getNewContactListeners

    public List<NewContactListener> getNewContactListeners()

  Returns the result of `getReachListeners()`.

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

### addReachListener

    public void addReachListener(NewContactListener listener)

  Adds the new-contact listener `listener` which will be notified upon right party connects.

  Parameters:
    `listener` - the new-contact listener being added.
  Throws:
    `NullPointerException` - if `listener` is `null`.

### removeReachListener

    public void removeReachListener(NewContactListener listener)

  Removes the new-contact listener `listener` from the list of listeners being notified upon right party connects.

  Parameters:
    `listener` - the new-contact listener being removed.

### clearReachListeners

    public void clearReachListeners()

  Removes all new-contact listeners being notified when this dialer makes a right party connect.

### getReachListeners

    public List<NewContactListener> getReachListeners()

  Returns an unmodifiable list containing all the new-contact listeners notified when a right-party connect occurs.

  Returns:
    the list of all registered new-contact listeners.

### addFailListener

    public void addFailListener(NewContactListener listener)

  Adds the new-contact listener `listener` which will be notified upon wrong party connects or connection failures.

  Parameters:
    `listener` - the new-contact listener being added.
  Throws:
    `NullPointerException` - if `listener` is `null`.

### removeFailListener

    public void removeFailListener(NewContactListener listener)

  Removes the new-contact listener `listener` from the list of listeners being notified upon wrong party connects or connection failures.

  Parameters:
    `listener` - the new-contact listener being removed.

### clearFailListeners

    public void clearFailListeners()

  Removes all new-contact listeners being notified when this dialer fails to make a contact.

### getFailListeners

    public List<NewContactListener> getFailListeners()

  Returns an unmodifiable list containing all the new-contact listeners notified when the dialer fails making a contact.

  Returns:
    the list of all registered new-contact listeners.

### getDialerPolicy

    public DialerPolicy getDialerPolicy()

  Returns the dialing policy used by this dialer.

  Returns:
    the used dialer's policy.

### setDialerPolicy

    public void setDialerPolicy(DialerPolicy policy)

  Sets the dialing policy to `policy`.

  Parameters:
    `policy` - the new dialer's policy.
  Throws:
    `NullPointerException` - if `policy` is `null`.

### getStreamReach

    public RandomStream getStreamReach()

  Returns the random stream used to determine if a called person is reached or not.

  Returns:
    the stream used to determine if a called person is reached.

### setStreamReach

    public void setStreamReach(RandomStream streamReach)

  Sets the stream used to determine if a called person is reached to `streamReach`.

  Parameters:
    `streamReach` - the new stream for success tests.
  Throws:
    `NullPointerException` - if `streamReach` is `null`.

### getProbReachGenerator

    public ValueGenerator getProbReachGenerator()

  Returns the value generator for the probability of a call to be successful, i.e., the probability of right party connect.

  Returns:
    the value generator for the reach probability.

### setProbReachGenerator

    public void setProbReachGenerator(ValueGenerator probReach)

  Sets the value generator for right party connect probabilities to `probReach`.

  Parameters:
    `probReach` - the value generator for right party connect probabilities.
  Throws:
    `NullPointerException` - if `probReach` is `null`.

### getReachTimeGenerator

    public ValueGenerator getReachTimeGenerator()

  Returns the value generator for the reach times. A reach time corresponds to the simulation time from the call to `dial()` to the notification of the successful call to the listeners.

  Returns:
    the value generator for reach times.

### setReachTimeGenerator

    public void setReachTimeGenerator(ValueGenerator reachTimeGen)

  Sets the value generator for reach times to `reachTimeGen`. If `reachTimeGen` is `null`, the dial delay for successful calls is reset to 0.

  Parameters:
    `reachTimeGen` - the value generator for reach times.

### getFailTimeGenerator

    public ValueGenerator getFailTimeGenerator()

  Returns the value generator for the fail times. A fail time corresponds to the simulation time from the call to `dial()` to the notification of the failed call to the listeners.

  Returns:
    the value generator for fail times.

### setFailTimeGenerator

    public void setFailTimeGenerator(ValueGenerator failTimeGen)

  Sets the value generator for fail times to `failTimeGen`. If `reachTimeGen` is `null`, the dial delay for successful calls is reset to 0.

  Parameters:
    `failTimeGen` - the value generator for fail times.

### isSuccessful

    public boolean isSuccessful(Contact contact)

  Determines if the call represented by `contact` is a right party connect. Returns `true` if the call is successful, or `false` otherwise.

  The default implementation uses the random stream returned by `getStreamReach()` to return `true` with some probability. The probability of right party connect is generated using the value generator returned by `getProbReachGenerator()`.

  Parameters:
    `contact` - the contact being tested.
  Returns:
    the success indicator.

### isUsingNumActionsEvents

    public boolean isUsingNumActionsEvents()

  Determines if the `dial()` method subtracts the number of action events returned by `getNumActionEvents()` from the return value of `DialerPolicy.getNumDials(Dialer)` in order to determine the number of calls to dial. When dial delays are large enough for the dialer to start often while phone numbers are being composed, the agents of the contact center might receive too many calls to serve, which results in a large number of mismatches. If this flag is enabled (the default), the dialer will take into account the number of calls for which dialing is in progress while determining the number of additional calls to dial.

  Returns:
    `true` if the number of action events must be taken into account while dialing.

### setUsingNumActionEvents

    public void setUsingNumActionEvents(boolean useNumActionEvents)

  Sets the flag for taking the number of action events into account while dialing to `useNumActionEvents`.

  Parameters:
    `useNumActionEvents` - the new value of the flag.
  See Also:
    `isUsingNumActionsEvents()`

### dial

    public void dial()

  Instructs the dialer to try performing outbound calls. This should be called at the end of a service, or at any time the number of agents capable of serving outbound calls increases. This method does nothing if the dialer is disabled.

  The method uses the dialer's policy to get the appropriate number of calls to dial as well as the dialer list. The contact objects representing the calls being made are removed from the dialer list, and each call is tested using `isSuccessful(Contact)`. After the success indicator is determined, a corresponding dial delay is generated, and an event is scheduled to happen if the delay is non-zero. After the delay is elapsed, the appropriate new-contact listeners are notified about the new call.

### notifyListeners

    protected void notifyListeners(Contact contact,
                                   boolean success)

  Notifies registered new-contact listeners about the success or failure of the contact `contact`.

  Parameters:
    `contact` - the contact to broadcast.
    `success` - the success indicator.

### stopDial

    public void stopDial()

  Stops any ongoing dialing of calls. This can be called when the simulation program knows that if the called persons are reached, a mismatch will occur. Cancelled calls are notified as failed calls to the appropriate listeners if dialer action events are kept. However, if the dialer does not keep track of the action events, cancelled calls are lost without any notification.

### save

    public DialerState save()

  Saves the state of this dialer and returns a state object containing the information.

  Returns:
    the state of the dialer.

### restore

    public void restore(DialerState state)

  Restores the state of this dialer with state information included in `state`.

  Parameters:
    `state` - the saved state of the dialer.

### init

    public void init()

  Description copied from interface: `ContactSource`
  Initializes the contact source for a new replication of a simulation. This method should disable the contact source if it is enabled, and cancel any scheduled event. One can assume this method will be called before any simulation replication starts.

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

### isKeepingActionEvents

    public boolean isKeepingActionEvents()

  Determines if this dialer is keeping the action events. If this returns `true`, the `getActionEvents()` method can be used to return a set containing the events. Otherwise, the action events are stored in the event list only, and cannot be enumerated by the dialer. By default, the events are not stored by the dialer.

  Returns:
    the keep action events indicator.

### setKeepingActionEvents

    public void setKeepingActionEvents(boolean keepActionEvents)

  Sets the keep-dial-events indicator to `keepActionEvents`.

  Parameters:
    `keepActionEvents` - the new value of the indicator.
  See Also:
    `isKeepingActionEvents()`

### dialerActionEventsIterator

    public Iterator<DialerActionEvent> dialerActionEventsIterator()

  Constructs and returns an iterator for the dialer-action events. If `isKeepingActionEvents()` returns `true`, the iterator is constructed from the set returned by `getActionEvents()`. Otherwise, an iterator traversing the event list and filtering the appropriate events is constructed and returned.

  Returns:
    the iterator for dialer-action events.

### getActionEvents

    public Set<DialerActionEvent> getActionEvents()

  Returns a set containing all the currently scheduled `DialerActionEvent` objects. If the dialer does not keep track of these events, an `IllegalStateException` is thrown.

  Returns:
    the set of dialer action events.

### getNumActionEvents

    public int getNumActionEvents()

  Returns the number of action events currently scheduled by this dialer. This corresponds to the number of calls the dialer is currently attempting.

  Returns:
    the current number of action events.

### getNumActionEvents

    public int getNumActionEvents(int k)

### 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.

### 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`

### startNoDial

    public void startNoDial()

  This is the same as `start()`, except that no call to `dial()` is made after the dialer is started. `dial()` will then be called only when an agent becomes free.

### 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`

### toString

    public String toString()

  Overrides:
    `toString` in class `Object`

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.