Developer Guide

Procedure 5.1. Configure the Cache store Programatically

1. Use the ConfigurationBuilder to create a new configuration object.
2. The passivation elements affects the way Red Hat JBoss Data Grid interacts with stores. Passivation removes an object from an in-memory cache and writes it to a secondary data store, such as a system or database. If no secondary data store exists, then the object will only be removed from the in-memory cache. Passivation is false by default.
3. The addSingleFileStore() elements adds the SingleFileStore as the cache store for this configuration. It is possible to create other stores, such as a JDBC Cache Store, which can be added using the addStore method.
4. 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.
5. The preload element 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. JBoss Data Grid will only preload up to the maximum configured number of entries in eviction.
6. The fetchPersistentState element 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 fetchPersistentState property is false by default.
7. The purgeOnStartup element controls whether cache store is purged when it starts up and is false by default.
8. The location element configuration element sets a location on disk where the store can write.
9. These attributes configure aspects specific to each cache store. For example, the location attribute points to where the SingleFileStore will keep files containing data. Other stores may require more complex configuration.
10. The singleton element enables modifications to be stored by only one node in the cluster. This node is called the coordinator. The coordinator pushes the caches in-memory states to disk. This function is activated by setting the enabled attribute to true in all nodes. The shared parameter cannot be defined with singleton enabled at the same time. The enabled attribute is false by default.
11. The pushStateWhenCoordinator element is set to true by default. If true, this property will cause a node that has become the coordinator to transfer in-memory state to the underlying cache store. This parameter is useful where the coordinator has crashed and a new coordinator is elected.

Procedure 5.2. LevelDB Cache Store programmatic configuration

1. Use the ConfigurationBuilder to create a new configuration object.
2. Add the store using LevelDBCacheStoreConfigurationBuilder class to build its configuration.
3. Set the LevelDB Cache Store location path. The specified path stores the primary cache store data. The directory is automatically created if it does not exist.
4. Specify the location for expired data using the expiredLocation parameter for the LevelDB Store. The specified path stores expired data before it is purged. The directory is automatically created if it does not exist.

Procedure 5.3. JdbcBinaryStore Programmatic Configuration (Library Mode)

1. Use the ConfigurationBuilder to create a new configuration object.
2. Add the JdbcBinaryStore configuration builder to build a specific configuration related to this store.
3. The fetchPersistentState element 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.
4. The ignoreModifications element 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.
5. The purgeOnStartup element specifies whether the cache is purged when initially started.
6. Configure the table as follows:
   1. dropOnExit determines if the table will be dropped when the cache store is stopped. This is set to false by default.
   2. createOnStart creates the table when starting the cache store if no table currently exists. This method is true by default.
   3. tableNamePrefix sets the prefix for the name of the table in which the data will be stored.
   4. The idColumnName property defines the column where the cache key or bucket ID is stored.
   5. The dataColumnName property specifies the column where the cache entry or bucket is stored.
   6. The timestampColumnName element specifies the column where the time stamp of the cache entry or bucket is stored.
7. 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.

Procedure 5.4. Configure the JdbcStringBasedStore Programmatically

1. Use the ConfigurationBuilder to create a new configuration object.
2. Add the JdbcStringBasedStore configuration builder to build a specific configuration related to this store.
3. The fetchPersistentState 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 loader has this property set to true. The fetchPersistentState property is false by default.
4. The ignoreModifications parameter 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.
5. The purgeOnStartup parameter specifies whether the cache is purged when initially started.
6. Configure the Table
   1. dropOnExit determines if the table will be dropped when the cache store is stopped. This is set to false by default.
   2. createOnStart creates the table when starting the cache store if no table currently exists. This method is true by default.
   3. tableNamePrefix sets the prefix for the name of the table in which the data will be stored.
   4. The idColumnName property defines the column where the cache key or bucket ID is stored.
   5. The dataColumnName property specifies the column where the cache entry or bucket is stored.
   6. The timestampColumnName element specifies the column where the time stamp of the cache entry or bucket is stored.
7. The dataSource element specifies a data source using the following parameters:
   • The jndiUrl specifies the JNDI URL to the existing JDBC.

Procedure 5.5. Configure JdbcMixedStore Programmatically

1. Use the ConfigurationBuilder to create a new configuration object.
2. Add the JdbcMixedStore configuration builder to build a specific configuration related to this store.
3. The fetchPersistentState 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 loader has this property set to true. The fetchPersistentState property is false by default.
4. The ignoreModifications parameter 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.
5. The purgeOnStartup parameter specifies whether the cache is purged when initially started.
6. Configure the table as follows:
   1. dropOnExit determines if the table will be dropped when the cache store is stopped. This is set to false by default.
   2. createOnStart creates the table when starting the cache store if no table currently exists. This method is true by default.
   3. tableNamePrefix sets the prefix for the name of the table in which the data will be stored.
   4. The idColumnName property defines the column where the cache key or bucket ID is stored.
   5. The dataColumnName property specifies the column where the cache entry or bucket is stored.
   6. The timestampColumnName element specifies the column where the time stamp of the cache entry or bucket is stored.
7. 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.

Procedure 6.1. Configure the CacheManager Programmatically

EmbeddedCacheManager manager = new DefaultCacheManager("my-config-file.xml");
Cache defaultCache = manager.getCache();
Configuration c = new ConfigurationBuilder().clustering().cacheMode(CacheMode.REPL_SYNC)
.build();

String newCacheName = "repl";
manager.defineConfiguration(newCacheName, c);
Cache<String, String> cache = manager.getCache(newCacheName);

1. Create a CacheManager as a starting point in an XML file. If required, this CacheManager can be programmed in runtime to the specification that meets the requirements of the use case.
2. Create a new synchronously replicated cache programmatically.
   1. Create a new configuration object instance using the ConfigurationBuilder helper object:
      In the first line of the configuration, a new cache configuration object (named c) is created using the ConfigurationBuilder. Configuration c is assigned the default values for all cache configuration options except the cache mode, which is overridden and set to synchronous replication (REPL_SYNC).
   2. Define or register the configuration with a manager:
      In the third line of the configuration, the cache manager is used to define a named cache configuration for itself. This named cache configuration is called repl and its configuration is based on the configuration provided for cache configuration c in the first line.
   3. In the fourth line of the configuration, the cache manager is used to obtain a reference to the unique instance of the repl that is held by the cache manager. This cache instance is now ready to be used to perform operations to store and retrieve data.

Procedure 6.2. Customize the Default Cache

String newCacheName = "newCache";
EmbeddedCacheManager manager = new DefaultCacheManager("infinispan-config-file.xml");
Configuration dcc = manager.getDefaultCacheConfiguration();
Configuration c = new ConfigurationBuilder().read(dcc).clustering()
	.cacheMode(CacheMode.DIST_SYNC).l1().lifespan(60000L).enable()
	.build();
manager.defineConfiguration(newCacheName, c);
Cache<String, String> cache = manager.getCache(newCacheName);

1. Read an instance of a default Configuration object to get the default configuration.
2. Use the ConfigurationBuilder to construct and modify the cache mode and L1 cache lifespan on a new configuration object.
3. Register/define your cache configuration with a cache manager.
4. Obtain a reference to newCache, containing the specified configuration.

Procedure 6.3. Creating a Customized Cache Using a Non-Default Named Cache

String newCacheName = "newCache";
EmbeddedCacheManager manager = new DefaultCacheManager("infinispan-config-file.xml");
Configuration rc = manager.getCacheConfiguration("replicatedCache");
Configuration c = new ConfigurationBuilder().read(rc).clustering()
	.cacheMode(CacheMode.DIST_SYNC).l1().lifespan(60000L).enable()
	.build();
manager.defineConfiguration(newCacheName, c);
Cache<String, String> cache = manager.getCache(newCacheName);

1. Read the replicatedCache to get the default configuration.
2. Use the ConfigurationBuilder to construct and modify the desired configuration on a new configuration object.
3. Register/define your cache configuration with a cache manager.
4. Obtain a reference to newCache, containing the specified configuration.

Procedure 8.1. Clustered Listener Configuration

@Listener(clustered = true)
  protected static class ClusterListener {
     List<CacheEntryEvent> events = Collections.synchronizedList(new ArrayList<CacheEntryEvent>());
 
     @CacheEntryCreated
     @CacheEntryModified
     @CacheEntryExpired
     @CacheEntryRemoved
     public void onCacheEvent(CacheEntryEvent event) {
        log.debugf("Adding new cluster event %s", event);
        events.add(event);
     }
  }
 
  public void addClusterListener(Cache<?, ?> cache) {
     ClusterListener clusterListener = new ClusterListener();
     cache.addListener(clusterListener);
  }

1. Clustered listeners are enabled by annotating the @Listener class with clustered=true.
2. The following methods are annotated to allow client applications to be notified when entries are added, modified, expired, or removed.
   • @CacheEntryCreated
   • @CacheEntryModified
   • @CacheEntryExpired
   • @CacheEntryRemoved
3. The listener is registered with a cache, with the option of passing on a filter or converter.

Procedure 8.2. Configuring Remote Event Listeners

1. Download the Red Hat JBoss Data Grid Server distribution from the Red Hat Customer Portal

   The latest Red Hat JBoss Data Grid distribution includes the Hot Rod server with which the client will communicate.

2. Start the server

   Start the JBoss Data Grid server by using the following command from the root of the server.

   $ ./bin/standalone.sh

3. Write an application to interact with the Hot Rod server

   • Maven users

     Create an application with the following dependency, changing the version to 8.3.0-Final-redhat-1 or better.

     <properties>
       <infinispan.version>8.3.0-Final-redhat-1</infinispan.version>
     </properties>
     [...]
     <dependency>
       <groupId>org.infinispan</groupId>
       <artifactId>infinispan-remote</artifactId>
       <version>${infinispan.version}</version>
     </dependency>
     

   • Non-Maven users, adjust according to your chosen build tool or download the distribution containing all JBoss Data Grid jars.

4. Write the client application

   The following demonstrates a simple remote event listener that logs all events received.

   import org.infinispan.client.hotrod.annotation.*;
   import org.infinispan.client.hotrod.event.*;
   
   
   @ClientListener
   public class EventLogListener {
   
   
    @ClientCacheEntryCreated
    @ClientCacheEntryModified
    @ClientCacheEntryRemoved
    public void handleRemoteEvent(ClientEvent event) {
      System.out.println(event);
     }
   
   
   }

5. Use the remote event listener to execute operations against the remote cache

   The following example demonstrates a simple main java class, which adds the remote event listener and executes some operations against the remote cache.

   import org.infinispan.client.hotrod.*;
   
   
   RemoteCacheManager rcm = new RemoteCacheManager();
   RemoteCache<Integer, String> cache = rcm.getCache();
   EventLogListener listener = new EventLogListener();
   try {
    cache.addClientListener(listener);
    cache.put(1, "one");
    cache.put(1, "new-one");
    cache.remove(1);
   } finally {
    cache.removeClientListener(listener);  
   }

Procedure 8.7. Using a Converter

1. Create a JAR file with the converter implementation within it. Each factory must have a name assigned to it via the org.infinispan.filter.NamedFactory annotation.
2. Create a META-INF/services/org.infinispan.notifications.cachelistener.filter.CacheEventConverterFactory file within the JAR file and within it, write the fully qualified class name of the converter class implementation.
3. Deploy the JAR file in the JBoss Data Grid Server by performing any of the following options:

   • Procedure 8.8. Option 1: Deploy the JAR through the deployment scanner.

     • Copy the JAR to the $JDG_HOME/standalone/deployments/ directory. The deployment scanner actively monitors this directory and will deploy the newly placed file.

   • Procedure 8.9. Option 2: Deploy the JAR through the CLI

     1. Connect to the desired instance with the CLI:

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

     2. Once connected execute the deploy command:

        deploy /path/to/artifact.jar

   • Procedure 8.10. Option 3: Deploy the JAR as a custom module

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

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

     2. The jar containing the Custom Converter must be defined as a module for the Server; to add this substitute the desired name of the module and the .jar name in the below command, adding additional dependencies as necessary for the Custom Converter:

        module add --name=$MODULE-NAME --resources=$JAR-NAME.jar --dependencies=org.infinispan

     3. In a different window add the newly added module as a dependency to the org.infinispan module by editing $JDG_HOME/modules/system/layers/base/org/infinispan/main/module.xml. In this file add the following entry:

        <dependencies>
          [...]
          <module name="$MODULE-NAME">
        </dependencies>

     4. Restart the JDG server.

Procedure 8.11. Deploying a Marshaller

1. Create a JAR file with the converter implementation within it. Each factory must have a name assigned to it via the org.infinispan.filter.NamedFactory annotation.
2. Create a META-INF/services/org.infinispan.commons.marshall.Marshaller file within the JAR file and within it, write the fully qualified class name of the marshaller class implementation
3. Deploy the JAR file in the JBoss Data Grid Server by performing any of the following options:

   • Procedure 8.12. Option 1: Deploy the JAR through the deployment scanner.

     • Copy the JAR to the $JDG_HOME/standalone/deployments/ directory. The deployment scanner actively monitors this directory and will deploy the newly placed file.

   • Procedure 8.13. Option 2: Deploy the JAR through the CLI

     1. Connect to the desired instance with the CLI:

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

     2. Once connected execute the deploy command:

        deploy /path/to/artifact.jar

   • Procedure 8.14. Option 3: Deploy the JAR as a custom module

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

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

     2. The jar containing the Custom Marshaller must be defined as a module for the Server; to add this substitute the desired name of the module and the .jar name in the below command, adding additional dependencies as necessary for the Custom Marshaller:

        module add --name=$MODULE-NAME --resources=$JAR-NAME.jar --dependencies=org.infinispan

     3. In a different window add the newly added module as a dependency to the org.infinispan module by editing $JDG_HOME/modules/system/layers/base/org/infinispan/main/module.xml. In this file add the following entry:

        <dependencies>
          [...]
          <module name="$MODULE-NAME">
        </dependencies>

     4. Restart the JDG server.

Procedure 11.1. Download Hot Rod Java Client

1. Log into the Customer Portal at https://access.redhat.com.
2. Click the Downloads button near the top of the page.
3. In the Product Downloads page, click Red Hat JBoss Data Grid.
4. Select the appropriate JBoss Data Grid version from the Version: drop down menu.
5. Locate the Red Hat JBoss Data Grid ${VERSION} Hot Rod Java Client entry and click the corresponding Download link.

Procedure 11.2. Installing the Hot Rod C# Client

1. As an administrator, navigate to the location where the Hot Rod C# .msi file is downloaded. Run the .msi file to launch the windows installer and then click Next.
   

   Figure 11.1. Hot Rod C# Client Setup Welcome

2. Review the end-user license agreement. Select the I accept the terms in the License Agreement check box and then click Next.
   

   Figure 11.2. Hot Rod C# Client End-User License Agreement

3. To change the default directory, click Change... or click Next to install in the default directory.
   

   Figure 11.3. Hot Rod C# Client Destination Folder

4. Click Finish to complete the Hot Rod C# client installation.
   

   Figure 11.4. Hot Rod C# Client Setup Completion

Procedure 11.3. Installing the Hot Rod Node.js Client

1. Download the jboss-datagrid-<version>-nodejs-client.zip from the Red Hat Customer Portal.
2. Extract the downloaded archive.
3. Use npm to install the provided tarball, as seen in the following command:

   npm install /path/to/jboss-datagrid-7.0.0-nodejs-client/infinispan-0.2.0.Final-redhat-1.tgz