Package com.sodius.oslc.core.cache

Class CacheBuilder<K,V>

java.lang.Object
com.sodius.oslc.core.cache.CacheBuilder<K,V>
Type Parameters:
K - the type of keys maintained by this cache
V - the type of mapped values
public abstract class CacheBuilder<K,V> extends Object
A builder of Cache instances.

An application supporting clusters must register a factory at application initialization time, to use a CacheBuilder subclass when a cluster cache is desired.

Since:
3.7.0

  • Constructor Summary

    Constructors
    Constructor
    Description
    CacheBuilder()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract Cache<K,V>
    build(String title)
    Builds a synchronous cache which does not automatically load values when keys are requested.
    static <V extends Serializable>
    CacheBuilder<String,V>
    cluster()
    Creates a builder for a cache that is to be valid in a cluster environment.
    static <V> CacheBuilder<String,V>
    clusteredLocal(long synchronizationThreshold)
    Creates a builder for a cache that is valid only within the current JVM, but that synchronizes with a cluster cache to detect when one cluster node invalidated some keys and when values need to be recomputed.
    CacheBuilder<K,V>
    expireAfterWrite(long duration, TimeUnit unit)
    Specifies that each entry should be automatically removed from the cache once a fixed duration has elapsed after the entry's creation, or the most recent replacement of its value.
    CacheBuilder<K,V>
    expireAfterWrite(String durationProperty, long duration, TimeUnit unit)
    Specifies that each entry should be automatically removed from the cache once a fixed duration has elapsed after the entry's creation, or the most recent replacement of its value.
    long
    getExpireAfterWriteMillis()
    Returns the duration in milliseconds after an entry is created that it should be automatically removed.
    long
    getMaximumSize()
    Returns the the maximum size of the cache, or -1 if not set
    static <K, V> CacheBuilder<K,V>
    local()
    Creates a builder for a cache that is valid only within the current JVM and cannot be shared across cluster nodes.
    CacheBuilder<K,V>
    maximumSize(long maximumSize)
    Specifies the maximum number of entries the cache may contain.
    static void
    setClusterFactory(Supplier<CacheBuilder<String,? extends Serializable>> builderFactory)
    Sets a factory to create a cluster-enabled CacheBuilder instance.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • CacheBuilder

      public CacheBuilder()

  • Method Details

    • setClusterFactory

      public static void setClusterFactory(Supplier<CacheBuilder<String,? extends Serializable>> builderFactory)
      Sets a factory to create a cluster-enabled CacheBuilder instance.

      The builder subclass must create a synchronous cache, that guarantees keys and values are immediately available to all nodes of the cluster. This usually goes with storing those cache entries in a database.

      Parameters:
      builderFactory - the supplier of cluster-enabled CacheBuilder
      See Also:

    • local

      public static <K, V> CacheBuilder<K,V> local()
      Creates a builder for a cache that is valid only within the current JVM and cannot be shared across cluster nodes.

      Use this cache to improve the performance and when each node can recompute the values whenever needed. Consider using clusteredLocal(long) if the source of the cached data can change and each cluster node needs to reload the values on next cache access.

      Type Parameters:
      K - the type of keys maintained by this cache builder
      V - the type of mapped values
      Returns:
      a local cache builder

    • clusteredLocal

      public static <V> CacheBuilder<String,V> clusteredLocal(long synchronizationThreshold)
      Creates a builder for a cache that is valid only within the current JVM, but that synchronizes with a cluster cache to detect when one cluster node invalidated some keys and when values need to be recomputed.

      Use this cache to improve the performance and when each node can recompute the values whenever needed. Each cluster node must invalidate the keys of the cache when a change in the local application that impact them is detected. This cache enables to use a long expiration to maximize the performances but also to immediately refresh the data when a configuration is changed. This cache is not to use when the potential changes occur in remote applications.

      When the source of the cached data is changed, the application must call Cache.invalidate(Object) or Cache.invalidateAll() to indicate some keys are to refresh. This makes other cluster nodes to detect the values need a refresh the next time those keys are accessed. Calling Cache.put(Object, Object) also makes other cluster nodes to detect values need a refresh; however the actual values stored with Cache.put(Object, Object) are not propagated to other cluster nodes (consider using cluster() for such case). Values should only be stored in this cache with Cache.get(Object, java.util.function.Function) to make sure each cluster node loads the data the same way.

      The synchronizationThreshold parameter is the delay in milliseconds between two synchronizations with the cluster cache to verify whether a given key was invalidated. It enables to avoid constantly accessing the cluster cache (usually a database) when the same key is accessed multiple times in a short period of time. There are cases where we want to wait for something like at most 3 seconds to have the values accurate. There are other cases where we can afford to wait longer, to minimize the cluster connections on high load usage, like when the cache is accessed for each incoming HTTP servlet request and the source of the cached data is rarely changed.

      Applications supporting clusters must register a factory at application initialization time, to create cluster-enabled CacheBuilder instances. In the absence of such factory, a local cache is returned.

      Type Parameters:
      V - the base value type for all caches created by this builder
      Parameters:
      synchronizationThreshold - the delay in milliseconds between two synchronizations with the cluster cache for a given key
      Returns:
      a cache builder
      Since:
      4.0.0

    • cluster

      public static <V extends Serializable> CacheBuilder<String,V> cluster()
      Creates a builder for a cache that is to be valid in a cluster environment.

      Use this cache when some information computed on a cluster node must be immediately available to all other nodes and cannot be computed locally. Such cache is similar to a database table to share information across cluster nodes, but with an expiration and maximum size for entries.

      Applications supporting clusters must register a factory at application initialization time, to create cluster-enabled CacheBuilder instances. In the absence of such factory, a local cache is returned.

      Type Parameters:
      V - the base value type for all caches created by this builder
      Returns:
      a cache builder
      See Also:

    • expireAfterWrite

      public CacheBuilder<K,V> expireAfterWrite(long duration, TimeUnit unit)
      Specifies that each entry should be automatically removed from the cache once a fixed duration has elapsed after the entry's creation, or the most recent replacement of its value.
      Parameters:
      duration - the length of time after an entry is created that it should be automatically removed
      unit - the unit that duration is expressed in
      Returns:
      this cache builder
      Throws:
      IllegalArgumentException - if duration is negative
      IllegalStateException - if a duration was already set

    • expireAfterWrite

      public CacheBuilder<K,V> expireAfterWrite(String durationProperty, long duration, TimeUnit unit)
      Specifies that each entry should be automatically removed from the cache once a fixed duration has elapsed after the entry's creation, or the most recent replacement of its value. Unlike expireAfterWrite(long, TimeUnit), this method searches a system property whose value, if found, overrides the duration in milliseconds.
      Parameters:
      durationProperty - the system property name for overriding the default duration if found
      duration - the length of time after an entry is created that it should be automatically removed, if the durationProperty is not found.
      unit - the unit that duration is expressed in
      Returns:
      this cache builder
      Throws:
      NullPointerException - if durationProperty is empty.
      IllegalArgumentException - if duration is negative.
      IllegalStateException - if a duration was already set.
      Since:
      4.0.0

    • maximumSize

      public CacheBuilder<K,V> maximumSize(long maximumSize)
      Specifies the maximum number of entries the cache may contain. Note that a cluster cache is not entitled to support a maximum size and may decide to silently ignore this setting.
      Parameters:
      maximumSize - the maximum size of the cache
      Returns:
      this cache builder
      Throws:
      IllegalArgumentException - if maximumSize is negative
      IllegalStateException - if a maximum size was already set

    • build

      public abstract Cache<K,V> build(String title)
      Builds a synchronous cache which does not automatically load values when keys are requested.

      For cluster-enabled builders, consider extending AbstractCache to limit the effort in supporting entries expiration.

      Parameters:
      title - the cache title
      Returns:
      a cache having the requested features

    • getExpireAfterWriteMillis

      public long getExpireAfterWriteMillis()
      Returns the duration in milliseconds after an entry is created that it should be automatically removed.
      Returns:
      the duration in milliseconds after an entry is created that it should be automatically removed

    • getMaximumSize

      public long getMaximumSize()
      Returns the the maximum size of the cache, or -1 if not set
      Returns:
      the maximum size of the cache