ContactCenters
V. 0.9.9.

umontreal.iro.lecuyer.contactcenters.dialer
Class Dialer

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

ContactCenters
V. 0.9.9.

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