org.apache.ignite

## Interface IgniteQueue<T>

All Superinterfaces:
  AutoCloseable, BlockingQueue<T>, Closeable, Collection<T>, Iterable<T>, Queue<T>

All Known Implementing Classes:
  GridAtomicCacheQueueImpl, GridCacheQueueAdapter, GridCacheQueueProxy, GridTransactionalCacheQueueImpl

    public interface IgniteQueue<T>
    extends BlockingQueue<T>, Closeable

This interface provides a rich API for working with distributed queues based on In-Memory Data Grid.

# Overview

Cache queue provides an access to cache elements using typical queue API. Cache queue also implements `Collection` interface and provides all methods from collections including `Collection.addAll(Collection)`, `Collection.removeAll(Collection)`, and `Collection.retainAll(Collection)` methods for bulk operations. Note that all `Collection` methods in the queue may throw `IgniteException` in case of failure.

# Bounded vs Unbounded

Queues can be `unbounded` or `bounded`. `Bounded` queues can have maximum capacity. Queue capacity can be set at creation time and cannot be changed later. Here is an example of how to create `bounded` `LIFO` queue with capacity of `1000` items.

     IgniteQueue<String> queue = cache().queue("anyName", LIFO, 1000);
     ...
     queue.add("item");

For `bounded` queues blocking operations, such as `take()` or `put(Object)` are available. These operations will block until queue capacity changes to make the operation possible.

# Collocated vs Non-collocated

Queue items can be placed on one node or distributed throughout grid nodes (governed by `collocated` parameter). `Non-collocated` mode is provided only for partitioned caches. If `collocated` parameter is `true`, then all queue items will be collocated on one node, otherwise items will be distributed through all grid nodes. Unless explicitly specified, by default queues are `collocated`.

Here is an example of how create `unbounded` queue in non-collocated mode.

     IgniteQueue<String> queue = cache().queue("anyName", 0 /*unbounded*/, false /*non-collocated*/);
     ...
     queue.add("item");

# Creating Cache Queues

Instances of distributed cache queues can be created by calling the following method on `Ignite` API:

- `Ignite.queue(String, int, org.apache.ignite.configuration.CollectionConfiguration)`

See Also:
  `Ignite.queue(String, int, org.apache.ignite.configuration.CollectionConfiguration)`

### Method Summary

Methods
`boolean` `add(T item)`
`boolean` `addAll(Collection<? extends T> items)`
`<R> R` `affinityCall(IgniteCallable<R> job)` Executes given job on collocated queue on the node where the queue is located (a.k.a. affinity co-location).
`void` `affinityRun(IgniteRunnable job)` Executes given job on collocated queue on the node where the queue is located (a.k.a. affinity co-location).
`boolean` `bounded()` Returns `true` if this queue is bounded.
`int` `capacity()` Gets maximum number of elements of the queue.
`void` `clear()`
`void` `clear(int batchSize)` Removes all of the elements from this queue.
`void` `close()` Removes this queue.
`boolean` `collocated()` Returns `true` if this queue can be kept on the one node only.
`boolean` `contains(Object item)`
`boolean` `containsAll(Collection<?> items)`
`boolean` `isEmpty()`
`Iterator<T>` `iterator()`
`String` `name()` Gets queue name.
`boolean` `offer(T item)`
`boolean` `offer(T item, long timeout, TimeUnit unit)`
`T` `peek()`
`T` `poll()`
`T` `poll(long timeout, TimeUnit unit)`
`void` `put(T item)`
`boolean` `remove(Object item)`
`boolean` `removeAll(Collection<?> items)`
`boolean` `removed()` Gets status of queue.
`boolean` `retainAll(Collection<?> items)`
`int` `size()`
`T` `take()`
`Object[]` `toArray()`
`<T> T[]` `toArray(T[] a)`

### Methods inherited from interface java.util.concurrent.BlockingQueue

`drainTo, drainTo, remainingCapacity`

### Methods inherited from interface java.util.Queue

`element, remove`

### Methods inherited from interface java.util.Collection

`equals, hashCode`

### Method Detail

#### name

    String name()

Gets queue name.

Returns:
  Queue name.

#### add

    boolean add(T item)
                throws IgniteException

Specified by:
  `add` in interface `BlockingQueue<T>`
Specified by:
  `add` in interface `Collection<T>`
Specified by:
  `add` in interface `Queue<T>`
Throws:
  `IgniteException`

#### offer

    boolean offer(T item)
                  throws IgniteException

Specified by:
  `offer` in interface `BlockingQueue<T>`
Specified by:
  `offer` in interface `Queue<T>`
Throws:
  `IgniteException`

#### offer

    boolean offer(T item,
                long timeout,
                TimeUnit unit)
                  throws IgniteException

Specified by:
  `offer` in interface `BlockingQueue<T>`
Throws:
  `IgniteException`

#### addAll

    boolean addAll(Collection<? extends T> items)
                   throws IgniteException

Specified by:
  `addAll` in interface `Collection<T>`
Throws:
  `IgniteException`

#### contains

    boolean contains(Object item)
                     throws IgniteException

Specified by:
  `contains` in interface `BlockingQueue<T>`
Specified by:
  `contains` in interface `Collection<T>`
Throws:
  `IgniteException`

#### containsAll

    boolean containsAll(Collection<?> items)
                        throws IgniteException

Specified by:
  `containsAll` in interface `Collection<T>`
Throws:
  `IgniteException`

#### clear

    void clear()
               throws IgniteException

Specified by:
  `clear` in interface `Collection<T>`
Throws:
  `IgniteException`

#### remove

    boolean remove(Object item)
                   throws IgniteException

Specified by:
  `remove` in interface `BlockingQueue<T>`
Specified by:
  `remove` in interface `Collection<T>`
Throws:
  `IgniteException`

#### removeAll

    boolean removeAll(Collection<?> items)
                      throws IgniteException

Specified by:
  `removeAll` in interface `Collection<T>`
Throws:
  `IgniteException`

#### isEmpty

    boolean isEmpty()
                    throws IgniteException

Specified by:
  `isEmpty` in interface `Collection<T>`
Throws:
  `IgniteException`

#### iterator

    Iterator<T> iterator()
                         throws IgniteException

Specified by:
  `iterator` in interface `Collection<T>`
Specified by:
  `iterator` in interface `Iterable<T>`
Throws:
  `IgniteException`

#### toArray

    Object[] toArray()
                     throws IgniteException

Specified by:
  `toArray` in interface `Collection<T>`
Throws:
  `IgniteException`

#### toArray

    <T> T[] toArray(T[] a)
                throws IgniteException

Specified by:
  `toArray` in interface `Collection<T>`
Throws:
  `IgniteException`

#### retainAll

    boolean retainAll(Collection<?> items)
                      throws IgniteException

Specified by:
  `retainAll` in interface `Collection<T>`
Throws:
  `IgniteException`

#### size

    int size()
             throws IgniteException

Specified by:
  `size` in interface `Collection<T>`
Throws:
  `IgniteException`

#### poll

    T poll()
           throws IgniteException

Specified by:
  `poll` in interface `Queue<T>`
Throws:
  `IgniteException`

#### peek

    T peek()
           throws IgniteException

Specified by:
  `peek` in interface `Queue<T>`
Throws:
  `IgniteException`

#### put

    void put(T item)
             throws IgniteException

Specified by:
  `put` in interface `BlockingQueue<T>`
Throws:
  `IgniteException`

#### take

    T take()
           throws IgniteException

Specified by:
  `take` in interface `BlockingQueue<T>`
Throws:
  `IgniteException`

#### poll

    T poll(long timeout,
         TimeUnit unit)
           throws IgniteException

Specified by:
  `poll` in interface `BlockingQueue<T>`
Throws:
  `IgniteException`

#### clear

    void clear(int batchSize)
               throws IgniteException

Removes all of the elements from this queue. Method is used in massive queues with huge numbers of elements.

Parameters:
  `batchSize` - Batch size.
Throws:
  `IgniteException` - if operation failed.

#### close

    void close()
               throws IgniteException

Removes this queue.

Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `Closeable`
Throws:
  `IgniteException` - if operation failed.

#### capacity

    int capacity()

Gets maximum number of elements of the queue.

Returns:
  Maximum number of elements. If queue is unbounded `Integer.MAX_SIZE` will return.

#### bounded

    boolean bounded()

Returns `true` if this queue is bounded.

Returns:
  `true` if this queue is bounded.

#### collocated

    boolean collocated()

Returns `true` if this queue can be kept on the one node only. Returns `false` if this queue can be kept on the many nodes.

Returns:
  `true` if this queue is in `collocated` mode `false` otherwise.

#### removed

    boolean removed()

Gets status of queue.

Returns:
  `true` if queue was removed from cache `false` otherwise.

#### affinityRun

    void affinityRun(IgniteRunnable job)
                     throws IgniteException

Executes given job on collocated queue on the node where the queue is located (a.k.a. affinity co-location).

This is not supported for non-collocated queues.

Parameters:
  `job` - Job which will be co-located with the queue.
Throws:
  `IgniteException` - If job failed.

#### affinityCall

    <R> R affinityCall(IgniteCallable<R> job)
                   throws IgniteException

Executes given job on collocated queue on the node where the queue is located (a.k.a. affinity co-location).

This is not supported for non-collocated queues.

Parameters:
  `job` - Job which will be co-located with the queue.
Throws:
  `IgniteException` - If job failed.

2015 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 1.8.0
Release Date | : December 5 2016