Cache2kBuilder (cache2k API 1.0.0.CR1 API)

java.lang.Object
- org.cache2k.Cache2kBuilder<K,V>

public class Cache2kBuilder<K,V>
extends Object

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().

Since:: 1.0
Author:: Jens Wilke

Constructor Summary

Constructors
Modifier Constructor and Description

protected Cache2kBuilder()
Constructor to override for the usage pattern:

Constructors
Modifier	Constructor and Description
`protected`	`Cache2kBuilder()` Constructor to override for the usage pattern:

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Cache2kBuilder<K,V>`	`addAsyncListener(CacheEntryOperationListener<K,V> listener)` A set of listeners.
`Cache2kBuilder<K,V>`	`addListener(CacheEntryOperationListener<K,V> listener)` Add a listener.
`Cache<K,V>`	`build()` Builds a cache with the specified configuration parameters.
`Cache2kBuilder<K,V>`	`disableStatistics(boolean flag)` By default statistic gathering is enabled.
`Cache2kBuilder<K,V>`	`entryCapacity(long v)` The maximum number of entries hold by the cache.
`Cache2kBuilder<K,V>`	`eternal(boolean v)` When set to true, cached values do not expire by time.
`Cache2kBuilder<K,V>`	`evictionSegmentCount(int v)` Number of eviction segments.
`Cache2kBuilder<K,V>`	`exceptionPropagator(ExceptionPropagator<K> ep)`
`Cache2kBuilder<K,V>`	`expireAfterWrite(long v, TimeUnit u)` Time duration after insert or updated an cache entry expires.
`Cache2kBuilder<K,V>`	`expiryPolicy(ExpiryPolicy<K,V> c)` Set expiry policy to use.
`static Cache2kBuilder`	`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`.
`Cache2kBuilder<K,V>`	`keepDataAfterExpired(boolean v)` Expired data is kept in the cache until the entry is evicted.
`<K2> Cache2kBuilder<K2,V>`	`keyType(CacheType<K2> t)` The used type of the cache key.
`<K2> Cache2kBuilder<K2,V>`	`keyType(Class<K2> t)` The used type of the cache key.
`Cache2kBuilder<K,V>`	`loader(AdvancedCacheLoader<K,V> l)`
`Cache2kBuilder<K,V>`	`loader(CacheLoader<K,V> l)`
`Cache2kBuilder<K,V>`	`loaderExecutor(Executor v)` Thread pool / executor service to use for asynchronous load operations.
`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.
`Cache2kBuilder<K,V>`	`manager(CacheManager manager)` The manager, the created cache will belong to.
`Cache2kBuilder<K,V>`	`maxRetryInterval(long v, TimeUnit u)` If a loader exception happens, this is the maximum time interval after a retry attempt is made.
`Cache2kBuilder<K,V>`	`name(Class<?> _class)` Sets a cache name from the fully qualified class name.
`Cache2kBuilder<K,V>`	`name(Class<?> _class, String _fieldName)` Constructs a cache name out of the class name and field name.
`Cache2kBuilder<K,V>`	`name(String v)` Sets the name of a cache.
`Cache2kBuilder<K,V>`	`name(String _uniqueName, Class<?> _class, String _fieldName)` Constructs a cache name out of the class name, a field name and a unique name identifying the component in the application.
`static <K,T> Cache2kBuilder<K,T>`	`of(Cache2kConfiguration<K,T> c)` Create a builder from the configuration.
`static <K,T> Cache2kBuilder<K,T>`	`of(Class<K> _keyType, Class<T> _valueType)` Create a new cache builder for key and value types are classes with no generic parameters.
`Cache2kBuilder<K,V>`	`permitNullValues(boolean flag)` When `true`, `null` values are allowed in the cache.
`Cache2kBuilder<K,V>`	`prefetchExecutor(Executor v)` Thread pool / executor service to use for refresh ahead and prefetch operations.
`Cache2kBuilder<K,V>`	`refreshAhead(boolean f)` When true, enable background refresh / refresh ahead.
`Cache2kBuilder<K,V>`	`resilienceDuration(long v, TimeUnit u)` Time span the cache will suppress loader exceptions if a value is available from a previous load.
`Cache2kBuilder<K,V>`	`resiliencePolicy(ResiliencePolicy<K,V> v)` Sets a custom resilience policy to control the cache behavior in the presence of exceptions from the loader.
`Cache2kBuilder<K,V>`	`retryInterval(long v, TimeUnit u)` If a loader exception happens, this is the time interval after a retry attempt is made.
`Cache2kBuilder<K,V>`	`sharpExpiry(boolean f)` By default the expiry time is not exact, which means, a value might be visible a few milliseconds after the time of expiry.
`Cache2kBuilder<K,V>`	`storeByReference(boolean v)` Ensure that the cache value is stored via direct object reference and that no serialization takes place.
`Cache2kBuilder<K,V>`	`strictEviction(boolean flag)` To increase performance cache2k optimizes the eviction and does eviction in greater chunks.
`Cache2kBuilder<K,V>`	`suppressExceptions(boolean v)` If an exceptions gets thrown by the cache loader, suppress it if there is a previous value.
`Cache2kConfiguration<K,V>`	`toConfiguration()` Returns the configuration object this builder operates on.
`<T2> Cache2kBuilder<K,T2>`	`valueType(CacheType<T2> t)` Sets the value type to use.
`<T2> Cache2kBuilder<K,T2>`	`valueType(Class<T2> t)` Sets the value type to use.
`Cache2kBuilder<K,V>`	`with(ConfigurationSectionBuilder<? extends ConfigurationSection>... sectionBuilders)` Add a new configuration sub section.
`Cache2kBuilder<K,V>`	`writer(CacheWriter<K,V> w)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- 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 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,T> Cache2kBuilder<K,T> of(Class<K> _keyType,
                                           Class<T> _valueType)
```
    Create a new cache builder for key and value types are classes with no generic parameters.
    
    See Also:
    
    keyType(Class), valueType(Class)
  - of
```
public static <K,T> Cache2kBuilder<K,T> of(Cache2kConfiguration<K,T> c)
```
    Create a builder from the configuration.
  - 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.
  - keyType
```
public final <K2> Cache2kBuilder<K2,V> keyType(Class<K2> t)
```
    The used type of the cache key. A suitable cache key must provide a useful equals and hashCode method. Arrays are not valid for cache keys.
    
    Throws:
    
    IllegalArgumentException - in case the type is illegal
    
    See Also:
    
    for a general discussion on types
  - valueType
```
public final <T2> Cache2kBuilder<K,T2> valueType(Class<T2> t)
```
    Sets the value type to use. Arrays are not supported.
    
    Throws:
    
    IllegalArgumentException - in case the type is illegal
    
    See Also:
    
    for a general discussion on types
  - keyType
```
public final <K2> Cache2kBuilder<K2,V> keyType(CacheType<K2> t)
```
    The used type of the cache key. A suitable cache key must provide a useful equals and hashCode method. Arrays are not valid for cache keys.
    
    Throws:
    
    IllegalArgumentException - in case the type is illegal
    
    See Also:
    
    for a general discussion on types
  - valueType
```
public final <T2> Cache2kBuilder<K,T2> valueType(CacheType<T2> t)
```
    Sets the value type to use. Arrays are not supported.
    
    Throws:
    
    IllegalArgumentException - in case the type is illegal
    
    See Also:
    
    for a general discussion on types
  - name
```
public final Cache2kBuilder<K,V> name(String _uniqueName,
                                      Class<?> _class,
                                      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<?> _class,
                                      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(Class<?> _class)
```
    Sets a cache name from the fully qualified class name.
    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 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.
    In case of a name collision the cache is generating a unique name by adding a counter value. This behavior may change.
    Allowed characters for a cache name, are URL non-reserved characters, these are: [A-Z], [a-z], [0-9] and [~-_.], see RFC3986 as well as the characters: [()]. The characters [@, ] are supported as well, but should be avoided.
    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 cache might not enforce the allowed character set for efficiency reasons.
    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 a 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: 2000. The default value is conservative, so the application will usually run stable without tuning or setting a reasonable size.
  - eternal
```
public final Cache2kBuilder<K,V> eternal(boolean v)
```
    When set to true, cached values do not expire by time. Entries will need to be removed from the cache explicitly or will be evicted if capacity constraints are reached.
    Setting eternal to false signals that the data should 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.
    The default behavior of the cache is identical to the setting eternal, meaning no expiry.
    Exceptions: If set to eternal with default setting and if there is no explicit expiry configured for exceptions with retryInterval(long, TimeUnit), exceptions will not be cached and expire immediately.
    
    Throws:
    
    IllegalArgumentException - in case a previous setting is reset
  - suppressExceptions
```
public final Cache2kBuilder<K,V> suppressExceptions(boolean v)
```
    If an exceptions gets thrown by the cache loader, suppress it if there is a previous value. When this is active, and an exception was suppressed the expiry is determined by retryInterval(long, TimeUnit).
    Setting this to false, will disable suppression or caching (aka resilience). Default value: true
    Additional information can be found under resilience in the documentation.
  - expireAfterWrite
```
public final Cache2kBuilder<K,V> expireAfterWrite(long v,
                                                  TimeUnit u)
```
    Time duration after insert or updated an cache entry expires. To switch off time based expiry use eternal(boolean).
    If an ExpiryPolicy is specified, the maximum expiry duration will not exceed the value that is specified here.
    A value of 0 means every entry should expire immediately. Low values or 0 together with read through operation mode with a CacheLoader should be avoided in production environments.
    
    Throws:
    
    IllegalArgumentException - if eternal(boolean) was set to true
  - exceptionPropagator
```
public final Cache2kBuilder<K,V> exceptionPropagator(ExceptionPropagator<K> ep)
```
  - loader
```
public final Cache2kBuilder<K,V> loader(CacheLoader<K,V> l)
```
  - loader
```
public final Cache2kBuilder<K,V> loader(AdvancedCacheLoader<K,V> l)
```
  - writer
```
public final Cache2kBuilder<K,V> writer(CacheWriter<K,V> w)
```
  - 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 be always executed asynchronously.
    
    Parameters:
    
    listener - The listener to add
    
    Throws:
    
    IllegalArgumentException - if an identical listener is already added.
  - addAsyncListener
```
public final Cache2kBuilder<K,V> addAsyncListener(CacheEntryOperationListener<K,V> listener)
```
    A set of listeners. Listeners added in this collection will be executed in a synchronous mode, meaning, further processing for an entry will stall until a registered listener is executed.
    
    Parameters:
    
    listener - The listener to add
    
    Throws:
    
    IllegalArgumentException - if an identical listener is already added.
  - expiryPolicy
```
public final Cache2kBuilder<K,V> expiryPolicy(ExpiryPolicy<K,V> c)
```
    Set expiry policy to use.
    If this is specified the maximum expiry time is still limited to the value in expireAfterWrite(long, java.util.concurrent.TimeUnit). If expireAfterWrite(long, java.util.concurrent.TimeUnit) is set to 0 then expiry calculation is not used, all entries expire immediately.
    If no maximum expiry is specified via expireAfterWrite(long, java.util.concurrent.TimeUnit) at leas the resilienceDuration(long, java.util.concurrent.TimeUnit) needs to be specified, if resilience should be enabled.
  - 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 trail 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 trail period is determined by the configured expiry time or the the ExpiryPolicy. In case an entry is not accessed any more it needs to reach the expiry time twice before removed from the cache.
    The number of threads used to do the refresh are configured via loaderThreadCount(int)
    
    See Also:
    
    CacheLoader, loaderThreadCount(int)
  - sharpExpiry
```
public final Cache2kBuilder<K,V> sharpExpiry(boolean f)
```
    By default the expiry time is not exact, which means, a value might be visible a few milliseconds after the time of expiry. The time lag depends on the system load. Switching to true, means that values will not be visible when the time is reached that ExpiryPolicy returned.
  - 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 a separate executor is defined the parameter has no effect.
    
    See Also:
    
    loaderExecutor(Executor), prefetchExecutor(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.
  - retryInterval
```
public final Cache2kBuilder<K,V> retryInterval(long v,
                                               TimeUnit u)
```
    If a loader exception happens, this is the time interval after a retry attempt is made. If not specified, 10% of maxRetryInterval(long, java.util.concurrent.TimeUnit).
  - maxRetryInterval
```
public final Cache2kBuilder<K,V> maxRetryInterval(long v,
                                                  TimeUnit u)
```
    If a loader exception happens, this is the maximum time interval after a retry attempt is made. For retries an exponential backoff algorithm is used. It starts with the retry time and then increases the time to the maximum according to an exponential pattern.
    By default identical to resilienceDuration(long, java.util.concurrent.TimeUnit)
  - resilienceDuration
```
public final Cache2kBuilder<K,V> resilienceDuration(long v,
                                                    TimeUnit u)
```
    Time span the cache will suppress loader exceptions if a value is available from a previous load. After the time span is passed the cache will start propagating loader exceptions. If suppressExceptions(boolean) is switched off, this setting has no effect.
    Defaults to expireAfterWrite(long, java.util.concurrent.TimeUnit). If suppressExceptions(boolean) is switched off, this setting has no effect.
  - resiliencePolicy
```
public final Cache2kBuilder<K,V> resiliencePolicy(ResiliencePolicy<K,V> v)
```
    Sets a custom resilience policy to control the cache behavior in the presence of exceptions from the loader. A specified policy will be ignored if expireAfterWrite(long, java.util.concurrent.TimeUnit) is set to 0.
  - with
```
public final Cache2kBuilder<K,V> with(ConfigurationSectionBuilder<? extends ConfigurationSection>... sectionBuilders)
```
    Add a new configuration sub section.
    
    See Also:
    
    ConfigurationWithSections
  - 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.
  - permitNullValues
```
public final Cache2kBuilder<K,V> permitNullValues(boolean flag)
```
    When true, null values are allowed in the cache. In the default configuration null values are prohibited.
    See the chapter in the user guide for details on null values.
    
    See Also:
    
    CacheLoader.load(Object), ExpiryPolicy.calculateExpiryTime(Object, Object, long, CacheEntry)
  - disableStatistics
```
public final Cache2kBuilder<K,V> disableStatistics(boolean flag)
```
    By default statistic gathering is enabled. Set true to disable statistics. Disabling statistics will minimize overhead and switch off any counters that are present for informational purposes only. Counters that don't have a significant overhead or are maintained in any case are still available. The setting doesn't affect whether JMX values are exposed or not.
  - evictionSegmentCount
```
public final Cache2kBuilder<K,V> evictionSegmentCount(int v)
```
    Number of eviction segments. The default is one or two if the available processor count is more than one. In case the workload has lots of concurrent inserts or eviction the segment count may be increased if the cache eviction becomes the bottle neck. A value higher then the processor count is ineffective. Setting a higher value has a negative impact on the eviction efficiency. There will be hardly any application with a little positive effect when this parameter is set. Usual applications that do mostly concurrent reads, do not need an increase.
  - loaderExecutor
```
public final Cache2kBuilder<K,V> loaderExecutor(Executor v)
```
    Thread pool / executor service to use for asynchronous load operations. If no executor is specified the cache will create a thread pool, if needed.
    
    See Also:
    
    loaderThreadCount(int), prefetchExecutor(Executor)
  - prefetchExecutor
```
public final Cache2kBuilder<K,V> prefetchExecutor(Executor v)
```
    Thread pool / executor service to use for refresh ahead and prefetch 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.
    
    See Also:
    
    loaderThreadCount(int), loaderExecutor(Executor)
  - toConfiguration
```
public final Cache2kConfiguration<K,V> toConfiguration()
```
    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.
    
    Returns:
    
    configuration objects with the parameters set in the builder.
  - build
```
public final Cache<K,V> build()
```
    Builds a cache with the specified configuration parameters. The builder reused to build caches with similar or identical configuration. The builder is not thread safe.
    
    Throws:
    
    IllegalArgumentException - if a cache of the same name is already active in the cache manager

Class Cache2kBuilder<K,V>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Cache2kBuilder

Method Detail

forUnknownTypes

of

of

manager

keyType

valueType

keyType

valueType

name

name

name

name

keepDataAfterExpired

entryCapacity

eternal

suppressExceptions

expireAfterWrite

exceptionPropagator

loader

loader

writer

addListener

addAsyncListener

expiryPolicy

refreshAhead

sharpExpiry

loaderThreadCount

storeByReference

retryInterval

maxRetryInterval

resilienceDuration

resiliencePolicy

with

strictEviction

permitNullValues

disableStatistics

evictionSegmentCount

loaderExecutor

prefetchExecutor

toConfiguration

build