ContactCenters
V. 0.9.9.

umontreal.iro.lecuyer.contactcenters.server
Class DetailedAgentGroup

java.lang.Object
  extended by java.util.AbstractCollection<EndServiceEvent>
      extended by umontreal.iro.lecuyer.contactcenters.server.AgentGroup
          extended by umontreal.iro.lecuyer.contactcenters.server.DetailedAgentGroup
All Implemented Interfaces:
Iterable<EndServiceEvent>, Collection<EndServiceEvent>, Initializable, Named, PeriodChangeListener

public class DetailedAgentGroup
extends AgentGroup

Extends the AgentGroup class for a detailed agent group, where individual agents can be differentiated. When serving a contact, a specific agent, represented by an instance of the class Agent, must be chosen automatically using the longest idle policy, or manually. At any time during the simulation, agents can be added to or removed from the group. Agents can also be made available or unavailable to process new contacts.


Field Summary
 
Fields inherited from class umontreal.iro.lecuyer.contactcenters.server.AgentGroup
ecTypeRet, esTypeRet
 
Constructor Summary
DetailedAgentGroup(int n)
          Constructs a new agent group with n available agents.
DetailedAgentGroup(PeriodChangeEvent pce, int[] ns)
          Constructs a new agent group with the period-change event pce, and ns[p] agents in the period p.
DetailedAgentGroup(Simulator sim, int n)
           
 
Method Summary
 void addAgent(Agent agent)
          Adds the agent agent to the agent group.
protected  Agent createAgent()
          Constructs a new agent object.
 boolean endContact(EndServiceEvent es, int ecType)
          Aborts the communication with a contact identified by the end-service event es, overriding the event's end-contact type with ecType.
 boolean endService(EndServiceEvent es, int esType)
          Aborts the service of a contact identified by the end-service event es, overriding the event's end-service type with esType.
protected  double getAfterContactTime(EndServiceEvent es)
          By default, this method calls Agent.getAfterContactTime(Contact).
 List<Agent> getBusyAgents()
          Returns a list containing all the busy agent objects which are members of this group.
protected  double getContactTime(EndServiceEvent es)
          By default, this method calls Agent.getContactTime(Contact).
 double getEfficiency()
          Returns the current efficiency of this agent group, which is given by the fraction of available agents (free or busy) over the total number of agents.
 List<Agent> getGhostAgents()
          Returns a list containing all the ghost agent objects having been members of this agent group and finishing an in-progress service.
 List<Agent> getIdleAgents()
          Returns a list containing all the idle agent objects.
 Agent getLongestIdleAgent()
          Returns the idle agent with the longest idle time in this agent group.
 int getNumAgents()
          Returns the total number of agents in the agent group.
 int getNumBusyAgents()
          Returns $ \Nb$[i](t), the number of busy agents in the group.
 int getNumFreeAgents()
          Returns the number of free agents available to process contacts.
 int getNumGhostAgents()
          Returns $ \Ng$[i](t), the number of agents that should disappear immediately after they have finished serving a contact.
 void init()
          Initializes the agent group for a new simulation replication.
 boolean isAddingAgent()
          Determines if this agent group is currently adding an agent using the addAgent(Agent) method.
 boolean isRemovingAgent()
          Determines if an agent is currently being removed using removeAgent(Agent).
protected  void notifyBeginService(EndServiceEvent es)
          Notifies every registered listener that a service, represented by es, was started by this agent group.
protected  void notifyEndContact(EndServiceEvent es, boolean aborted)
          Notifies every registered listener that the communication part of the service represented by es has ended.
protected  void notifyEndService(EndServiceEvent es, boolean aborted)
          Notifies every registered listener that the service represented by es is finished.
 void removeAgent(Agent agent)
          Removes the agent agent from this agent group.
 void restore(AgentGroupState state)
          Restores the state of this agent group by using the restore method of state.
 DetailedAgentGroupState save()
          Constructs a new AgentGroupState instance holding the state of this agent group.
 EndServiceEventDetailed serve(Contact contact)
          Begins the service of the contact contact by the agent with the longest idle time in this group.
 EndServiceEventDetailed serve(Contact contact, Agent agent)
          Begins the service of the contact contact by the agent agent.
 EndServiceEventDetailed serve(Contact contact, Agent agent, double contactTime, int ecType)
          This is similar to serve(Contact,Agent), except that the specified contact time and end-contact type are used instead of generated ones.
 EndServiceEventDetailed serve(Contact contact, Agent agent, double contactTime, int ecType, double afterContactTime, int esType)
          This is similar to serve(Contact,Agent) except that the contact and after-contact times are specified explicitly.
 EndServiceEventDetailed serve(Contact contact, double contactTime, int ecType)
          This is similar to AgentGroup.serve(Contact), except that the specified contact time and end-contact type are used instead of generated ones.
 EndServiceEventDetailed serve(Contact contact, double contactTime, int ecType, double afterContactTime, int esType)
          This is similar to AgentGroup.serve(Contact) except that the contact and after-contact times are specified explicitly.
 EndServiceEvent serve(EndServiceEvent oldEndServiceEvent)
          Starts the service of a contact based on information stored in the old end-service event oldEndServiceEvent.
 void setEfficiency(double eff)
          Sets the efficiency of the agents in the group.
 void setNumAgents(int n)
          Sets the number of agents in the agent group to n.
 void setSimulator(Simulator sim)
          Sets the attached simulator of this agent group to sim.
 Simulator simulator()
          Returns a reference to the simulator used to obtain simulation times at which agents are added or become free, for computing login and idle times of agents.
 
Methods inherited from class umontreal.iro.lecuyer.contactcenters.server.AgentGroup
addAgentGroupListener, changePeriod, clearAgentGroupListeners, contains, endServiceEventsIterator, getAfterContactTimeGenerator, getAgentGroupListeners, getAllNumAgents, getAttributes, getContactTimeGenerator, getEndServiceEvents, getId, getName, getNumAgents, getNumBusyAgents, getNumIdleAgents, getPeriodChangeEvent, isKeepingEndServiceEvents, iterator, notifyChange, notifyInit, removeAgentGroupListener, setAfterContactTimeGenerator, setContactTimeGenerator, setId, setKeepingEndServiceEvents, setName, setNumAgents, setNumAgents, size, stop, toString
 
Methods inherited from class java.util.AbstractCollection
add, addAll, clear, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Collection
equals, hashCode
 

Constructor Detail

DetailedAgentGroup

public DetailedAgentGroup(int n)
Constructs a new agent group with n available agents.

Parameters:
n - the number of agents in the group.

DetailedAgentGroup

public DetailedAgentGroup(Simulator sim,
                          int n)

DetailedAgentGroup

public DetailedAgentGroup(PeriodChangeEvent pce,
                          int[] ns)
Constructs a new agent group with the period-change event pce, and ns[p] agents in the period p. The agent group is automatically added to the period-change event for the number of agents to be set automatically during the simulation.

Parameters:
pce - the period-change event defining the simulation periods.
ns - the number of agents in the group for each period.
Throws:
IllegalArgumentException - if there is not a number of agents for each period.
Method Detail

simulator

public Simulator simulator()
Returns a reference to the simulator used to obtain simulation times at which agents are added or become free, for computing login and idle times of agents.

Returns:
the attached simulator.

setSimulator

public void setSimulator(Simulator sim)
Sets the attached simulator of this agent group to sim.

Parameters:
sim - the new attached simulator.

getNumAgents

public int getNumAgents()
Description copied from class: AgentGroup
Returns the total number of agents in the agent group. It is possible that only a fraction of these agents can serve contacts.

Overrides:
getNumAgents in class AgentGroup
Returns:
the total number of agents in the group.

setNumAgents

public void setNumAgents(int n)
Sets the number of agents in the agent group to n. When the number of agents is increased, the createAgent() method is used to create the required new agents. When removing agents, the method uses the busyness status (busy agents are removed only if there is no more idle agent), and the login time (the agent with the longest login time is chosen) to decide which agent to remove. The methods addAgent(Agent) and removeAgent(Agent) are used to add and remove the agents.

Overrides:
setNumAgents in class AgentGroup
Parameters:
n - the new number of agents.
Throws:
IllegalArgumentException - if the number of agents is negative.

addAgent

public void addAgent(Agent agent)
Adds the agent agent to the agent group. When an agent is a ghost, it can be added back to its previous group, but it cannot be added to another group until he has terminated his in-progress service. When an agent is not in any group and not serving any contact, he can be added to any group.

Parameters:
agent - the agent being added.
Throws:
NullPointerException - if agent is null.
IllegalArgumentException - if the agent is already in a group.

removeAgent

public void removeAgent(Agent agent)
Removes the agent agent from this agent group. If the agent is serving a contact, it becomes a ghost until the contact is served.

Parameters:
agent - the agent being removed.
Throws:
NullPointerException - if agent is null.
IllegalArgumentException - if the removed agent is not in this group.

isAddingAgent

public boolean isAddingAgent()
Determines if this agent group is currently adding an agent using the addAgent(Agent) method. This method can be used by AgentGroupListener.agentGroupChange(AgentGroup) to determine the origin of a change in an observed agent group. If an agent is added explicitly using addAgent(Agent), this method returns true. Otherwise, the change originates from a call to setNumAgents(int).

Returns:
the result of the test.

isRemovingAgent

public boolean isRemovingAgent()
Determines if an agent is currently being removed using removeAgent(Agent). This method can be used by an agent-group listener as described in isAddingAgent().

Returns:
the result of the test.

init

public void init()
Description copied from class: AgentGroup
Initializes the agent group for a new simulation replication. It must be called after the simulator is initialized and before it is started.

Specified by:
init in interface Initializable
Overrides:
init in class AgentGroup

getIdleAgents

public List<Agent> getIdleAgents()
Returns a list containing all the idle agent objects. These idle agents are not necessarily available to process contacts.

Returns:
the idle agents.

getBusyAgents

public List<Agent> getBusyAgents()
Returns a list containing all the busy agent objects which are members of this group. This excludes ghost agents since they have been removed from the group.

Returns:
the busy agents.

getGhostAgents

public List<Agent> getGhostAgents()
Returns a list containing all the ghost agent objects having been members of this agent group and finishing an in-progress service.

Returns:
the ghost agents.

getNumFreeAgents

public int getNumFreeAgents()
Returns the number of free agents available to process contacts. These are the free agents for which Agent.isAvailable() returns true.

Overrides:
getNumFreeAgents in class AgentGroup
Returns:
the number of free agents.

getNumGhostAgents

public int getNumGhostAgents()
Description copied from class: AgentGroup
Returns $ \Ng$[i](t), the number of agents that should disappear immediately after they have finished serving a contact. Such ghost agents appear when the total number of agents is set to be smaller than the number of busy agents.

Overrides:
getNumGhostAgents in class AgentGroup
Returns:
the number of ghost agents.

getNumBusyAgents

public int getNumBusyAgents()
Description copied from class: AgentGroup
Returns $ \Nb$[i](t), the number of busy agents in the group. At any time during the simulation, the value returned by this method should be smaller than or equal to the sum of AgentGroup.getNumAgents() and AgentGroup.getNumGhostAgents().

Overrides:
getNumBusyAgents in class AgentGroup
Returns:
the number of busy agents.

getEfficiency

public double getEfficiency()
Returns the current efficiency of this agent group, which is given by the fraction of available agents (free or busy) over the total number of agents. This efficiency can change when the agents are added to or removed from the group, or when the availability status of agents changes.

Overrides:
getEfficiency in class AgentGroup
Returns:
the efficiency of the agent group.

setEfficiency

public void setEfficiency(double eff)
Sets the efficiency of the agents in the group. The method computes a target number of available agents by multiplying Ni(t) by eff and rounding the result to the nearest integer. Some agents are then made available or unavailable to meet this target, starting with free agents, then with busy agents. This method is provided for compatibility with the AgentGroup base class. The recommended way to change the efficiency is to change the availability of each individual agent by using Agent.setAvailable(boolean). This permits the implementation of more complex and realistic models of agents' availability.

Overrides:
setEfficiency in class AgentGroup
Parameters:
eff - the new agent group's efficiency.
Throws:
IllegalArgumentException - if eff is smaller than 0 or greater than 1.

getLongestIdleAgent

public Agent getLongestIdleAgent()
Returns the idle agent with the longest idle time in this agent group. If all agents are busy or unavailable to process new contacts, this returns null.

Returns:
the idle agent with the longest idle time.

serve

public EndServiceEventDetailed serve(Contact contact)
Begins the service of the contact contact by the agent with the longest idle time in this group. After the agent is selected, the serve(Contact,Agent) method is called to begin the service.

Overrides:
serve in class AgentGroup
Parameters:
contact - the contact being served.
Returns:
the end of service event being created.

serve

public EndServiceEventDetailed serve(Contact contact,
                                     double contactTime,
                                     int ecType)
Description copied from class: AgentGroup
This is similar to AgentGroup.serve(Contact), except that the specified contact time and end-contact type are used instead of generated ones. The after-contact time is generated as in AgentGroup.serve(Contact). The main purpose of this method is for recreating an end-service event based on saved state information.

Overrides:
serve in class AgentGroup
Parameters:
contact - the contact being served.
contactTime - the communication time of the contact with the agent.
ecType - the end-contact type.
Returns:
the end-service event representing the service.

serve

public EndServiceEventDetailed serve(Contact contact,
                                     double contactTime,
                                     int ecType,
                                     double afterContactTime,
                                     int esType)
Description copied from class: AgentGroup
This is similar to AgentGroup.serve(Contact) except that the contact and after-contact times are specified explicitly. The main purpose of this method is for recreating an end-service event based on saved state information.

Overrides:
serve in class AgentGroup
Parameters:
contact - the contact being served.
contactTime - the contact time.
ecType - the end-contact type.
afterContactTime - the after-contact time.
esType - the end-service type.
Returns:
the end-service event representing the service.

serve

public EndServiceEventDetailed serve(Contact contact,
                                     Agent agent)
Begins the service of the contact contact by the agent agent. Returns the constructed end-service event. Communication times are generated using getContactTime(EndServiceEvent), and after-contact times are obtained using getAfterContactTime(EndServiceEvent).

Parameters:
contact - the contact being served.
agent - the agent serving the contact.
Returns:
the constructed end-service event.
Throws:
NullPointerException - if an argument is null.
IllegalArgumentException - if the given agent is in the wrong agent group.
IllegalStateException - if the agent is not available or already serving a contact.

serve

public EndServiceEventDetailed serve(Contact contact,
                                     Agent agent,
                                     double contactTime,
                                     int ecType)
This is similar to serve(Contact,Agent), except that the specified contact time and end-contact type are used instead of generated ones. The after-contact time is generated as in serve(Contact). The main purpose of this method is for recreating an end-service event based on saved state information.

Parameters:
contact - the contact being served.
agent - the agent serving the contact.
contactTime - the communication time of the contact with the agent.
ecType - the end-contact type.
Returns:
the end-service event representing the service.
Throws:
IllegalStateException - if no free agent is available.

serve

public EndServiceEventDetailed serve(Contact contact,
                                     Agent agent,
                                     double contactTime,
                                     int ecType,
                                     double afterContactTime,
                                     int esType)
This is similar to serve(Contact,Agent) except that the contact and after-contact times are specified explicitly. The main purpose of this method is for recreating an end-service event based on saved state information.

Parameters:
contact - the contact being served.
agent - the agent serving the contact.
contactTime - the contact time.
ecType - the end-contact type.
afterContactTime - the after-contact time.
esType - the end-service type.
Returns:
the end-service event representing the service.
Throws:
IllegalStateException - if no free agent is available.

serve

public EndServiceEvent serve(EndServiceEvent oldEndServiceEvent)
Description copied from class: AgentGroup
Starts the service of a contact based on information stored in the old end-service event oldEndServiceEvent. If the event contains information about the effective end-contact time, i.e., if EndServiceEvent.contactDone() returns true, the method uses the effective end-contact time and end-contact type, and the scheduled end-service time and end-service type to start the service. Otherwise, it uses the scheduled end-contact time and end-contact type only.

Overrides:
serve in class AgentGroup
Parameters:
oldEndServiceEvent - the old end-service event.
Returns:
the new end-service event.

save

public DetailedAgentGroupState save()
Description copied from class: AgentGroup
Constructs a new AgentGroupState instance holding the state of this agent group. The method AgentGroup.isKeepingEndServiceEvents() must return true for this method to be called, because the state includes every contact served by agents in this group.

Overrides:
save in class AgentGroup
Returns:
the state of this agent group.

restore

public void restore(AgentGroupState state)
Description copied from class: AgentGroup
Restores the state of this agent group by using the restore method of state.

Overrides:
restore in class AgentGroup
Parameters:
state - the saved state of this agent group.

getContactTime

protected double getContactTime(EndServiceEvent es)
By default, this method calls Agent.getContactTime(Contact). If this returns Double.NaN, the method of the superclass is called.

Overrides:
getContactTime in class AgentGroup
Parameters:
es - the end-service event.
Returns:
the generated contact time.

getAfterContactTime

protected double getAfterContactTime(EndServiceEvent es)
By default, this method calls Agent.getAfterContactTime(Contact). If the called method returns Double.NaN, the method calls the equivalent method of the superclass.

Overrides:
getAfterContactTime in class AgentGroup
Parameters:
es - the end-service event.
Returns:
the generated after-contact time.

endContact

public boolean endContact(EndServiceEvent es,
                          int ecType)
Description copied from class: AgentGroup
Aborts the communication with a contact identified by the end-service event es, overriding the event's end-contact type with ecType. Returns true if the operation was successful, or false otherwise. Note that the after-contact time is generated and after-contact work is performed. One must call AgentGroup.endService(EndServiceEvent,int) after this method to completely abort the service.

Overrides:
endContact in class AgentGroup
Parameters:
es - the end-service event representing the service to be aborted.
ecType - the type of communication termination.
Returns:
the success indicator of the operation.

endService

public boolean endService(EndServiceEvent es,
                          int esType)
Description copied from class: AgentGroup
Aborts the service of a contact identified by the end-service event es, overriding the event's end-service type with esType. Returns true if the operation was successful, or false otherwise. For this method to return true, the communication between the agent and the contactor must have ended. One can use AgentGroup.endContact(EndServiceEvent,int) to abort the communication.

Overrides:
endService in class AgentGroup
Parameters:
es - the end-service event representing the after-contact work to be aborted.
esType - the type of service termination.
Returns:
the success indicator of the operation.

notifyBeginService

protected void notifyBeginService(EndServiceEvent es)
Description copied from class: AgentGroup
Notifies every registered listener that a service, represented by es, was started by this agent group.

Overrides:
notifyBeginService in class AgentGroup
Parameters:
es - the end-service event representing the service.

notifyEndContact

protected void notifyEndContact(EndServiceEvent es,
                                boolean aborted)
Description copied from class: AgentGroup
Notifies every registered listener that the communication part of the service represented by es has ended.

Overrides:
notifyEndContact in class AgentGroup
Parameters:
es - the end-service event.
aborted - determines if the service was aborted or terminated normally.

notifyEndService

protected void notifyEndService(EndServiceEvent es,
                                boolean aborted)
Description copied from class: AgentGroup
Notifies every registered listener that the service represented by es is finished.

Overrides:
notifyEndService in class AgentGroup
Parameters:
es - the end-service vent representing the ended service.
aborted - determines if the after-contact work was aborted or terminated normally.

createAgent

protected Agent createAgent()
Constructs a new agent object. This method can be overridden to create subclasses of Agent containing additional information.

Returns:
the constructed agent object.

ContactCenters
V. 0.9.9.

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