Class LoomJCache<K,V>

java.lang.Object
com.loomcache.server.jcache.LoomJCache<K,V>
Type Parameters:
K - the key type
V - the value type
All Implemented Interfaces:
ICache<K,V>, Closeable, AutoCloseable, Iterable<javax.cache.Cache.Entry<K,V>>, javax.cache.Cache<K,V>
public class LoomJCache<K,V> extends Object implements ICache<K,V>
JCache-compatible (JSR-107) cache wrapper.

Implements Cache so the cache can be used through the standard JSR-107 API. Legacy native methods (e.g. invoke(Object, EntryProcessor), registerCacheEntryListener(CacheEntryListener)) are preserved and live alongside their JSR-107 counterparts via overloading.

Supports standard cache operations: get, put, remove, containsKey, getAll, putAll, removeAll, getAndPut, getAndRemove, getAndReplace, putIfAbsent, replace, and invoke.

Supports cache entry listeners for CREATED, UPDATED, REMOVED, and EXPIRED events. Configuration is immutable and supplied at creation time.

TCK compliance: the default CI gate runs the official JSR-107 TCK harness from the jcache-tck Maven profile across provider, cache, loader/writer, entry processor, expiry, listener, management, and annotation contracts.

  • Constructor Details

    • LoomJCache

      public LoomJCache(LoomJCacheConfig<K,V> config)
      Create a new JCache instance with default manager URI.
      Parameters:
      config - the cache configuration

    • LoomJCache

      public LoomJCache(LoomJCacheConfig<K,V> config, String managerUri)
      Create a new JCache instance.
      Parameters:
      config - the cache configuration
      managerUri - the URI of the owning cache manager (for MXBean ObjectName)

    • LoomJCache

      public LoomJCache(LoomJCacheConfig<K,V> config, String managerUri, @Nullable com.loomcache.server.jcache.LoomJCacheClusterClient distributedClusterClient)

  • Method Details

    • isDistributed

      public boolean isDistributed()
      Returns:
      whether this cache is running in distributed (Raft-replicated) mode.

    • get

      public @Nullable V get(K key)
      Specified by:
      get in interface javax.cache.Cache<K,V>

    • put

      public void put(K key, V value)
      Specified by:
      put in interface javax.cache.Cache<K,V>

    • remove

      public boolean remove(K key)
      Remove a key from the cache. JSR-107 contract: returns true if a mapping was removed.
      Specified by:
      remove in interface javax.cache.Cache<K,V>

    • remove

      public boolean remove(K key, V expected)
      Remove a key only if it maps to the specified value. JSR-107 contract.
      Specified by:
      remove in interface javax.cache.Cache<K,V>

    • containsKey

      public boolean containsKey(K key)
      Specified by:
      containsKey in interface javax.cache.Cache<K,V>

    • setExpiryPolicy

      public boolean setExpiryPolicy(K key, javax.cache.expiry.ExpiryPolicy expiryPolicy)
      Description copied from interface: ICache
      Associate a live cache entry with a key-specific expiry policy.

      The supplied policy takes precedence over the cache-wide expiry policy for this key. The entry's time-to-live is recalculated immediately from ExpiryPolicy.getExpiryForUpdate(). If the key is absent or already expired, no policy is stored and the method returns false.

      Specified by:
      setExpiryPolicy in interface ICache<K,V>
      Parameters:
      key - the existing cache key
      expiryPolicy - the key-specific expiry policy
      Returns:
      true if a live entry was updated, false otherwise

    • getAsync

      public CompletableFuture<@Nullable V> getAsync(K key)
      Description copied from interface: ICache
      Asynchronously retrieve a cache entry.
      Specified by:
      getAsync in interface ICache<K,V>
      Parameters:
      key - the cache key
      Returns:
      a future completed with the value, or null if absent

    • putAsync

      public CompletableFuture<Void> putAsync(K key, V value)
      Description copied from interface: ICache
      Asynchronously store a cache entry.
      Specified by:
      putAsync in interface ICache<K,V>
      Parameters:
      key - the cache key
      value - the cache value
      Returns:
      a future completed when the write finishes

    • getAll

      public Map<K,V> getAll(Set<? extends K> keys)
      Specified by:
      getAll in interface javax.cache.Cache<K,V>

    • putAll

      public void putAll(Map<? extends K, ? extends V> map)
      Specified by:
      putAll in interface javax.cache.Cache<K,V>

    • removeAll

      public void removeAll(Set<? extends K> keys)
      Specified by:
      removeAll in interface javax.cache.Cache<K,V>

    • removeAll

      public void removeAll()
      JSR-107 Cache.removeAll(): remove every entry, firing REMOVED per entry (differs from clear() which suppresses listener events).
      Specified by:
      removeAll in interface javax.cache.Cache<K,V>

    • clear

      public void clear()
      Specified by:
      clear in interface javax.cache.Cache<K,V>

    • getAndPut

      public @Nullable V getAndPut(K key, V value)
      Specified by:
      getAndPut in interface javax.cache.Cache<K,V>

    • getAndRemove

      public @Nullable V getAndRemove(K key)
      Specified by:
      getAndRemove in interface javax.cache.Cache<K,V>

    • getAndReplace

      public @Nullable V getAndReplace(K key, V value)
      Specified by:
      getAndReplace in interface javax.cache.Cache<K,V>

    • putIfAbsent

      public boolean putIfAbsent(K key, V value)
      Specified by:
      putIfAbsent in interface javax.cache.Cache<K,V>

    • replace

      public boolean replace(K key, V value)
      Specified by:
      replace in interface javax.cache.Cache<K,V>

    • replace

      public boolean replace(K key, V oldValue, V newValue)
      Specified by:
      replace in interface javax.cache.Cache<K,V>

    • invoke

      public <T> @Nullable T invoke(K key, EntryProcessor<K,V,T> processor)
      Invoke a native entry processor on the entry for the specified key.

    • invoke

      public <T> @Nullable T invoke(K key, javax.cache.processor.EntryProcessor<K,V,T> processor, Object... args) throws javax.cache.processor.EntryProcessorException
      JSR-107 entry-processor invocation.
      Specified by:
      invoke in interface javax.cache.Cache<K,V>
      Throws:
      javax.cache.processor.EntryProcessorException

    • invokeAll

      public <T> Map<K, javax.cache.processor.EntryProcessorResult<T>> invokeAll(Set<? extends K> keys, javax.cache.processor.EntryProcessor<K,V,T> processor, Object... args)
      JSR-107 bulk entry-processor invocation.
      Specified by:
      invokeAll in interface javax.cache.Cache<K,V>

    • loadAll

      public void loadAll(Set<? extends K> keys, boolean replaceExistingValues, @Nullable javax.cache.integration.CompletionListener completionListener)
      Specified by:
      loadAll in interface javax.cache.Cache<K,V>

    • registerCacheEntryListener

      public void registerCacheEntryListener(CacheEntryListener<K,V> listener)
      Register a native cache entry listener.

    • deregisterCacheEntryListener

      public void deregisterCacheEntryListener(CacheEntryListener<K,V> listener)
      Deregister a native cache entry listener.

    • registerCacheEntryListener

      public void registerCacheEntryListener(javax.cache.configuration.CacheEntryListenerConfiguration<K,V> cfg)
      JSR-107: register a listener via its configuration.
      Specified by:
      registerCacheEntryListener in interface javax.cache.Cache<K,V>

    • deregisterCacheEntryListener

      public void deregisterCacheEntryListener(javax.cache.configuration.CacheEntryListenerConfiguration<K,V> cfg)
      JSR-107: deregister a listener by its configuration.
      Specified by:
      deregisterCacheEntryListener in interface javax.cache.Cache<K,V>

    • iterator

      public Iterator<javax.cache.Cache.Entry<K,V>> iterator()
      Specified by:
      iterator in interface javax.cache.Cache<K,V>
      Specified by:
      iterator in interface Iterable<K>

    • getConfiguration

      public LoomJCacheConfig<K,V> getConfiguration()
      Native accessor for the configuration (typed).

    • getConfiguration

      public <C extends javax.cache.configuration.Configuration<K,V>> C getConfiguration(Class<C> clazz)
      JSR-107 typed configuration accessor.
      Specified by:
      getConfiguration in interface javax.cache.Cache<K,V>

    • getName

      public String getName()
      Specified by:
      getName in interface javax.cache.Cache<K,V>

    • getCacheManager

      public @Nullable javax.cache.CacheManager getCacheManager()
      Specified by:
      getCacheManager in interface javax.cache.Cache<K,V>

    • size

      public int size()
      Get the number of entries in the cache.

      Not part of JSR-107 Cache API — provided for convenience.

    • getStatisticsManager

      public @Nullable CacheStatisticsManager getStatisticsManager()
      Get the statistics manager for this cache, if statistics are enabled.

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface javax.cache.Cache<K,V>
      Specified by:
      close in interface Closeable

    • unwrap

      public <T> T unwrap(Class<T> clazz)
      Specified by:
      unwrap in interface javax.cache.Cache<K,V>