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

Class UnifiedCacheBase<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>
    public abstract class UnifiedCacheBase<K,​V>
extends Object
implements Cache<K,​V>
    Unified base class for all cache implementations providing comprehensive functionality.

    This class consolidates functionality from multiple inheritance layers into a single, efficient base class that provides:

    • Core Operations: Parameter validation, statistics tracking, configuration management
    • Data Storage: ConcurrentHashMap-based storage with optimal capacity calculation
    • Concurrency: Striped locking, thread-safe operations, eviction management
    • Collection Views: Efficient keys(), values(), entries() implementations
    • Async Operations: CompletableFuture-based async method implementations
    • Event Handling: Event listener notification system
    • Maintenance: Scheduled cleanup and expiration handling

    This unified approach eliminates the complexity of multiple inheritance layers while providing all necessary functionality for cache implementations.

    Since:
    1.0.0

    • Constructor Detail

      • UnifiedCacheBase

        protected UnifiedCacheBase​(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)
        Description copied from interface: Cache
        Returns the value associated with the key in this cache, or null if there is no cached value for the key.
        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)
        Description copied from interface: Cache
        Associates the specified value with the specified key in this cache.
        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)
        Description copied from interface: Cache
        Removes the mapping for a key from this cache if it is present.
        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()
        Description copied from interface: Cache
        Removes all mappings from this cache.
        Specified by:
        clear in interface Cache<K,​V>

      • containsKey

        public final boolean containsKey​(K key)
        Description copied from interface: Cache
        Returns true if this cache contains a mapping for the specified key.
        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

      • size

        public final long size()
        Description copied from interface: Cache
        Returns the approximate number of entries in this cache.
        Specified by:
        size in interface Cache<K,​V>
        Returns:
        the number of entries in this cache

      • keys

        public final Set<K> keys()
        Description copied from interface: Cache
        Returns a view of all the keys in this cache.
        Specified by:
        keys in interface Cache<K,​V>
        Returns:
        a set view of the keys contained in this cache

      • values

        public final Collection<V> values()
        Description copied from interface: Cache
        Returns a view of all the values in this cache.
        Specified by:
        values in interface Cache<K,​V>
        Returns:
        a collection view of the values contained in this cache

      • entries

        public final Set<Map.Entry<K,​V>> entries()
        Description copied from interface: Cache
        Returns a view of all the key-value pairs in this cache.
        Specified by:
        entries in interface Cache<K,​V>
        Returns:
        a set view of the mappings contained in this cache

      • 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

      • config

        public final CacheConfig<K,​V> config()
        Description copied from interface: Cache
        Returns the cache configuration.
        Specified by:
        config in interface Cache<K,​V>
        Returns:
        the cache configuration

      • stats

        public final CacheStats stats()
        Description copied from interface: Cache
        Returns the cache statistics.
        Specified by:
        stats in interface Cache<K,​V>
        Returns:
        the cache statistics

      • 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.

      • validateValue

        protected boolean validateValue​(V value)
        Validates that a value is acceptable.

      • isValidEntry

        protected boolean isValidEntry​(CacheEntry<V> entry)
        Checks if an entry is valid (not expired, etc.).

      • recordGetStatistics

        protected void recordGetStatistics​(boolean hit)
        Records statistics for get operations.

      • recordPutStatistics

        protected void recordPutStatistics()
        Records statistics for put operations.

      • recordRemoveStatistics

        protected void recordRemoveStatistics​(boolean removed)
        Records statistics for remove operations.

      • recordClearStatistics

        protected void recordClearStatistics​(long sizeBefore)
        Records statistics for clear operations.

      • updateStatsFromCounters

        protected void updateStatsFromCounters()
        Updates statistics from internal counters.

      • isSizeLimitReached

        protected boolean isSizeLimitReached()
        Checks if size limit has been reached.

      • triggerEviction

        protected void triggerEviction()
        Triggers eviction when size limit is reached.

      • calculateOptimalCapacity

        protected static int calculateOptimalCapacity​(long maximumSize)
        Calculates optimal capacity for the underlying ConcurrentHashMap.

      • getStripeIndex

        protected int getStripeIndex​(K key)
        Gets the stripe index for a key.

      • scheduleCleanup

        protected void scheduleCleanup()
        Schedules cleanup operations for expired entries.

      • scheduleRefresh

        protected void scheduleRefresh()
        Schedules refresh operations.

      • cleanupExpiredEntries

        protected void cleanupExpiredEntries()
        Cleans up expired entries.

      • refreshStaleEntries

        protected void refreshStaleEntries()
        Refreshes stale entries.

      • shutdown

        public void shutdown()
        Shuts down the cache and cleans up resources.