Developer Guide

Procedure 5.1. Steps for Programmatic Configuration in JBoss Data Grid

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. The following is an example of how to create a CacheManager:

   EmbeddedCacheManager manager = new DefaultCacheManager("my-config-file.xml");
   Cache defaultCache = manager.getCache();
   

2. Create a new synchronously replicated cache programmatically.
   1. Create a new configuration object instance using the ConfigurationBuilder helper object:

      Configuration c = new ConfigurationBuilder().clustering().cacheMode(CacheMode.REPL_SYNC)
      .build();
      

      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. Set the cache mode to synchronous replication:

      String newCacheName = "repl";
      

      In the second line of the configuration, a new variable (of type String) is created and assigned the value repl.
   3. Define or register the configuration with a manager:

      manager.defineConfiguration(newCacheName, c);
      

      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.

   4. Cache<String, String> cache = manager.getCache(newCacheName);
      

      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 5.2. Customize the Default Cache

1. Read an instance of a default Configuration object to get the default configuration:

   EmbeddedCacheManager manager = new DefaultCacheManager("infinispan-config-file.xml");
   Configuration dcc = cacheManager.getDefaultCacheConfiguration();
   

2. Use the ConfigurationBuilder to construct and modify the cache mode and L1 cache lifespan on a new configuration object:

   Configuration c = new ConfigurationBuilder().read(dcc).clustering()
   .cacheMode(CacheMode.DIST_SYNC).l1().lifespan(60000L).enable()
   .build();
   

3. Register/define your cache configuration with a cache manager, where cacheName is name of cache specified in infinispan-config-file.xml:

   manager.defineConfiguration(newCacheName, c);
   

4. Get default cache with custom configuration changes:

   Cache<String, String> cache = manager.getCache(newCacheName);
   

Procedure 5.3. Create a Customized Cache Using a Non-Default Named Cache

1. Read the replicatedCache to get the default configuration:

   EmbeddedCacheManager manager = new DefaultCacheManager("infinispan-config-file.xml");
   Configuration rc = cacheManager.getCacheConfiguration("replicatedCache");
   

2. Use the ConfigurationBuilder to construct and modify the desired configuration on a new configuration object:

   Configuration c = new ConfigurationBuilder().read(rc).clustering()
   .cacheMode(CacheMode.DIST_SYNC).l1().lifespan(60000L).enable()
   .build();
   

3. Register/define your cache configuration with a cache manager where newCacheName is the name of cache specified in infinispan-config-file.xml

   manager.defineConfiguration(newCacheName, c);
   

4. Get a default cache with custom configuration changes:

   Cache<String, String> cache = manager.getCache(newCacheName);
   

Procedure 6.1. Register the Advanced Externalizer

1. Add the global element to the infinispan element:

   <infinispan>
     <global />
   </infinispan>
   

2. Add the serialization element to the global element as follows:

   <infinispan>
     <global>
       <serialization />
     </global>
   </infinispan>
   

3. Add the advancedExternalizers element to add information about the new advanced externalizer as follows:

   <infinispan>
     <global>
       <serialization>
         <advancedExternalizers />
       </serialization>
     </global>
   </infinispan>
   

4. Define the externalizer class using the externalizerClass attribute as follows:

   <infinispan>
       <global>
           <serialization>
               <advancedExternalizers>            
                   <advancedExternalizer externalizerClass="org.infinispan.marshall.AdvancedExternalizerTest$IdViaAnnotationObj$Externalizer"/>
               </advancedExternalizers>
           </serialization>
       </global>
   </infinispan>
   

   Replace the $IdViaAnnotationObj and $AdvancedExternalizer values as required.

Procedure 6.2. Customizing the Externalizer ID (Declaratively)

1. Add the global element to the infinispan element:

   <infinispan>
     <global />
   </infinispan>
   

2. Add the serialization element to the global element as follows:

   <infinispan>
     <global>
       <serialization />
     </global>
   </infinispan>
   

3. Add the advancedExternalizer element to add information about the new advanced externalizer as follows:

   <infinispan>
     <global>
       <serialization>
         <advancedExternalizer />
       </serialization>
     </global>
   </infinispan>
   

4. Define the externalizer ID using the id attribute as follows:

   <infinispan>
     <global>
       <serialization>
         <advancedExternalizers>
          <advancedExternalizer id="$ID" />
         </advancedExternalizers>
       </serialization>
     </global>
   </infinispan>
   

   Ensure that the selected ID is not from the range of IDs reserved for other modules.
5. Define the externalizer class using the externalizerClass attribute as follows:

   <infinispan>
     <global>
       <serialization>
         <advancedExternalizers>
          <advancedExternalizer id="$ID" externalizerClass="org.infinispan.marshall.AdvancedExternalizerTest$IdViaConfigObj$Externalizer"/>
          </advancedExternalizers>
       </serialization>    
     </global>
   </infinispan>
   

   Replace the $IdViaAnnotationObj and $AdvancedExternalizer values as required.

Procedure 9.1. Configuring REST Connectors for Remote Client-Server Mode

1. The virtual-server Parameter

   The virtual-server parameter specifies the virtual server used by the REST connector. The default value for this parameter is default-host. This is an optional parameter.

   <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
      <rest-connector virtual-server="default-host" />
   </subsystem>
   

2. The cache-container Parameter

   The cache-container parameter names the cache container used by the REST connector. This is a mandatory parameter.

   <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
      <rest-connector virtual-server="default-host"
                    cache-container="local" />
   </subsystem>
   

3. The context-path Parameter

   The context-path parameter specifies the context path for the REST connector. The default value for this parameter is an empty string (""). This is an optional parameter.

   <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
      <rest-connector virtual-server="default-host"
                    cache-container="local"
                    context-path="${CONTEXT_PATH}" />
   </subsystem>
   

4. The security-domain Parameter

   The security-domain parameter specifies that the specified domain, declared in the security subsystem, should be used to authenticate access to the REST endpoint. This is an optional parameter. If this parameter is omitted, no authentication is performed.

   <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
      <rest-connector virtual-server="default-host"
                    cache-container="local"
                    context-path="${CONTEXT_PATH}"
                    security-domain="${SECURITY_DOMAIN}" />
   </subsystem>
   

5. The auth-method Parameter

   The auth-method parameter specifies the method used to retrieve credentials for the end point. The default value for this parameter is BASIC. Supported alternate values include DIGEST, CLIENT-CERT and SPNEGO. This is an optional parameter.

   <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
      <rest-connector virtual-server="default-host"
                    cache-container="local"
                    context-path="${CONTEXT_PATH}"
                    security-domain="${SECURITY_DOMAIN}"
                    auth-method="${METHOD}"  />
   </subsystem>
   

6. The security-mode Parameter

   The security-mode parameter specifies whether authentication is required only for write operations (such as PUT, POST and DELETE) or for read operations (such as GET and HEAD) as well. Valid values for this parameter are WRITE for authenticating write operations only, or READ_WRITE to authenticate read and write operations. The default value for this parameter is READ_WRITE.

   <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
      <rest-connector virtual-server="default-host"
                    cache-container="local"
                    context-path="${CONTEXT_PATH}"
                    security-domain="${SECURITY_DOMAIN}"
                    auth-method="${METHOD}" 
                    security-mode="${MODE}" /> 
   </subsystem>
   

Procedure 9.2. Enable Security for the REST Endpoint

1. Specify Security Parameters

   Ensure that the rest endpoint specifies a valid value for the security-domain and auth-method parameters. Recommended settings for these parameters are as follows:

   <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
               <rest-connector virtual-server="default-host" 
                               cache-container="local" 
                               security-domain="other" 
                               auth-method="BASIC"/>
   </subsystem>
   

2. Check Security Domain Declaration

   Ensure that the security subsystem contains the corresponding security-domain declaration. For details about setting up security-domain declarations, see the WildFly 7 or JBoss Enterprise Application Platform 6 documentation.

3. Add an Application User

   Run the relevant script and enter the configuration settings to add an application user.
   1. Run the adduser.sh script (located in $JDG_HOME/bin).
      • On a Windows system, run the adduser.bat file (located in $JDG_HOME/bin) instead.
   2. When prompted about the type of user to add, select Application User (application-users.properties) by entering b.
   3. Accept the default value for realm (ApplicationRealm) by pressing the return key.
   4. Specify a username and password.
   5. When prompted for a role for the created user, enter REST.
   6. Ensure the username and application realm information is correct when prompted and enter "yes" to continue.

4. Verify the Created Application User

   Ensure that the created application user is correctly configured.
   1. Check the configuration listed in the application-users.properties file (located in $JDG_HOME/standalone/configuration/). The following is an example of what the correct configuration looks like in this file:

      user1=2dc3eacfed8cf95a4a31159167b936fc
      

   2. Check the configuration listed in the application-roles.properties file (located in $JDG_HOME/standalone/configuration/). The following is an example of what the correct configuration looks like in this file:

      user1=REST
      

5. Test the Server

   Start the server and enter the following link in a browser window to access the REST endpoint:

   http://localhost:8080/rest/namedCache
   

   Note

   If testing using a GET request, a 405 response code is expected and indicates that the server was successfully authenticated.

Procedure 10.1. Configuring the Memcached Connector in Remote Client-Server Mode

1. The socket-binding Parameter

   The socket-binding parameter specifies the socket binding port used by the memcached connector. This is a mandatory parameter.

   <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
   <memcached-connector socket-binding="memcached" />
   

2. The cache-container Parameter

   The cache-container parameter names the cache container used by the memcached connector. This is a mandatory parameter.

   <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
   <memcached-connector socket-binding="memcached" 
                        cache-container="local" />
   

3. The worker-threads Parameter

   The worker-threads parameter specifies the number of worker threads available for the memcached connector. The default value for this parameter is 160. This is an optional parameter.

   <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
   <memcached-connector socket-binding="memcached" 
                        cache-container="local" 
                        worker-threads="${VALUE}" />
   

4. The idle-timeout Parameter

   The idle-timeout parameter specifies the time (in milliseconds) the connector can remain idle before the connection times out. The default value for this parameter is -1, which means that no timeout period is set. This is an optional parameter.

   <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
   <memcached-connector socket-binding="memcached" 
                        cache-container="local" 
                        worker-threads="${VALUE}" 
                        idle-timeout="${VALUE}" />
   

5. The tcp-nodelay Parameter

   The tcp-nodelay parameter specifies whether TCP packets will be delayed and sent out in batches. Valid values for this parameter are true and false. The default value for this parameter is true. This is an optional parameter.

   <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
   <memcached-connector socket-binding="memcached" 
                        cache-container="local" 
                        worker-threads="${VALUE}" 
                        idle-timeout="{VALUE}"
                        tcp-nodelay="{TRUE/FALSE}"/>
   

6. The send-buffer-size Parameter

   The send-buffer-size parameter indicates the size of the send buffer for the memcached connector. The default value for this parameter is the size of the TCP stack buffer. This is an optional parameter.

   <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
   <memcached-connector socket-binding="memcached" 
                        cache-container="local" 
                        worker-threads="${VALUE}" 
                        idle-timeout="{VALUE}"
                        tcp-nodelay="{TRUE/FALSE}" 
                        send-buffer-size="{VALUE}" />
   

7. The receive-buffer-size Parameter

   The receive-buffer-size parameter indicates the size of the receive buffer for the memcached connector. The default value for this parameter is the size of the TCP stack buffer. This is an optional parameter.

   <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
   <memcached-connector socket-binding="memcached" 
                        cache-container="local" 
                        worker-threads="${VALUE}" 
                        idle-timeout="{VALUE}"
                        tcp-nodelay="{TRUE/FALSE}" 
                        send-buffer-size="{VALUE}" 
                        receive-buffer-size="${VALUE}" />
   </subsystem>
   

Procedure 11.1. Configuring Hot Rod Connectors for Remote Client-Server Mode

1. The hotrod-connector Element

   The hotrod-connector element defines the configuration elements for use with Hot Rod.

   1. The socket-binding Parameter

      The socket-binding parameter specifies the socket binding port used by the Hot Rod connector. This is a mandatory parameter.

      <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
            <hotrod-connector socket-binding="hotrod" />
      

   2. The cache-container Parameter

      The cache-container parameter names the cache container used by the Hot Rod connector. This is a mandatory parameter.

      <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
            <hotrod-connector socket-binding="hotrod"
                              cache-container="local" />
      

   3. The worker-threads Parameter

      The worker-threads parameter specifies the number of worker threads available for the Hot Rod connector. The default value for this parameter is the number of cores available multiplied by two. This is an optional parameter.

      <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
            <hotrod-connector socket-binding="hotrod"
                              cache-container="local" 
                              worker-threads="${VALUE}" />
      

   4. The idle-timeout Parameter

      The idle-timeout parameter specifies the time (in milliseconds) the connector can remain idle before the connection times out. The default value for this parameter is -1, which means that no timeout period is set. This is an optional parameter.

      <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
            <hotrod-connector socket-binding="hotrod"
                              cache-container="local" 
                              worker-threads="${VALUE}" 
                              idle-timeout="${VALUE}"/>
      

   5. The tcp-nodelay Parameter

      The tcp-nodelay parameter specifies whether TCP packets will be delayed and sent out in batches. Valid values for this parameter are true and false. The default value for this parameter is true. This is an optional parameter.

      <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
            <hotrod-connector socket-binding="hotrod"
                              cache-container="local" 
                              worker-threads="${VALUE}" 
                              idle-timeout="${VALUE}"
                              tcp-nodelay="${TRUE/FALSE}" />
      

   6. The send-buffer-size Parameter

      The send-buffer-size parameter indicates the size of the send buffer for the Hot Rod connector. The default value for this parameter is the size of the TCP stack buffer. This is an optional parameter.

      <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
            <hotrod-connector socket-binding="hotrod"
                              cache-container="local" 
                              worker-threads="${VALUE}" 
                              idle-timeout="${VALUE}"
                              tcp-nodelay="${TRUE/FALSE}" 
                              send-buffer-size="${VALUE}"/>
      

   7. The receive-buffer-size Parameter

      The receive-buffer-size parameter indicates the size of the receive buffer for the Hot Rod connector. The default value for this parameter is the size of the TCP stack buffer. This is an optional parameter.

      subsystem xmlns="urn:infinispan:server:endpoint:6.0">
            <hotrod-connector socket-binding="hotrod"
                              cache-container="local" 
                              worker-threads="${VALUE}" 
                              idle-timeout="${VALUE}"
                              tcp-nodelay="${TRUE/FALSE}" 
                              send-buffer-size="${VALUE}"
                              receive-buffer-size="${VALUE}"   />
      

2. The topology-state-transfer Element

   The topology-state-transfer element specifies the topology state transfer configurations for the Hot Rod connector. This element can only occur once within a hotrod-connector element.

   1. The lock-timeout Parameter

      The lock-timeout parameter specifies the time (in milliseconds) after which the operation attempting to obtain a lock times out. The default value for this parameter is 10 seconds. This is an optional parameter.

      <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
            <hotrod-connector socket-binding="hotrod"
                              cache-container="local" 
                              worker-threads="${VALUE}" 
                              idle-timeout="${VALUE}"
                              tcp-nodelay="${TRUE/FALSE}" 
                              send-buffer-size="${VALUE}"
                              receive-buffer-size="${VALUE}"   />
            <topology-state-transfer lock-timeout"="${MILLISECONDS}" />
      

   2. The replication-timeout Parameter

      The replication-timeout parameter specifies the time (in milliseconds) after which the replication operation times out. The default value for this parameter is 10 seconds. This is an optional parameter.

      <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
            <hotrod-connector socket-binding="hotrod"
                              cache-container="local" 
                              worker-threads="${VALUE}" 
                              idle-timeout="${VALUE}"
                              tcp-nodelay="${TRUE/FALSE}" 
                              send-buffer-size="${VALUE}"
                              receive-buffer-size="${VALUE}"   />
            <topology-state-transfer lock-timeout"="${MILLISECONDS}" 
                                     replication-timeout="${MILLISECONDS}" />
      

   3. The update-timeout Parameter

      The update-timeout parameter specifies the time (in milliseconds) after which the update operation times out. The default value for this parameter is 30 seconds. This is an optional parameter.

      <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
            <hotrod-connector socket-binding="hotrod"
                              cache-container="local" 
                              worker-threads="${VALUE}" 
                              idle-timeout="${VALUE}"
                              tcp-nodelay="${TRUE/FALSE}" 
                              send-buffer-size="${VALUE}"
                              receive-buffer-size="${VALUE}"   />
            <topology-state-transfer lock-timeout"="${MILLISECONDS}" 
                                     replication-timeout="${MILLISECONDS}" 
                                     update-timeout="${MILLISECONDS}"/>
      

   4. The external-host Parameter

      The external-host parameter specifies the hostname sent by the Hot Rod server to clients listed in the topology information. The default value for this parameter is the host address. This is an optional parameter.

      <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
            <hotrod-connector socket-binding="hotrod"
                              cache-container="local" 
                              worker-threads="${VALUE}" 
                              idle-timeout="${VALUE}"
                              tcp-nodelay="${TRUE/FALSE}" 
                              send-buffer-size="${VALUE}"
                              receive-buffer-size="${VALUE}"   />
            <topology-state-transfer lock-timeout"="${MILLISECONDS}" 
                                     replication-timeout="${MILLISECONDS}" 
                                     update-timeout="${MILLISECONDS}" 
                                     external-host="${HOSTNAME}" />
      

   5. The external-port Parameter

      The external-port parameter specifies the port sent by the Hot Rod server to clients listed in the topology information. The default value for this parameter is the configured port. This is an optional parameter.

      <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
            <hotrod-connector socket-binding="hotrod"
                              cache-container="local" 
                              worker-threads="${VALUE}" 
                              idle-timeout="${VALUE}"
                              tcp-nodelay="${TRUE/FALSE}" 
                              send-buffer-size="${VALUE}"
                              receive-buffer-size="${VALUE}"   />
            <topology-state-transfer lock-timeout"="${MILLISECONDS}" 
                                     replication-timeout="${MILLISECONDS}" 
                                     update-timeout="${MILLISECONDS}" 
                                     external-host="${HOSTNAME}" 
                                     external-port="${PORT}" />
      

   6. The lazy-retrieval Parameter

      The lazy-retrieval parameter indicates whether the Hot Rod connector will carry out retrieval operations lazily. The default value for this parameter is true. This is an optional parameter.

      <subsystem xmlns="urn:infinispan:server:endpoint:6.0">
      	<hotrod-connector socket-binding="hotrod" 
      			  cache-container="local" 
      			  worker-threads="${VALUE}" 
      			  idle-timeout="${VALUE}"
      			  tcp-nodelay="${TRUE/FALSE}"
      			  send-buffer-size="${VALUE}"
      			  receive-buffer-size="${VALUE}" />
      	<topology-state-transfer lock-timeout"="${MILLISECONDS}"
      				 replication-timeout="${MILLISECONDS}"
      				 update-timeout="${MILLISECONDS}"
      				 external-host="${HOSTNAME}"
      				 external-port="${PORT}"
      				 lazy-retrieval="${TRUE/FALSE}" /> 
      </subsystem>
      

Procedure 11.2. Secure Hot Rod Using SSL/TLS

1. Generate a Keystore

   Create a Java Keystore using the keytool application distributed with the JDK and add your certificate to it. The certificate can be either self signed, or obtained from a trusted CA depending on your security policy.

2. Place the Keystore in the Configuration Directory

   Put the keystore in the ~/JDG_HOME/standalone/configuration directory with the standalone-hotrod-ssl.xml file from the ~/JDG_HOME/docs/examples/configs directory.

3. Declare an SSL Server Identity

   Declare an SSL server identity within a security realm in the management section of the configuration file. The SSL server identity must specify the path to a keystore and its secret key.

   <server-identities>
     <ssl protocol="...">
       <keystore path="..." relative-to="..." keystore-password="..." alias="..." key-password="..." />
     </ssl>
     <secret value="..." />
   </server-identities>
   

4. Add the Security Element

   Add the security element to the Hot Rod connector as follows:

   <hotrod-connector socket-binding="hotrod" cache-container="local">
       <security ssl="true" security-realm="ApplicationRealm" require-ssl-client-auth="false" />
   </hotrod-connector>
   

   1. Server Authentication of Certificate

      If you require the server to perform authentication of the client certificate, create a truststore that contains the valid client certificates and set the require-ssl-client-auth attribute to true.

5. Start the Server

   Start the server using the following:

   bin/standalone.sh -c standalone-hotrod-ssl.xml

   This will start a server with a Hot Rod endpoint on port 11222. This endpoint will only accept SSL connections.

1. Declare a cache field in Mapper.
2. Annotate the cache field Mapper with @org.infinispan.cdi.Input.
3. Annotate with mandatory @Inject annotation.