Package org.cache2k

Class Cache2kBuilder<K,​V>

  • All Implemented Interfaces:
    ConfigBuilder<Cache2kBuilder<K,​V>,​Cache2kConfig<K,​V>>, DataAware<K,​V>
    public class Cache2kBuilder<K,​V>
extends Object
implements ConfigBuilder<Cache2kBuilder<K,​V>,​Cache2kConfig<K,​V>>, DataAware<K,​V>
    Builder to create a Cache instance. The usage is: 
    
    Cache<Long, List<String>> c =
      new Cache2kBuilder<Long, List<String>>() {}
        .name("myCache")
        .eternal(true)
        .build();

    Caches belong to a cache manager. If no cache manager is set explicitly via manager the default cache manager will be used, as defined by CacheManager.getInstance().

    To create a cache from a known configuration in a specified cache manager, use: 

    
   CacheManager manager = ...
   CacheConfiguration<Long, List<String>> config = ...

   Cache<Long, List<String>> c =
     Cache2kBuilder.of(config)
       .manager(manager)
       .build();

    To create a cache without type parameters or Cache<Object,Object>, use forUnknownTypes().

    This builder can also be used to alter and build a configuration object that can be retrieved with config()

    Since:
    1.0
    Author:
    Jens Wilke

    • Constructor Detail

      • Cache2kBuilder

        protected Cache2kBuilder()
        Constructor to override for the usage pattern: 
        
    Cache<Long, List<String>> c =
      new Cache2kBuilder<Long, List<String>>() {}
        .name("myCache")
        .eternal(true)
        .build();
        The builder extracts the generic type parameters from the anonymous subclass.

    • Method Detail

      • forUnknownTypes

        public static Cache2kBuilder<Object,​Object> forUnknownTypes()
        Create a new cache builder for a cache that has no type restrictions or to set the type information later via the builder methods keyType or valueType.

      • of

        public static <K,​V> Cache2kBuilder<K,​V> of​(Cache2kConfig<K,​V> c)
        Create a builder from the configuration bean. The builder is not assigned to a cache manager and any default configurations, if present, will not be applied.

      • manager

        public final Cache2kBuilder<K,​V> manager​(CacheManager manager)
        The manager, the created cache will belong to. If this is set, it must be the first method called.
        Parameters:
        manager - The manager the created cache should belong to, or null if the default cache manager should be used
        Throws:
        IllegalStateException - if the manager is not provided immediately after the builder is created.

      • name

        public final Cache2kBuilder<K,​V> name​(@Nullable
                                            @Nullable String uniqueName,
                                            Class<?> clazz,
                                            String fieldName)
        Constructs a cache name out of the class name, a field name and a unique name identifying the component in the application. Result example: webImagePool~com.example.ImagePool.id2Image

        See name(String) for a general discussion about cache names.

        Parameters:
        uniqueName - unique name differentiating multiple components of the same type. May be null.
        See Also:
        name(String)

      • name

        public final Cache2kBuilder<K,​V> name​(Class<?> clazz,
                                            String fieldName)
        Constructs a cache name out of the class name and field name. Result example: com.example.ImagePool.id2Image

        See name(String) for a general discussion about cache names.

        See Also:
        name(String)

      • name

        public final Cache2kBuilder<K,​V> name​(String v)
        Sets the name of a cache. If a name is specified it must be ensured it is unique within the cache manager. Cache names are used at several places to have a unique ID of a cache. For example, for referencing additional configuration or to register JMX beans.

        If a name is not specified the cache generates a name automatically. The name is inferred from the call stack trace and contains the simple class name, the method and the line number of the caller to build(). The name also contains a random number. Automatically generated names don't allow reliable management, logging and additional configuration of caches. If no name is set, build() will always create a new cache with a new unique name within the cache manager. Automatically generated cache names start with the character '_' as prefix to separate the names from the usual class name space.

        For maximum compatibility cache names should only be composed with the characters [-_.a-zA-Z0-9]. The characters {}|\^&=";:<>*?/ are not allowed in a cache name. The reason for restricting the characters in names, is that the names may be used to derive other resource names from it, e.g. for file based storage. The characters * and ? are used for wildcards in JMX and cannot be used in an object name.

        The method is overloaded with variants to provide a naming convention of names.

        For brevity within log messages and other displays the cache name may be shortened if the manager name is included as prefix.

        See Also:
        Cache.getName()

      • keepDataAfterExpired

        public final Cache2kBuilder<K,​V> keepDataAfterExpired​(boolean v)
        Expired data is kept in the cache until the entry is evicted. This consumes memory, but if the data is accessed again the previous data can be used by the cache loader for optimizing (e.g. if-modified-since for an HTTP request). Default value: false
        See Also:
        AdvancedCacheLoader

      • entryCapacity

        public final Cache2kBuilder<K,​V> entryCapacity​(long v)
        The maximum number of entries hold by the cache. When the maximum size is reached, by inserting new entries, the cache eviction algorithm will remove one or more entries to keep the size within the configured limit.

        The value Long.MAX_VALUE means the capacity is not limited.

        The default value is Cache2kConfig.DEFAULT_ENTRY_CAPACITY. The odd value is intentional, to serve as an indicator for SREs that the cache is running on its default size. A low capacity default is different to caches like Guava or Caffeine, that create an unbounded cache by default, which potentially is a memory leak.

      • eternal

        public final Cache2kBuilder<K,​V> eternal​(boolean v)
        When set to true, cached values do not expire and do not need refreshing. Entries will need to be removed from the cache explicitly, will be evicted if capacity constraints are reached, or can be evicted after a period of no usage via idleScanTime(long, TimeUnit). It also means that no expiry functions are available and MutableCacheEntry.setExpiryTime(long)` cannot be used. If no expiry is needed it is a good idea to enable eternal, which safes resources used for the timer data structures. Changing when data is considered eternal, will lead to and error.

        Setting eternal to false signals that the data might expire, but there is no predefined expiry value at programmatic level. This value needs to be set by other means, e.g. within a configuration file. This is the default setting.

        Throws:
        IllegalArgumentException - in case a previous setting is reset

      • idleScanTime

        public final Cache2kBuilder<K,​V> idleScanTime​(Duration v)
        Sets the time for a regular scan of all cache entries which evicts idle entries that are not accessed since the last scan. The effect is similar then the setting time to idle or expire after access in other caches when set to about two thirds of the time value. The actual eviction of an idle entry will approximately happen between one or two times the configured idle scan time.

        Idle scanning works in combination with a cache size limit and expiry.

        For entries removed by the idle scanner an eviction event is generated and counted as eviction in the cache statistics.

        Rationale: Although a regular scan sounds like a lot of overhead it is the opposite, since there is no additional overhead of bookkeeping when an item is accessed. This is more efficient then a straight forward time to idle implementation via a linked list.

        Since:
        2.6
        See Also:
        Github issue #39

      • writer

        public final Cache2kBuilder<K,​V> writer​(CacheWriter<K,​V> w)
        Enables write through operation and sets a writer customization that gets called synchronously upon cache mutations. By default, write through is not enabled.

      • addCacheClosedListener

        public final Cache2kBuilder<K,​V> addCacheClosedListener​(CacheClosedListener listener)
        Listener that is called after a cache is closed. This is mainly used for the JCache integration.

      • addListener

        public final Cache2kBuilder<K,​V> addListener​(CacheEntryOperationListener<K,​V> listener)
        Add a listener. The listeners will be executed in a synchronous mode, meaning, further processing for an entry will stall until a registered listener is executed. The expiry will always be executed asynchronously.
        Parameters:
        listener - The listener to add
        Throws:
        IllegalArgumentException - if an identical listener is already added.

      • refreshAhead

        public final Cache2kBuilder<K,​V> refreshAhead​(boolean f)
        When true, enable background refresh / refresh ahead. After the expiry time of a value is reached, the loader is invoked to fetch a fresh value. The old value will be returned by the cache, although it is expired, and will be replaced by the new value, once the loader is finished. In the case there are not enough loader threads available, the value will expire immediately and the next get() request will trigger the load.

        Once refreshed, the entry is in a probation period. If it is not accessed until the next expiry, no refresh will be done and the entry expires regularly. This means that the time an entry stays within the probation period is determined by the configured expiry time or the ExpiryPolicy. When an entry is not accessed for two times the expiry time, it gets removed from the cache.

        The number of threads used to do the refresh are configured via loaderThreadCount(int)

        By default, refresh ahead is not enabled.

        See Also:
        CacheLoader, loaderThreadCount(int)

      • sharpExpiry

        public final Cache2kBuilder<K,​V> sharpExpiry​(boolean f)
        By default, the time of expiry is not exact, which means, a value might be visible for up to a second longer after the requested time of expiry. The time lag depends on the system load and the parameter timerLag(long, TimeUnit) Switching to true, means that values will not be visible when the entry is reached past its expiry time which set by the ExpiryPolicy. This has no effect on expireAfterWrite(long, TimeUnit).

        Alternatively, sharp expiry can be requested on a per-entry basis in the ExpiryPolicy via Expiry.toSharpTime(long)

      • loaderThreadCount

        public final Cache2kBuilder<K,​V> loaderThreadCount​(int v)
        If no separate executor is set via loaderExecutor(Executor) the cache will create a separate thread pool used exclusively by it. Defines the maximum number of threads this cache should use for calls to the CacheLoader. The default is one thread per available CPU. If threads are exhausted the executor rejects the execution. If that happens the cache will carry out load requests in the calling thread or, in case of a refresh, drop the request.

        If a separate executor is defined the parameter has no effect.

        See Also:
        loaderExecutor(Executor), refreshExecutor(Executor)

      • storeByReference

        public final Cache2kBuilder<K,​V> storeByReference​(boolean v)
        Ensure that the cache value is stored via direct object reference and that no serialization takes place. Cache clients leveraging the fact that an in heap cache stores object references directly should set this value.

        If this value is not set to true this means: The key and value objects need to have a defined serialization mechanism and the cache may choose to transfer off the heap. For cache2k version 1.0 this value has no effect. It should be used by application developers to future-proof the applications with upcoming versions.

      • strictEviction

        public final Cache2kBuilder<K,​V> strictEviction​(boolean flag)
        To increase performance cache2k optimizes the eviction and does eviction in greater chunks. With strict eviction, the eviction is done for one entry as soon as the capacity constraint is met. This is primarily used for testing and evaluation purposes.

      • disableStatistics

        public final Cache2kBuilder<K,​V> disableStatistics​(boolean flag)
        By default, statistic gathering is enabled. Switching this to true will disable all statistics that have significant overhead. Whether the values become visible in monitoring can be controlled via disableMonitoring(boolean)

      • boostConcurrency

        public final Cache2kBuilder<K,​V> boostConcurrency​(boolean f)
        When true, optimize for high core counts and applications that do lots of mutations in the cache. When switched on, the cache will occupy slightly more memory and eviction efficiency may drop slightly. This overhead is negligible for big cache sizes (100K and more).

        Typical interactive do not need to enable this. May improve concurrency for applications that utilize all cores and cache operations account for most CPU cycles.

      • disableMonitoring

        public final Cache2kBuilder<K,​V> disableMonitoring​(boolean f)
        Disables reporting of cache metrics to monitoring systems or management. This should be set, e.g. if a cache is created dynamically and intended to be short-lived. All extensions for monitoring or management respect this parameter.

      • loaderExecutor

        public final Cache2kBuilder<K,​V> loaderExecutor​(Executor v)
        Thread pool / executor service to use for triggered load operations. If no executor is specified the cache will create a thread pool, if needed.

        The loader thread pool is used by the cache for executing load requests concurrent to the application, when a Cache.loadAll(Iterable) is issued. If no bulk loader is specified the thread pool will be used to carry out load requests in parallel. If an AsyncCacheLoader is used, the cache itself does not use the loader executor.

        The executor should reject when not enough threads are available. In that case the cache will use the calling thread for the load operation.

        See Also:
        loaderThreadCount(int)

      • refreshExecutor

        public final Cache2kBuilder<K,​V> refreshExecutor​(Executor v)
        Thread pool / executor service to use for refresh ahead operations. If not specified the same refresh ahead operation will use the thread pool defined by loaderExecutor(Executor) or a cache local pool is created.

        The executor for refresh operations may reject execution when not enough resources are available. If a refresh is rejected, the cache entry expires normally.

        See Also:
        loaderThreadCount(int), loaderExecutor(Executor)

      • scheduler

        public final Cache2kBuilder<K,​V> scheduler​(Scheduler v)
        Use a different scheduler to run timer tasks for.

      • weigher

        public final Cache2kBuilder<K,​V> weigher​(Weigher<K,​V> v)
        Set the weigher to be used to calculate the entry weight. The parameter maximumWeight(long) needs to be specified as well. Using a weigher has a slight performance impact on the update of existing entries. When a weigher is set the entryCapacity(long) parameter is ignored.

      • maximumWeight

        public final Cache2kBuilder<K,​V> maximumWeight​(long v)
        Specifies the maximum weight of entries the cache may contain. To obtain the entry weight a Weigher must be specified via weigher(org.cache2k.operation.Weigher<K, V>).

        The weight of an entry does not influence which entry is evicted next, but is only used to constrain the capacity of the cache. The cache implementation tries the best to keep the cache within its maximum weight limit, but eviction may kick in before or after reaching the limit.

        The maximum weight setting cannot be used together with entryCapacity(long).

      • setup

        public final Cache2kBuilder<K,​V> setup​(Consumer<Cache2kBuilder<K,​V>> consumer)
        Call the consumer with this builder. This can be used to apply configuration fragments within the fluent configuration scheme.

      • with

        public final <B extends SectionBuilder<B,​CFG>,​CFG extends ConfigSection<CFG,​B>> Cache2kBuilder<K,​V> with​(Class<CFG> configSectionClass,
                                                                                                                                 Consumer<B> builderAction)
        Configure a config section. If the section is not existing it a new section is created. If the section is existing the existing instance is modified.
        Type Parameters:
        B - type of the builder for the config section
        CFG - the type of the config section
        Parameters:
        configSectionClass - type of the config section that is created or altered
        builderAction - lambda that alters the config section via its builder

      • setupWith

        public <B extends SectionBuilder<B,​CFG>,​CFG extends ConfigSection<CFG,​B>,​SUP extends WithSection<CFG,​B> & CustomizationSupplier<?>> Cache2kBuilder<K,​V> setupWith​(Function<Cache2kBuilder<K,​V>,​SUP> setupAction,
                                                                                                                                                                                                      Consumer<B> builderAction)
        Execute setup code for a feature or customization and configure its associated configuration section via its builder.
        Type Parameters:
        B - the builder for the customizations' configuration section
        CFG - the configuration section
        SUP - the supplier for the customization
        Parameters:
        setupAction - function modifying the configuration
        builderAction - function for configuring the customization

      • setup

        public <B extends ConfigBuilder<B,​CFG>,​CFG extends ConfigBean<CFG,​B>> Cache2kBuilder<K,​V> setup​(Function<Cache2kBuilder<K,​V>,​CFG> enabler,
                                                                                                                        Consumer<B> builderAction)
        Executes setup code for a feature or customization which has additional parameters and configures it via its builder.
        Parameters:
        enabler - setup function returning am associated configuration
        builderAction - function to configure

      • enable

        public <B extends ConfigBuilder<B,​T>,​T extends ToggleFeature & ConfigBean<T,​B>> Cache2kBuilder<K,​V> enable​(Class<T> featureType,
                                                                                                                                   Consumer<B> builderAction)
        Enables a toggle feature which has additional parameters and configures it via its builder.
        Parameters:
        featureType - Type of feature which has additional bean properties
        builderAction - function to configure the feature

      • config

        public final Cache2kConfig<K,​V> config()
        Returns the configuration object this builder operates on. Changes to the configuration also will influence the created cache when build() is called. The method does not return the effective configuration if additional external/XML configuration is present, since this is applied when build is called. On the other hand, the method can be used to inspect the effective configuration after build completed.
        Specified by:
        config in interface ConfigBuilder<K,​V>
        Returns:
        configuration objects with the parameters set in the builder.

      • getManager

        public final CacheManager getManager()
        Get the associated cache manager.

      • build

        public final Cache<K,​V> build()
        Builds a cache with the specified configuration parameters.

        If XML configuration is present, the section for the cache name is looked up and the configuration in it applied, before the cache is build.

        Throws:
        IllegalArgumentException - if a cache of the same name is already active in the cache manager
        IllegalArgumentException - if a configuration entry for the named cache is required but not present