Chapter 15. JDBC Based Cache Stores

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

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

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