19.2. Cache Store Configuration Details (Library Mode)

The passivation parameter affects the way in which Red Hat JBoss Data Grid interacts with stores. When an object is evicted from in-memory cache, passivation writes it to a secondary data store, such as a system or a database. Valid values for this parameter are true and false but passivation is set to false by default.

The shared parameter indicates that the cache store is shared by different cache instances. For example, where all instances in a cluster use the same JDBC settings to talk to the same remote, shared database. shared is false by default. When set to true, it prevents duplicate data being written to the cache store by different cache instances. For the LevelDB cache stores, this parameter must be excluded from the configuration, or set to false because sharing this cache store is not supported.

The preload parameter is set to false by default. When set to true the data stored in the cache store is preloaded into the memory when the cache starts. This allows data in the cache store to be available immediately after startup and avoids cache operations delays as a result of loading data lazily. Preloaded data is only stored locally on the node, and there is no replication or distribution of the preloaded data. Red Hat JBoss Data Grid will only preload up to the maximum configured number of entries in eviction.

The fetch-state parameter determines whether or not to fetch the persistent state of a cache and apply it to the local cache store when joining the cluster. If the cache store is shared the fetch persistent state is ignored, as caches access the same cache store. A configuration exception will be thrown when starting the cache service if more than one cache store has this property set to true. The fetch-state property is false by default.

In order to speed up lookups, the single file cache store keeps an index of keys and their corresponding position in the file. To avoid this index resulting in memory consumption problems, this cache store can be bounded by a maximum number of entries that it stores, defined by the max-entries parameter. If this limit is exceeded, entries are removed permanently using the LRU algorithm both from the in-memory index and the underlying file based cache store. The default value is -1, allowing unlimited entries.

The singleton parameter enables a singleton store cache store. SingletonStore is a delegating cache store used when only one instance in a cluster can interact with the underlying store; however, singleton parameter is not recommended for file-store. The default value is false.

The purge parameter controls whether cache store is purged when it starts up.

The location configuration element sets a location on disk where the store can write.

The thread-pool-size parameter specifies the number of threads that concurrently apply modifications to the store. The default value for this parameter is 1.

The flush-lock-timeout parameter specifies the time to acquire the lock which guards the state to be flushed to the cache store periodically. The default value for this parameter is 1.

The modification-queue-size parameter specifies the size of the modification queue for the asynchronous store. If updates are made at a rate that is faster than the underlying cache store can process this queue, then the asynchronous store behaves like a synchronous store for that period, blocking until the queue can accept more elements. The default value for this parameter is 1024 elements.

The shutdown-timeout parameter specifies maximum amount of time that can be taken to stop the cache store. Default value for this parameter is 25000 milliseconds.

The cache attribute specifies the name of the remote cache to which it intends to connect in the remote Infinispan cluster. The default cache will be used if the remote cache name is unspecified.

The fetch-state attribute, when set to true, ensures that the persistent state is fetched when the remote cache joins the cluster. If multiple cache stores are chained, only one cache store can have this property set to true . The default for this value is false.

The shared attribute is set to true when multiple cache instances share a cache store, which prevents multiple cache instances writing the same modification individually. The default for this attribute is false.

The preload attribute ensures that the cache store data is pre-loaded into memory and is immediately accessible after starting up. The disadvantage of setting this to true is that the start up time increases. The default value for this attribute is false.

The singleton parameter enables the SingletonStore delegating cache store, used in situations when only one instance in a cluster should interact with the underlying store. The default value is false.

The purge attribute ensures that the cache store is purged during the start up process. The default value for this attribute is false.

The tcp-no-delay attribute triggers the TCP NODELAY stack. The default value for this attribute is true.

The ping-on-start attribute sends a ping request to a back end server to fetch the cluster topology. The default value for this attribute is true.

The key-size-estimate attribute provides an estimation of the key size. The default value for this attribute is 64.

The value-size-estimate attribute specifies the size of the byte buffers when serializing and deserializing values. The default value for this attribute is 512.

The force-return-values attribute sets whether FORCE_RETURN_VALUE is enabled for all calls. The default value for this attribute is false.

The host attribute configures the host address.

The port attribute configures the port used by the Remote Cache Store. This defaults to 11222.

The max-active parameter indicates the maximum number of active connections for each server at a time. The default value for this attribute is -1 which indicates an infinite number of active connections.

The max-idle parameter indicates the maximum number of idle connections for each server at a time. The default value for this attribute is -1 which indicates an infinite number of idle connections.

The max-total parameter indicates the maximum number of persistent connections within the combined set of servers. The default setting for this attribute is -1 which indicates an infinite number of connections.

The min-idle-time parameter sets a target value for the minimum number of idle connections (per server) that should always be available. If this parameter is set to a positive number and timeBetweenEvictionRunsMillis > 0, each time the idle connection eviction thread runs, it will try to create enough idle instances so that there will be minIdle idle instances available for each server. The default setting for this parameter is 1.

The eviction-interval parameter indicates how long the eviction thread should sleep before "runs" of examining idle connections. When non-positive, no eviction thread will be launched. The default setting for this parameter is 120000 milliseconds, or 2 minutes.

The min-evictable-idle-time parameter specifies the minimum amount of time that an connection may sit idle in the pool before it is eligible for eviction due to idle time. When non-positive, no connection will be dropped from the pool due to idle time alone. This setting has no effect unless timeBetweenEvictionRunsMillis > 0. The default setting for this parameter is 1800000, or (30 minutes).

The test-idle parameter indicates whether or not idle connections should be validated by sending an TCP packet to the server, during idle connection eviction runs. Connections that fail to validate will be dropped from the pool. This setting has no effect unless timeBetweenEvictionRunsMillis > 0. The default setting for this parameter is true.

The relative-to parameter specifies the base directory in which to store the cache state.

The path parameter specifies the location within the relative-to parameter to store the cache state.

The shared parameter specifies whether the cache store is shared. The only supported value for this parameter in the LevelDB cache store is false.

The preload parameter specifies whether the cache store will be pre-loaded. Valid values are true and false.

The block-size parameter defines the block size of the cache store.

The singleton parameter enables the SingletonStore delegating cache store, used in situations when only one instance in a cluster should interact with the underlying store. The default value is false.

The cache-size parameter defines the cache size of the cache store.

The clear-threshold parameter defines the cache clear threshold of the cache store.

The persistence-unit attribute specifies the name of the JPA cache store.

The entity-class attribute specifies the fully qualified class name of the JPA entity used to store the cache entry value.

The batch-size (optional) attribute specifies the batch size for cache store streaming. The default value for this attribute is 100.

The store-metadata (optional) attribute specifies whether the cache store keeps the metadata (for example expiration and versioning information) with the entries. The default value for this attribute is true.

The singleton parameter enables the SingletonStore delegating cache store, used in situations when only one instance in a cluster should interact with the underlying store. The default value is false.

The fetch-state parameter determines whether the persistent state is fetched when joining a cluster. Set this to true if using a replication and invalidation in a clustered environment. Additionally, if multiple cache stores are chained, only one cache store can have this property enabled. If a shared cache store is used, the cache does not allow a persistent state transfer despite this property being set to true. The fetch-state parameter is false by default.

The singleton parameter enables the SingletonStore delegating cache store, used in situations when only one instance in a cluster should interact with the underlying store. The default value is false.

The purge parameter specifies whether the cache store is purged when initially started.

The key-to-string-mapper parameter specifies the class name used to map keys to strings for the database tables.

The connection-url parameter specifies the JDBC driver-specific connection URL.

The username parameter contains the username used to connect via the connection-url.

The password parameter contains the password to use when connecting via the connection-url

The driver parameter specifies the class name of the driver used to connect to the database.

The prefix attribute defines the string prepended to name of the target cache when composing the name of the cache bucket table.

The drop-on-exit parameter specifies whether the database tables are dropped upon shutdown.

The create-on-start parameter specifies whether the database tables are created by the store on startup.

The fetch-size parameter specifies the size to use when querying from this table. Use this parameter to avoid heap memory exhaustion when the query is large.

The batch-size parameter specifies the batch size used when modifying this table.

The name parameter specifies the name of the column used.

The type parameter specifies the type of the column used.

The class parameter specifies the class name of the cache store implementation.

The preload parameter specifies whether to load entries into the cache during start up. Valid values for this parameter are true and false.

The shared parameter specifies whether the cache store is shared. This is used when multiple cache instances share a cache store. Valid values for this parameter are true and false.

The name attribute specifies the name of the property.