Package org.apache.ignite

## Interface IgniteQueue<T>

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

      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

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `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)`
    `<V1> IgniteQueue<V1>` | `withKeepBinary()` | Returns queue that will operate with binary objects.

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

      `drainTo, drainTo, remainingCapacity`

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

      `equals, hashCode, parallelStream, removeIf, spliterator, stream, toArray`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach`

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

      `element, remove`

- - ### 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.

      Type Parameters:
        `R` - Type of the job result.
      Parameters:
        `job` - Job which will be co-located with the queue.
      Returns:
        Job result.
      Throws:
        `IgniteException` - If job failed.

    - #### withKeepBinary

          <V1> IgniteQueue<V1> withKeepBinary()

      Returns queue that will operate with binary objects. This is similar to `IgniteCache.withKeepBinary()` but for queues.
      Type Parameters:
        `V1` - Type of the queued binary objects.
      Returns:
        New queue instance for binary objects.