Package io.github.dhruv1110.jcachex.impl.base

Class AbstractCacheBase<K,​V>

  • Type Parameters:
    K - the type of keys maintained by this cache
    V - the type of mapped values
    All Implemented Interfaces:
    Cache<K,​V>
    Direct Known Subclasses:
    DataBackedCacheBase
    public abstract class AbstractCacheBase<K,​V>
extends Object
implements Cache<K,​V>
    Abstract base class for all cache implementations providing common functionality. This class implements the common patterns found across cache implementations: - Parameter validation - Statistics tracking - Configuration management - Async operation wrappers - Template methods for extension points

    • Field Detail

      • statsEnabled

        protected final boolean statsEnabled

      • maximumSize

        protected final long maximumSize

      • hasExpiration

        protected final boolean hasExpiration

      • hasMaximumSize

        protected final boolean hasMaximumSize

      • hasMaximumWeight

        protected final boolean hasMaximumWeight

    • Constructor Detail

      • AbstractCacheBase

        protected AbstractCacheBase​(CacheConfig<K,​V> config)
        Constructor for all cache implementations.
        Parameters:
        config - the cache configuration
        Throws:
        IllegalArgumentException - if config is null

    • Method Detail

      • get

        public final V get​(K key)
        Template method for get operation with common validation and statistics.
        Specified by:
        get in interface Cache<K,​V>
        Parameters:
        key - the key whose associated value is to be returned
        Returns:
        the value to which the specified key is mapped, or null if this cache contains no mapping for the key

      • put

        public final void put​(K key,
                      V value)
        Template method for put operation with common validation.
        Specified by:
        put in interface Cache<K,​V>
        Parameters:
        key - key with which the specified value is to be associated
        value - value to be associated with the specified key

      • remove

        public final V remove​(K key)
        Template method for remove operation with common validation.
        Specified by:
        remove in interface Cache<K,​V>
        Parameters:
        key - key whose mapping is to be removed from the cache
        Returns:
        the previous value associated with key, or null if there was no mapping for key

      • clear

        public final void clear()
        Template method for clear operation with statistics recording.
        Specified by:
        clear in interface Cache<K,​V>

      • containsKey

        public final boolean containsKey​(K key)
        Common implementation of containsKey with validation.
        Specified by:
        containsKey in interface Cache<K,​V>
        Parameters:
        key - key whose presence in this cache is to be tested
        Returns:
        true if this cache contains a mapping for the specified key

      • stats

        public final CacheStats stats()
        Common implementation of stats() method.
        Specified by:
        stats in interface Cache<K,​V>
        Returns:
        the cache statistics

      • config

        public final CacheConfig<K,​V> config()
        Common implementation of config() method.
        Specified by:
        config in interface Cache<K,​V>
        Returns:
        the cache configuration

      • getAsync

        public CompletableFuture<V> getAsync​(K key)
        Description copied from interface: Cache
        Asynchronously returns the value associated with the key in this cache.
        Specified by:
        getAsync in interface Cache<K,​V>
        Parameters:
        key - the key whose associated value is to be returned
        Returns:
        a CompletableFuture that will be completed with the value to which the specified key is mapped, or null if this cache contains no mapping for the key

      • putAsync

        public CompletableFuture<Void> putAsync​(K key,
                                        V value)
        Description copied from interface: Cache
        Asynchronously associates the specified value with the specified key in this cache.
        Specified by:
        putAsync in interface Cache<K,​V>
        Parameters:
        key - key with which the specified value is to be associated
        value - value to be associated with the specified key
        Returns:
        a CompletableFuture that will be completed when the operation is done

      • removeAsync

        public CompletableFuture<V> removeAsync​(K key)
        Description copied from interface: Cache
        Asynchronously removes the mapping for a key from this cache if it is present.
        Specified by:
        removeAsync in interface Cache<K,​V>
        Parameters:
        key - key whose mapping is to be removed from the cache
        Returns:
        a CompletableFuture that will be completed with the previous value associated with key, or null if there was no mapping for key

      • clearAsync

        public CompletableFuture<Void> clearAsync()
        Description copied from interface: Cache
        Asynchronously removes all mappings from this cache.
        Specified by:
        clearAsync in interface Cache<K,​V>
        Returns:
        a CompletableFuture that will be completed when the operation is done

      • doGet

        protected abstract V doGet​(K key)
        Implementation-specific get operation.
        Parameters:
        key - the key (already validated)
        Returns:
        the value or null if not found/expired

      • doPut

        protected abstract void doPut​(K key,
                              V value)
        Implementation-specific put operation.
        Parameters:
        key - the key (already validated)
        value - the value (already validated)

      • doRemove

        protected abstract V doRemove​(K key)
        Implementation-specific remove operation.
        Parameters:
        key - the key (already validated)
        Returns:
        the removed value or null if not found

      • doClear

        protected abstract void doClear()
        Implementation-specific clear operation.

      • doContainsKey

        protected abstract boolean doContainsKey​(K key)
        Implementation-specific containsKey operation.
        Parameters:
        key - the key (already validated)
        Returns:
        true if key exists and is not expired

      • validateKey

        protected boolean validateKey​(K key)
        Validates that a key is not null.
        Parameters:
        key - the key to validate
        Returns:
        true if key is valid

      • validateValue

        protected boolean validateValue​(V value)
        Validates that a value is not null.
        Parameters:
        value - the value to validate
        Returns:
        true if value is valid

      • recordGetStatistics

        protected void recordGetStatistics​(boolean hit)
        Records statistics for get operations.
        Parameters:
        hit - true if the operation was a hit

      • recordPutStatistics

        protected void recordPutStatistics()
        Records statistics for put operations.

      • recordRemoveStatistics

        protected void recordRemoveStatistics​(boolean removed)
        Records statistics for remove operations.
        Parameters:
        removed - true if an entry was actually removed

      • recordClearStatistics

        protected void recordClearStatistics​(long sizeBefore)
        Records statistics for clear operations.
        Parameters:
        sizeBefore - the size before clearing

      • updateStatsFromCounters

        protected void updateStatsFromCounters()
        Updates the stats object from the atomic counters.

      • isEntryExpired

        protected boolean isEntryExpired​(CacheEntry<V> entry)
        Checks if an entry is expired based on cache configuration.
        Parameters:
        entry - the cache entry to check
        Returns:
        true if the entry is expired

      • createCacheEntry

        protected CacheEntry<V> createCacheEntry​(V value)
        Creates a cache entry with proper timestamp and expiration settings.
        Parameters:
        value - the value to wrap
        Returns:
        a new cache entry

      • isSizeLimitReached

        protected boolean isSizeLimitReached()
        Checks if the cache has reached its maximum size or weight.
        Returns:
        true if size or weight limit is exceeded

      • getCurrentWeight

        protected long getCurrentWeight()
        Calculates the current total weight of entries in the cache. Default implementation returns size as weight. Subclasses should override if they track weight separately.
        Returns:
        the current total weight

      • enforceSize

        protected void enforceSize()
        Hook for subclasses to perform size enforcement. Called after operations that might exceed size limits.