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();
   

   Copy to Clipboard Toggle word wrap
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();
      

      Copy to Clipboard Toggle word wrap
      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";
      

      Copy to Clipboard Toggle word wrap
      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);
      

      Copy to Clipboard Toggle word wrap
      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);
      

      Copy to Clipboard Toggle word wrap
      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();
   

   Copy to Clipboard Toggle word wrap
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();
   

   Copy to Clipboard Toggle word wrap
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);
   

   Copy to Clipboard Toggle word wrap
4. Get default cache with custom configuration changes:

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

   Copy to Clipboard Toggle word wrap

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");
   

   Copy to Clipboard Toggle word wrap
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();
   

   Copy to Clipboard Toggle word wrap
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);
   

   Copy to Clipboard Toggle word wrap
4. Get a default cache with custom configuration changes:

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

   Copy to Clipboard Toggle word wrap

Procedure 6.1. Register the Advanced Externalizer

1. Add the global element to the infinispan element:

   <infinispan>
     <global />
   </infinispan>
   

   Copy to Clipboard Toggle word wrap
2. Add the serialization element to the global element as follows:

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

   Copy to Clipboard Toggle word wrap
3. Add the advancedExternalizers element to add information about the new advanced externalizer as follows:

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

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap
   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>
   

   Copy to Clipboard Toggle word wrap
2. Add the serialization element to the global element as follows:

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

   Copy to Clipboard Toggle word wrap
3. Add the advancedExternalizer element to add information about the new advanced externalizer as follows:

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

   Copy to Clipboard Toggle word wrap
4. Define the externalizer ID using the id attribute as follows:

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

   Copy to Clipboard Toggle word wrap
   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>
   

   Copy to Clipboard Toggle word wrap
   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>
   

   Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap

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
      

      Copy to Clipboard Toggle word wrap
   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
      

      Copy to Clipboard Toggle word wrap

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
   

   Copy to Clipboard Toggle word wrap

   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" />
   

   Copy to Clipboard Toggle word wrap

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" />
   

   Copy to Clipboard Toggle word wrap

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}" />
   

   Copy to Clipboard Toggle word wrap

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}" />
   

   Copy to Clipboard Toggle word wrap

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}"/>
   

   Copy to Clipboard Toggle word wrap

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}" />
   

   Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap