Overview | Package | Class | Tree | Deprecated | Index | Help
| ContactCenters V. 0.9.9.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## umontreal.iro.lecuyer.contactcenters.queue
Class WaitingQueue

    java.lang.Object
      java.util.AbstractCollection<E>
          java.util.AbstractQueue<DequeueEvent>
              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* = {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>`

Overview | Package | Class | Tree | Deprecated | Index | Help
| ContactCenters V. 0.9.9.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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