19.2. Cache Store Configuration Details (Library Mode)
The following lists contain details about the configuration elements and parameters for cache store elements in JBoss Data Grid's Library mode. The following list is meant to highlight certain parameters on each element, and a full list may be found in the schemas.
The persistence Element
- 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 aretrue
andfalse
butpassivation
is set tofalse
by default.
The file-store Element
- 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
isfalse
by default. When set totrue
, 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 tofalse
because sharing this cache store is not supported. - The
preload
parameter is set tofalse
by default. When set totrue
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 totrue
. Thefetch-state
property isfalse
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 forfile-store
. The default value isfalse
. - 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 write-behind Element
The write-behind
element contains parameters that configure various aspects of the cache store.
- The
thread-pool-size
parameter specifies the number of threads that concurrently apply modifications to the store. The default value for this parameter is1
. - 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 is1
. - 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 is1024
elements. - The
shutdown-timeout
parameter specifies maximum amount of time that can be taken to stop the cache store. Default value for this parameter is25000
milliseconds.
The remote-store Element
- 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 totrue
, 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 totrue
. The default for this value isfalse
. - The
shared
attribute is set totrue
when multiple cache instances share a cache store, which prevents multiple cache instances writing the same modification individually. The default for this attribute isfalse
. - 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 totrue
is that the start up time increases. The default value for this attribute isfalse
. - 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 isfalse
. - The
purge
attribute ensures that the cache store is purged during the start up process. The default value for this attribute isfalse
. - The
tcp-no-delay
attribute triggers theTCP
NODELAY
stack. The default value for this attribute istrue
. - 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 istrue
. - The
key-size-estimate
attribute provides an estimation of the key size. The default value for this attribute is64
. - The
value-size-estimate
attribute specifies the size of the byte buffers when serializing and deserializing values. The default value for this attribute is512
. - The
force-return-values
attribute sets whetherFORCE_RETURN_VALUE
is enabled for all calls. The default value for this attribute isfalse
.
The remote-server Element
Create a remote-server
element within the remote-store
element to define the server information.
- The
host
attribute configures the host address. - The
port
attribute configures the port used by the Remote Cache Store. This defaults to11222
.
The connection-pool Element (Remote Store)
- 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 andtimeBetweenEvictionRunsMillis
> 0, each time the idle connection eviction thread runs, it will try to create enough idle instances so that there will beminIdle
idle instances available for each server. The default setting for this parameter is1
. - 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 is120000
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 unlesstimeBetweenEvictionRunsMillis
> 0. The default setting for this parameter is1800000
, 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 unlesstimeBetweenEvictionRunsMillis
> 0. The default setting for this parameter istrue
.
The leveldb-store Element
- The
relative-to
parameter specifies the base directory in which to store the cache state. - The
path
parameter specifies the location within therelative-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 isfalse
. - The
preload
parameter specifies whether the cache store will be pre-loaded. Valid values aretrue
andfalse
. - 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 isfalse
. - 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 jpa-store Element
- 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 is100
. - 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 istrue
. - 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 isfalse
.
The binary-keyed-jdbc-store, string-keyed-jdbc-store, and mixed-keyed-jdbc-store Elements
- The
fetch-state
parameter determines whether the persistent state is fetched when joining a cluster. Set this totrue
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 totrue
. Thefetch-state
parameter isfalse
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 isfalse
. - 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-pool Element (JDBC Store)
- The
connection-url
parameter specifies the JDBC driver-specific connection URL. - The
username
parameter contains the username used to connect via theconnection-url
. - The
password
parameter contains the password to use when connecting via theconnection-url
- The
driver
parameter specifies the class name of the driver used to connect to the database.
The binary-keyed-table and string-keyed-table Elements
- 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 id-column, data-column, and timestamp-column Elements
- The
name
parameter specifies the name of the column used. - The
type
parameter specifies the type of the column used.
The custom-store Element
- 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 aretrue
andfalse
. - 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 aretrue
andfalse
.
The property Element
A property may be defined inside of a cache store, with the entry between the property tags being the stored value. For instance, in the below example a value of 1
is defined for minOccurs
.
<property name="minOccurs">1</property>
- The
name
attribute specifies the name of the property.