ContactCenters
V. 0.9.9.

umontreal.iro.lecuyer.contactcenters.queue
Class WaitingQueue

java.lang.Object
  extended by java.util.AbstractCollection<E>
      extended by java.util.AbstractQueue<DequeueEvent>
          extended by umontreal.iro.lecuyer.contactcenters.queue.WaitingQueue
All Implemented Interfaces:
Iterable<DequeueEvent>, Collection<DequeueEvent>, Queue<DequeueEvent>, Initializable, Named
Direct Known Subclasses:
PriorityWaitingQueue, QueueWaitingQueue, StandardWaitingQueue

public abstract class WaitingQueue
extends AbstractQueue<DequeueEvent>
implements Initializable, Named

Represents a waiting queue where contacts are added if they cannot be served immediately. The queue contains DequeueEvent objects being scheduled to happen at the time of automatic removal, e.g., abandonment, disconnection, etc. These dequeue events, which encapsulate contacts, are used to support abandonment as well as other types of exits of queue. When a contact is added at the end of the queue using the add(Contact) method, its dequeue event is constructed, and scheduled if a maximal queue time is available. If the dequeue event occurs, the associated queued contact is removed from the queue. Queued contacts can also be removed manually using the removeFirst(int) or removeLast(int) methods (this cancels the appropriate dequeue event), or visited by an iterator returned by iterator(int). An iterator is useful to enumerate queued contacts, and to remove arbitrary ones.

All registered waiting-queue listeners are notified about added and removed contacts. The reason of the removal is available for listeners through an integer called the dequeue type, encapsulated in the dequeue event. For example, this permits statistical collectors to distinguish abandonment from disconnection.

This abstract class does not implement a data structure for storing queued contacts. The subclasses StandardWaitingQueue, QueueWaitingQueue, and PriorityWaitingQueue implement such data structures.

Note: the WaitingQueueListener implementations are notified in the order of the list returned by getWaitingQueueListeners(), and a waiting-queue listener modifying the list of listeners by using addWaitingQueueListener(WaitingQueueListener) or removeWaitingQueueListener(WaitingQueueListener) could result in unpredictable behavior.


Field Summary
protected  int dqTypeRet
          Contains the dequeue type generated by getMaximalQueueTime(DequeueEvent).
 
Constructor Summary
WaitingQueue()
          Constructs a new waiting queue.
 
Method Summary
 DequeueEvent add(Contact contact)
          Adds the contact contact to the waiting queue and returns a reference to the constructed dequeue event.
 DequeueEvent add(Contact contact, double enqueueTime, double maxQueueTime, int dqType)
          This is the same as add(Contact), except that the enqueue time, maximal queue time and dequeue type if the queue time is reached, are specified explicitly.
 DequeueEvent addFromOldEvent(DequeueEvent oldDequeueEvent)
          Adds a contact into the queue by using the information stored in an old dequeue event oldDequeueEvent.
 void addWaitingQueueListener(WaitingQueueListener listener)
          Adds the new waiting-queue listener listener to this object.
 void clear()
           
 void clear(int dqType)
          Removes all the contacts contained into this waiting queue with dequeue type dqType.
 void clearWaitingQueueListeners()
          Removes all waiting-queue listeners registered with this waiting queue.
protected abstract  void elementsAdd(DequeueEvent dqEvent)
          Adds the new dequeued event dqEvent to the internal data structure representing the waiting queue.
protected abstract  void elementsClear()
          Clears all elements in the data structure representing the queued contacts.
protected abstract  DequeueEvent elementsGetFirst()
          Returns the first element of the waiting queue's internal data structure, or throws a NoSuchElementException if no such element exists.
protected abstract  DequeueEvent elementsGetLast()
          Returns the last element of the waiting queue's internal data structure, or throws a NoSuchElementException if no such element exists.
protected abstract  boolean elementsIsEmpty()
          Determines if the internal waiting queue data structure is empty.
protected abstract  Iterator<DequeueEvent> elementsIterator()
          Returns an iterator capable of traversing, in the correct order, the elements in the waiting queue's internal data structure.
protected abstract  DequeueEvent elementsRemoveFirst()
          Removes and returns the first element in the waiting queue's internal data structure.
protected abstract  DequeueEvent elementsRemoveLast()
          Removes and returns the last element in the waiting queue's internal data structure.
 Map<Object,Object> getAttributes()
          Returns the map containing the attributes for this waiting queue.
 int getDefaultDequeueType()
          Returns the default dequeue type used by this object when the user does not specify a dequeue type explicitly.
 DequeueEvent getDequeueEvent(Contact contact)
          Returns the dequeue event for the contact contact.
 DequeueEvent getFirst()
          Returns the dequeue event representing the first contact in the queue, or throws a NoSuchElementException if the queue is empty.
 int getId()
          Returns the identifier associated with this queue.
 DequeueEvent getLast()
          Returns the dequeue event representing the last contact in the queue, or throws a NoSuchElementException if the queue is empty.
protected  double getMaximalQueueTime(DequeueEvent ev)
          Generates and returns the maximal queue time for the queued contact represented by ev.
 ValueGenerator getMaximalQueueTimeGenerator(int dqType)
          Returns the maximal queue time generator associated with dequeue type dqType for this waiting queue.
 String getName()
          Returns the name associated with this object.
 List<WaitingQueueListener> getWaitingQueueListeners()
          Returns an unmodifiable list containing all the waiting-queue listeners registered with this waiting queue.
 void init()
          Initializes this waiting queue for a new simulation replication.
 boolean isEmpty()
           
 Iterator<DequeueEvent> iterator()
          This is similar to iterator(int), except it uses the default dequeue type returned by getDefaultDequeueType().
 Iterator<DequeueEvent> iterator(int dqType)
          Returns an iterator allowing the dequeue events representing contacts in queue to be enumerated.
protected  void notifyDequeued(DequeueEvent ev)
          Notifies every registered listener that a contact left this queue, this event being represented by ev.
protected  void notifyEnqueued(DequeueEvent ev)
          Notifies every registered listener that a contact was enqueued, this event being represented by ev.
protected  void notifyInit()
          Notifies every registered listener that this waiting queue was initialized.
 boolean offer(DequeueEvent ev)
           
 DequeueEvent peek()
           
 DequeueEvent poll()
           
 boolean remove(Contact contact, int dqType)
          Removes the contact contact from the waiting queue.
 boolean remove(DequeueEvent dqEvent, int dqType)
          Removes the contact identified by the dequeue event dqEvent, setting its effective dequeue type to dqType.
 boolean remove(Object o)
           
 DequeueEvent removeFirst(int dqType)
          Removes the first contact in the waiting queue and returns the corresponding dequeue event.
 DequeueEvent removeLast(int dqType)
          Removes the last contact in the waiting queue and returns the corresponding dequeue event.
 void removeWaitingQueueListener(WaitingQueueListener listener)
          Removes the waiting-queue listener listener from this object.
 void restore(WaitingQueueState state)
          Restores the state of the waiting queue by using the restore method of state.
 WaitingQueueState save()
          Constructs a new WaitingQueueState object holding the current state of this waiting queue, i.e., every queued contact.
 void setDefaultDequeueType(int dqTypeDefault)
          Sets the default dequeue type to dqTypeDefault.
 void setId(int id)
          Sets the identifier of this queue to id.
 void setMaximalQueueTimeGenerator(int dqType, ValueGenerator dqgen)
          Changes the maximal queue time generator associated with dequeue type dqType for this waiting queue to dqgen.
 void setName(String name)
          Sets the name of this object to name.
 int size()
          Returns the number of contacts in this waiting queue.
 int size(int k)
          Returns the number of contacts of type k in this waiting queue.
 String toString()
           
 
Methods inherited from class java.util.AbstractQueue
add, addAll, element, remove
 
Methods inherited from class java.util.AbstractCollection
contains, containsAll, 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
contains, containsAll, equals, hashCode, removeAll, retainAll, toArray, toArray
 

Field Detail

dqTypeRet

protected int dqTypeRet
Contains the dequeue type generated by getMaximalQueueTime(DequeueEvent).

Constructor Detail

WaitingQueue

public WaitingQueue()
Constructs a new waiting queue.

Method Detail

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.

init

public void init()
Initializes this waiting queue for a new simulation replication. This removes all the contacts from the queue without notification of individual contacts to the listeners.

Specified by:
init in interface Initializable

clear

public void clear()
Specified by:
clear in interface Collection<DequeueEvent>
Overrides:
clear in class AbstractQueue<DequeueEvent>

isEmpty

public boolean isEmpty()
Specified by:
isEmpty in interface Collection<DequeueEvent>
Overrides:
isEmpty in class AbstractCollection<DequeueEvent>

offer

public boolean offer(DequeueEvent ev)
Specified by:
offer in interface Queue<DequeueEvent>

peek

public DequeueEvent peek()
Specified by:
peek in interface Queue<DequeueEvent>

poll

public DequeueEvent poll()
Specified by:
poll in interface Queue<DequeueEvent>

clear

public void clear(int dqType)
Removes all the contacts contained into this waiting queue with dequeue type dqType. In contrast with init(), any removed contact is notified to the registered listeners.

Parameters:
dqType - the dequeue type of the removed contacts.

size

public int size()
Returns the number of contacts in this waiting queue.

Specified by:
size in interface Collection<DequeueEvent>
Specified by:
size in class AbstractCollection<DequeueEvent>
Returns:
the number of contacts in the waiting queue.

size

public int size(int k)
Returns the number of contacts of type k in this waiting queue.

Parameters:
k - the tested contact type.
Returns:
the number of contacts of type k in the queue.

add

public DequeueEvent add(Contact contact)
Adds the contact contact to the waiting queue and returns a reference to the constructed dequeue event. The maximal queue time is obtained using getMaximalQueueTime(DequeueEvent), and an event is scheduled with its corresponding dequeue type. In case of a zero or negative maximal queue time, the contact is enqueued then immediately dequeued. Otherwise, the contact is enqueued and a dequeue event is scheduled if the maximal queue time is not Double.POSITIVE_INFINITY or Double.NaN. The returned event can be used to get information about the queued contact and to manually remove it from the queue. If it is directly cancelled, the contact will not leave the queue automatically.

Parameters:
contact - the contact to be added.
Returns:
a reference to the dequeue event.

add

public DequeueEvent add(Contact contact,
                        double enqueueTime,
                        double maxQueueTime,
                        int dqType)
This is the same as add(Contact), except that the enqueue time, maximal queue time and dequeue type if the queue time is reached, are specified explicitly.

Parameters:
contact - the contact being queued.
enqueueTime - the time at which the contact joined the queue.
maxQueueTime - the maximal queue time.
dqType - the dequeue type if the maximal queue time is reached.
Returns:
the dequeue event representing the queued contact.

addFromOldEvent

public DequeueEvent addFromOldEvent(DequeueEvent oldDequeueEvent)
Adds a contact into the queue by using the information stored in an old dequeue event oldDequeueEvent. This method extracts the queued contact, the scheduled maximal queue time, and the scheduled dequeue type from the given event, and uses that information to call add(Contact,double,double,int).

Parameters:
oldDequeueEvent - the old dequeue event.
Returns:
the new dequeue event representing the queued contact.

getMaximalQueueTime

protected double getMaximalQueueTime(DequeueEvent ev)
Generates and returns the maximal queue time for the queued contact represented by ev. The method can store a dequeue type in the protected field dqTypeRet if the default value of 1 is not appropriate.

By default, a MinValueGenerator is used. For each dequeue type q with an associated value generator, a maximal queue time Vq is generated. The scheduled queue time is Vq* = $ \htmin_{q}^{}${Vq}, and the dequeue type is q*.

Parameters:
ev - the dequeue event representing the queued contact.
Returns:
the maximal queue time.

remove

public boolean remove(DequeueEvent dqEvent,
                      int dqType)
Removes the contact identified by the dequeue event dqEvent, setting its effective dequeue type to dqType. Returns true if the removal was successful, false otherwise.

Parameters:
dqEvent - the dequeue event.
dqType - the effective dequeue type.
Returns:
the success indicator of the operation.

remove

public boolean remove(Object o)
Specified by:
remove in interface Collection<DequeueEvent>
Overrides:
remove in class AbstractCollection<DequeueEvent>

remove

public boolean remove(Contact contact,
                      int dqType)
Removes the contact contact from the waiting queue. with dequeue type dqType. Returns true if the contact was removed, false otherwise. If a dequeue event was scheduled when the contact was added, this event is cancelled. This method has to linearly search for the contact being removed using getDequeueEvent(Contact), which is less efficient than when a dequeue event is given.

Parameters:
contact - the contact being removed from the queue.
dqType - the effective dequeue type of the contact.
Returns:
true if the contact was removed, false otherwise.

getDequeueEvent

public DequeueEvent getDequeueEvent(Contact contact)
Returns the dequeue event for the contact contact. If the contact is not in queue, this returns null. Since this method has to perform a linear search, it is more efficient to keep the dequeue events returned by add(Contact) when they are needed.

Parameters:
contact - the queried contact.
Returns:
the dequeue event for the contact, or null if the contact was not found.

getFirst

public DequeueEvent getFirst()
Returns the dequeue event representing the first contact in the queue, or throws a NoSuchElementException if the queue is empty.

Returns:
the dequeue event for the first contact in the queue.
Throws:
NoSuchElementException - if the queue is empty.

getLast

public DequeueEvent getLast()
Returns the dequeue event representing the last contact in the queue, or throws a NoSuchElementException if the queue is empty.

Returns:
the dequeue event for the last contact in the queue.
Throws:
NoSuchElementException - if the queue is empty.

removeFirst

public DequeueEvent removeFirst(int dqType)
Removes the first contact in the waiting queue and returns the corresponding dequeue event. The event is assigned the effective dequeue type dqType. If the queue is empty, a NoSuchElementException is thrown. The getFirst() method is used to get the dequeue event.

Parameters:
dqType - the effective dequeue type.
Returns:
the dequeue event corresponding to the removed contact.
Throws:
NoSuchElementException - if the queue is empty.

removeLast

public DequeueEvent removeLast(int dqType)
Removes the last contact in the waiting queue and returns the corresponding dequeue event. The event is assigned the effective dequeue type dqType. If the queue is empty, a NoSuchElementException is thrown. The getLast() method is used to get the dequeue event.

Parameters:
dqType - the effective dequeue type.
Returns:
the dequeue event corresponding to the removed contact.
Throws:
NoSuchElementException - if the queue is empty.

iterator

public Iterator<DequeueEvent> iterator(int dqType)
Returns an iterator allowing the dequeue events representing contacts in queue to be enumerated. The order of the elements depends on the type of waiting queue and the order of insertion. The objects returned by the iterator's next() method are instances of the DequeueEvent class. The optional remove() method is implemented and removes contacts with dequeue type dqType. If remove() is never called on the returned iterator, dqType is not used.

Parameters:
dqType - the dequeue type of any removed contact.
Returns:
an iterator enumerating the contacts in queue.

iterator

public Iterator<DequeueEvent> iterator()
This is similar to iterator(int), except it uses the default dequeue type returned by getDefaultDequeueType().

Specified by:
iterator in interface Iterable<DequeueEvent>
Specified by:
iterator in interface Collection<DequeueEvent>
Specified by:
iterator in class AbstractCollection<DequeueEvent>
Returns:
the constructed iterator.

getDefaultDequeueType

public int getDefaultDequeueType()
Returns the default dequeue type used by this object when the user does not specify a dequeue type explicitly. The initial default dequeue type is 0.

Returns:
the default dequeue type.

setDefaultDequeueType

public void setDefaultDequeueType(int dqTypeDefault)
Sets the default dequeue type to dqTypeDefault.

Parameters:
dqTypeDefault - the new default dequeue type.

addWaitingQueueListener

public void addWaitingQueueListener(WaitingQueueListener listener)
Adds the new waiting-queue listener listener to this object. If the listener is already added, nothing happens; it is not added a second time.

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

removeWaitingQueueListener

public void removeWaitingQueueListener(WaitingQueueListener listener)
Removes the waiting-queue listener listener from this object. If the listener is not registered, nothing happens.

Parameters:
listener - the waiting-queue listener being removed.

clearWaitingQueueListeners

public void clearWaitingQueueListeners()
Removes all waiting-queue listeners registered with this waiting queue.


getWaitingQueueListeners

public List<WaitingQueueListener> getWaitingQueueListeners()
Returns an unmodifiable list containing all the waiting-queue listeners registered with this waiting queue.

Returns:
the list of all registered waiting-queue listeners.

notifyInit

protected void notifyInit()
Notifies every registered listener that this waiting queue was initialized.


notifyEnqueued

protected void notifyEnqueued(DequeueEvent ev)
Notifies every registered listener that a contact was enqueued, this event being represented by ev.

Parameters:
ev - the dequeue event representing the queued contact.

notifyDequeued

protected void notifyDequeued(DequeueEvent ev)
Notifies every registered listener that a contact left this queue, this event being represented by ev.

Parameters:
ev - the event representing the contact having left the queue.

save

public WaitingQueueState save()
Constructs a new WaitingQueueState object holding the current state of this waiting queue, i.e., every queued contact.

Returns:
the state of this waiting queue.

restore

public void restore(WaitingQueueState state)
Restores the state of the waiting queue by using the restore method of state.

Parameters:
state - the saved state of the waiting queue.

getId

public int getId()
Returns the identifier associated with this queue. This identifier, which defaults to -1, can be used as an index in routers.

Returns:
the identifier associated with this queue.

setId

public void setId(int id)
Sets the identifier of this queue to id. Once this identifier is set to a positive or 0 value, it cannot be changed anymore. This method is automatically called by the router when a waiting queue is connected. If one tries to attach the same queue to different routers, the queue must have the same index for each of them. For this reason, if one tries to change the identifier, an IllegalStateException is thrown.

Parameters:
id - the new identifier associated with the queue.
Throws:
IllegalStateException - if the identifier was already set.

getMaximalQueueTimeGenerator

public ValueGenerator getMaximalQueueTimeGenerator(int dqType)
Returns the maximal queue time generator associated with dequeue type dqType for this waiting queue. Returns null if no value generator is associated with the given dqType.

Parameters:
dqType - the queried dequeue type.
Returns:
the maximal queue time generator of this object.

setMaximalQueueTimeGenerator

public void setMaximalQueueTimeGenerator(int dqType,
                                         ValueGenerator dqgen)
Changes the maximal queue time generator associated with dequeue type dqType for this waiting queue to dqgen.

Parameters:
dqType - the affected dequeue type.
dqgen - the new maximal queue time generator.
Throws:
IllegalArgumentException - if the given dequeue type is negative.
NullPointerException - if dqgen is null.

elementsIterator

protected abstract Iterator<DequeueEvent> elementsIterator()
Returns an iterator capable of traversing, in the correct order, the elements in the waiting queue's internal data structure. This is different from the iterator(int) method because this iterator returns the contacts marked for dequeue as well as the contacts still enqueued. If the returned iterator does not implement remove(), remove(Contact,int) and getDequeueEvent(Contact) will not work properly.

Returns:
an iterator for the waiting queue elements.

elementsClear

protected abstract void elementsClear()
Clears all elements in the data structure representing the queued contacts.


elementsAdd

protected abstract void elementsAdd(DequeueEvent dqEvent)
Adds the new dequeued event dqEvent to the internal data structure representing the waiting queue.

Parameters:
dqEvent - the dequeue event being added.

elementsIsEmpty

protected abstract boolean elementsIsEmpty()
Determines if the internal waiting queue data structure is empty.

Returns:
true if the data structure is empty, false otherwise.

elementsGetFirst

protected abstract DequeueEvent elementsGetFirst()
Returns the first element of the waiting queue's internal data structure, or throws a NoSuchElementException if no such element exists.

Returns:
the first element of the data structure.
Throws:
NoSuchElementException - if the queue's data structure is empty.

elementsGetLast

protected abstract DequeueEvent elementsGetLast()
Returns the last element of the waiting queue's internal data structure, or throws a NoSuchElementException if no such element exists.

Returns:
the last element of the data structure.
Throws:
NoSuchElementException - if the queue's data structure is empty.

elementsRemoveFirst

protected abstract DequeueEvent elementsRemoveFirst()
Removes and returns the first element in the waiting queue's internal data structure. Throws a NoSuchElementException if no such element exists.

Returns:
the removed element.
Throws:
NoSuchElementException - if the queue's data structure is empty.

elementsRemoveLast

protected abstract DequeueEvent elementsRemoveLast()
Removes and returns the last element in the waiting queue's internal data structure. Throws a NoSuchElementException if no such element exists.

Returns:
the removed element.
Throws:
NoSuchElementException - if the queue's data structure is empty.

getAttributes

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

Returns:
the map containing the attributes for this object.

toString

public String toString()
Overrides:
toString in class AbstractCollection<DequeueEvent>

ContactCenters
V. 0.9.9.

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