Embedding Data Grid in Java Applications

Procedure

1. Log in to the Red Hat customer portal.
2. Navigate to the Software Downloads for Data Grid.
3. Download the Red Hat Data Grid 8.5 Maven Repository.
4. Extract the archived Maven repository to your local file system.
5. Open the README.md file and follow the appropriate installation instructions.

Procedure

1. Open your project pom.xml for editing.
2. Define the version.infinispan property with the correct Data Grid version.

3. Include the infinispan-bom in a dependencyManagement section.

   The Bill Of Materials (BOM) controls dependency versions, which avoids version conflicts and means you do not need to set the version for each Data Grid artifact you add as a dependency to your project.

4. Save and close pom.xml.

Procedure

1. Initialize a CacheManager.

   Note

   You must always call the cacheManager.start() method to initialize a CacheManager before you can create caches. Default constructors do this for you but there are overloaded versions of the constructors that do not.

   Cache Managers are also heavyweight objects and Data Grid recommends instantiating only one instance per JVM.

2. Use the ConfigurationBuilder API to define cache configuration.

3. Obtain caches with getCache(), createCache(), or getOrCreateCache() methods.

   Data Grid recommends using the getOrCreateCache() method because it either creates a cache on all nodes or returns an existing cache.

4. If necessary use the PERMANENT flag for caches to survive restarts.
5. Stop the CacheManager by calling the cacheManager.stop() method to release JVM resources and gracefully shutdown any caches.

Procedure

1. Construct a GlobalConfigurationBuilder and enable security authorization with the security().authorization().enable() method.
2. Specify a role mapper with the principalRoleMapper() method.

3. If required, define custom role and permission mappings with the role() and permission() methods.

   GlobalConfigurationBuilder global = new GlobalConfigurationBuilder();
     global.security().authorization().enable()
             .principalRoleMapper(new ClusterRoleMapper())
             .role("myroleone").permission(AuthorizationPermission.ALL_WRITE)
             .role("myroletwo").permission(AuthorizationPermission.ALL_READ);

   Copy to Clipboard Toggle word wrap

4. Enable authorization for caches in the ConfigurationBuilder.

   • Add all roles from the global configuration.

     ConfigurationBuilder config = new ConfigurationBuilder();
     config.security().authorization().enable();

     Copy to Clipboard Toggle word wrap

   • Explicitly define roles for a cache so that Data Grid denies access for users who do not have the role.

     ConfigurationBuilder config = new ConfigurationBuilder();
     config.security().authorization().enable().role("myroleone");

     Copy to Clipboard Toggle word wrap

Procedure

1. Obtain the RolePermissionMapper instance.

2. Define new roles with the addRole() method.

   MutableRolePermissionMapper mapper = (MutableRolePermissionMapper) cacheManager.getCacheManagerConfiguration().security().authorization().rolePermissionMapper();
   mapper.addRole(Role.newRole("myroleone", true, AuthorizationPermission.ALL_WRITE, AuthorizationPermission.LISTEN));
   mapper.addRole(Role.newRole("myroletwo", true, AuthorizationPermission.READ, AuthorizationPermission.WRITE));

   Copy to Clipboard Toggle word wrap

Procedure

1. If necessary, retrieve the current Subject from the Data Grid context:

   Security.getSubject();

   Copy to Clipboard Toggle word wrap

2. Wrap method calls in a PrivilegedAction to execute them with the Subject.

   Security.doAs(mySubject, (PrivilegedAction<String>)() -> cache.put("key", "value"));

   Copy to Clipboard Toggle word wrap

Procedure

1. Open your Data Grid configuration for editing.

2. Specify the maximum number of entries for the ACL cache with the cache-size attribute.

   Entries in the ACL cache have a cardinality of caches * users. You should set the maximum number of entries to a value that can hold information for all your caches and users. For example, the default size of 1000 is appropriate for deployments with up to 100 caches and 10 users.

3. Set the timeout value, in milliseconds, with the cache-timeout attribute.

   If Data Grid does not access an entry in the ACL cache within the timeout period that entry is evicted. When the user subsequently attempts cache operations then Data Grid recalculates their cache permissions and adds an entry to the ACL cache.

   Important

   Specifying a value of 0 for either the cache-size or cache-timeout attribute disables the ACL cache. You should disable the ACL cache only if you disable authorization.

4. Save the changes to your configuration.

Procedure

1. Open your Data Grid configuration for editing.
2. Add the statistics="true" attribute or the .statistics(true) method.
3. Save and close your Data Grid configuration.

Procedure

1. Open your Data Grid configuration for editing.
2. Add the metrics element or object to the cache container.
3. Enable or disable gauges with the gauges attribute or field.
4. Enable or disable histograms with the histograms attribute or field.
5. Save and close your client configuration.

Procedure

1. Open your Data Grid configuration for editing.
2. Add the jmx element or object to the cache container and specify true as the value for the enabled attribute or field.
3. Add the domain attribute or field and specify the domain where JMX MBeans are exposed, if required.
4. Save and close your client configuration.

Procedure

1. Implement a script to poll the REST endpoint.

   The following example demonstrates how you can use a Python script to poll the site status every five seconds.

Procedure

1. Configure Data Grid metrics.

2. Configure alerting rules using the Prometheus metrics format.

   • For the site status, use 1 for online and 0 for offline.

   • For the expr filed, use the following format:
     vendor_cache_manager_default_cache_<cache name>_x_site_admin_<site name>_status.

     In the following example, Prometheus alerts you when the NYC site gets offline for cache named work or sessions.

     groups:
     - name: Cross Site Rules
       rules:
       - alert: Cache Work and Site NYC
         expr: vendor_cache_manager_default_cache_work_x_site_admin_nyc_status == 0
       - alert: Cache Sessions and Site NYC
         expr: vendor_cache_manager_default_cache_sessions_x_site_admin_nyc_status == 0

     Copy to Clipboard Toggle word wrap

     The following image shows an alert that the NYC site is offline for cache work.

     Figure 4.1. Prometheus Alert

     

     View larger image

     

Procedure

1. Create a new JGroups stack declaration in your infinispan.xml file.
2. Add the extends attribute and specify a JGroups stack to inherit properties from.
3. Use the stack.combine attribute to modify properties for protocols configured in the inherited stack.
4. Use the stack.position attribute to define the location for your custom stack.

5. Specify the stack name as the value for the stack attribute in the transport configuration.

   For example, you might evaluate using a Gossip router and symmetric encryption with the default TCP stack as follows:

   <infinispan>
     <jgroups>
       <!-- Creates a custom JGroups stack named "my-stack". -->
       <!-- Inherits properties from the default TCP stack. -->
       <stack name="my-stack" extends="tcp">
         <!-- Uses TCPGOSSIP as the discovery mechanism instead of MPING -->
         <TCPGOSSIP initial_hosts="${jgroups.tunnel.gossip_router_hosts:localhost[12001]}"
                stack.combine="REPLACE"
                stack.position="MPING" />
         <!-- Removes the FD_SOCK2 protocol from the stack. -->
         <FD_SOCK2 stack.combine="REMOVE"/>
         <!-- Modifies the timeout value for the VERIFY_SUSPECT2 protocol. -->
         <VERIFY_SUSPECT2 timeout="2000"/>
         <!-- Adds SYM_ENCRYPT to the stack after VERIFY_SUSPECT2. -->
         <SYM_ENCRYPT sym_algorithm="AES"
                      keystore_name="mykeystore.p12"
                      keystore_type="PKCS12"
                      store_password="changeit"
                      key_password="changeit"
                      alias="myKey"
                      stack.combine="INSERT_AFTER"
                      stack.position="VERIFY_SUSPECT2" />
       </stack>
     </jgroups>
     <cache-container name="default" statistics="true">
       <!-- Uses "my-stack" for cluster transport. -->
       <transport cluster="${infinispan.cluster.name}"
                  stack="my-stack"
                  node-name="${infinispan.node.name:}"/>
     </cache-container>
   </infinispan>

   Copy to Clipboard Toggle word wrap

6. Check Data Grid logs to ensure it uses the stack.

   [org.infinispan.CLUSTER] ISPN000078: Starting JGroups channel cluster with stack my-stack

   Copy to Clipboard Toggle word wrap

Procedure

1. Put custom JGroups stack files on the application classpath.

   Alternatively you can specify an absolute path when you declare the external stack file.

2. Reference the external stack file with the stack-file element.

   <infinispan>
     <jgroups>
        <!-- Creates a "prod-tcp" stack that references an external file. -->
        <stack-file name="prod-tcp" path="prod-jgroups-tcp.xml"/>
     </jgroups>
     <cache-container default-cache="replicatedCache">
       <!-- Use the "prod-tcp" stack for cluster transport. -->
       <transport stack="prod-tcp" />
       <replicated-cache name="replicatedCache"/>
     </cache-container>
     <!-- Cache configuration goes here. -->
   </infinispan>

   Copy to Clipboard Toggle word wrap

Procedure

1. Initialize the ClusteredLockManager interface from a Cache Manager. This interface is the entry point for defining, retrieving, and removing clustered locks.
2. Give a unique name for each clustered lock.
3. Acquire locks with the lock.tryLock(1, TimeUnit.SECONDS) method.

Procedure

1. Define the number of nodes in the cluster that store the state of clustered locks. The default value is -1, which replicates the value to all nodes.

2. Specify one of the following values for the cache reliability, which controls how clustered locks behave when clusters split into partitions or multiple nodes leave:

   • AVAILABLE: Nodes in any partition can concurrently operate on locks.
   • CONSISTENT: Only nodes that belong to the majority partition can operate on locks. This is the default value.

   • Programmatic configuration

     import org.infinispan.lock.configuration.ClusteredLockManagerConfiguration;
     import org.infinispan.lock.configuration.ClusteredLockManagerConfigurationBuilder;
     import org.infinispan.lock.configuration.Reliability;
     ...
     
     GlobalConfigurationBuilder global = GlobalConfigurationBuilder.defaultClusteredBuilder();
     
     final ClusteredLockManagerConfiguration config = global.addModule(ClusteredLockManagerConfigurationBuilder.class).numOwner(2).reliability(Reliability.AVAILABLE).create();
     
     DefaultCacheManager cm = new DefaultCacheManager(global.build());
     
     ClusteredLockManager clm1 = EmbeddedClusteredLockManagerFactory.from(cm);
     
     clm1.defineLock("lock");

     Copy to Clipboard Toggle word wrap

   • Declarative configuration

     <infinispan
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="urn:infinispan:config:15.0 https://infinispan.org/schemas/infinispan-config-15.0.xsd"
             xmlns="urn:infinispan:config:15.0">
     
         <cache-container default-cache="default">
             <transport/>
             <local-cache name="default">
                 <locking concurrency-level="100" acquire-timeout="1000"/>
             </local-cache>
             <clustered-locks xmlns="urn:infinispan:config:clustered-locks:15.0"
                              num-owners = "3"
                              reliability="AVAILABLE">
                 <clustered-lock name="lock1" />
                 <clustered-lock name="lock2" />
             </clustered-locks>
         </cache-container>
         <!-- Cache configuration goes here. -->
     </infinispan>

     Copy to Clipboard Toggle word wrap

1. The desired segments are grouped by which node is the primary owner of the given segment

2. A request is generated to send to each remote node that contains the intermediate and terminal operations including which segments it should process

   1. The terminal operation will be performed locally if necessary
   2. Each remote node will receive this request and run the operations and subsequently send the response back
3. The local node will then gather the local response and remote responses together performing any kind of reduction required by the operations themselves.
4. Final reduced response is then returned to the user

Procedure

1. Import the Data Grid dependency management to control the versions of runtime Maven dependencies.

   <dependency>
     <groupId>org.infinispan</groupId>
     <artifactId>infinispan-bom</artifactId>
     <version>${version.infinispan.bom}</version>
     <type>pom</type>
     <scope>import</scope>
   </dependency>

   Copy to Clipboard Toggle word wrap

   You must define the value for ${version.infinispan.bom}`in the `<properties> section of the pom.xml file.

2. Declare the required Data Grid dependencies as provided.

   pom.xml

   <dependencies>
     <dependency>
       <groupId>org.infinispan</groupId>
       <artifactId>infinispan-core</artifactId>
       <scope>provided</scope>
     </dependency>
   </dependencies>

   Copy to Clipboard Toggle word wrap

Procedure

1. Connect to the Red Hat JBoss EAP management CLI.

   $ jboss-cli.sh --connect

   Copy to Clipboard Toggle word wrap

2. Create a cache container.

   /subsystem=infinispan/cache-container=exampleCacheContainer:add(statistics-enabled=true)

   Copy to Clipboard Toggle word wrap

   This creates a cache container called exampleCacheContainer with statistics enabled.

3. Add a cache to the cache container.

   /subsystem=infinispan/cache-container=exampleCacheContainer/local-cache=exampleCache:add(statistics-enabled=true)

   Copy to Clipboard Toggle word wrap

   This creates a local cache named exampleCache in the exampleCacheContainer cache container with statistics enabled.

Procedure

1. You can lookup Data Grid caches in your applications like this:

   @Resource(lookup = "java:jboss/infinispan/cache/exampleCacheContainer/exampleCache")
   private Cache<String, String> ispnCache;

   Copy to Clipboard Toggle word wrap

   This defines a Cache called ispnCache.

2. You can put, get and remove entries from the cache as follows:

   Get value of a key

   String value = ispnCache.get(key);

   Copy to Clipboard Toggle word wrap

   This retrieves the value of the key in the cache. If the key is not found, null is returned.

   Put value in a key

   String oldValue = ispnCache.put(key,value);

   Copy to Clipboard Toggle word wrap

   This defines a new key if it does not already exist and associates the value passed. If the key already exists, the original value is replaced.

   Remove a key

   String value = ispnCache.remove(key);

   Copy to Clipboard Toggle word wrap

   This removes the key from the cache.

Procedure

1. Create a cache qualifier annotation.

   ...
   import jakarta.inject.Qualifier;
   
   @Qualifier
   @Target({ElementType.FIELD, ElementType.PARAMETER, ElementType.METHOD})
   @Retention(RetentionPolicy.RUNTIME)
   @Documented
   public @interface GreetingCache { 

   1

   
   }

   Copy to Clipboard Toggle word wrap

   1

   Creates a @GreetingCache qualifier.

2. Add a producer method that defines the cache configuration.

   ...
   import org.infinispan.configuration.cache.Configuration;
   import org.infinispan.configuration.cache.ConfigurationBuilder;
   import org.infinispan.cdi.ConfigureCache;
   import jakarta.transaction.inject.Produces;
   
   public class Config {
   
       @ConfigureCache("mygreetingcache") 

   1

   
       @GreetingCache 

   2

   
       @Produces
       public Configuration greetingCacheConfiguration() {
           return new ConfigurationBuilder()
                       .memory()
                           .size(1000)
                       .build();
       }
   }

   Copy to Clipboard Toggle word wrap

   1

   Names the cache to inject.

   2

   Adds the cache qualifier.

3. Add a producer method that creates a clustered Cache Manager, if required

   ...
   package org.infinispan.configuration.global.GlobalConfigurationBuilder;
   
   public class Config {
   
       @GreetingCache 

   1

   
       @Produces
       @ApplicationScoped 

   2

   
       public EmbeddedCacheManager defaultClusteredCacheManager() { 

   3

   
         return new DefaultCacheManager(
           new GlobalConfigurationBuilder().transport().defaultTransport().build();
      }
   }

   Copy to Clipboard Toggle word wrap

   1

   Adds the cache qualifier.

   2

   Creates the bean once for the application. Producers that create Cache Managers should always include the @ApplicationScoped annotation to avoid creating multiple Cache Managers.

   3

   Creates a new DefaultCacheManager instance that is bound to the @GreetingCache qualifier.

   Note

   Cache managers are heavy weight objects. Having more than one Cache Manager running in your application can degrade performance. When injecting multiple caches, either add the qualifier of each cache to the Cache Manager producer method or do not add any qualifier.

4. Add the @GreetingCache qualifier to your cache injection point.

   ...
   import jakarta.inject.Inject;
   
   public class GreetingService {
   
       @Inject @GreetingCache
       private Cache<String, String> cache;
   
       public String greet(String user) {
           String cachedValue = cache.get(user);
           if (cachedValue == null) {
               cachedValue = "Hello " + user;
               cache.put(user, cachedValue);
           }
           return cachedValue;
       }
   }

   Copy to Clipboard Toggle word wrap

Procedure

1. Create a cache qualifier annotation.

   @Remote("mygreetingcache") 

   1

   
   @Qualifier
   @Target({ElementType.FIELD, ElementType.PARAMETER, ElementType.METHOD})
   @Retention(RetentionPolicy.RUNTIME)
   @Documented
   public @interface RemoteGreetingCache { 

   2

   
   }

   Copy to Clipboard Toggle word wrap

   1

   names the cache to inject.

   2

   creates a @RemoteGreetingCache qualifier.

2. Add the @RemoteGreetingCache qualifier to your cache injection point.

   public class GreetingService {
   
       @Inject @RemoteGreetingCache
       private RemoteCache<String, String> cache;
   
       public String greet(String user) {
           String cachedValue = cache.get(user);
           if (cachedValue == null) {
               cachedValue = "Hello " + user;
               cache.put(user, cachedValue);
           }
           return cachedValue;
       }
   }

   Copy to Clipboard Toggle word wrap