Class LoomCache

java.lang.Object
com.loomcache.client.LoomCache
All Implemented Interfaces:
AutoCloseable
public final class LoomCache extends Object implements AutoCloseable
Simplified entry point for the LoomCache client SDK.

This is a convenience wrapper around LoomClient that provides a higher-level fluent interface for applications that do not need advanced configuration. For applications requiring fine-grained control over connection parameters, timeouts, near-cache settings, or TLS, use LoomClient directly via its builder.

Quick Start

LoomCache cache = LoomCache.connect("127.0.0.1:5701", "127.0.0.1:5702");

// Access distributed data structures
LoomMap<String, String> users = cache.getMap("users");
users.put("user:1", "Alice");
String name = users.get("user:1");

// Publish-subscribe messaging
LoomTopic<String> events = cache.getTopic("events");
events.publish("user-logged-in");

// FIFO queuing
LoomQueue<String> tasks = cache.getQueue("tasks");
tasks.offer("send-email");
String task = tasks.poll();

// Always clean up
cache.close();

Supported Data Structures

  • Distributed Map: getMap(String) — Key-value store with TTL support
  • Distributed Queue: getQueue(String) — FIFO queue for job distribution
  • Distributed Topic: getTopic(String) — Publish-subscribe messaging
  • Distributed Set: getSet(String) — Unique elements with set operations
  • CP Lock: Use LoomClient CP subsystem directly for linearizable locks
  • CP Atomic Long: Use LoomClient CP subsystem directly for atomic counters

Thread Safety

This class is thread-safe. All returned data structure proxies are thread-safe and can be safely shared across threads.

Advanced Usage

For fine-grained control, construct a LoomClient directly: 
LoomClient client = LoomClient.builder()
    .addSeed("127.0.0.1:5701")
    .connectionTimeout(Duration.ofSeconds(10))
    .requestTimeout(Duration.ofSeconds(30))
    .nearCacheTtl(Duration.ofMinutes(5))
    .tlsConfig(...)  // Enable TLS
    .build();
client.connect();

LoomCache cache = LoomCache.wrap(client);
Since:
1.0
See Also:

  • Method Details

    • connect

      public static LoomCache connect(String... seeds)
      Connect to a LoomCache cluster using default configuration.

      Creates a new LoomClient with default settings and connects to the specified cluster nodes. For advanced configuration, use LoomClient.builder() directly.

      Parameters:
      seeds - one or more cluster node addresses (format: "host:port")
      Returns:
      a connected LoomCache instance
      Throws:
      NullPointerException - if seeds array is null
      ConnectionException - if all seed nodes are unreachable or connection fails
      See Also:

    • connect

      public static LoomCache connect(List<String> seeds)
      Connect to a LoomCache cluster using default configuration.

      Creates a new LoomClient with default settings and connects to the specified cluster nodes. For advanced configuration, use LoomClient.builder() directly.

      Parameters:
      seeds - a list of cluster node addresses (format: "host:port", must not be null)
      Returns:
      a connected LoomCache instance
      Throws:
      NullPointerException - if seeds list is null
      ConnectionException - if all seed nodes are unreachable or connection fails
      See Also:

    • wrap

      public static LoomCache wrap(LoomClient client)
      Wrap an existing LoomClient in a LoomCache instance. Used by Spring Boot auto-configuration to wrap a pre-configured client.
      Parameters:
      client - the LoomClient instance (must not be null and must already be connected)
      Returns:
      a LoomCache wrapper
      Throws:
      NullPointerException - if client is null

    • connectFailover

      public static LoomCache connectFailover(ClientFailoverConfig config)
      Connect using an ordered blue/green failover configuration.
      Parameters:
      config - failover client configuration
      Returns:
      a cache wrapper around the first reachable configured client

    • addLifecycleListener

      public LoomCache addLifecycleListener(LifecycleListener listener)

    • removeLifecycleListener

      public boolean removeLifecycleListener(LifecycleListener listener)

    • addMembershipListener

      public LoomCache addMembershipListener(MembershipListener listener)

    • removeMembershipListener

      public boolean removeMembershipListener(MembershipListener listener)

    • addDistributedObjectListener

      public LoomCache addDistributedObjectListener(DistributedObjectListener listener)

    • removeDistributedObjectListener

      public boolean removeDistributedObjectListener(DistributedObjectListener listener)

    • getMap

      public LoomMap<String,String> getMap(String name)
      Get a distributed map proxy.

      The returned map is backed by the LoomCache cluster and can be used for atomic, linearizable key-value operations. Multiple threads may safely use the same map proxy concurrently.

      Parameters:
      name - the name of the distributed map
      Returns:
      a distributed map proxy with String keys and String values
      Throws:
      LoomException - if the cluster is unavailable
      See Also:

    • getQueue

      public LoomQueue<String> getQueue(String name)
      Get a distributed queue proxy.

      The returned queue is a FIFO (first-in-first-out) queue backed by the LoomCache cluster. Elements are inserted at the tail and removed from the head. Useful for job queues, task distribution, and event ordering. Multiple threads may safely enqueue and dequeue concurrently.

      Parameters:
      name - the name of the distributed queue
      Returns:
      a distributed queue proxy with String elements
      Throws:
      LoomException - if the cluster is unavailable
      See Also:

    • getMultiMap

      public LoomMultiMap<String,String> getMultiMap(String name)

    • getList

      public LoomList<String> getList(String name)

    • getPriorityQueue

      public LoomPriorityQueue<String> getPriorityQueue(String name)

    • getRingbuffer

      public LoomRingbuffer<String> getRingbuffer(String name)

    • getRingbuffer

      public LoomRingbuffer<String> getRingbuffer(String name, int capacity)

    • getReliableTopic

      public LoomReliableTopic<String> getReliableTopic(String name)

    • getReliableTopic

      public LoomReliableTopic<String> getReliableTopic(String name, int capacity, TopicOverloadPolicy policy)

    • getPNCounter

      public LoomPNCounter getPNCounter(String name)

    • getGSet

      public LoomGSet<String> getGSet(String name)

    • getORSet

      public LoomORSet<String> getORSet(String name)

    • getLWWRegister

      public LoomLWWRegister<String> getLWWRegister(String name)

    • getIdGenerator

      public LoomIdGenerator getIdGenerator(String name)

    • getIdGenerator

      public LoomIdGenerator getIdGenerator(String name, int prefetchCount, long prefetchValidityMillis)

    • getTopic

      public LoomTopic<String> getTopic(String name)
      Get a distributed topic proxy for publish-subscribe messaging.

      The returned topic allows publishers to broadcast messages to all subscribers. Multiple threads may safely publish concurrently. Subscription support is a placeholder for future implementation.

      Parameters:
      name - the name of the distributed topic
      Returns:
      a distributed topic proxy with String messages
      Throws:
      LoomException - if the cluster is unavailable
      See Also:

    • getSet

      public LoomSet<String> getSet(String name)
      Get a distributed set proxy.

      The returned set stores unique elements (no duplicates) in an unordered collection. Useful for membership tests, deduplication, and set operations. Multiple threads may safely add and remove elements concurrently.

      Parameters:
      name - the name of the distributed set
      Returns:
      a distributed set proxy with String elements
      Throws:
      LoomException - if the cluster is unavailable
      See Also:

    • batch

      public LoomBatch batch()
      Create a new LoomBatch for batching multiple data-structure operations into a single server-side execution.

      Batching reduces network round-trips and increases throughput for high-volume operations. All operations in a batch are executed atomically on the server.

      Returns:
      a new batch builder
      Since:
      1.3
      See Also:

    • isConnected

      public boolean isConnected()
      Checks whether the cache is connected to the cluster.
      Returns:
      true if connected to at least one cluster node; false otherwise

    • connectedNodes

      public int connectedNodes()
      Returns the number of connected cluster nodes.
      Returns:
      the count of nodes currently connected (0 if disconnected)

    • close

      public void close()
      Closes the cache connection and releases all resources.

      After closing, no further operations can be performed on this instance. This method is idempotent and safe to call multiple times.

      Specified by:
      close in interface AutoCloseable