Class LoomQueryCache<K,V>

java.lang.Object
com.loomcache.client.query.LoomQueryCache<K,V>
Type Parameters:
K - the key type (must round-trip through ClientSerializer)
V - the value type (must round-trip through ClientSerializer)
All Implemented Interfaces:
AutoCloseable
public final class LoomQueryCache<K,V> extends Object implements AutoCloseable
Client-side proxy for a continuous query cache — a locally materialized, predicate-filtered view over a distributed LoomMap.

Relationship to the server-side ContinuousQueryCache

The server-side ContinuousQueryCache is an in-process view maintained on a single node. There is no wire message to subscribe a remote client to it, and the existing MapChangeListener wire protocol delivers serialized String key/value pairs only. Consequently, this client proxy implements its own filtered view backed by the existing listener push channel plus an initial seed scan. The predicate is evaluated client-side against deserialized values; no predicate is shipped to the server. This keeps the v2.0 surface additive — no new MessageType entries are required — while giving client callers the same CQC-style API as the server-side class.

Lifecycle

  • create(LoomClient, String, BiPredicate, Class, Class) registers a LoomClient.MapChangeListener (via the existing registerMapListener), then seeds the view by scanning the source map. Events delivered between registration and seed completion are recorded in bootstrapDirtyKeys so the scan does not overwrite newer values.
  • Live mutations are evaluated against predicate: matching entries are inserted or updated in the local view; non-matching entries are removed.
  • close() deregisters the listener and freezes the view.

Thread safety

The backing view is a ConcurrentHashMap; listener dispatch uses CopyOnWriteArrayList. All public methods are safe for concurrent use.
Since:
2.0

  • Method Details

    • create

      public static <K,V> LoomQueryCache<K,V> create(LoomClient client, String sourceMapName, BiPredicate<K,V> predicate, Class<K> keyType, Class<V> valueType)
      Create a client-side continuous query cache over the named map.

      The predicate is evaluated client-side after deserializing every incoming event payload via ClientSerializer. Entries whose deserialized type does not match keyType / valueType are ignored (and counted against predicateEvaluations).

      Type Parameters:
      K - key type
      V - value type
      Parameters:
      client - connected LoomClient (must be connected before calling)
      sourceMapName - name of the distributed map to observe
      predicate - client-side filter predicate (non-null)
      keyType - runtime Class for K
      valueType - runtime Class for V
      Returns:
      an active LoomQueryCache; call close() to tear it down
      Throws:
      LoomException - if listener registration fails

    • createServerFiltered

      public static <K,V> LoomQueryCache<K,V> createServerFiltered(LoomClient client, String sourceMapName, SerializablePredicate serverPredicate, Class<K> keyType, Class<V> valueType)
      Create a client-side continuous query cache with server-side predicate evaluation.

      Unlike create(LoomClient, String, BiPredicate, Class, Class), the supplied SerializablePredicate is shipped over the wire via MessageType.CQC_SUBSCRIBE and evaluated server-side. Only entries matching the predicate are pushed back to this client as CQC_EVENT messages — non-matching mutations never traverse the wire, saving bandwidth on large maps.

      Client-side events are delivered through the same LoomClient.MapChangeListener adapter used by the legacy client-filter path, so event handling and the local view semantics are identical. Because the predicate has already been evaluated server-side, the client-side BiPredicate degrades to (k, v) -> true.

      Type Parameters:
      K - key type
      V - value type
      Parameters:
      client - connected LoomClient
      sourceMapName - source map name (non-blank)
      serverPredicate - the wire-serializable predicate to evaluate server-side
      keyType - runtime Class for K
      valueType - runtime Class for V
      Returns:
      an active LoomQueryCache; call close() to tear it down
      Throws:
      LoomException - if CQC registration fails on every connected node
      Since:
      2.0

    • get

      public @Nullable V get(K key)
      Look up a key in the locally cached view.
      Parameters:
      key - the key (non-null)
      Returns:
      the cached value, or null if the entry does not match

    • containsKey

      public boolean containsKey(K key)
      True if the locally cached view contains the given key.

    • size

      public int size()
      Number of entries in the locally cached view.

    • isEmpty

      public boolean isEmpty()
      True if the locally cached view has no entries.

    • snapshot

      public Map<K,V> snapshot()
      Immutable snapshot of the current view. Iteration order is unspecified.

    • keySet

      public Set<K> keySet()
      Unmodifiable view of current keys.

    • values

      public Collection<V> values()
      Unmodifiable view of current values.

    • isActive

      public boolean isActive()
      True while this proxy is actively receiving events from the server.

    • addListener

      public void addListener(LoomQueryCache.CQCListener<K,V> listener)
      Register a listener for view-level change notifications.
      Parameters:
      listener - listener to add (non-null)

    • removeListener

      public boolean removeListener(LoomQueryCache.CQCListener<K,V> listener)
      Remove a previously registered listener.
      Returns:
      true if the listener was present and removed

    • getStatistics

      public LoomQueryCache.QueryCacheStatistics getStatistics()
      Returns:
      snapshot of this query cache's observability counters

    • close

      public void close()
      Deregister from the server and freeze the view. Idempotent.
      Specified by:
      close in interface AutoCloseable