18.9. 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 Section 17.1, “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 and map/reduce iterations.
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:

Procedure 18.10. 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 Downloads.
  3. In the section labeled JBoss Development and Management, click Red Hat JBoss Data Grid.
  4. Enter the relevant credentials in the Red Hat Login and Password fields and click Log In.
  5. From the list of downloadable files, locate Red Hat JBoss Data Grid ${VERSION} Source Code and click Download. Save and unpack it in a desired location.
  6. Locate the SingleFileStore source code by navigating through jboss-datagrid-6.6.1-sources/infinispan-6.4.1.Final-redhat-1-src/core/src/main/java/org/infinispan/persistence/file/SingleFileStore.java.
Report a bug

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

Procedure 18.11. 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-6.6.0-maven-repository/" 
  archetype:generate 
  -DarchetypeGroupId=org.infinispan 
  -DarchetypeArtifactId=custom-cache-store-archetype 
  -DarchetypeVersion=6.4.1.Final-redhat-1

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

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

Example 18.2. 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 Section 18.3, “Cache Store Configuration Details (Remote Client-Server Mode)”.
Report a bug

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

Procedure 18.12. 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 Section 18.9, “Custom Cache Stores”: 
    <subsystem xmlns="urn:infinispan:server:core:6.2">
  [...]
  <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>
Report a bug

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

Procedure 18.13. 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=$IP:$PORT
  2. Deploy the .jar file by executing the following command: 
    deploy /path/to/artifact.jar
Report a bug

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

Procedure 18.14.  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.
Report a bug

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

Example 18.3. Custom Cache Store Configuration

<persistence>
	<store class="org.infinispan.custom.CustomCacheStore" 
	       preload="true" 
	       shared="true">
		<properties>
			<property name="customStoreProperty" 
				  value="10" />
		</properties>
	</store>
</persistence>
For details about the elements and parameters used in this sample configuration, see Section 18.2, “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.
Report a bug