Chapter 21. Cache Store Implementations

21.1. Cache Stores

The cache store connects Red Hat JBoss Data Grid to the persistent data store. Cache stores are associated with individual caches. Different caches attached to the same cache manager can have different cache store configurations.

Note

If a clustered cache is configured with an unshared cache store (where shared is set to false), on node join, stale entries which might have been removed from the cluster might still be present in the stores and can reappear.

21.2. Cache Store Comparison

Select a cache store based on your requirements. The following is a summary of high level differences between the cache stores available in Red Hat JBoss Data Grid:

  • The Single File Cache Store is a local file cache store. It persists data locally for each node of the clustered cache. The Single File Cache Store provides superior read and write performance, but keeps keys in memory which limits its use when persisting large data sets at each node. See Single File Cache Store for details.
  • The LevelDB file cache store is a local file cache store which provides high read and write performance. It does not have the limitation of Single File Cache Store of keeping keys in memory. See LevelDB Cache Store for details.
  • The JDBC cache store is a cache store that may be shared, if required. When using it, all nodes of a clustered cache persist to a single database or a local JDBC database for every node in the cluster. The shared cache store lacks the scalability and performance of a local cache store such as the LevelDB cache store, but it provides a single location for persisted data. The JDBC cache store persists entries as binary blobs, which are not readable outside JBoss Data Grid. See JDBC Based Cache Stores for details.
  • The JPA Cache Store (supported in Library mode only) is a shared cache store like JDBC cache store, but preserves schema information when persisting to the database. Therefore, the persisted entries can be read outside JBoss Data Grid. See JPA Cache Store for details.

21.3. 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 are true and false but passivation is set to false 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 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 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 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 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 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 TCPNODELAY 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 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 to 11222.

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

21.4. Cache Store Configuration Details (Remote Client-Server Mode)

The following tables contain details about the configuration elements and parameters for cache store elements in JBoss Data Grid’s Remote Client-Server mode. The following list is meant to highlight certain parameters on each element, and a full list may be found in the schemas.

The local-cache Element

  • The name parameter of the local-cache attribute is used to specify a name for the cache.
  • The statistics parameter specifies whether statistics are enabled at the container level. Enable or disable statistics on a per-cache basis by setting the statistics attribute to false.

The file-store Element

  • The name parameter of the file-store element is used to specify a name for the file store.
  • The passivation parameter determines whether entries in the cache are passivated (true) or if the cache store retains a copy of the contents in memory (false).
  • The purge parameter specifies whether or not the cache store is purged when it is started. Valid values for this parameter are true and false.
  • The shared parameter is used when multiple cache instances share a cache store. This parameter can be set to prevent multiple cache instances writing the same modification multiple times. Valid values for this parameter are true and false. However, the shared parameter is not recommended for the LevelDB cache store because this cache store cannot be shared.
  • The relative-to property is the directory where the file-store stores the data. It is used to define a named path.
  • The path property is the name of the file where the data is stored. It is a relative path name that is appended to the value of the relative-to property to determine the complete path.
  • The max-entries parameter provides maximum number of entries allowed. The default value is -1 for unlimited entries.
  • The fetch-state parameter when set to true fetches the persistent state when joining a cluster. If multiple cache stores are chained, only one of them can have this property enabled. Persistent state transfer with a shared cache store does not make sense, as the same persistent store that provides the data will just end up receiving it. Therefore, if a shared cache store is used, the cache does not allow a persistent state transfer even if a cache store has this property set to true. It is recommended to set this property to true only in a clustered environment. The default value for this parameter is false.
  • The preload parameter when set to true, loads the data stored in the cache store into memory when the cache starts. However, setting this parameter to true affects the performance as the startup time is increased. The default value for this parameter is false.
  • 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 store Element

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

The property Element

  • The name parameter specifies the name of the property.
  • The value parameter specifies the value assigned to the property.

The remote-store Element

  • The cache parameter defines the name for the remote cache. If left undefined, the default cache is used instead.
  • The socket-timeout parameter sets whether the value defined in SO_TIMEOUT (in milliseconds) applies to remote Hot Rod servers on the specified timeout. A timeout value of 0 indicates an infinite timeout. The default value is 60,000 ms, or one minute.
  • The tcp-no-delay sets whether TCP_NODELAY applies on socket connections to remote Hot Rod servers.
  • The hotrod-wrapping sets whether a wrapper is required for Hot Rod on the remote 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 remote-server Element

  • The outbound-socket-binding parameter sets the outbound socket binding for the remote server.

The binary-keyed-jdbc-store, string-keyed-jdbc-store, and mixed-keyed-jdbc-store Elements

  • The datasource parameter defines the name of a JNDI for the datasource.
  • The passivation parameter determines whether entries in the cache are passivated (true) or if the cache store retains a copy of the contents in memory (false).
  • The preload parameter specifies whether to load entries into the cache during start up. Valid values for this parameter are true and false.
  • The purge parameter specifies whether or not the cache store is purged when it is started. Valid values for this parameter are true and false.
  • The shared parameter is used when multiple cache instances share a cache store. This parameter can be set to prevent multiple cache instances writing the same modification multiple times. Valid values for this parameter are true and false.
  • 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

The binary-keyed-table and string-keyed-table Elements

  • The prefix parameter specifies a prefix string for the database table name.

The id-column, data-column, and timestamp-column Elements

  • The name parameter specifies the name of the database column.
  • The type parameter specifies the type of the database column.

The leveldb-store Element

  • The relative-to parameter specifies the base directory to store the cache state. This value defaults to jboss.server.data.dir.
  • The path parameter defines where, within the directory specified in the relative-to parameter, the cache state is stored. If undefined, the path defaults to the cache container name.
  • The passivation parameter specifies whether passivation is enabled for the LevelDB cache store. Valid values are true and 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 parameter specifies whether the cache store is purged when it starts up. Valid values are true and false.

21.5. Single File Cache Store

21.5.1. Single File Cache Store

Red Hat JBoss Data Grid includes one file system based cache store: the SingleFileCacheStore.

The SingleFileCacheStore is a simple file system based implementation and a replacement to the older file system based cache store: the FileCacheStore.

SingleFileCacheStore stores all key/value pairs and their corresponding metadata information in a single file. To speed up data location, it also keeps all keys and the positions of their values and metadata in memory. Hence, using the single file cache store slightly increases the memory required, depending on the key size and the amount of keys stored. Hence SingleFileCacheStore is not recommended for use cases where the keys are too big.

To reduce memory consumption, the size of the cache store can be set to a fixed number of entries to store in the file; however, this works only when JBoss Data Grid is used as a cache. When JBoss Data Grid is used this way, data which is not present in the cache can be recomputed or re-retrieved from the authoritative data store and stored in the JBoss Data Grid cache. This limitation exists so that once the maximum number of entries is reached older data in the cache store is removed. If JBoss Data Grid were used as an authoritative data store in this scenario it would lead to potential data loss.

Due to its limitations, SingleFileCacheStore can be used in a limited capacity in production environments. It can not be used on shared file system (such as NFS and Windows shares) due to a lack of proper file locking, resulting in data corruption. Furthermore, file systems are not inherently transactional, resulting in file writing failures during the commit phase if the cache is used in a transactional context.

21.5.2. Single File Store Configuration (Remote Client-Server Mode)

The following is an example of a Single File Store configuration for Red Hat JBoss Data Grid’s Remote Client-Server mode: 

<local-cache name="default" statistics="true">
    <file-store name="myFileStore"
                passivation="true"
                purge="true"
                relative-to="{PATH}"
                path="{DIRECTORY}"
                max-entries="10000"
                fetch-state="true"
                preload="false" />
</local-cache>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Remote Client-Server Mode).

21.5.3. Single File Store Configuration (Library Mode)

In Red Hat JBoss Grid’s Library mode, configure a Single File Cache Store as follows:. 

<local-cache name="writeThroughToFile">
      <persistence passivation="false">
         <file-store fetch-state="true"
                      purge="false"
                      shared="false"
                      preload="false"
                      location="/tmp/Another-FileCacheStore-Location"
                      max-entries="100">
            <write-behind enabled="true"
    	           threadPoolSize="500"
    	           flush-lock-timeout="1"
	           modification-queue-size="1024"
	           shutdown-timeout="25000"/>
        </singleFile>
      </persistence>
 </local-cache>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Library Mode).

21.5.4. Upgrade JBoss Data Grid Cache Stores

Red Hat JBoss Data Grid 7 stores data in a different format than previous versions of JBoss Data Grid. As a result, the newer version of JBoss Data Grid cannot read data stored by older versions. Use rolling upgrades to upgrade persisted data from the format used by the old JBoss Data Grid to the new format. Additionally, the newer version of JBoss Data Grid also stores persistence configuration information in a different location.

Rolling upgrades is the process by which a JBoss Data Grid installation is upgraded without a service shutdown. For JBoss Data Grid servers, this procedure refers to the server side components. The upgrade can be due to either hardware or software change, such as upgrading JBoss Data Grid.

Rolling upgrades are only available in JBoss Data Grid’s Remote Client-Server mode.

21.6. LevelDB Cache Store

21.6.1. LevelDB Cache Store

LevelDB is a key-value storage engine that provides an ordered mapping from string keys to string values.

The LevelDB Cache Store uses two filesystem directories. Each directory is configured for a LevelDB database. One directory stores the non-expired data and the second directory stores the keys pending to be purged permanently.

21.6.2. Configuring LevelDB Cache Store (Remote Client-Server Mode)

Procedure: To configure LevelDB Cache Store:

  1. Add the following elements to a cache definition in standalone.xml to configure the database: 

    <leveldb-store path="/path/to/leveldb/data"
    	       passivation="false"
    	       purge="false" >
    <leveldb-expiration path="/path/to/leveldb/expires/data" />
    <implementation type="JNI" />
</leveldb-store>
    Note

    Directories will be automatically created if they do not exist.

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Remote Client-Server Mode).

21.6.3. LevelDB Cache Store Sample XML Configuration (Library Mode)

The following is a sample XML configuration of LevelDB Cache Store: 

<local-cache name="vehicleCache">
      <persistence passivation="false">
          <leveldb-store xmlns="urn:infinispan:config:store:leveldb:8.0
                        relative-to="/path/to/leveldb/data"
                        shared="false"
                        preload="true"/>
      </persistence>
   </local-cache>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Library Mode).

21.6.4. Configure a LevelDB Cache Store Using JBoss Operations Network

Use the following procedure to set up a new LevelDB cache store using the JBoss Operations Network.

  1. Ensure that Red Hat JBoss Operations Network 3.2 or higher is installed and started.
  2. Install the Red Hat JBoss Data Grid Plugin Pack for JBoss Operations Network 3.2.0.
  3. Ensure that JBoss Data Grid is installed and started.
  4. Import JBoss Data Grid server into the inventory.
  5. Configure the JBoss Data Grid connection settings.

  6. Create a new LevelDB cache store as follows:

    Figure 21.1. Create a new LevelDB Cache Store

    Use JBoss Operations Network to create a new cache store.
    1. Right-click the default cache.
    2. In the menu, mouse over the option.
    3. In the submenu, click menu:LevelDB Store[] .

  7. Name the new LevelDB cache store as follows:

    Figure 21.2. Name the new LevelDB Cache Store

    Name the new LevelDB Cache Store
    1. In the Resource Create Wizard that appears, add a name for the new LevelDB Cache Store.
    2. Click btn:[Next] to continue.

  8. Configure the LevelDB Cache Store settings as follows:

    Figure 21.3. Configure the LevelDB Cache Store Settings

    Configure the new LevelDB Cache Store
    1. Use the options in the configuration window to configure a new LevelDB cache store.
    2. Click menu:Finish[] to complete the configuration.

  9. Schedule a restart operation as follows:

    Figure 21.4. Schedule a Restart Operation

    Schedule a restart operation
    1. In the screen’s left panel, expand the JBoss AS7 Standalone Servers entry, if it is not currently expanded.
    2. Click JDG (0.0.0.0:9990) from the expanded menu items.
    3. In the screen’s right panel, details about the selected server display. Click the menu:Operations[] tab.
    4. In the Operation drop-down box, select the Restart operation.
    5. Select the radio button for the Now entry.
    6. Click menu:Schedule[] to restart the server immediately.

  10. Discover the new LevelDB cache store as follows:

    Figure 21.5. Discover the New LevelDB Cache Store

    Discover the new LevelDB cache store
    1. In the screen’s left panel, select each of the following items in the specified order to expand them: menu:JBoss AS7 Standalong Servers[JDG (0.0.0.0:9990) > infinispan > Cache Containers > local > Caches > default > LevelDB Stores]
    2. Click the name of your new LevelDB Cache Store to view its configuration information in the right panel.

21.7. JDBC Based Cache Stores

21.7.1. JDBC Based Cache Stores

Red Hat JBoss Data Grid offers several cache stores for use with common data storage formats. JDBC based cache stores are used with any cache store that exposes a JDBC driver. JBoss Data Grid offers the following JDBC based cache stores depending on the key to be persisted:

  • JdbcBinaryStore.
  • JdbcStringBasedStore.
  • JdbcMixedStore.
Important

Both Binary and Mixed JDBC stores are deprecated in JBoss Data Grid 7.1, and are not recommended for production use. It is recommended to utilize a String Based store instead.

21.7.2. JdbcBinaryStores

21.7.2.1. JdbcBinaryStores

The JdbcBinaryStore supports all key types. It stores all keys with the same hash value (hashCode method on the key) in the same table row/blob. The hash value common to the included keys is set as the primary key for the table row/blob. As a result of this hash value, JdbcBinaryStore offers excellent flexibility but at the cost of concurrency and throughput.

As an example, if three keys (k1, k2 and k3) have the same hash code, they are stored in the same table row. If three different threads attempt to concurrently update k1, k2 and k3, they must do it sequentially because all three keys share the same row and therefore cannot be simultaneously updated.

Important

Binary JDBC stores are deprecated in JBoss Data Grid 7.1, and are not recommended for production use. It is recommended to utilize a String Based store instead.

21.7.2.2. JdbcBinaryStore Configuration (Remote Client-Server Mode)

The following is a configuration for JdbcBinaryStore using Red Hat JBoss Data Grid’s Remote Client-Server mode with Passivation enabled: 

<local-cache name="customCache">
    <!-- Additional configuration elements here -->
    <binary-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS"
   			     passivation="${true/false}"
			     preload="${true/false}"
			     purge="${true/false}">
        <binary-keyed-table prefix="JDG">
            <id-column name="id"
	               type="${id.column.type}"/>
            <data-column name="datum"
	  	         type="${data.column.type}"/>
            <timestamp-column name="version"
	 		      type="${timestamp.column.type}"/>
        </binary-keyed-table>
    </binary-keyed-jdbc-store>
</local-cache>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Remote Client-Server Mode).

21.7.2.3. JdbcBinaryStore Configuration (Library Mode)

The following is a sample configuration for the JdbcBinaryStore : 

<infinispan
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:infinispan:config:8.4 http://www.infinispan.org/schemas/infinispan-config-8.4.xsd
            urn:infinispan:config:store:jdbc:8.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-8.0.xsd"
        xmlns="urn:infinispan:config:8.4">
    <!-- Additional configuration elements here -->
    <persistence>
    <binary-keyed-jdbc-store xmlns="urn:infinispan:config:store:jdbc:8.0
                             fetch-state="false"
			     purge="false">
        <connection-pool connection-url="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1"
			 username="sa"
			 driver="org.h2.Driver"/>
        <binary-keyed-table dropOnExit="true"
			    createOnStart="true"
			    prefix="ISPN_BUCKET_TABLE">
            <id-column name="ID_COLUMN"
		       type="VARCHAR(255)" />
            <data-column name="DATA_COLUMN"
			 type="BINARY" />
	    <timestamp-column name="TIMESTAMP_COLUMN"
			      type="BIGINT" />
        </binary-keyed-table>
    </binary-keyed-jdbc-store>
</persistence>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Library Mode).

21.7.3. JdbcStringBasedStores

21.7.3.1. JdbcStringBasedStores

The JdbcStringBasedStore stores each entry in its own row in the table, instead of grouping multiple entries into each row, resulting in increased throughput under a concurrent load. It also uses a (pluggable) bijection that maps each key to a String object. The key-to-string-mapper interface defines the bijection.

Red Hat JBoss Data Grid includes a default implementation called DefaultTwoWayKey2StringMapper that handles primitive types.

21.7.3.2. JdbcStringBasedStore Configuration (Remote Client-Server Mode)

The following is a sample JdbcStringBasedStore for Red Hat JBoss Data Grid’s Remote Client-Server mode: 

<local-cache name="customCache">
    <!-- Additional configuration elements here -->
    <string-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS"
			     passivation="true"
			     preload="false"
			     purge="false"
			     shared="false"
			     singleton="true">
        <string-keyed-table prefix="JDG">
            <id-column name="id"
	 	       type="${id.column.type}"/>
	    <data-column name="datum"
		         type="${data.column.type}"/>
	    <timestamp-column name="version"
			      type="${timestamp.column.type}"/>
	</string-keyed-table>
    </string-keyed-jdbc-store>
</local-cache>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Remote Client-Server Mode).

21.7.3.3. JdbcStringBasedStore Configuration (Library Mode)

The following is a sample configuration for the JdbcStringBasedStore : 

<infinispan
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:infinispan:config:8.4 http://www.infinispan.org/schemas/infinispan-config-8.4.xsd
            urn:infinispan:config:store:jdbc:8.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-8.0.xsd"
        xmlns="urn:infinispan:config:8.4">
    <!-- Additional configuration elements here -->
    <persistence>
        <string-keyed-jdbc-store xmlns="urn:infinispan:config:store:jdbc:8.0"
	                         fetch-state="false"
			         purge="false"
			         key2StringMapper="org.infinispan.loaders.keymappers.DefaultTwoWayKey2StringMapper">
            <dataSource jndiUrl="java:jboss/datasources/JdbcDS"/>
	    <string-keyed-table dropOnExit="true"
				createOnStart="true"
				prefix="ISPN_STRING_TABLE">
	        <id-column name="ID_COLUMN"
			   type="VARCHAR(255)" />
		<data-column name="DATA_COLUMN"
			     type="BINARY" />
		<timestamp-column name="TIMESTAMP_COLUMN"
			          type="BIGINT" />
            </string-keyed-table>
        </string-keyed-jdbc-store>
    </persistence>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Library Mode).

21.7.3.4. JdbcStringBasedStore Multiple Node Configuration (Remote Client-Server Mode)

The following is a configuration for the JdbcStringBasedStore in Red Hat JBoss Data Grid’s Remote Client-Server mode. This configuration is used when multiple nodes must be used. 

<subsystem xmlns="urn:infinispan:server:core:8.4" default-cache-container="default">
	<cache-container <!-- Additional configuration information here --> >
		<!-- Additional configuration elements here -->
      <replicated-cache>
			<!-- Additional configuration elements here -->
	      <string-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS"
	            		       fetch-state="true"
	            		       passivation="false"
	            		       preload="false"
	            		       purge="false"
	            		       shared="false"
	            		       singleton="true">
	         <string-keyed-table prefix="JDG">
	             <id-column name="id"
	                        type="${id.column.type}"/>
	             <data-column name="datum"
	                          type="${data.column.type}"/>
	             <timestamp-column name="version"
	                               type="${timestamp.column.type}"/>
				</string-keyed-table>
			</string-keyed-jdbc-store>
		</replicated-cache>
	</cache-container>
</subsystem>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Remote Client-Server Mode).

21.7.4. JdbcMixedStores

21.7.4.1. JdbcMixedStores

The JdbcMixedStore is a hybrid implementation that delegates keys based on their type to either the JdbcBinaryStore or JdbcStringBasedStore.

Important

Mixed JDBC stores are deprecated in JBoss Data Grid 7.1, and are not recommended for production use. It is recommended to utilize a String Based store instead.

21.7.4.2. JdbcMixedStore Configuration (Remote Client-Server Mode)

The following is a configuration for a JdbcMixedStore for Red Hat JBoss Data Grid’s Remote Client-Server mode: 

<local-cache name="customCache">
	<mixed-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS"
				passivation="true"
				preload="false"
				purge="false">
		<binary-keyed-table prefix="MIX_BKT2">
			<id-column name="id"
				   type="${id.column.type}"/>
			<data-column name="datum"
				     type="${data.column.type}"/>
			<timestamp-column name="version"
				   	  type="${timestamp.column.type}"/>
		</binary-keyed-table>
		<string-keyed-table prefix="MIX_STR2">
			<id-column name="id"
				   type="${id.column.type}"/>
			<data-column name="datum"
				     type="${data.column.type}"/>
			<timestamp-column name="version"
				   	  type="${timestamp.column.type}"/>
		</string-keyed-table>
	</mixed-keyed-jdbc-store>
</local-cache>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Remote Client-Server Mode).

21.7.4.3. JdbcMixedStore Configuration (Library Mode)

The following is a sample configuration for the JdbcMixedStore : 

<infinispan
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:infinispan:config:8.4 http://www.infinispan.org/schemas/infinispan-config-8.4.xsd
            urn:infinispan:config:store:jdbc:8.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-8.0.xsd"
        xmlns="urn:infinispan:config:8.4">
        <!-- Additional configuration elements here -->
	<persistence>
	<mixed-keyed-jdbc-store xmlns="urn:infinispan:config:store:jdbc:8.0"
	                      fetch-state="false"
			      purge="false"
			      key-to-string-mapper="org.infinispan.persistence.keymappers.DefaultTwoWayKey2StringMapper">
		<connection-pool connection-url="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1"
				username="sa"
				driver="org.h2.Driver"/>
		<binary-keyed-table dropOnExit="true"
				  createOnStart="true"
				  prefix="ISPN_BUCKET_TABLE_BINARY">
			<id-column name="ID_COLUMN"
				  type="VARCHAR(255)" />
			<data-column name="DATA_COLUMN"
				    type="BINARY" />
			<timestamp-column name="TIMESTAMP_COLUMN"
					 type="BIGINT" />
		</binary-keyed-table>
		<string-keyed-table dropOnExit="true"
				  createOnStart="true"
				  prefix="ISPN_BUCKET_TABLE_STRING">
			<id-column name="ID_COLUMN"
				  type="VARCHAR(255)" />
			<data-column name="DATA_COLUMN"
				    type="BINARY" />
			<timestamp-column name="TIMESTAMP_COLUMN"
					 type="BIGINT" />
		</string-keyed-table>
	</mixed-keyed-jdbc-store>
</persistence>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Library Mode).

21.7.5. Cache Store Troubleshooting

21.7.5.1. IOExceptions with JdbcStringBasedStore

An IOException Unsupported protocol version 48 error when using JdbcStringBasedStore indicates that your data column type is set to VARCHAR, CLOB or something similar instead of the correct type, BLOB or VARBINARY. Despite its name, JdbcStringBasedStore only requires that the keys are strings while the values can be any data type, so that they can be stored in a binary column.

21.8. The Remote Cache Store

21.8.1. Remote Cache Stores

The RemoteCacheStore is an implementation of the cache loader that stores data in a remote Red Hat JBoss Data Grid cluster. The RemoteCacheStore uses the Hot Rod client-server architecture to communicate with the remote cluster.

For remote cache stores, Hot Rod provides load balancing, fault tolerance and the ability to fine tune the connection between the RemoteCacheStore and the cluster.

21.8.2. Remote Cache Store Configuration (Remote Client-Server Mode)

The following is a sample remote cache store configuration for Red Hat JBoss Data Grid’s Remote Client-Server mode: 

<remote-store cache="default"
              socket-timeout="60000"
              tcp-no-delay="true"
              hotrod-wrapping="true">
	<remote-server outbound-socket-binding="remote-store-hotrod-server" />
</remote-store>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Remote Client-Server Mode).

21.8.3. Remote Cache Store Configuration (Library Mode)

The following is a sample remote cache store configuration for Red Hat JBoss Data Grid’s Library mode: 

<persistence passivation="false">
	<remote-store xmlns="urn:infinispan:config:store:remote:8.0"
	             cache="default"
		     fetch-state="false"
		     shared="true"
		     preload="false"
		     purge="false"
		     tcp-no-delay="true"
		     key-size-estimate="62"
		     value-size-estimate="512"
		     force-return-values="false">
		<remote-server host="127.0.0.1"
			port="1971" />
		<connectionPool max-active="99"
				max-idle="97"
				max-total="98" />
	</remote-store>
</persistence>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Library Mode).

21.8.4. Define the Outbound Socket for the Remote Cache Store

The Hot Rod server used by the remote cache store is defined using the outbound-socket-binding element in a standalone.xml file.

An example of this configuration in the standalone.xml file is as follows:

Define the Outbound Socket

<server>
    <!-- Additional configuration elements here -->
    <socket-binding-group name="standard-sockets"
    			  default-interface="public"
    			  port-offset="${jboss.socket.binding.port-offset:0}">
        <!-- Additional configuration elements here -->
        <outbound-socket-binding name="remote-store-hotrod-server">
            <remote-destination host="remote-host"
                                port="11222"/>
        </outbound-socket-binding>
    </socket-binding-group>
</server>

21.9. JPA Cache Store

21.9.1. JPA Cache Stores

The JPA (Java Persistence API) Cache Store stores cache entries in the database using a formal schema, which allows other applications to read the persisted data and load data provided by other applications into Red Hat JBoss Data Grid. The database should not be used by the other applications concurrently with JBoss Data Grid.

Important

In Red Hat JBoss Data Grid, JPA cache stores are only supported in Library mode.

21.9.2. JPA Cache Store Sample XML Configuration (Library Mode)

To configure JPA Cache Stores using XML in Red Hat JBoss Data Grid, add the following configuration to the infinispan.xml file: 

<local-cache name="users">
  <!-- Insert additional configuration elements here -->
	<persistence passivation="false">
            <jpa-store xmlns="urn:infinispan:config:store:jpa:8.0"
                      shared="true"
                      preload="true"
                      persistence-unit="MyPersistenceUnit"
                      entity-class="org.infinispan.loaders.jpa.entity.User" />
	</persistence>
</local-cache>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Library Mode).

21.9.3. Storing Metadata in the Database

When storeMetadata is set to true (default value), meta information about the entries such as expiration, creation and modification timestamps, and versioning is stored in the database. JBoss Data Grid stores the metadata in an additional table named _ispn_metadata_ because the entity table has a fixed layout that cannot accommodate the metadata.

The structure of this table depends on the database in use. Enable the automatic creation of this table using the same database as the test environment and then transfer the structure to the production database.

Configure persistence.xml for Metadata Entities

  1. Using Hibernate as the JPA implementation allows automatic creation of these tables using the property hibernate.hbm2ddl.auto in persistence.xml as follows: 

    <property name="hibernate.hbm2ddl.auto" value="update"/>

  2. Declare the metadata entity class to the JPA provider by adding the following to persistence.xml : 

    <class>org.infinispan.persistence.jpa.impl.MetadataEntity</class>

As outlined, metadata is always stored in a new table. If metadata information collection and storage is not required, set the storeMetadata attribute to false in the JPA Store configuration.

21.9.4. Deploying JPA Cache Stores in Various Containers

Red Hat JBoss Data Grid’s JPA Cache Store implementations are deployed normally for all supported containers, except Red Hat JBoss Enterprise Application Platform. JBoss Data Grid’s JBoss EAP modules contain the JPA cache store and related libraries (such as Hibernate). As a result, the relevant libraries are not packaged inside the application, but instead the application refers to the libraries in the JBoss EAP modules that have them installed.

These modules are not required for containers other than JBoss EAP. As a result, all the relevant libraries are packaged in the application’s WAR/EAR file, such as with the following Maven dependency: 

<dependency>
    <groupId>org.infinispan</groupId>
    <artifactId>infinispan-cachestore-jpa</artifactId>
    <version>8.4.0.Final-redhat-2</version>
</dependency>

Deploy JPA Cache Stores in JBoss EAP 6.3.x and earlier

  • To add dependencies from the JBoss Data Grid modules to the application’s classpath, provide the JBoss EAP deployer a list of dependencies in one of the following ways:

    • Add a dependency configuration to the MANIFEST.MF file: 

      Manifest-Version: 1.0
Dependencies: org.infinispan:jdg-7.1 services, org.infinispan.persistence.jpa:jdg-7.1 services

    • Add a dependency configuration to the jboss-deployment-structure.xml file: 

      <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
    <deployment>
        <dependencies>
            <module name="org.infinispan.persistence.jpa" slot="jdg-7.1" services="export"/>
            <module name="org.infinispan" slot="jdg-7.1" services="export"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>

Deploy JPA Cache Stores in JBoss EAP 6.4 and later

  1. Add the following property in persistence.xml : 

    <persistence-unit>
  [...]
  <properties>
    <property name="jboss.as.jpa.providerModule" value="application" />
  </properties>
</persistence-unit>

  2. Add the following dependencies to the jboss-deployment-structure.xml : 

    <jboss-deployment-structure>
    <deployment>
        <dependencies>
            <module name="org.infinispan" slot="jdg-7.1"/>
            <module name="org.jgroups" slot="jdg-7.1"/>
            <module name="org.infinispan.persistence.jpa" slot="jdg-7.1" services="export"/>
            <module name="org.hibernate"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>
  3. Add any additional dependencies, such as additional JDG modules, are in use add these to the dependencies section in jboss-deployment-structure.xml .
Important

JPA Cache Store is not supported in Apache Karaf in JBoss Data Grid 7.1.

21.10. Cassandra Cache Store

21.10.1. Cassandra Cache Store

Red Hat JBoss Data Grid allows Apache Cassandra to function as a Cache Store, leveraging their distributed database architecture to provide a virtually unlimited, horizontally scalable persistent store for cache entries.

In order to use the Cassandra Cache Store an appropriate keyspace must first be created on the Cassandra database. This may either be performed automatically or by enabling the auto-create-keyspace parameter in the cache store configuration. A sample keyspace creation is demonstrated below: 

CREATE KEYSPACE IF NOT EXISTS Infinispan WITH replication = {'class':'SimpleStrategy', 'replication_factor':1};
CREATE TABLE Infinispan.InfinispanEntries (key blob PRIMARY KEY, value blob, metadata blob);

21.10.2. Enabling the Cassandra Cache Store

The Cassandra Cache Store is included based on the downloaded distribution. The following indicates where this is located, and steps to enable it if required:

  • Library Mode - The infinispan-cachestore-cassandra-8.4.0.Final-redhat-2-deployable.jar is included in the jboss-datagrid-${jdg-version}-library/ directory, and may be added to any projects that are using the Cassandra Cache Store.
  • Remote Client-Server Mode - The Cassandra Cache Store is prepackaged in the modules/ directory of the server, and may be used by default with no additional configuration necessary.
  • JBoss Data Grid modules for JBoss EAP - The Cassandra Cache Store is included in the modules distributed, and may be added by using the org.infinispan.persistence.cassandra as the module name.

21.10.3. Cassandra Cache Store Sample XML Configuration (Remote Client-Server Mode)

In Remote Client-Server mode the Cassandra Cache Store is defined by using the class org.infinispan.persistence.cassandra.CassandraStore and defining the properties individually within the store.

The following configuration snippet provides an example on how to define a Cassandra Cache Store inside of an xml file: 

<local-cache name="cassandracache">
    <locking acquire-timeout="30000" concurrency-level="1000" striping="false"/>
    <transaction mode="NONE"/>
    <store name="cassstore1"
           class="org.infinispan.persistence.cassandra.CassandraStore"
           shared="true"
           passivation="false">
        <property name="autoCreateKeyspace">true</property>
        <property name="keyspace">store1</property>
        <property name="entryTable">entries1</property>
        <property name="consistencyLevel">LOCAL_ONE</property>
        <property name="serialConsistencyLevel">SERIAL</property>
        <property name="servers">127.0.0.1[9042],127.0.0.1[9041]</property>
        <property name="connectionPool.heartbeatIntervalSeconds">30</property>
        <property name="connectionPool.idleTimeoutSeconds">120</property>
        <property name="connectionPool.poolTimeoutMillis">5</property>
    </store>
</local-cache>

21.10.4. Cassandra Cache Store Sample XML Configuration (Library Mode)

In Library Mode the Cassandra Cache Store may be configured using two different methods:

  • Option 1: Using the same method discussed for Remote Client-Server Mode, found in Cassandra Cache Store Sample XML Configuration (Remote Client-Server Mode).

  • Option 2: Using the cassandra-store schema. The following snippet shows an example configuration defining a Cassandra Cache Store: 

    <cache-container default-cache="cassandracache">
  <local-cache name="cassandracache">
    <persistence passivation="false">
      <cassandra-store xmlns="urn:infinispan:config:store:cassandra:8.2"
            auto-create-keyspace="true"
            keyspace="Infinispan"
            entry-table="InfinispanEntries" shared="true">
        <cassandra-server host="127.0.0.1" port="9042" />
        <connection-pool heartbeat-interval-seconds="30"
            idle-timeout-seconds="120"
            pool-timeout-millis="5" />
      </cassandra-store>
    </persistence>
  </local-cache>
</cache-container>

21.10.5. Cassandra Configuration Parameters

When defining a backing Cassandra instance in Library Mode one or more cassandra-server elements may be specified in the configuration. Each of the elements has the following properties:

Table 21.1. Cassandra Server Configuration Parameters

Parameter NameDescriptionDefault Value

host

The hostname or ip address of a Cassandra server.

127.0.0.1

port

The port on which the server is listening.

9042

The following properties may be configured on the Cassandra Cache Store:

Table 21.2. Cassandra Configuration Parameter

Parameter NameDescriptionDefault Value

auto-create-keyspace

Determines whether the keyspace and entry table should be automatically created on startup.

true

keyspace

Name of the keyspace to use.

Infinispan

entry-table

Name of the table storing entries.

InfinispanEntries

consistency-level

Consistency level to use for the queries.

LOCAL_ONE

serial-consistency-level

Serial consistency level to use for the queries.

SERIAL

A connection-pool may also be defined with the following elements:

Table 21.3. Connection Pool Configuration Parameters

Parameter NameDescriptionDefault Value

pool-timeout-millis

Time that the driver blocks when no connection from hosts pool is available. After this timeout, the driver will try the next host.

5

heartbeat-interval-seconds

Application-side heartbeat to avoid the connections being dropped when no activity is happening. Set to 0 to disable.

30

idle-timeout-seconds

Timeout before an idle connection is removed.

120

21.11. Custom Cache Stores

21.11.1. Custom Cache Stores

Custom cache stores are a customized implementation of Red Hat JBoss Data Grid cache stores.

In order to create a custom cache store (or loader), implement all or a subset of the following interfaces based on the need:

  • CacheLoader
  • CacheWriter
  • AdvancedCacheLoader
  • AdvancedCacheWriter
  • ExternalStore
  • AdvancedLoadWriteStore

See Cache Loaders and Cache Writers for individual functions of the interfaces.

Note

If the AdvancedCacheWriter is not implemented, the expired entries cannot be purged or cleared using the given writer.

Note

If the AdvancedCacheLoader is not implemented, the entries stored in the given loader will not be used for preloading.

To migrate the existing cache store to the new API or to write a new store implementation, use SingleFileStore as an example. To view the SingleFileStore example code, download the JBoss Data Grid source code.

Use the following procedure to download SingleFileStore example code from the Customer Portal:

Download JBoss Data Grid Source Code

  1. To access the Red Hat Customer Portal, navigate to https://access.redhat.com/home in a browser.
  2. Click menu:Downloads[] .
  3. In the section labeled JBoss Development and Management , click menu:Red Hat JBoss Data Grid[] .
  4. Enter the relevant credentials in the Red Hat Login and Password fields and click menu:Log In[] .
  5. From the list of downloadable files, locate Red Hat JBoss Data Grid 7 Source Code and click menu:Download[] . Save and unpack it in a desired location.
  6. Locate the SingleFileStore source code by navigating through jboss-datagrid-7.1.0-sources/infinispan-8.4.0.Final-redhat-2-src/core/src/main/java/org/infinispan/persistence/file/SingleFileStore.java .

21.11.2. Custom Cache Store Maven Archetype

An easy way to get started with developing a Custom Cache Store is to use the Maven archetype; creating an archetype will generate a new Maven project with the correct directory layout and sample code.

Generate a Maven Archetype

  1. Ensure the JBoss Data Grid Maven repository has been installed by following the instructions in the Red Hat JBoss Data Grid Getting Started Guide .

  2. Open a command prompt and execute the following command to generate an archetype in the current directory: 

    mvn -Dmaven.repo.local="path/to/unzipped/jboss-datagrid-7.1.0-maven-repository/"
  archetype:generate
  -DarchetypeGroupId=org.infinispan
  -DarchetypeArtifactId=custom-cache-store-archetype
  -DarchetypeVersion=0.0.2.Final-redhat-2
    Note

    The above command has been broken into multiple lines for readability; however, when executed this command and all arguments must be on a single line.

21.11.3. Custom Cache Store Configuration (Remote Client-Server Mode)

21.11.3.1. Custom Cache Store Configuration (Remote Client-Server Mode)

The following is a sample configuration for a custom cache store in Red Hat JBoss Data Grid’s Remote Client-Server mode:

Custom Cache Store Configuration

<distributed-cache name="cacheStore" mode="SYNC" segments="20" owners="2" remote-timeout="30000">
    <store class="my.package.CustomCacheStore">
        <property name="customStoreProperty">10</property>
    </store>
</distributed-cache>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Remote Client-Server Mode).

21.11.3.2. Option 1: Add Custom Cache Store using deployments (Remote Client-Server Mode)

Deploy Custom Cache Store .jar file to JDG server using deployments

  1. Add the following Java service loader file META-INF/services/org.infinispan.persistence.spi.AdvancedLoadWriteStore to the module and add a reference to the Custom Cache Store Class, such as seen below: 

    my.package.CustomCacheStore
  2. Copy the jar to the $JDG_HOME/standalone/deployments/ directory.

  3. If the .jar file is available the server the following message will be displayed in the logs: 

    JBAS010287: Registering Deployed Cache Store service for store 'my.package.CustomCacheStore'

  4. In the infinispan-core subsystem add an entry for the cache inside a cache-container, specifying the class that overrides one of the interfaces from Custom Cache Stores: 

    <subsystem xmlns="urn:infinispan:server:core:8.4">
  [...]
  <distributed-cache name="cacheStore" mode="SYNC" segments="20" owners="2" remote-timeout="30000"">
    <store class="my.package.CustomCacheStore">
      <!-- If custom properties are included these may be specified as below -->
      <property name="customStoreProperty">10</property>
    </store>
  </distributed-cache>
  [...]
</subsystem>

21.11.3.3. Option 2: Add Custom Cache Store using the CLI (Remote Client-Server Mode)

Deploying Custom Cache Store .jar file to JDG server using the CLI

  1. Connect to the JDG server by running the below command: 

    [$JDG_HOME] $ bin/cli.sh --connect --controller=$IP:$PORT

  2. Deploy the .jar file by executing the following command: 

    deploy /path/to/artifact.jar

21.11.3.4. Option 3: Add Custom Cache Store using JON (Remote Client-Server Mode)

Deploying Custom Cache Store .jar file to JDG server using JBoss Operation Network

  1. Log into JON.
  2. Navigate to Bundles along the upper bar.
  3. Click the New button and choose the Recipe radio button.

  4. Insert a deployment bundle file content that references the store, similar to the following example: 

    <?xml version="1.0"?>
<project name="cc-bundle" default="main" xmlns:rhq="antlib:org.rhq.bundle">

  <rhq:bundle name="Mongo DB Custom Cache Store" version="1.0" description="Custom Cache Store">
  	<rhq:deployment-unit name="JDG" compliance="full">
  	  <rhq:file name="custom-store.jar"/>
  	</rhq:deployment-unit>
  </rhq:bundle>

  <target name="main" />

</project>
  5. Proceed with Next button to Bundle Groups configuration wizard page and proceed with Next button once again.
  6. Locate custom cache store .jar file using file uploader and Upload the file.
  7. Proceed with Next button to Summary configuration wizard page. Proceed with Finish button in order to finish bundle configuration.
  8. Navigate back to the Bundles tab along the upper bar.
  9. Select the newly created bundle and click Deploy button.
  10. Enter Destination Name and choose the proper Resource Group; this group should only consist of JDG servers.
  11. Choose Install Directory from Base Location's radio box group.
  12. Enter /standalone/deployments in Deployment Directory text field below.
  13. Proceed with the wizard using the default options.

  14. Validate the deployment using the following command on the server’s host: 

    find $JDG_HOME -name "custom-store.jar"
  15. Confirm the bundle has been installed in $JDG_HOME/standalone/deployments.

Once the above steps are completed the .jar file will be successfully uploaded and registered by the JDG server.

Note

The JON plugin has been deprecated in JBoss Data Grid 7.1 and is expected to be removed in a subsequent version.

21.11.4. Custom Cache Store Configuration (Library Mode)

The following is a sample configuration for a custom cache store in Red Hat JBoss Data Grid’s Library mode:

Custom Cache Store Configuration

<persistence>
	<store class="org.infinispan.custom.CustomCacheStore"
	       preload="true"
	       shared="true">
	       <property name="customStoreProperty">10</property>
	</store>
</persistence>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Library Mode).

Note

The Custom Cache Store classes must be in the classpath where Red Hat JBoss Data Grid is used. Most often this is accomplished by packaging the Custom Cache Store in with the application; however, it may also be accomplished by defining the Custom Cache Store as a module to EAP and listed as a dependency, as discussed in the Red Hat JBoss Enterprise Application Platform Administration and Configuration Guide .