Class Cache<K,​V>

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected Cache()  
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract V cache​(K key, V value)
      Places a value in the cache only if no value exists with the same key.
      boolean contains​(K key)
      Gets a value indicating whether a cached value exists for the given key.
      boolean contains​(K key, V value)
      Gets a value indicating whether the cached value matches the given value for a specified key.
      static <K,​V>
      Cache<K,​V>
      createSatelliteCache()
      Creates an unsynchronized, concurrency-unsafe Level 1 cache that can only be used safely by a single thread.
      static <K,​V>
      Cache<K,​V>
      createSatelliteCache​(Cache<K,​V> parent)
      Creates an unsynchronized, concurrency-unsafe Level 2 cache that can only be used safely by a single thread.
      static <K,​V>
      Cache<K,​V>
      createSatelliteIdentityCache()
      Creates an unsynchronized, concurrency-unsafe Level 1 cache that can only be used safely by a single thread.
      static <K,​V>
      Cache<K,​V>
      createSatelliteIdentityCache​(Cache<K,​V> parent)
      Creates an unsynchronized, concurrency-unsafe Level 2 cache that can only be used safely by a single thread.
      static <K,​V>
      Cache<K,​V>
      createThreadLocalCache()
      Creates a Level 1 cache that internally maintains a separate satellite cache for each thread that accesses it.
      static <K,​V>
      Cache<K,​V>
      createThreadLocalCache​(Cache<K,​V> parent)
      Creates a Level 2 cache that internally maintains a separate satellite cache for each thread that accesses it.
      static <K,​V>
      Cache<K,​V>
      createThreadLocalIdentityCache()
      Creates a Level 1 cache that internally maintains a separate satellite cache for each thread that accesses it.
      static <K,​V>
      Cache<K,​V>
      createThreadLocalIdentityCache​(Cache<K,​V> parent)
      Creates a Level 2 cache that internally maintains a separate satellite cache for each thread that accesses it.
      static <K,​V>
      Cache<K,​V>
      createTopLevelCache()
      Creates a concurrency-safe Level 1 cache that may be used in isolation or as the root cache in a multi-level cache design.
      abstract V get​(K key)
      Gets the value associated with the given key.
      abstract Cache<K,​V> getSatelliteCache()
      Returns a thread-specific satellite cache chained to this cache.
      abstract boolean replace​(K key, V expectedValue, V updatedValue)
      Replaces the value associated with a given key if the current value matches the expected value.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Cache

        protected Cache()
    • Method Detail

      • contains

        public boolean contains​(K key)
        Gets a value indicating whether a cached value exists for the given key.
      • contains

        public boolean contains​(K key,
                                V value)
        Gets a value indicating whether the cached value matches the given value for a specified key.
      • getSatelliteCache

        public abstract Cache<K,​V> getSatelliteCache()
        Returns a thread-specific satellite cache chained to this cache. If the target cache is already a satellite cache, it will simply return itself. Note that the returned cache is completely unsynchronized and is not safe for concurrent access.
        Returns:
        A thread-specific satellite cache.
      • replace

        public abstract boolean replace​(K key,
                                        @Nullable
                                        V expectedValue,
                                        V updatedValue)

        Replaces the value associated with a given key if the current value matches the expected value.

        Note that the replaced value will not be propagated to child caches that already have a value for the same key. As such, this method is of limited usefulness and should only be called on isolated Level 1 caches.

        Parameters:
        key - The key for which to change the associated value.
        expectedValue - The expected value to be replaced.
        updatedValue - The new value.
        Returns:
        true if the expected value was replaced; otherwise, false.
      • get

        public abstract V get​(K key)
        Gets the value associated with the given key.
        Parameters:
        key - The key associated with the desired value.
        Returns:
        The value corresponding the given key, or null if no value was found.
      • cache

        public abstract V cache​(K key,
                                V value)
        Places a value in the cache only if no value exists with the same key.
        Parameters:
        key - The key associated with the given value.
        value - The value to insert into the cache.
        Returns:
        The cached value associated with the given key, which will be the provided value if no existing value was found.
      • createTopLevelCache

        public static <K,​V> Cache<K,​V> createTopLevelCache()
        Creates a concurrency-safe Level 1 cache that may be used in isolation or as the root cache in a multi-level cache design.
        Type Parameters:
        K - The type of keys used to identify values in the cache.
        V - The type of values stored in the cache.
        Returns:
        The newly created cache.
      • createSatelliteCache

        public static <K,​V> Cache<K,​V> createSatelliteCache()
        Creates an unsynchronized, concurrency-unsafe Level 1 cache that can only be used safely by a single thread.
        Type Parameters:
        K - The type of keys used to identify values in the cache.
        V - The type of values stored in the cache.
        Returns:
        The newly created cache.
      • createSatelliteCache

        public static <K,​V> Cache<K,​V> createSatelliteCache​(Cache<K,​V> parent)
        Creates an unsynchronized, concurrency-unsafe Level 2 cache that can only be used safely by a single thread. On a cache miss, the parent cache will be checked. On an insert, the value will propagate up to the parent cache.
        Type Parameters:
        K - The type of keys used to identify values in the cache.
        V - The type of values stored in the cache.
        Returns:
        The newly created cache.
      • createSatelliteIdentityCache

        public static <K,​V> Cache<K,​V> createSatelliteIdentityCache()
        Creates an unsynchronized, concurrency-unsafe Level 1 cache that can only be used safely by a single thread. Keys are compared by reference identity.
        Type Parameters:
        K - The type of keys used to identify values in the cache.
        V - The type of values stored in the cache.
        Returns:
        The newly created cache.
      • createSatelliteIdentityCache

        public static <K,​V> Cache<K,​V> createSatelliteIdentityCache​(Cache<K,​V> parent)
        Creates an unsynchronized, concurrency-unsafe Level 2 cache that can only be used safely by a single thread. On a cache miss, the parent cache will be checked. On an insert, the value will propagate up to the parent cache. Keys are compared by reference identity.
        Type Parameters:
        K - The type of keys used to identify values in the cache.
        V - The type of values stored in the cache.
        Returns:
        The newly created cache.
      • createThreadLocalCache

        public static <K,​V> Cache<K,​V> createThreadLocalCache()
        Creates a Level 1 cache that internally maintains a separate satellite cache for each thread that accesses it.
        Type Parameters:
        K - The type of keys used to identify values in the cache.
        V - The type of values stored in the cache.
        Returns:
        The newly created cache.
      • createThreadLocalIdentityCache

        public static <K,​V> Cache<K,​V> createThreadLocalIdentityCache()
        Creates a Level 1 cache that internally maintains a separate satellite cache for each thread that accesses it. Keys are compared by reference identity.
        Type Parameters:
        K - The type of keys used to identify values in the cache.
        V - The type of values stored in the cache.
        Returns:
        The newly created cache.
      • createThreadLocalCache

        public static <K,​V> Cache<K,​V> createThreadLocalCache​(Cache<K,​V> parent)
        Creates a Level 2 cache that internally maintains a separate satellite cache for each thread that accesses it. On a cache miss, the parent cache will be checked. On an insert, the value will propagate up to the parent cache.
        Type Parameters:
        K - The type of keys used to identify values in the cache.
        V - The type of values stored in the cache.
        Returns:
        The newly created cache.
      • createThreadLocalIdentityCache

        public static <K,​V> Cache<K,​V> createThreadLocalIdentityCache​(Cache<K,​V> parent)
        Creates a Level 2 cache that internally maintains a separate satellite cache for each thread that accesses it. On a cache miss, the parent cache will be checked. On an insert, the value will propagate up to the parent cache. Keys are compared by reference identity.
        Type Parameters:
        K - The type of keys used to identify values in the cache.
        V - The type of values stored in the cache.
        Returns:
        The newly created cache.