Package jsl.modeling.queue

Class Queue<T extends QObject>

  • Type Parameters:
    T - queues must hold sub-types of QObject
    All Implemented Interfaces:
    java.lang.Iterable<T>, ObservableIfc, GetNameIfc, IdentityIfc
    public class Queue<T extends QObject>
extends ModelElement
implements java.lang.Iterable<T>
    The Queue class provides the ability to hold entities (QObjects) within the model. Any object can be added to a Queue. When an object is added to a Queue, the object is wrapped by a QObject which provides statistical collection. In this way, objects that queue do not need additional behavior.

    FIFODiscipline ensures first-in, first-out behavior. LIFODiscipoine ensures last-in, last-out behavior. RankedDiscipline ensures that each new element is added such that the priority is maintained from smallest first to largest priority last using the compareTo method of the QObject. Ties in priority give preference to time of creation, then to order of creation. RandomDiscipline causes the elements to be randomly selected (uniformly).

    • Field Detail

      • myList

        protected java.util.List<T extends QObject> myList
        The list of items in the queue.

      • myQueueListeners

        protected java.util.List<QueueListenerIfc<T extends QObject>> myQueueListeners
        Holds the listeners for this queue's enqueue and removeNext method use

      • myStatus

        protected Queue.Status myStatus
        Indicates whether something was just enqueued or dequeued

      • myResponses

        protected QueueResponse<T extends QObject> myResponses
        Collect statistics on time in queue and number in queue

    • Constructor Detail

      • Queue

        public Queue​(ModelElement parent)
        Constructs a Queue. The default will be a FIFO queue
        Parameters:
        parent - its parent

      • Queue

        public Queue​(ModelElement parent,
             java.lang.String name)
        Constructs a Queue with the given name. The queue will be a FIFO by default.
        Parameters:
        parent - its parent
        name - The name of the queue

      • Queue

        public Queue​(ModelElement parent,
             Queue.Discipline discipline)
        Constructs a Queue that follows the given queue discipline.
        Parameters:
        parent - its parent
        discipline - The queuing discipline to be followed

      • Queue

        public Queue​(ModelElement parent,
             java.lang.String name,
             Queue.Discipline discipline)
        Constructs a Queue with the given name that follows the given queue discipline.
        Parameters:
        parent - its parent
        name - The name of the queue
        discipline - The queuing discipline to be followed

      • Queue

        public Queue​(ModelElement parent,
             java.lang.String name,
             Queue.Discipline discipline,
             boolean statOption)
        Constructs a Queue with the given name that follows the given queue discipline.
        Parameters:
        parent - its parent
        name - The name of the queue
        discipline - The queuing discipline to be followed
        statOption - true turns on statistical response

    • Method Detail

      • getQueueResponses

        public final java.util.Optional<QueueResponse<T>> getQueueResponses()
        Returns:
        If the queue has responses then return them

      • initialize

        protected void initialize()
        can be called to initialize the queue The default behavior is to have the queue cleared after the replication
        Overrides:
        initialize in class ModelElement

      • beforeExperiment

        protected void beforeExperiment()
        Description copied from class: ModelElement
        This method should be overridden by subclasses that need logic to be performed prior to an experiment. The beforeExperiment method allows model elements to be setup prior to the first replication within an experiment. It is called once before any replications occur.
        Overrides:
        beforeExperiment in class ModelElement

      • afterReplication

        protected void afterReplication()
        Description copied from class: ModelElement
        This method should be overridden by subclasses that need actions performed after each replication. It is called after replicationEnded() has been called.
        Overrides:
        afterReplication in class ModelElement

      • removedFromModel

        protected void removedFromModel()
        Description copied from class: ModelElement
        This method should be overridden by subclasses that need actions performed when a model element is removed from a model
        Overrides:
        removedFromModel in class ModelElement

      • getQueueStatsOption

        public final boolean getQueueStatsOption()
        Returns:
        true if queue statistics have been turned on

      • getUnmodifiableList

        public final java.util.List<T> getUnmodifiableList()
        Returns:
        a unmodifiable view of the underlying list for the Queue

      • addQueueListener

        public final boolean addQueueListener​(QueueListenerIfc<T> listener)
        Adds the supplied listener to this queue
        Parameters:
        listener - Must not be null, cannot already be added
        Returns:
        true if added

      • removeQueueListener

        public boolean removeQueueListener​(QueueListenerIfc<T> listener)
        Removes the supplied listener from this queue
        Parameters:
        listener - Must not be null
        Returns:
        true if removed

      • getStatus

        public final Queue.Status getStatus()
        Gets whether or not the last action was enqueue or dequeueing an object
        Returns:
        the status

      • changeDiscipline

        public final void changeDiscipline​(Queue.Discipline discipline)
        Changes the queue's discipline to the given discipline.
        Parameters:
        discipline - An interface to a queue discipline

      • getCurrentDiscipline

        public final Queue.Discipline getCurrentDiscipline()
        Returns:
        The current discipline for the queue

      • changePriority

        public final void changePriority​(QObject qObject,
                                 int priority)
        Changes the priority of the supplied QObject. May cause the queue to reorder using its discipline
        Parameters:
        qObject - the sub-type of QObject that is getting its priority changed
        priority - the priority to change the value to

      • getInitialDiscipline

        public final Queue.Discipline getInitialDiscipline()
        Gets the initial queue discipline
        Returns:
        the initial queue discipline

      • setInitialDiscipline

        public final void setInitialDiscipline​(Queue.Discipline discipline)
        Sets the initial queue discipline
        Parameters:
        discipline - the discipline

      • enqueue

        public final void enqueue​(T queueingObject)
        Places the QObject in the queue, uses the priority associated with the QObject, which is 1 by default Automatically, updates the number in queue response variable.
        Parameters:
        queueingObject - the QObject to enqueue

      • enqueue

        public final <S> void enqueue​(T queueingObject,
                              S obj)
        Places the QObject in the queue, uses the priority associated with the QObject, which is 1 by default Automatically, updates the number in queue response variable.
        Type Parameters:
        S - The type of the object being attached to the QObject
        Parameters:
        queueingObject - the sub-type of QObject to enqueue
        obj - an Object to be "wrapped" and queued while the QObject is in the queue

      • enqueue

        public final void enqueue​(T queueingObject,
                          int priority)
        Places the QObject in the queue, with the default priority of 1 Automatically, updates the number in queue response variable.
        Parameters:
        queueingObject - the QObject to enqueue
        priority - the priority for ordering the object, lower has more priority

      • enqueue

        public <S> void enqueue​(T qObject,
                        int priority,
                        S obj)
        Places the QObject in the queue, with the specified priority Automatically, updates the number in queue response variable.
        Type Parameters:
        S - The type of the object being attached to the QObject
        Parameters:
        qObject - - the QObject to enqueue
        priority - - the priority for ordering the object, lower has more priority
        obj - an Object to be "wrapped" and queued while the QObject is queued

      • peekNext

        public final T peekNext()
        Returns a reference to the QObject representing the item that is next to be removed from the queue according to the queue discipline that was specified.
        Returns:
        a reference to the QObject object next item to be removed, or null if the queue is empty

      • removeNext

        public final T removeNext()
        Removes the next item from the queue according to the queue discipline that was specified. Returns a reference to the QObject representing the item that was removed

        Automatically, collects the time in queue for the item and includes it in the time in queue response variable.

        Automatically, updates the number in queue response variable.

        Returns:
        a reference to the QObject object, or null if the queue is empty

      • contains

        public final boolean contains​(T qObj)
        Returns true if this queue contains the specified element. More formally, returns true if and only if this list contains at least one element e such that (o==null ? e==null : o.equals(e)).

        Throws an IllegalArgumentException if QObject qObj is null.

        Parameters:
        qObj - The object to be removed
        Returns:
        True if the queue contains the specified element.

      • contains

        public final boolean contains​(java.util.Collection<T> c)
        Returns true if this queue contains all of the elements in the specified collection WARNING: The collection should contain references to QObject's otherwise it will certainly return false.

        Throws an IllegalArguementException if the Collection is null

        Parameters:
        c - Collection c of items to check
        Returns:
        True if the queue contains all of the elements.

      • indexOf

        public final int indexOf​(T qObj)
        Returns the index in this queue of the first occurrence of the specified element, or -1 if the queue does not contain this element. More formally, returns the lowest index i such that (o==null ? get(i)==null : o.equals(get(i))), or -1 if there is no such index.

        Throws an IllegalArgumentException if QObject qObj is null.

        Parameters:
        qObj - The object to be found
        Returns:
        The index (zero based) of the element or -1 if not found.

      • lastIndexOf

        public final int lastIndexOf​(T qObj)
        Returns the index in this queue of the last occurrence of the specified element, or -1 if the queue does not contain this element. More formally, returns the lowest index i such that (o==null ? get(i)==null : o.equals(get(i))), or -1 if there is no such index.

        Throws an IllegalArgumentException if QObject qObj is null.

        Parameters:
        qObj - The object to be found
        Returns:
        The (zero based) index or -1 if not found.

      • find

        public final boolean find​(java.util.function.Predicate<T> condition,
                          java.util.Collection<T> foundItems)
        Finds all the QObjects in the Queue that satisfy the condition and adds them to the foundItems collection
        Parameters:
        condition - the condition of the search
        foundItems - the items found
        Returns:
        yields true if at least one was found, false otherwise

      • find

        public final T find​(java.lang.Object object)
        Finds the first QObject whose getQueuedObject().equals(object)
        Parameters:
        object - the object to look for
        Returns:
        null if no QObject is found

      • find

        public final boolean find​(java.util.Collection<T> foundQObjects,
                          java.lang.Object object)
        Finds all QObjects whose getQueuedObject().equals(object)
        Parameters:
        foundQObjects - all QObjects whose getQueuedObject().equals(object)
        object - the object to search
        Returns:
        returns true if at least one match is found

      • remove

        public final boolean remove​(java.util.function.Predicate<T> condition,
                            java.util.Collection<T> deletedItems)
        Finds and removes all the QObjects in the Queue that satisfy the condition and adds them to the deletedItems collection. Waiting time statistics are automatically collected
        Parameters:
        condition - The condition to check
        deletedItems - Holds the items that were removed from the Queue
        Returns:
        yields true if at least one was deleted, false otherwise

      • remove

        public final boolean remove​(java.util.function.Predicate<T> condition,
                            java.util.Collection<T> deletedItems,
                            boolean waitStats)
        Finds and removes all the QObjects in the Queue that satisfy the condition and adds them to the deletedItems collection
        Parameters:
        condition - The condition to check
        deletedItems - Holds the items that were removed from the Queue
        waitStats - indicates whether or not waiting time statistics should be collected
        Returns:
        yields true if at least one was deleted, false otherwise

      • remove

        public final boolean remove​(T qObj)
        Removes the first occurrence in the queue of the specified element Automatically collects waiting time statistics and number in queue statistics. If the queue does not contain the element then it is unchanged and false is returned

        Throws an IllegalArgumentException if QObject qObj is null.

        Parameters:
        qObj -
        Returns:
        true if the item was removed

      • remove

        public final boolean remove​(T qObj,
                            boolean waitStats)
        Removes the first occurrence in the queue of the specified element Automatically collects waiting time statistics and number in queue statistics. If the queue does not contain the element then it is unchanged and false is returned

        Throws an IllegalArgumentException if QObject qObj is null.

        Parameters:
        qObj - The object to be removed
        waitStats - Indicates whether waiting time statistics should be collected on the removed item, true means collect statistics
        Returns:
        True if the item was removed.

      • remove

        public final T remove​(int index)
        Removes the element at the specified position in this queue. Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the list.

        Automatically, collects the time in queue for the item and includes it in the time in queue response variable.

        Automatically, updates the number in queue response variable.

        Throws an IndexOutOfBoundsException if the specified index is out of range (index < 0 || index >= size()).

        Parameters:
        index - - the index of the element to be removed.
        Returns:
        the element previously at the specified position

      • remove

        public final T remove​(int index,
                      boolean waitStats)
        Removes the element at the specified position in this queue. Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the list.

        Automatically, collects number in queue statistics. If waitStats flag is true, then automatically collects the time in queue for the item and includes it in the time in queue response variable.

        Throws an IndexOutOfBoundsException if the specified index is out of range (index < 0 || index >= size()).

        Parameters:
        index - - the index of the element to be removed.
        waitStats - - true means collect waiting time statistics, false means do not
        Returns:
        the element previously at the specified position

      • removeFirst

        public final T removeFirst()
        Removes the QObject at the front of the queue Uses remove(int index) where index = 0
        Returns:
        The first QObject in the queue or null if the list is empty

      • removeLast

        public final T removeLast()
        Removes the QObject at the last index in the queue. Uses remove(int index) where index is the size of the list - 1
        Returns:
        The last QObject in the queue or null if the list is empty

      • peekFirst

        public final T peekFirst()
        Returns the QObject at the front of the queue Depending on the queue discipline this may not be the next QObject
        Returns:
        The first QObject in the queue or null if the list is empty

      • peekLast

        public final T peekLast()
        Returns the QObject at the last index in the queue.
        Returns:
        The last QObject in the queue or null if the list is empty

      • peekAt

        public final T peekAt​(int index)
        Returns the QObject at the supplied index in the queue.

        Throws an IndexOutOfBoundsException if the specified index is out of range (index < 0 || index >= size()).

        Parameters:
        index - the index to inspect
        Returns:
        The QObject at index in the queue or null if the list is empty

      • removeAll

        public final boolean removeAll​(java.util.Collection<T> c)
        Removes from this queue all the elements that are contained in the specified collection The collection should contain references to objects of type QObject that had been enqueued in this queue; otherwise, nothing will be removed.

        Automatically, updates the number in queue variable and time in queue statistics on removed items

        Throws an IllegalArguementException if the Collection is null

        Parameters:
        c - The collection containing the QObject's to remove
        Returns:
        true if the queue changed as a result of the call

      • removeAll

        public final boolean removeAll​(java.util.Collection<T> c,
                               boolean statFlag)
        Removes from this queue all the elements that are contained in the specified collection The collection should contain references to objects of type QObject that had been enqueued in this queue; otherwise, nothing will be removed.

        Automatically, updates the number in queue variable If statFlag is true it automatically collects time in queue statistics on removed items

        Throws an IllegalArgumentException if the Collection is null

        Parameters:
        c - The collection containing the QObject's to remove
        statFlag - true means collect statistics, false means do not
        Returns:
        true if the queue changed as a result of the call

      • removeAll

        public final boolean removeAll​(java.util.Iterator<T> c)
        Removes from this queue all the elements that are presented by iterating through this iterator The iterator should be based on a collection that contains references to objects of type QObject that had been enqueued in this queue; otherwise, nothing will be removed.

        Automatically, updates the number in queue variable and time in queue statistics on removed items

        Throws an IllegalArgumentException if the Iterator is null

        Parameters:
        c - The iterator over the collection containing the QObject's to remove
        Returns:
        true if the queue changed as a result of the call

      • removeAll

        public final boolean removeAll​(java.util.Iterator<T> c,
                               boolean statFlag)
        Removes from this queue all the elements that are presented by iterating through this iterator The iterator should be based on a collection that contains references to objects of type QObject that had been enqueued in this queue; otherwise, nothing will be removed.

        Automatically, updates the number in queue variable If statFlag is true it automatically collects time in queue statistics on removed items

        Throws an IllegalArguementException if the Iterator is null

        Parameters:
        c - The iterator over the collection containing the QObject's to remove
        statFlag - true means collect statistics, false means do not
        Returns:
        true if the queue changed as a result of the call

      • clear

        public final void clear()
        Removes all of the elements from this collection

        WARNING: This method DOES NOT record the time in queue for the cleared items if the user wants this functionality, it can be accomplished using the remove(int index) method, while looping through the items to remove Listeners are notified of the queue change with IGNORE

        This method simply clears the underlying data structure that holds the objects

      • iterator

        public final java.util.Iterator<T> iterator()
        Returns an iterator (as specified by Collection ) over the elements in the queue in proper sequence. The elements will be ordered according to the state of the queue given the specified queue discipline.

        WARNING: The remove() method is not supported by this iterator. A call to remove() with this iterator will result in an UnsupportedOperationException

        Specified by:
        iterator in interface java.lang.Iterable<T extends QObject>
        Returns:
        an iterator over the elements in the queue

      • listIterator

        public final java.util.ListIterator<T> listIterator()
        Returns an iterator (as specified by Collection ) over the elements in the queue in proper sequence. The elements will be ordered according to the state of the queue given the specified queue discipline.

        WARNING: The add(), remove(), and set() methods are not supported by this iterator. Calls to these methods will result in an UnsupportedOperationException

        Returns:
        an iterator over the elements in the queue

      • size

        public final int size()
        Gets the size (number of elements) of the queue.
        Returns:
        The number of items in the queue.

      • isEmpty

        public final boolean isEmpty()
        Returns whether or not the queue is empty.
        Returns:
        True if the queue is empty.

      • isNotEmpty

        public final boolean isNotEmpty()
        Returns true if the queue is not empty
        Returns:
        true if the queue is not empty

      • notifyQueueListeners

        protected void notifyQueueListeners​(T qObject)
        Notifies any listeners that the queue changed
        Parameters:
        qObject - The qObject associated with the notification

      • getRandomness

        public java.util.Optional<RandomElementIfc> getRandomness()
        If the Queue uses randomness, this method will return a RandomElementIfc that can be used to control the randomness according to the returned interface.
        Returns:
        an Optional containing a RandomElementIfc or null