org.jgroups.util

## Class Queue

- java.lang.Object
- - org.jgroups.util.Queue

    public class Queue
    extends java.lang.Object

Elements are added at the tail and removed from the head. Class is thread-safe in that 1 producer and 1 consumer may add/remove elements concurrently. The class is not explicitely designed for multiple producers or consumers. Implemented as a linked list, so that removal of an element at the head does not cause a right-shift of the remaining elements (as in a Vector-based implementation).

Author:
  Bela Ban

### Field Summary

Fields
`protected static Log` `log`

### Constructor Summary

Constructors
Constructor and Description
`Queue()` creates an empty queue

### Method Summary

Methods
`void` `add(java.lang.Object obj)` adds an object to the tail of this queue If the queue has been closed with close(true) no exception will be thrown if the queue has not been flushed yet.
`void` `addAll(java.util.Collection c)`
`void` `addAll(java.util.List<java.lang.Object> list)`
`void` `clear()` Removes all elements from the queue.
`void` `close(boolean flush_entries)` Marks the queues as closed.
`boolean` `closed()` returns true if the Queue has been closed however, this method will return false if the queue has been closed using the close(true) method and the last element has yet not been received.
`java.lang.Object` `getFirst()` Returns the first element.
`java.lang.Object` `getLast()` Returns the last element.
`java.lang.Object` `peek()` returns the first object on the queue, without removing it.
`java.lang.Object` `peek(long timeout)` returns the first object on the queue, without removing it.
`java.lang.Object` `remove()` Removes 1 element from head or blocks until next element has been added or until queue has been closed
`java.lang.Object` `remove(long timeout)` Removes 1 element from the head.
`void` `removeElement(java.lang.Object obj)` removes a specific object from the queue.
`java.lang.Object` `removeWait(long timeout)`
`void` `reset()` resets the queue.
`int` `size()` returns the number of objects that are currently in the queue
`java.lang.String` `toString()` prints the size of the queue
`java.util.LinkedList` `values()` Returns all the elements of the queue
`void` `waitUntilClosed(long timeout)` Waits until the queue has been closed.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Field Detail

#### log

    protected static final Log log

### Constructor Detail

#### Queue

    public Queue()

creates an empty queue

### Method Detail

#### getFirst

    public java.lang.Object getFirst()

Returns the first element. Returns null if no elements are available.

#### getLast

    public java.lang.Object getLast()

Returns the last element. Returns null if no elements are available.

#### closed

    public boolean closed()

returns true if the Queue has been closed however, this method will return false if the queue has been closed using the close(true) method and the last element has yet not been received.

Returns:
  true if the queue has been closed

#### add

    public void add(java.lang.Object obj)
             throws QueueClosedException

adds an object to the tail of this queue If the queue has been closed with close(true) no exception will be thrown if the queue has not been flushed yet.

Parameters:
  `obj` - - the object to be added to the queue
Throws:
  `QueueClosedException` - exception if closed() returns true

#### addAll

    public void addAll(java.util.Collection c)
                throws QueueClosedException

Throws:
  `QueueClosedException`

#### addAll

    public void addAll(java.util.List<java.lang.Object> list)
                throws QueueClosedException

Throws:
  `QueueClosedException`

#### remove

    public java.lang.Object remove()
                            throws QueueClosedException

Removes 1 element from head or blocks until next element has been added or until queue has been closed

Returns:
  the first element to be taken of the queue
Throws:
  `QueueClosedException`

#### remove

    public java.lang.Object remove(long timeout)
                            throws QueueClosedException,
                                   TimeoutException

Removes 1 element from the head. If the queue is empty the operation will wait for timeout ms. if no object is added during the timeout time, a Timout exception is thrown (bela Aug 2009) Note that the semantics of remove(long timeout) are weird - the method waits until an element has been added, but doesn't do so in a loop ! So if we have 10 threads waiting on an empty queue, and 1 thread adds an element, all 10 threads will return (but only 1 will have the element), therefore 9 will throw a TimeoutException ! If I change this to the 'correct' semantics, however (e.g. the method removeWait() below), GMS.ViewHandler doesn't work correctly anymore. I won't change this now, as Queue will get removed anyway in 3.0.

Parameters:
  `timeout` - - the number of milli seconds this operation will wait before it times out
Returns:
  the first object in the queue
Throws:
  `QueueClosedException`
  `TimeoutException`

#### removeWait

    public java.lang.Object removeWait(long timeout)
                                throws QueueClosedException,
                                       TimeoutException

Throws:
  `QueueClosedException`
  `TimeoutException`

#### removeElement

    public void removeElement(java.lang.Object obj)
                       throws QueueClosedException

removes a specific object from the queue. the object is matched up using the Object.equals method.

Parameters:
  `obj` - the actual object to be removed from the queue
Throws:
  `QueueClosedException`

#### peek

    public java.lang.Object peek()
                          throws QueueClosedException

returns the first object on the queue, without removing it. If the queue is empty this object blocks until the first queue object has been added

Returns:
  the first object on the queue
Throws:
  `QueueClosedException`

#### peek

    public java.lang.Object peek(long timeout)
                          throws QueueClosedException,
                                 TimeoutException

returns the first object on the queue, without removing it. If the queue is empty this object blocks until the first queue object has been added or the operation times out

Parameters:
  `timeout` - how long in milli seconds will this operation wait for an object to be added to the queue before it times out
Returns:
  the first object on the queue
Throws:
  `QueueClosedException`
  `TimeoutException`

#### clear

    public void clear()

Removes all elements from the queue. This method can succeed even when the queue is closed

#### close

    public void close(boolean flush_entries)

Marks the queues as closed. When an `add` or `remove` operation is attempted on a closed queue, an exception is thrown.

Parameters:
  `flush_entries` - When true, a end-of-entries marker is added to the end of the queue. Entries may be added and removed, but when the end-of-entries marker is encountered, the queue is marked as closed. This allows to flush pending messages before closing the queue.

#### waitUntilClosed

    public void waitUntilClosed(long timeout)

Waits until the queue has been closed. Returns immediately if already closed

Parameters:
  `timeout` - Number of milliseconds to wait. A value <= 0 means to wait forever

#### reset

    public void reset()

resets the queue. This operation removes all the objects in the queue and marks the queue open

#### values

    public java.util.LinkedList values()

Returns all the elements of the queue

Returns:
  A copy of the queue

#### size

    public int size()

returns the number of objects that are currently in the queue

#### toString

    public java.lang.String toString()

prints the size of the queue

Overrides:
  `toString` in class `java.lang.Object`