Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 15. 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.
Report a bug

15.1. JdbcBinaryStores
Copy link

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.
Report a bug
The following is a configuration for JdbcBinaryStore using Red Hat JBoss Data Grid's Remote Client-Server mode with Passivation enabled.

Procedure 15.1. Configure the JdbcBinaryStore for Remote Client-Server Mode

  1. The binary-keyed-jdbc-store Element

    The binary-keyed-jdbc-store element specifies the configuration for a binary keyed cache JDBC store.
    1. The datasource parameter defines the name of a JNDI for the datasource.
    2. 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).
    3. The preload parameter specifies whether to load entries into the cache during start up. Valid values for this parameter are true and false.
    4. 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. 
    <local-cache>
	...
	<binary-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
				 passivation="${true/false}" 
				 preload="${true/false]" 
				 purge="${true/false}">
    Copy to Clipboard Toggle word wrap

  2. The binary-keyed-table Element

    The binary-keyed-table element specifies information about the database table used to store binary cache entries.
    1. The prefix parameter specifies a prefix string for the database table name. 
    <local-cache>
	...
	<binary-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
				 passivation="${true/false}" 
				 preload="${true/false]" 
				 purge="${true/false}">
               	<binary-keyed-table prefix="JDG">
    Copy to Clipboard Toggle word wrap

  3. The id-column Element

    The id-column element specifies information about a database column that holds cache entry IDs.
    1. The name parameter specifies the name of the database column.
    2. The type parameter specifies the type of the database column. 
    <local-cache>
	...
	<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}"/>
    Copy to Clipboard Toggle word wrap

  4. The data-column Element

    The data-column element contains information about a database column that holds cache entry data.
    1. The name parameter specifies the name of the database column.
    2. The type parameter specifies the type of the database column. 
    <local-cache>
	...
	<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}"/>
    Copy to Clipboard Toggle word wrap

  5. The timestamp-column Element

    The timestamp-column element specifies information about the database column that holds cache entry timestamps.
    1. The name parameter specifies the name of the database column.
    2. The type parameter specifies the type of the database column. 
    <local-cache>
	...
	<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>
    Copy to Clipboard Toggle word wrap
Report a bug
The following is a sample configuration for the JdbcBinaryStore:

Procedure 15.2. Configure the JdbcBinaryStore for Library Mode

  1. The binaryKeyedJdbcStore Element

    The binaryKeyedJdbcStore element uses the following parameters to configure the cache store:
    1. The fetchPersistentState 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 fetchPersistentState parameter is false by default.
    2. The ignoreModifications parameter determines whether operations that modify the cache (e.g. put, remove, clear, store, etc.) do not affect the cache store. As a result, the cache store can become out of sync with the cache.
    3. The purgeOnStartup parameter specifies whether the cache store is purged when initially started. 
    <infinispan
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
            urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
        xmlns="urn:infinispan:config:6.0">
        ...
<persistence>
	<binaryKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
	                      fetchPersistentState="false"
			      ignoreModifications="false" 
			      purgeOnStartup="false">
    Copy to Clipboard Toggle word wrap

  2. The connectionPool Element

    The connectionPool element specifies a connection pool for the JDBC driver using the following parameters:
    1. The connectionUrl parameter specifies the JDBC driver-specific connection URL.
    2. The username parameter contains the username used to connect via the connectionUrl.
    3. The driverClass parameter specifies the class name of the driver used to connect to the database. 
    <infinispan
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
            urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
        xmlns="urn:infinispan:config:6.0">
        ...
<persistence>
	<binaryKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
	                      fetchPersistentState="false"
			      ignoreModifications="false" 
			      purgeOnStartup="false">
		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
				username="sa" 
				driverClass="org.h2.Driver"/>
    Copy to Clipboard Toggle word wrap

  3. The binaryKeyedTable Element

    The binaryKeyedTable element defines the table that stores cache entries. It uses the following parameters to configure the cache store:
    1. The dropOnExit parameter specifies whether the database tables are dropped upon shutdown.
    2. The createOnStart parameter specifies whether the database tables are created by the store on startup.
    3. The prefix parameter defines the string prepended to name of the target cache when composing the name of the cache bucket table. 
    <infinispan
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
            urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
        xmlns="urn:infinispan:config:6.0">
        ...
<persistence>
	<binaryKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
	                      fetchPersistentState="false"
			      ignoreModifications="false" 
			      purgeOnStartup="false">
		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
				username="sa" 
				driverClass="org.h2.Driver"/>
		<binaryKeyedTable dropOnExit="true" 
				  createOnStart="true" 
				  prefix="ISPN_BUCKET_TABLE">
    Copy to Clipboard Toggle word wrap

  4. The idColumn Element

    The idColumn element defines the column where the cache key or bucket ID is stored. It uses the following parameters:
    1. Use the name parameter to specify the name of the column used.
    2. Use the type parameter to specify the type of the column used. 
    <infinispan
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
            urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
        xmlns="urn:infinispan:config:6.0">
        ...
<persistence>
	<binaryKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
	                      fetchPersistentState="false"
			      ignoreModifications="false" 
			      purgeOnStartup="false">
		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
				username="sa" 
				driverClass="org.h2.Driver"/>
		<binaryKeyedTable dropOnExit="true" 
				  createOnStart="true" 
				  prefix="ISPN_BUCKET_TABLE">
			<idColumn name="ID_COLUMN" 
				  type="VARCHAR(255)" />
    Copy to Clipboard Toggle word wrap

  5. The dataColumn Element

    The dataColumn element specifies the column where the cache entry or bucket is stored.
    1. Use the name parameter to specify the name of the column used.
    2. Use the type parameter to specify the type of the column used. 
    <infinispan
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
            urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
        xmlns="urn:infinispan:config:6.0">
        ...
<persistence>
	<binaryKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
	                      fetchPersistentState="false"
			      ignoreModifications="false" 
			      purgeOnStartup="false">
		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
				username="sa" 
				driverClass="org.h2.Driver"/>
		<binaryKeyedTable dropOnExit="true" 
				  createOnStart="true" 
				  prefix="ISPN_BUCKET_TABLE">
			<idColumn name="ID_COLUMN" 
				  type="VARCHAR(255)" />
			<dataColumn name="DATA_COLUMN" 
				    type="BINARY" />
    Copy to Clipboard Toggle word wrap

  6. The timestampColumn Element

    The timestampColumn element specifies the column where the time stamp of the cache entry or bucket is stored.
    1. Use the name parameter to specify the name of the column used.
    2. Use the type parameter to specify the type of the column used. 
    <infinispan
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
            urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
        xmlns="urn:infinispan:config:6.0">
        ...
<persistence>
	<binaryKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
	                      fetchPersistentState="false"
			      ignoreModifications="false" 
			      purgeOnStartup="false">
		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
				username="sa" 
				driverClass="org.h2.Driver"/>
		<binaryKeyedTable dropOnExit="true" 
				  createOnStart="true" 
				  prefix="ISPN_BUCKET_TABLE">
			<idColumn name="ID_COLUMN" 
				  type="VARCHAR(255)" />
			<dataColumn name="DATA_COLUMN" 
				    type="BINARY" />
			<timestampColumn name="TIMESTAMP_COLUMN" 
					 type="BIGINT" />
		</binaryKeyedTable>
	</binaryKeyedJdbcStore>
</persistence>
    Copy to Clipboard Toggle word wrap
Report a bug

15.1.3. JdbcBinaryStore Programmatic Configuration
Copy link

The following is a sample configuration for the JdbcBinaryStore:

Procedure 15.3. JdbcBinaryStore Programmatic Configuration (Library Mode)

  1. Create a New Configuration Builder

    Use the ConfigurationBuilder to create a new configuration object. 
    ConfigurationBuilder builder = new ConfigurationBuilder();
  builder.persistence()
    Copy to Clipboard Toggle word wrap

  2. Add the JdbcBinaryStoreConfigurationBuilder

    Add the JdbcBinaryStore configuration builder to build a specific configuration related to this store. 
    ConfigurationBuilder builder = new ConfigurationBuilder();
  builder.persistence()
     .addStore(JdbcBinaryStoreConfigurationBuilder.class)
    Copy to Clipboard Toggle word wrap

  3. Set Up Persistence

    fetchPersistentState 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 loader has this property set to true. The fetchPersistentState property is false by default. 
    ConfigurationBuilder builder = new ConfigurationBuilder();
  builder.persistence()
     .addStore(JdbcBinaryStoreConfigurationBuilder.class)
     .fetchPersistentState(false)
    Copy to Clipboard Toggle word wrap

  4. Set Modifications

    ignoreModifications determines whether write methods are pushed to the specific cache loader by allowing write operations to the local file cache loader, but not the shared cache loader. In some cases, transient application data should only reside in a file-based cache loader on the same server as the in-memory cache. For example, this would apply with a further JDBC based cache loader used by all servers in the network. ignoreModifications is false by default. 
    ConfigurationBuilder builder = new ConfigurationBuilder();
  builder.persistence()
     .addStore(JdbcBinaryStoreConfigurationBuilder.class)
     .fetchPersistentState(false)
     .ignoreModifications(false)
    Copy to Clipboard Toggle word wrap

  5. Configure Purging

    purgeOnStartup specifies whether the cache is purged when initially started. 
    ConfigurationBuilder builder = new ConfigurationBuilder();
  builder.persistence()
     .addStore(JdbcBinaryStoreConfigurationBuilder.class)
     .fetchPersistentState(false)
     .ignoreModifications(false)
     .purgeOnStartup(false)
    Copy to Clipboard Toggle word wrap

  6. Configure the Table

    1. Set Drop Table On Exit Method

      dropOnExit determines if the table will be created when the cache store is stopped. This is set to false by default.

    2. Set Create Table On Start Method

      createOnStart creates the table when starting the cache store if no table currently exists. This method is true by default.

    3. Set the Table Name Prefix

      tableNamePrefix sets the prefix for the name of the table in which the data will be stored.

    4. idColumnName

      The idColumnName property defines the column where the cache key or bucket ID is stored.

    5. dataColumnName

      The dataColumnName property specifies the column where the cache entry or bucket is stored.

    6. timestampColumnName

      The timestampColumnName element specifies the column where the time stamp of the cache entry or bucket is stored. 
    ConfigurationBuilder builder = new ConfigurationBuilder();
  builder.persistence()
     .addStore(JdbcBinaryStoreConfigurationBuilder.class)
     .fetchPersistentState(false)
     .ignoreModifications(false)
     .purgeOnStartup(false)
     .table()
        .dropOnExit(true)
        .createOnStart(true)
        .tableNamePrefix("ISPN_BUCKET_TABLE")
        .idColumnName("ID_COLUMN").idColumnType("VARCHAR(255)")
        .dataColumnName("DATA_COLUMN").dataColumnType("BINARY")
        .timestampColumnName("TIMESTAMP_COLUMN").timestampColumnType("BIGINT")
    Copy to Clipboard Toggle word wrap

  7. The connectionPool Element

    The connectionPool element specifies a connection pool for the JDBC driver using the following parameters:
    1. The connectionUrl parameter specifies the JDBC driver-specific connection URL.
    2. The username parameter contains the user name used to connect via the connectionUrl.
    3. The driverClass parameter specifies the class name of the driver used to connect to the database. 
    ConfigurationBuilder builder = new ConfigurationBuilder();
  builder.persistence()
     .addStore(JdbcBinaryStoreConfigurationBuilder.class)
     .fetchPersistentState(false)
     .ignoreModifications(false)
     .purgeOnStartup(false)
     .table()
        .dropOnExit(true)
        .createOnStart(true)
        .tableNamePrefix("ISPN_BUCKET_TABLE")
        .idColumnName("ID_COLUMN").idColumnType("VARCHAR(255)")
        .dataColumnName("DATA_COLUMN").dataColumnType("BINARY")
        .timestampColumnName("TIMESTAMP_COLUMN").timestampColumnType("BIGINT")
     .connectionPool()
        .connectionUrl("jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1")
        .username("sa")
        .driverClass("org.h2.Driver");
    Copy to Clipboard Toggle word wrap

Note

Programmatic configurations can only be used with Red Hat JBoss Data Grid Library mode.
Report a bug
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red Hat