ContactCenters
V. 0.9.9.

umontreal.iro.lecuyer.contactcenters.contact
Class Contact

java.lang.Object
  extended by umontreal.iro.lecuyer.contactcenters.contact.Contact
All Implemented Interfaces:
Cloneable, Comparable<Contact>, Named
Direct Known Subclasses:
Call

public class Contact
extends Object
implements Comparable<Contact>, Named, Cloneable

Represents a contact (phone call, fax, e-mail, etc.) into the contact center. A contact enters the system at a given time, and requires some form of service. If it cannot be served immediately, it joins a queue or leaves the system. In more complex contact centers, contacts can be served more than once and can join several queues sequentially. A contact object holds all the information about a single contact. The arrival time, the total time spent in queue, the total time spent in service, the last joined queue, and the last serving agent group can be obtained from any contact object. Information about the complete path of the contact into the system can also be stored, but this is disabled by default to reduce memory usage.

For easier indexing in skill-based routers, every contact has a numerical type identifier. For waiting queues supporting it, a contact object also holds a priority. The Contact class implements the Comparable interface which allows to define the default priorities when contacts are in priority queues.

Extra information can be added to a contact object using two different mechanisms: by adding attributes to the map returned by getAttributes(), or by defining fields in a subclass. The getAttributes() method returns a Map that can be used to define custom contact attributes dynamically. This can be used for quick implementation of user-defined attributes, but it can reduce performance of the application since look-ups in a map are slower than direct manipulation of fields. Alternatively, this class can be extended to add new attributes as fields. However, the contact subclass will have to be used for communication between parts of the program needing the extra information, which involves casts.

By default, no trunk group is associated with contacts. As a result, every contact can enter the system, since its capacity is infinite. If a contact is associated with a trunk group using setTrunkGroup(umontreal.iro.lecuyer.contactcenters.contact.TrunkGroup), a line is allocated by the router at the time of its arrival. If no line is available in the associated trunk group, the contact is blocked. Otherwise, it is processed and the channel is released when it exits.

Each contact has an associated simulator which is used to schedule contact-related events such as abandonment or service termination. This simulator is determined at the time of construction. If a constructor accepting a Simulator instance is called, the given simulator is used. Otherwise, the default simulator returned by Simulator.getDefaultSimulator() is used.


Constructor Summary
Contact()
          Constructs a new contact object with type identifier 0, priority 1, and the default simulator.
Contact(double priority, int typeId)
          Constructs a new contact object with a priority priority, type identifier typeId, and the default simulator.
Contact(int typeId)
          Constructs a new contact with priority 1, type identifier typeId, and the default simulator.
Contact(Simulator sim)
          Equivalent to constructor Contact(), with the given simulator sim.
Contact(Simulator sim, double priority, int typeId)
          Equivalent to constructor Contact(double,int), with the given simulator sim.
Contact(Simulator sim, int typeId)
          Equivalent to constructor Contact(int), with the given simulator sim.
 
Method Summary
 void addToTotalQueueTime(double delta)
          Adds delta to the currently recorded total queue time returned by getTotalQueueTime().
 void addToTotalServiceTime(double delta)
          Adds delta to the currently recorded total service time returned by getTotalServiceTime() for this contact.
 void beginService(EndServiceEvent ev)
          This method is called when the service of this contact by an agent begins, the end-service event ev representing the contact being served.
 void blocked(int bType)
          This method is called when the contact is blocked by its current router with blocking type bType.
 Contact clone()
          Returns a copy of this contact object.
 int compareTo(Contact otherContact)
          Compares this contact with otherContact.
 void dequeued(DequeueEvent ev)
          This method is called when a contact leaves a queue, the dequeue event ev representing the queued contact.
 void enableStepsTracing()
          Enables steps tracing for this contact object.
 void endContact(EndServiceEvent ev)
          This method is called when the communication between this contact and an agent is terminated.
 void endService(EndServiceEvent ev)
          This method is called when the service of this contact (communication and after-contact work) was terminated, ev containing information about the served contact.
 void enqueued(DequeueEvent ev)
          This method is called by a waiting queue object when a contact is put in queue, the dequeue event ev representing the queued contact.
 void ensureCapacityForDefaultAfterContactTime(int capacity)
          Makes sure that the array containing default after-contact times specific to each agent group contains at least capacity elements.
 void ensureCapacityForDefaultContactTime(int capacity)
          Makes sure that the array containing default contact times specific to each agent group contains at least capacity elements.
 ServiceTimes getAfterContactTimes()
          Returns the after-contact times for this contact.
 double getArrivalTime()
          Returns the contact's arrival simulation time.
 Map<Object,Object> getAttributes()
          Returns the map containing the attributes for this contact.
 ServiceTimes getContactTimes()
          Returns the contact times for this contact.
 double getDefaultAfterContactTime()
          Returns the default duration of after-contact work performed by an agent after this contact is served.
 double getDefaultAfterContactTime(int i)
          Returns the default after-contact time if this contact is served by an agent in group i.
 double getDefaultContactTime()
          Returns the default contact time with an agent.
 double getDefaultContactTime(int i)
          Returns the default contact time if this contact is served by an agent in group i.
 double getDefaultPatienceTime()
          Returns the default patience time for this contact object.
 double getDefaultServiceTime()
          Returns the default service time for this contact object.
 double getDefaultServiceTime(int i)
          Returns the default service time for this contact if served by an agent in group i.
 AgentGroup getLastAgentGroup()
          Returns the last agent group who began serving this contact.
 WaitingQueue getLastWaitingQueue()
          Returns the last waiting queue this contact entered in.
 String getName()
          Returns the name associated with this object.
 int getNumAgentGroups()
          Returns the number of agent groups serving this contact simultaneously at the current simulation time.
 int getNumWaitingQueues()
          Returns the number of waiting queues this contact is waiting in simultaneously, at the current simulation time.
 double getPriority()
          Returns the priority for this contact.
 Router getRouter()
          Returns a reference to the router currently managing this contact, or null if the contact is not currently in a router.
 ContactSource getSource()
          Returns the contact's primary source which has produced this contact object.
 List<ContactStepInfo> getSteps()
          Returns the list containing the steps in the life cycle of this contact.
 double getTotalQueueTime()
          Returns the total time the contact has spent waiting in queues.
 double getTotalServiceTime()
          Returns the total time this contact has spent being served by agents.
 TrunkGroup getTrunkGroup()
          Returns the trunk group this contact will take a trunk from.
 int getTypeId()
          Returns the type identifier for this contact object.
 boolean hasExited()
          Determines if the contact has exited the system.
 boolean isSetDefaultAfterContactTime(int i)
          Determines if an after-contact time was set specifically for agent group i, by using setDefaultAfterContactTime(int,double).
 boolean isSetDefaultContactTime(int i)
          Determines if a contact time was set specifically for agent group i, by using setDefaultContactTime(int,double).
 void setArrivalTime(double arrivalTime)
          Sets the arrival time of this contact to arrivalTime.
 void setDefaultAfterContactTime(double afterContactTime)
          Sets the default after-contact time to afterContactTime.
 void setDefaultAfterContactTime(int i, double t)
          Sets the default after-contact time for this contact to t, if served by an agent in group i.
 void setDefaultContactTime(double contactTime)
          Sets the default contact time to contactTime.
 void setDefaultContactTime(int i, double t)
          Sets the default contact time for this contact if served by an agent in group i to t.
 void setDefaultPatienceTime(double patienceTime)
          Sets the default patience time of this contact to patienceTime.
 void setDefaultServiceTime(double serviceTime)
          Sets the default service time of this contact to serviceTime.
 void setExited(boolean b)
          Sets the exited indicator to b.
 void setName(String name)
          Sets the name of this object to name.
 void setPriority(double newPriority)
          Changes the contact's priority to newPriority.
 void setRouter(Router router)
          This should only be called by the router.
 void setSimulator(Simulator sim)
          Sets the simulator attached to this contact to sim.
 void setSource(ContactSource src)
          Sets the source of this contact to src.
 void setTrunkGroup(TrunkGroup tg)
          Sets the trunk group for this contact to tg.
 void setTypeId(int newTypeId)
          Changes the type identifier for this contact object to newTypeId.
 Simulator simulator()
          Returns a reference to the simulator attached to this contact.
 String toString()
           
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Contact

public Contact()
Constructs a new contact object with type identifier 0, priority 1, and the default simulator.


Contact

public Contact(Simulator sim)
Equivalent to constructor Contact(), with the given simulator sim.

Parameters:
sim - the simulator attached to the new contact.
Throws:
NullPointerException - if sim is null.

Contact

public Contact(int typeId)
Constructs a new contact with priority 1, type identifier typeId, and the default simulator.

Parameters:
typeId - type identifier of the new contact.
Throws:
IllegalArgumentException - if the type identifier is negative.

Contact

public Contact(Simulator sim,
               int typeId)
Equivalent to constructor Contact(int), with the given simulator sim.

Parameters:
sim - the simulator attached to the new contact.
typeId - type identifier of the new contact.
Throws:
NullPointerException - if sim is null.
IllegalArgumentException - if the type identifier is negative.

Contact

public Contact(double priority,
               int typeId)
Constructs a new contact object with a priority priority, type identifier typeId, and the default simulator. The contact type identifier must be non-negative while the priority can be any value. The smaller is the value of priority, the greater is the priority of the contact.

Parameters:
priority - the contact's priority.
typeId - the type identifier of this contact.
Throws:
IllegalArgumentException - if the type identifier is negative.

Contact

public Contact(Simulator sim,
               double priority,
               int typeId)
Equivalent to constructor Contact(double,int), with the given simulator sim.

Parameters:
sim - the simulator attached to the new contact.
priority - the contact's priority.
typeId - type identifier of the new contact.
Throws:
NullPointerException - if sim is null.
IllegalArgumentException - if the type identifier is negative.
Method Detail

simulator

public final Simulator simulator()
Returns a reference to the simulator attached to this contact.

Returns:
the simulator attached to this contact.

setSimulator

public final void setSimulator(Simulator sim)
Sets the simulator attached to this contact to sim. This method should not be called while this contact is in a waiting queue, or being served. The main use of this method is for splitting: a contact is cloned, and a new simulator is assigned to the copy while the original contact keeps the old simulator.

Parameters:
sim - the new simulator.
Throws:
NullPointerException - if sim is null.

getArrivalTime

public double getArrivalTime()
Returns the contact's arrival simulation time. This is the simulation time at which the contact object was constructed.

Returns:
the arrival simulation time of this contact.

setArrivalTime

public void setArrivalTime(double arrivalTime)
Sets the arrival time of this contact to arrivalTime. This method should be called before the contact enters into a waiting queue or an agent group.

Parameters:
arrivalTime - the new arrival time.
Throws:
IllegalArgumentException - if arrivalTime is negative.

getDefaultPatienceTime

public double getDefaultPatienceTime()
Returns the default patience time for this contact object. This corresponds to the maximal queue time before the contact abandons the queue. By default, this is Double.POSITIVE_INFINITY, i.e., no abandonment occurs.

Returns:
the patience time of the contact.

setDefaultPatienceTime

public void setDefaultPatienceTime(double patienceTime)
Sets the default patience time of this contact to patienceTime.

Parameters:
patienceTime - the new patience time of the contact.
Throws:
IllegalArgumentException - if the given patience time is negative or NaN.

getContactTimes

public ServiceTimes getContactTimes()
Returns the contact times for this contact.

Returns:
the contact times.

getAfterContactTimes

public ServiceTimes getAfterContactTimes()
Returns the after-contact times for this contact.

Returns:
the after-contact times.

getDefaultServiceTime

public double getDefaultServiceTime()
Returns the default service time for this contact object. This corresponds to the result of the sum of getDefaultContactTime(), and getDefaultAfterContactTime().

Returns:
the service time of the contact.

setDefaultServiceTime

public void setDefaultServiceTime(double serviceTime)
Sets the default service time of this contact to serviceTime. This method sets the contact time to serviceTime, and resets the after-contact time to 0.

Parameters:
serviceTime - the new service time of the contact.
Throws:
IllegalArgumentException - if the given service time is negative or NaN.

getDefaultContactTime

public double getDefaultContactTime()
Returns the default contact time with an agent. By default, this is set to Double.POSITIVE_INFINITY.

Returns:
the default contact time.

setDefaultContactTime

public void setDefaultContactTime(double contactTime)
Sets the default contact time to contactTime.

Parameters:
contactTime - the new contact time.
Throws:
IllegalArgumentException - if the contact time is negative or NaN.

getDefaultAfterContactTime

public double getDefaultAfterContactTime()
Returns the default duration of after-contact work performed by an agent after this contact is served. By default, this is set to 0.

Returns:
the default after-contact time.

setDefaultAfterContactTime

public void setDefaultAfterContactTime(double afterContactTime)
Sets the default after-contact time to afterContactTime.

Parameters:
afterContactTime - the new after-contact time.
Throws:
IllegalArgumentException - if the after-contact time is negative or NaN.

getDefaultContactTime

public double getDefaultContactTime(int i)
Returns the default contact time if this contact is served by an agent in group i. If this contact time was never set, this returns the result of getDefaultContactTime().

Parameters:
i - the index of the agent group.
Returns:
the contact time.

isSetDefaultContactTime

public boolean isSetDefaultContactTime(int i)
Determines if a contact time was set specifically for agent group i, by using setDefaultContactTime(int,double).

Parameters:
i - the tested agent group index.
Returns:
the result of the test.

setDefaultContactTime

public void setDefaultContactTime(int i,
                                  double t)
Sets the default contact time for this contact if served by an agent in group i to t. Note that setting t to Double.NaN unsets the contact time for the specified agent group.

Parameters:
i - the index of the agent group to set.
t - the new contact time.

ensureCapacityForDefaultContactTime

public void ensureCapacityForDefaultContactTime(int capacity)
Makes sure that the array containing default contact times specific to each agent group contains at least capacity elements. This method should be called before setDefaultContactTime(int,double) to avoid multiple array reallocation.

Parameters:
capacity - the new capacity.

getDefaultAfterContactTime

public double getDefaultAfterContactTime(int i)
Returns the default after-contact time if this contact is served by an agent in group i. If this after-contact time was never set, this returns the result of getDefaultAfterContactTime().

Parameters:
i - the index of the agent group.
Returns:
the after-contact time.

isSetDefaultAfterContactTime

public boolean isSetDefaultAfterContactTime(int i)
Determines if an after-contact time was set specifically for agent group i, by using setDefaultAfterContactTime(int,double).

Parameters:
i - the tested agent group index.
Returns:
the result of the test.

setDefaultAfterContactTime

public void setDefaultAfterContactTime(int i,
                                       double t)
Sets the default after-contact time for this contact to t, if served by an agent in group i. Note that setting t to Double.NaN unsets the after-contact time for the specified agent group.

Parameters:
i - the index of the agent group to set.
t - the new after-contact time.

ensureCapacityForDefaultAfterContactTime

public void ensureCapacityForDefaultAfterContactTime(int capacity)
Makes sure that the array containing default after-contact times specific to each agent group contains at least capacity elements. This method should be called before setDefaultAfterContactTime(int,double) to avoid multiple array reallocation.

Parameters:
capacity - the new capacity.

getDefaultServiceTime

public double getDefaultServiceTime(int i)
Returns the default service time for this contact if served by an agent in group i. This returns the sum of getDefaultContactTime(int) and getDefaultAfterContactTime(int).

Parameters:
i - the tested agent group.
Returns:
the default service time.

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.

getSteps

public List<ContactStepInfo> getSteps()
Returns the list containing the steps in the life cycle of this contact. This list should contain ContactStepInfo implementations only. If steps tracing was not enabled for this contact, this returns null.

Returns:
the list of contact steps, or null if steps tracing is disabled.

enableStepsTracing

public void enableStepsTracing()
Enables steps tracing for this contact object. By default, steps tracing is disabled for better performance and memory usage. This method should be called as soon as the contact is constructed to avoid any loss of information.


getPriority

public double getPriority()
Returns the priority for this contact. The priority is a number which indicates the level of emergency of the contact. A low value represents a high priority.

Returns:
the contact's priority.

setPriority

public void setPriority(double newPriority)
Changes the contact's priority to newPriority. This method should not be called when a contact is in a priority queue.

Parameters:
newPriority - the new contact's priority.

getTotalQueueTime

public double getTotalQueueTime()
Returns the total time the contact has spent waiting in queues. This returns the cumulative waiting time, for all waiting queues visited by the contact.

Returns:
the contact's queue time.

addToTotalQueueTime

public void addToTotalQueueTime(double delta)
Adds delta to the currently recorded total queue time returned by getTotalQueueTime(). This method can be used, e.g., to subtract time passed in a virtual queue from the queue time of a contact.

Parameters:
delta - the amount to add.

getLastWaitingQueue

public WaitingQueue getLastWaitingQueue()
Returns the last waiting queue this contact entered in. If the contact was never queued, this returns null.

Returns:
the last waiting queue of the contact.

getTotalServiceTime

public double getTotalServiceTime()
Returns the total time this contact has spent being served by agents. This returns the cumulative contact time (not after-contact time) for all agents visited by the contact.

Returns:
the contact's service time.

addToTotalServiceTime

public void addToTotalServiceTime(double delta)
Adds delta to the currently recorded total service time returned by getTotalServiceTime() for this contact.

Parameters:
delta - the amount to add.

getLastAgentGroup

public AgentGroup getLastAgentGroup()
Returns the last agent group who began serving this contact. If the contact was never served, this returns null.

Returns:
the last agent group serving the contact.

getTypeId

public int getTypeId()
Returns the type identifier for this contact object.

Returns:
the contact's type identifier.

setTypeId

public void setTypeId(int newTypeId)
Changes the type identifier for this contact object to newTypeId. The type identifier of a contact should not change when it is in a waiting queue or served by an agent.

Parameters:
newTypeId - the contact's new type identifier.
Throws:
IllegalArgumentException - if the type identifier is smaller than 0.

getAttributes

public Map<Object,Object> getAttributes()
Returns the map containing the attributes for this contact. Attributes can be used to add user-defined information to contact objects at runtime, without creating a subclass. However, for maximal efficiency, it is recommended to create a subclass of Contact instead of using attributes.

Returns:
the map containing the attributes for this object.

getSource

public ContactSource getSource()
Returns the contact's primary source which has produced this contact object. If no source has created this contact, this returns null. If a contact results from a call back managed by a dialer, this returns the preceding arrival process which created the contact, not the dialer managing the call back.

Returns:
the source having created this contact.

setSource

public void setSource(ContactSource src)
Sets the source of this contact to src. Once a non-null source was given, it cannot be changed. If one tries to change the contact source, an IllegalStateException is thrown.

Parameters:
src - the new contact source.
Throws:
IllegalStateException - if one tries to change the contact source.

getTrunkGroup

public TrunkGroup getTrunkGroup()
Returns the trunk group this contact will take a trunk from. By default, this returns null.

Returns:
the associated trunk group.

setTrunkGroup

public void setTrunkGroup(TrunkGroup tg)
Sets the trunk group for this contact to tg. This method does not allocate a trunk in the group; this task is performed by the router.

Parameters:
tg - the new trunk group.

getRouter

public Router getRouter()
Returns a reference to the router currently managing this contact, or null if the contact is not currently in a router.

Returns:
the router taking care of this contact.

setRouter

public void setRouter(Router router)
This should only be called by the router. Associates the router router to this contact.

Parameters:
router - the new router.

hasExited

public boolean hasExited()
Determines if the contact has exited the system. If a contact has exited the system, it will not be admitted into a router for further processing. This is used to prevent contacts from incorrectly entering in the router several times.

Returns:
the exited indicator.

setExited

public void setExited(boolean b)
Sets the exited indicator to b.

Parameters:
b - the exited indicator.

enqueued

public void enqueued(DequeueEvent ev)
This method is called by a waiting queue object when a contact is put in queue, the dequeue event ev representing the queued contact.

Parameters:
ev - the dequeue event associated with the contact.

dequeued

public void dequeued(DequeueEvent ev)
This method is called when a contact leaves a queue, the dequeue event ev representing the queued contact.

Parameters:
ev - the dequeue event associated with the contact.

blocked

public void blocked(int bType)
This method is called when the contact is blocked by its current router with blocking type bType. The getRouter() method can be used to access the reference to the router which blocked this contact while bType indicates the reason why the contact was blocked.

Parameters:
bType - the contact blocking type.

beginService

public void beginService(EndServiceEvent ev)
This method is called when the service of this contact by an agent begins, the end-service event ev representing the contact being served.

Parameters:
ev - the event occurring at the end of the service.

endContact

public void endContact(EndServiceEvent ev)
This method is called when the communication between this contact and an agent is terminated. The end-service event ev can be used to obtain information about the end of communication.

Parameters:
ev - the end-service event associated with the contact.

endService

public void endService(EndServiceEvent ev)
This method is called when the service of this contact (communication and after-contact work) was terminated, ev containing information about the served contact.

Parameters:
ev - the end-service event associated with the contact.

getNumWaitingQueues

public int getNumWaitingQueues()
Returns the number of waiting queues this contact is waiting in simultaneously, at the current simulation time.

Returns:
the number of waiting queues this contact is waiting in.

getNumAgentGroups

public int getNumAgentGroups()
Returns the number of agent groups serving this contact simultaneously at the current simulation time.

Returns:
the number of agent groups serving this contact simultaneously.

compareTo

public int compareTo(Contact otherContact)
Compares this contact with otherContact. By default, the contacts are ordered in ascending order of priority. The lower the priority value, the more important the contact will be. If two compared contacts share the same priority, they are ordered using their arrival times.

Specified by:
compareTo in interface Comparable<Contact>
Parameters:
otherContact - the other contact this contact is compared to.
Returns:
a value smaller than 0 if this contact is greater than the other object, 0 if it is equal, or a value greater than 0 if it is smaller.

toString

public String toString()
Overrides:
toString in class Object

clone

public Contact clone()
Returns a copy of this contact object. In contrast with the original contact object, the returned copy is not in any waiting queue, router, or agent group. The map containing the attributes, if getAttributes() returns a non-null value, is cloned, but the elements in the map are not cloned. If contact steps tracing is enabled, the list of steps as well as the step objects are cloned.

Overrides:
clone in class Object
Returns:
the copy of the contact.

ContactCenters
V. 0.9.9.

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