Class LoomSet<E>

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

Provides transparent access to a distributed set (unordered, unique elements) stored in the LoomCache cluster. 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-set");
LoomClient client = LoomClient.builder()
    .addSeed("127.0.0.1:5701")
    .build();
client.connect();

LoomSet<String> tags = client.getSet("tags");
tags.add("java");
tags.add("distributed");
tags.add("java");  // no-op; "java" already exists
boolean hasJava = tags.contains("java");  // true
int size = tags.size();  // 2
tags.remove("java");

// Async variant
tags.addAsync("kotlin")
    .thenCompose(v -> tags.containsAsync("kotlin"))
    .thenAccept(found -> log.info("Found: {}", found))
    .join();
Since:
1.0

  • Method Details

    • add

      public boolean add(@Nullable E element)
      Adds an element to the set.

      If the element is already present, this operation has no effect.

      Parameters:
      element - the element to add (serialized via ClientSerializer)
      Returns:
      true if the element was newly added; false if it already existed
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • remove

      public boolean remove(@Nullable E element)
      Removes an element from the set.

      If the element is not present, this operation has no effect.

      Parameters:
      element - the element to remove
      Returns:
      true if the element was present and removed; false if it was not found
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • contains

      public boolean contains(@Nullable E element)
      Checks whether an element exists in the set.
      Parameters:
      element - the element to check for
      Returns:
      true if the element is present; false otherwise
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • size

      public int size()
      Returns the number of elements in the set.
      Returns:
      the number of unique elements
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • clear

      public void clear()
      Removes all elements from the set, leaving it empty.
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • scan

      public ScanResult scan(long cursor)
      Scans the set using cursor-based iteration (Redis-like SCAN). Starts from the beginning with default count of 10.
      Parameters:
      cursor - the cursor position (0 to start from beginning)
      Returns:
      a ScanResult containing the next cursor and matched elements
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • scan

      public ScanResult scan(long cursor, @Nullable String pattern)
      Scans the set using cursor-based iteration with a glob pattern filter. Default count of 10 elements per iteration.
      Parameters:
      cursor - the cursor position (0 to start from beginning)
      pattern - optional glob pattern (* = any chars, ? = single char), null = match all
      Returns:
      a ScanResult containing the next cursor and matched elements
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • scan

      public ScanResult scan(long cursor, @Nullable String pattern, int count)
      Scans the set using cursor-based iteration with full control.
      Parameters:
      cursor - the cursor position (0 to start from beginning)
      pattern - optional glob pattern (* = any chars, ? = single char), null = match all
      count - maximum number of elements to return per iteration
      Returns:
      a ScanResult containing the next cursor and matched elements
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • scanner

      public Iterable<@Nullable E> scanner()
      Returns a cursor-based iterator for scanning set elements.

      This method provides a clean, idiomatic Java iterator API that handles cursor management and pagination transparently. Useful for iterating over large sets without loading all elements into memory.

      Usage Example: 

      org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger("loom-set-scan");

// Simple iteration
for (String tag : tags.scanner()) {
    log.info("Tag: {}", tag);
}

// With Stream API
tags.scanner("java*", 50)
    .stream()
    .filter(t -> t.length() > 3)
    .forEach(tag -> log.info("Tag: {}", tag));
      Returns:
      an Iterable for iterating over all set elements with default page size (10)
      Since:
      1.3

    • scanner

      public Iterable<@Nullable E> scanner(@Nullable String pattern)
      Returns a cursor-based iterator for scanning set elements with a glob pattern filter.
      Parameters:
      pattern - optional glob pattern (* = any chars, ? = single char), null = match all
      Returns:
      an Iterable for iterating over matching elements with default page size (10)
      Since:
      1.3

    • scanner

      public Iterable<@Nullable E> scanner(@Nullable String pattern, int pageSize)
      Returns a cursor-based iterator for scanning set elements with full control.

      This is the most flexible scanner method, allowing control over both pattern matching and page size for optimal performance.

      Parameters:
      pattern - optional glob pattern (* = any chars, ? = single char), null = match all
      pageSize - number of elements to fetch per scan operation (1-10000 recommended)
      Returns:
      an Iterable for iterating over matching elements with the specified page size
      Throws:
      IllegalArgumentException - if pageSize invalid input: '<'= 0
      Since:
      1.3

    • addAsync

      public CompletableFuture<Boolean> addAsync(@Nullable E element)
      Asynchronously adds an element to the set.

      If the element is already present, this operation has no effect.

      Parameters:
      element - the element to add (serialized via ClientSerializer)
      Returns:
      a CompletableFuture with true if the element was newly added; false if it already existed

    • removeAsync

      public CompletableFuture<Boolean> removeAsync(@Nullable E element)
      Asynchronously removes an element from the set.

      If the element is not present, this operation has no effect.

      Parameters:
      element - the element to remove
      Returns:
      a CompletableFuture with true if the element was present and removed; false if it was not found

    • containsAsync

      public CompletableFuture<Boolean> containsAsync(@Nullable E element)
      Asynchronously checks whether an element exists in the set.
      Parameters:
      element - the element to check for
      Returns:
      a CompletableFuture with true if the element is present; false otherwise

    • sizeAsync

      public CompletableFuture<Integer> sizeAsync()
      Asynchronously returns the number of elements in the set.
      Returns:
      a CompletableFuture with the number of unique elements

    • clearAsync

      public CompletableFuture<Void> clearAsync()
      Asynchronously removes all elements from the set, leaving it empty.
      Returns:
      a CompletableFuture that completes when the clear operation is done