Administration and Configuration Guide

Procedure 2.1. Configure a New RemoteCacheManager

import org.infinispan.client.hotrod.configuration.Configuration;
import org.infinispan.client.hotrod.configuration.ConfigurationBuilder;

Configuration conf = new 
ConfigurationBuilder().addServer().host("localhost").port(11222).build();
RemoteCacheManager manager = new RemoteCacheManager(conf);
RemoteCache defaultCache = manager.getCache();

import org.infinispan.client.hotrod.configuration.Configuration;
import org.infinispan.client.hotrod.configuration.ConfigurationBuilder;

Configuration conf = new 
ConfigurationBuilder().addServer().host("localhost").port(11222).build();
RemoteCacheManager manager = new RemoteCacheManager(conf);
RemoteCache defaultCache = manager.getCache();

1. Use the ConfigurationBuilder() constructor to create a new configuration builder. The .addServer() method adds a remote server, configured via the .host(<hostname|ip>) and .port(<port>) properties.
2. Create a new RemoteCacheManager using the supplied configuration.
3. Retrieve the default cache from the remote server.

Procedure 2.2. Create a New Embedded Cache Manager

1. Create a configuration XML file. For example, create the my-config-file.xml file on the classpath (in the resources/ folder) and add the configuration information in this file.
2. Use the following programmatic configuration to create a cache manager using the configuration file:

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

   Copy to Clipboard Toggle word wrap

Procedure 2.3. Use CDI to Create a New EmbeddedCacheManager

1. Specify a default configuration:

   public class Config
      @Produces
      public EmbeddedCacheManager defaultCacheManager() {
         ConfigurationBuilder builder = new ConfigurationBuilder();          
         Configuration configuration = builder.eviction().strategy(EvictionStrategy.LRU).maxEntries(100).build();
         return new DefaultCacheManager(configuration);
      }
   }

   Copy to Clipboard Toggle word wrap
2. Inject the default cache manager.

   <!-- Additional configuration information here -->
   @Inject
   EmbeddedCacheManager cacheManager;
   <!-- Additional configuration information here -->

   Copy to Clipboard Toggle word wrap

Procedure 3.1. Initialize Eviction

1. Add the Eviction Tag

   Add the <eviction> tag to your project's <cache> tags as follows:

   <eviction />

   Copy to Clipboard Toggle word wrap

2. Set the Eviction Strategy

   Set the strategy value to set the eviction strategy employed. Possible values are LRU, UNORDERED and LIRS (or NONE if no eviction is required). The following is an example of this step:

   <eviction strategy="LRU" />

   Copy to Clipboard Toggle word wrap

3. Set the Maximum Entries

   Set the maximum number of entries allowed in memory. The default value is -1 for unlimited entries.
   1. In Library mode, set the maxEntries parameter as follows:

      <eviction strategy="LRU" maxEntries="200" />

      Copy to Clipboard Toggle word wrap
   2. In Remote Client Server mode, set the max-entries as follows:

      <eviction strategy="LRU" max-entries="200" />

      Copy to Clipboard Toggle word wrap

Procedure 5.1. Configure the Root Logger

1. Set the level Property

   The level property sets the maximum level of log message that the root logger records.

   <subsystem xmlns="urn:jboss:domain:logging:1.4">
      <root-logger>
         <level name="INFO"/>

   Copy to Clipboard Toggle word wrap

2. List handlers

   handlers is a list of log handlers that are used by the root logger.

   <subsystem xmlns="urn:jboss:domain:logging:1.4">
        <root-logger>
           <level name="INFO"/>
           <handlers>
              <handler name="CONSOLE"/>
              <handler name="FILE"/>
           </handlers>
        </root-logger>
     </subsystem>

   Copy to Clipboard Toggle word wrap

Procedure 5.2. Configure a Log Category

<subsystem xmlns="urn:jboss:domain:logging:1.4">
   <logger category="com.company.accounts.rec" use-parent-handlers="true">
      <level name="WARN"/>
      <handlers>
         <handler name="accounts-rec"/>
      </handlers>
   </logger>
</subsystem>

<subsystem xmlns="urn:jboss:domain:logging:1.4">
   <logger category="com.company.accounts.rec" use-parent-handlers="true">
      <level name="WARN"/>
      <handlers>
         <handler name="accounts-rec"/>
      </handlers>
   </logger>
</subsystem>

1. Use the category property to specify the log category from which log messages will be captured.
   The use-parent-handlers is set to "true" by default. When set to "true", this category will use the log handlers of the root logger in addition to any other assigned handlers.
2. Use the level property to set the maximum level of log message that the log category records.
3. The handlers element contains a list of log handlers.

Procedure 5.3. Configure the Console Log Handler

<subsystem xmlns="urn:jboss:domain:logging:1.4">
   <console-handler name="CONSOLE" autoflush="true">
      <level name="INFO"/>
      <encoding value="UTF-8"/>
      <target value="System.out"/>
      <filter-spec value="not(match(&quot;JBAS.*&quot;))"/>
      <formatter>
         <pattern-formatter pattern="%K{level}%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
      </formatter>
   </console-handler>
</subsystem>

<subsystem xmlns="urn:jboss:domain:logging:1.4">
   <console-handler name="CONSOLE" autoflush="true">
      <level name="INFO"/>
      <encoding value="UTF-8"/>
      <target value="System.out"/>
      <filter-spec value="not(match(&quot;JBAS.*&quot;))"/>
      <formatter>
         <pattern-formatter pattern="%K{level}%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
      </formatter>
   </console-handler>
</subsystem>

1. Add the Log Handler Identifier Information

   The name property sets the unique identifier for this log handler.
   When autoflush is set to "true" the log messages will be sent to the handler's target immediately upon request.

2. Set the level Property

   The level property sets the maximum level of log messages recorded.

3. Set the encoding Output

   Use encoding to set the character encoding scheme to be used for the output.

4. Define the target Value

   The target property defines the system output stream where the output of the log handler goes. This can be System.err for the system error stream, or System.out for the standard out stream.

5. Define the filter-spec Property

   The filter-spec property is an expression value that defines a filter. The example provided defines a filter that does not match a pattern: not(match("JBAS.*")).

6. Specify the formatter

   Use formatter to list the log formatter used by the log handler.

Procedure 5.4. Configure the File Log Handler

<file-handler name="accounts-rec-trail" autoflush="true">
    <level name="INFO"/>
    <encoding value="UTF-8"/>
    <file relative-to="jboss.server.log.dir" path="accounts-rec-trail.log"/>
    <formatter>
        <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
    </formatter>
    <append value="true"/>
</file-handler>

<file-handler name="accounts-rec-trail" autoflush="true">
    <level name="INFO"/>
    <encoding value="UTF-8"/>
    <file relative-to="jboss.server.log.dir" path="accounts-rec-trail.log"/>
    <formatter>
        <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
    </formatter>
    <append value="true"/>
</file-handler>

1. Add the File Log Handler Identifier Information

   The name property sets the unique identifier for this log handler.
   When autoflush is set to "true" the log messages will be sent to the handler's target immediately upon request.

2. Set the level Property

   The level property sets the maximum level of log message that the root logger records.

3. Set the encoding Output

   Use encoding to set the character encoding scheme to be used for the output.

4. Set the file Object

   The file object represents the file where the output of this log handler is written to. It has two configuration properties: relative-to and path.
   The relative-to property is the directory where the log file is written to. JBoss Enterprise Application Platform 6 file path variables can be specified here. The jboss.server.log.dir variable points to the log/ directory of the server.
   The path property is the name of the file where the log messages will be written. It is a relative path name that is appended to the value of the relative-to property to determine the complete path.

5. Specify the formatter

   Use formatter to list the log formatter used by the log handler.

6. Set the append Property

   When the append property is set to "true", all messages written by this handler will be appended to an existing file. If set to "false" a new file will be created each time the application server launches. Changes to append require a server reboot to take effect.

Procedure 5.5. Configure the Periodic Log Handler

<periodic-rotating-file-handler name="FILE" autoflush="true">
   <level name="INFO"/>
   <encoding value="UTF-8"/>
   <formatter>
      <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
   </formatter>
   <file relative-to="jboss.server.log.dir" path="server.log"/>
   <suffix value=".yyyy-MM-dd"/>
   <append value="true"/>
</periodic-rotating-file-handler>

<periodic-rotating-file-handler name="FILE" autoflush="true">
   <level name="INFO"/>
   <encoding value="UTF-8"/>
   <formatter>
      <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
   </formatter>
   <file relative-to="jboss.server.log.dir" path="server.log"/>
   <suffix value=".yyyy-MM-dd"/>
   <append value="true"/>
</periodic-rotating-file-handler>

1. Add the Periodic Log Handler Identifier Information

   The name property sets the unique identifier for this log handler.
   When autoflush is set to "true" the log messages will be sent to the handler's target immediately upon request.

2. Set the level Property

   The level property sets the maximum level of log message that the root logger records.

3. Set the encoding Output

   Use encoding to set the character encoding scheme to be used for the output.

4. Specify the formatter

   Use formatter to list the log formatter used by the log handler.

5. Set the file Object

   The file object represents the file where the output of this log handler is written to. It has two configuration properties: relative-to and path.
   The relative-to property is the directory where the log file is written to. JBoss Enterprise Application Platform 6 file path variables can be specified here. The jboss.server.log.dir variable points to the log/ directory of the server.
   The path property is the name of the file where the log messages will be written. It is a relative path name that is appended to the value of the relative-to property to determine the complete path.

6. Set the suffix Value

   The suffix is appended to the filename of the rotated logs and is used to determine the frequency of rotation. The format of the suffix is a dot (.) followed by a date string, which is parsable by the java.text.SimpleDateFormat class. The log is rotated on the basis of the smallest time unit defined by the suffix. For example, yyyy-MM-dd will result in daily log rotation. See http://docs.oracle.com/javase/6/docs/api/index.html?java/text/SimpleDateFormat.html

7. Set the append Property

   When the append property is set to "true", all messages written by this handler will be appended to an existing file. If set to "false" a new file will be created each time the application server launches. Changes to append require a server reboot to take effect.

Procedure 5.6. Configure the Size Log Handler

<size-rotating-file-handler name="accounts_debug" autoflush="false">
   <level name="DEBUG"/>
   <encoding value="UTF-8"/>
   <file relative-to="jboss.server.log.dir" path="accounts-debug.log"/>
   <rotate-size value="500k"/>
   <max-backup-index value="5"/>
   <formatter>
        <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
    </formatter>
   <append value="true"/>
</size-rotating-file-handler>

<size-rotating-file-handler name="accounts_debug" autoflush="false">
   <level name="DEBUG"/>
   <encoding value="UTF-8"/>
   <file relative-to="jboss.server.log.dir" path="accounts-debug.log"/>
   <rotate-size value="500k"/>
   <max-backup-index value="5"/>
   <formatter>
        <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
    </formatter>
   <append value="true"/>
</size-rotating-file-handler>

1. Add the Size Log Handler Identifier Information

   The name property sets the unique identifier for this log handler.
   When autoflush is set to "true" the log messages will be sent to the handler's target immediately upon request.

2. Set the level Property

   The level property sets the maximum level of log message that the root logger records.

3. Set the encoding Output

   Use encoding to set the character encoding scheme to be used for the output.

4. Set the file Object

   The file object represents the file where the output of this log handler is written to. It has two configuration properties: relative-to and path.
   The relative-to property is the directory where the log file is written to. JBoss Enterprise Application Platform 6 file path variables can be specified here. The jboss.server.log.dir variable points to the log/ directory of the server.
   The path property is the name of the file where the log messages will be written. It is a relative path name that is appended to the value of the relative-to property to determine the complete path.

5. Specify the rotate-size Value

   The maximum size that the log file can reach before it is rotated. A single character appended to the number indicates the size units: b for bytes, k for kilobytes, m for megabytes, g for gigabytes. For example: 50m for 50 megabytes.

6. Set the max-backup-index Number

   The maximum number of rotated logs that are kept. When this number is reached, the oldest log is reused.

7. Specify the formatter

   Use formatter to list the log formatter used by the log handler.

8. Set the append Property

   When the append property is set to "true", all messages written by this handler will be appended to an existing file. If set to "false" a new file will be created each time the application server launches. Changes to append require a server reboot to take effect.

Procedure 5.7. Configure the Async Log Handler

<async-handler name="Async_NFS_handlers">
   <level name="INFO"/>
   <queue-length value="512"/>
   <overflow-action value="block"/>
   <subhandlers>
      <handler name="FILE"/>
      <handler name="accounts-record"/>
   </subhandlers>
</async-handler>

<async-handler name="Async_NFS_handlers">
   <level name="INFO"/>
   <queue-length value="512"/>
   <overflow-action value="block"/>
   <subhandlers>
      <handler name="FILE"/>
      <handler name="accounts-record"/>
   </subhandlers>
</async-handler>

1. The name property sets the unique identifier for this log handler.
2. The level property sets the maximum level of log message that the root logger records.
3. The queue-length defines the maximum number of log messages that will be held by this handler while waiting for sub-handlers to respond.
4. The overflow-action defines how this handler responds when its queue length is exceeded. This can be set to BLOCK or DISCARD. BLOCK makes the logging application wait until there is available space in the queue. This is the same behavior as an non-async log handler. DISCARD allows the logging application to continue but the log message is deleted.
5. The subhandlers list is the list of log handlers to which this async handler passes its log messages.

Procedure 6.2. The local-cache Element

<cache-container name="local"
                  default-cache="default" 
                  statistics="true">
         <local-cache name="default"
                          start="EAGER"
                          batching="false"
                          statistics="true">
                  <indexing index="NONE">
	                <property name="default.directory_provider">ram</property>
                  </indexing>
         </local-cache>

<cache-container name="local"
                  default-cache="default" 
                  statistics="true">
         <local-cache name="default"
                          start="EAGER"
                          batching="false"
                          statistics="true">
                  <indexing index="NONE">
	                <property name="default.directory_provider">ram</property>
                  </indexing>
         </local-cache>

1. The name parameter specifies the name of the local cache to use.
2. The start parameter indicates when the cache container starts, i.e. whether it will start lazily when requested or "eagerly" when the server starts up. Valid values for this parameter are EAGER and LAZY.
3. The batching parameter specifies whether batching is enabled for the local cache.
4. If statistics are enabled at the container level, per-cache statistics can be selectively disabled for caches that do not require monitoring by setting the statistics attribute to false.
5. The indexing parameter specifies the type of indexing used for the local cache. Valid values for this parameter are NONE, LOCAL and ALL.

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

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

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

1. 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.
2. The cache-container parameter names the cache container used by the REST connector. This is a mandatory parameter.
3. 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.
4. 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.
5. 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 BASIC, DIGEST, and CLIENT-CERT. This is an optional parameter.
6. 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.

Procedure 11.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.1">
               <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 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 12.1. Configuring the Memcached Connector in Remote Client-Server Mode

<subsystem xmlns="urn:infinispan:server:endpoint:6.1">
<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>

<subsystem xmlns="urn:infinispan:server:endpoint:6.1">
<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>

1. The socket-binding parameter specifies the socket binding port used by the memcached connector. This is a mandatory parameter.
2. The cache-container parameter names the cache container used by the memcached connector. This is a mandatory parameter.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.

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

<subsystem xmlns="urn:infinispan:server:endpoint:6.1">
	<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}"
				 external-host="${HOSTNAME}"
				 external-port="${PORT}"
				 lazy-retrieval="${TRUE/FALSE}" 
				 await-initial-transfer="${TRUE/FALSE}" /> 
</subsystem>

<subsystem xmlns="urn:infinispan:server:endpoint:6.1">
	<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}"
				 external-host="${HOSTNAME}"
				 external-port="${PORT}"
				 lazy-retrieval="${TRUE/FALSE}" 
				 await-initial-transfer="${TRUE/FALSE}" /> 
</subsystem>

1. The hotrod-connector element defines the configuration elements for use with Hot Rod.
   1. The socket-binding parameter specifies the socket binding port used by the Hot Rod connector. This is a mandatory parameter.
   2. The cache-container parameter names the cache container used by the Hot Rod connector. This is a mandatory parameter.
   3. The worker-threads parameter specifies the number of worker threads available for the Hot Rod connector. The default value for this parameter is 160. This is an optional parameter.
   4. 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.
   5. 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.
   6. 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.
   7. 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.
2. 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 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.
   2. 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.
   3. 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.
   4. 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.
   5. 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.
   6. The await-initial-transfer parameter specifies whether the initial state retrieval happens immediately at startup. This parameter only applies when lazy-retrieval is set to false. This default value for this parameter is true.