Class LoomQueue<E>

java.lang.Object
com.loomcache.client.LoomQueue<E>
Type Parameters:
E - the type of elements in the queue
public final class LoomQueue<E> extends Object
Client-side distributed queue proxy.

Provides transparent access to a distributed FIFO queue stored in the LoomCache cluster. Elements are inserted at the tail and removed from the head. All operations are routed through the connected LoomClient and may raise LoomException if the cluster becomes unavailable or a timeout occurs.

Thread Safety

This class is thread-safe. Multiple threads may call methods concurrently; the underlying LoomClient handles synchronization and connection pooling.

Async API

This class provides both synchronous and asynchronous methods. Async methods return CompletableFuture for non-blocking operations.

Usage Example

org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger("loom-queue");
LoomClient client = LoomClient.builder()
    .addSeed("127.0.0.1:5701")
    .build();
client.connect();

LoomQueue<String> tasks = client.getQueue("tasks");
tasks.offer("process-order-123");
tasks.offer("send-notification");
String nextTask = tasks.poll();  // "process-order-123"

// Async variant
tasks.offerAsync("process-order-456")
    .thenCompose(v -> tasks.pollAsync())
    .thenAccept(item -> log.info("Got task: {}", item))
    .join();
Since:
1.0

  • Method Details

    • offer

      public boolean offer(E item)
      Inserts an element at the tail of the queue.
      Parameters:
      item - the element to add (serialized via ClientSerializer)
      Returns:
      true if the element was successfully added; false if the queue is full
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • poll

      public @Nullable E poll()
      Removes and returns the element at the head of the queue.

      This is a non-blocking operation; if the queue is empty, returns null.

      Returns:
      the head element, or null if the queue is empty
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • peek

      public @Nullable E peek()
      Returns the element at the head of the queue without removing it.

      This is a non-blocking, read-only operation; if the queue is empty, returns null.

      Returns:
      the head element, or null if the queue is empty
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • size

      public int size()
      Return the number of items currently in the queue.
      Returns:
      queue size, or 0 when the queue does not exist
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • offerAll

      public int offerAll(Collection<? extends E> items)
      Inserts all supplied elements at the tail of the queue.
      Parameters:
      items - elements to add (serialized via ClientSerializer)
      Returns:
      number of elements accepted by the queue
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • poll

      public List<E> poll(int count)
      Removes up to count elements from the head of the queue.
      Parameters:
      count - maximum number of elements to remove
      Returns:
      removed elements in FIFO order
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • drain

      public List<E> drain()
      Drains the queue into a new list.
      Returns:
      removed elements in FIFO order
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • drainTo

      public int drainTo(Collection<? super E> target, int maxElements)
      Drains up to maxElements elements into the supplied target collection.
      Parameters:
      target - collection receiving removed elements
      maxElements - maximum number of elements to remove
      Returns:
      number of elements added to target
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • drainTo

      public int drainTo(Collection<? super E> target)
      Drains all currently available elements into the supplied target collection.
      Parameters:
      target - collection receiving removed elements
      Returns:
      number of elements added to target
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • offerAsync

      public CompletableFuture<Boolean> offerAsync(E item)
      Asynchronously inserts an element at the tail of the queue.
      Parameters:
      item - the element to add (serialized via ClientSerializer)
      Returns:
      a CompletableFuture with true if the element was successfully added; false if the queue is full

    • pollAsync

      public CompletableFuture<@Nullable E> pollAsync()
      Asynchronously removes and returns the element at the head of the queue.

      This is a non-blocking operation; if the queue is empty, returns null.

      Returns:
      a CompletableFuture with the head element, or null if the queue is empty

    • peekAsync

      public CompletableFuture<@Nullable E> peekAsync()
      Asynchronously returns the element at the head of the queue without removing it.

      This is a non-blocking, read-only operation; if the queue is empty, returns null.

      Returns:
      a CompletableFuture with the head element, or null if the queue is empty

    • sizeAsync

      public CompletableFuture<Integer> sizeAsync()

    • offerAllAsync

      public CompletableFuture<Integer> offerAllAsync(Collection<? extends E> items)

    • pollAsync

      public CompletableFuture<List<E>> pollAsync(int count)

    • drainAsync

      public CompletableFuture<List<E>> drainAsync()

    • drainToAsync

      public CompletableFuture<Integer> drainToAsync(Collection<? super E> target, int maxElements)