Administration and Configuration Guide

Procedure 2.1. 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();
   

Procedure 2.2. Use CDI to Create a New EmbeddedCacheManager

1. Specify a default configuration:

   public class Config {
       @Produces
       public Configuration defaultEmbeddedConfiguration () {
           return new ConfigurationBuilder()
                            .eviction()
                                    .strategy(EvictionStrategy.LRU)
                                    .maxEntries(100)
                            .build();
       }
   }
   

2. Create a clustered or a non-clustered cache.
3. Invoke the method to create an EmbeddedCacheManager.

   ...
   @Inject
   EmbeddedCacheManager cacheManager;
   ...
   

Procedure 3.1. Initialize Eviction

1. Add the Eviction Tag

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

   <eviction />
   

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

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

   2. In Remote Client Server mode, set the max-entries as follows:

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

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.2">
      <root-logger>
         <level name="INFO"/>
   

2. List handlers

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

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

Procedure 5.2. Configure a Log Category

1. Define the Category

   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.

   <subsystem xmlns="urn:jboss:domain:logging:1.2">
      <logger category="com.company.accounts.rec" use-parent-handlers="true">
   

2. Set the level property

   Use the level property to set the maximum level of log message that the log category records.

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

3. List handlers

   handlers is a list of log handlers.

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

Procedure 5.3. Configure the Console Log Handler

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.

   <subsystem xmlns="urn:jboss:domain:logging:1.2">
      <console-handler name="CONSOLE" autoflush="true">
   

2. Set the level Property

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

   <subsystem xmlns="urn:jboss:domain:logging:1.2">
      <console-handler name="CONSOLE" autoflush="true">
         <level name="INFO"/>
   

3. Set the encoding Output

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

   <subsystem xmlns="urn:jboss:domain:logging:1.2">
      <console-handler name="CONSOLE" autoflush="true">
         <level name="INFO"/>
         <encoding value="UTF-8"/>
   

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.

   <subsystem xmlns="urn:jboss:domain:logging:1.2">
      <console-handler name="CONSOLE" autoflush="true">
         <level name="INFO"/>
         <encoding value="UTF-8"/>
         <target value="System.out"/>
   

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.*")).

   <subsystem xmlns="urn:jboss:domain:logging:1.2">
      <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;))"/>
   

6. Specify the formatter

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

   <subsystem xmlns="urn:jboss:domain:logging:1.2">
      <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>
   

Procedure 5.4. Configure the File Log 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.

   <file-handler name="accounts-rec-trail" autoflush="true">
   

2. Set the level Property

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

   <file-handler name="accounts-rec-trail" autoflush="true">
       <level name="INFO"/>
   

3. Set the encoding Output

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

   <file-handler name="accounts-rec-trail" autoflush="true">
       <level name="INFO"/>
       <encoding value="UTF-8"/>
   

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.

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

5. Specify the formatter

   Use formatter to list the log formatter used by the 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>
   

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.

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

Procedure 5.5. Configure the Periodic Log 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.

   <periodic-rotating-file-handler name="FILE" autoflush="true">
   

2. Set the level Property

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

   <periodic-rotating-file-handler name="FILE" autoflush="true">
      <level name="INFO"/>
   

3. Set the encoding Output

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

   <periodic-rotating-file-handler name="FILE" autoflush="true">
      <level name="INFO"/>
      <encoding value="UTF-8"/>
   

4. Specify the formatter

   Use formatter to list the log formatter used by the 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>
   

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.

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

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

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

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.

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

Procedure 5.6. Configure the Size Log 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.

   <size-rotating-file-handler name="accounts_debug" autoflush="false">
   

2. Set the level Property

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

   <size-rotating-file-handler name="accounts_debug" autoflush="false">
      <level name="DEBUG"/>
   

3. Set the encoding Output

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

   <size-rotating-file-handler name="accounts_debug" autoflush="false">
      <level name="DEBUG"/>
      <encoding value="UTF-8"/>
   

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.

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

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.

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

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.

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

7. Specify the formatter

   Use formatter to list the log formatter used by the 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>
   

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.

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

Procedure 5.7. Configure the Async Log Handler

1. Add the Async Log Handler Identifier Information

   The name property sets the unique identifier for this log handler.

   <async-handler name="Async_NFS_handlers">
   

2. Set the level Property

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

   <async-handler name="Async_NFS_handlers">
      <level name="INFO"/>
   

3. Define the queue-length

   The queue-length defines the maximum number of log messages that will be held by this handler while waiting for sub-handlers to respond.

   <async-handler name="Async_NFS_handlers">
      <level name="INFO"/>
      <queue-length value="512"/>
   

4. Set Overflow Response

   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.

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

5. List subhandlers

   The subhandlers list is the list of log handlers to which this async handler passes its log messages.

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

Procedure 6.2. The local-cache Element

1. Add the Local Cache Name

   The name parameter specifies the name of the local cache to use.

   <cache-container name="local"
                     default-cache="default" 
                     statistics="true">
            <local-cache name="default" >
   

2. Set the Cache Container Start Mode

   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.

   <cache-container name="local"
                     default-cache="default" 
                     statistics="true">
            <local-cache name="default"
                             start="EAGER" >
   

3. Configure Batching

   The batching parameter specifies whether batching is enabled for the local cache.

   <cache-container name="local"
                     default-cache="default"
                     statistics="true">
            <local-cache name="default"
                             start="EAGER"
                             batching="false" >
   

4. Per-cache Statistics

   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.

   <cache-container name="local"
                     default-cache="default"
                     statistics="true">
            <local-cache name="default"
                             start="EAGER"
                             batching="false"
                             statistics="true">
   

5. Specify Indexing Type

   The indexing parameter specifies the type of indexing used for the local cache. Valid values for this parameter are NONE, LOCAL and ALL.

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

Procedure 10.3. Transaction with Explicit Pessimistic Locking

1. When the line cache.lock(K) executes, a cluster-wide lock is acquired on K.

   tx.begin()
   cache.lock(K)
   

2. When the line cache.put(K,V5) executes, it guarantees success.

   tx.begin()
   cache.lock(K)           
   cache.put(K,V5)
   

3. When the line tx.commit() executes, the locks held for this process are released.

   tx.begin()
   cache.lock(K)           
   cache.put(K,V5)         
   tx.commit()             
   
   

Procedure 10.4. Transaction with Implicit Pessimistic locking

1. When the line cache.put(K,V) executes, a cluster-wide lock is acquired on K.

   tx.begin()
   cache.put(K,V)
   

2. When the line cache.put(K2,V2) executes, a cluster-wide lock is acquired on K2.

   tx.begin()
   cache.put(K,V)
   cache.put(K2,V2)
   

3. When the line cache.put(K,V5) executes, the lock acquisition is non operational because a cluster-wide lock for K has been previously acquired. The put operation will still occur.

   tx.begin()
   cache.put(K,V)
   cache.put(K2,V2)
   cache.put(K,V5)
   

4. When the line tx.commit() executes, all locks held for this transaction are released.

   tx.begin()
   cache.put(K,V)
   cache.put(K2,V2)
   cache.put(K,V5)
   tx.commit()
   

Procedure 13.1. Configure the Single File Store

1. Add the Cache Name

   The name parameter of the local-cache attribute is used to specify a name for the cache.

   <local-cache name="default">
   

2. Per-cache Statistics

   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.

   <local-cache name="default" statistics="true">
   

3. Configure the file-store Element

   The file-store element specifies configuration information for the single file store.
   The name parameter of the file-store element is used to specify a name for the file store.

   <local-cache name="default" statistics="true">
       <file-store name="myFileStore" />
   

4. Set the passivation Parameter

   The passivation parameter determines whether entries in the cache are passivated (true) or if the cache store retains a copy of the contents in memory (false).

   <local-cache name="default" statistics="true">
       <file-store name="myFileStore"
                   passivation="true" />
   

5. Set the purge Parameter

   The purge parameter specifies whether or not the cache store is purged when it is started. Valid values for this parameter are true and false.

   <local-cache name="default" statistics="true">
       <file-store name="myFileStore"
                   passivation="true"
                   purge="true" />
   

6. Set the shared Parameter

   The shared parameter is used when multiple cache instances share a cache store. This parameter can be set to prevent multiple cache instances writing the same modification multiple times. Valid values for this parameter are true and false. However, the shared parameter is not recommended for file-store.

   <local-cache name="default" statistics="true">
       <file-store name="myFileStore"
                   passivation="true"
                   purge="true"
                   shared="false" />
   

7. Specify the Directory Path Within the relative-to Parameter

   The relative-to property is the directory where the file-store stores the data. It is used to define a named path.
   The path property is the name of the file where the data is stored. It is a relative path name that is appended to the value of the relative-to property to determine the complete path.

   <local-cache name="default" statistics="true">
       <file-store name="myFileStore"
                   passivation="true"
                   purge="true"
                   shared="false"
                   relative-to="{PATH}"
                   path="{DIRECTORY}" />
   </local-cache>
   

8. Specify the maximum number of entries

   The maxEntries parameter provides maximum number of entries allowed. The default value is -1 for unlimited entries.

   <local-cache name="default" statistics="true">
       <file-store name="myFileStore"
                   passivation="true"
                   purge="true"
                   shared="false"
                   relative-to="{PATH}"
                   path="{DIRECTORY}"
                   max-entries="10000"/>
   </local-cache>
   

9. Set the fetch-state Parameter

   The fetch-state parameter when set to true fetches the persistent state when joining a cluster. If multiple cache stores are chained, only one of them can have this property enabled. Persistent state transfer with a shared cache store does not make sense, as the same persistent store that provides the data will just end up receiving it. Therefore, if a shared cache store is used, the cache does not allow a persistent state transfer even if a cache store has this property set to true. It is recommended to set this property to true only in a clustered environment. The default value for this parameter is false.

   <local-cache name="default" statistics="true">
       <file-store name="myFileStore"
                   passivation="true"
                   purge="true"
                   shared="false"
                   relative-to="{PATH}"
                   path="{DIRECTORY}"
                   max-entries="10000"
                   fetch-state="true"/>
   </local-cache>
   

10. Set the preload Parameter

    The preload parameter when set to true, loads the data stored in the cache store into memory when the cache starts. However, setting this parameter to true affects the performance as the startup time is increased. The default value for this parameter is false.

    <local-cache name="default" statistics="true">
        <file-store name="myFileStore"
                    passivation="true"
                    purge="true"
                    shared="false"
                    relative-to="{PATH}"
                    path="{DIRECTORY}"
                    max-entries="10000"
                    fetch-state="true"
                    preload="false"/>
    </local-cache>
    

11. Set the singleton Parameter

    The singleton parameter enables a singleton store cache store. SingletonStore is a delegating cache store used when only one instance in a cluster can interact with the underlying store. However, singleton parameter is not recommended for file-store.

    <local-cache name="default" statistics="true">
        <file-store name="myFileStore"
                    passivation="true"
                    purge="true"
                    shared="false"
                    relative-to="{PATH}"
                    path="{DIRECTORY}"
                    max-entries="10000"
                    fetch-state="true"
                    preload="false"
                    singleton="true"/>
    </local-cache>
    

Procedure 13.2. Configuring the Single File Store in Library Mode

1. Add the name value to the namedCache element. The following is an example of this step:

   <namedCache name="writeThroughToFile">
   

2. In the persistence element, set the passivation parameter to false. Possible values are true and false.

   <namedCache name="writeThroughToFile">
         <persistence passivation="false" />
   

3. Set up a single file configuration using the singleFile element:
   • fetchPersistentState - If set to true, the persistent state is fetched when joining a cluster. If multiple cache stores are chained, only one cache store can have this property set to true . The default for this value is false.
   • The ignoreModifications parameter determines whether operations that modify the cache (e.g. put, remove, clear, store, etc.) do not affect the cache store. As a result, the cache store can become out of sync with the cache.
   • The purgeOnStartup parameter specifies whether the cache store is purged when initially started.
   • The shared parameter is set to true when multiple cache instances share a cache store, which prevents multiple cache instances writing the same modification individually. The default for this attribute is false. However, the shared parameter is not recommended for file-store.
   • The preload parameter sets whether the cache store data is pre-loaded into memory and becomes immediately accessible after starting up. The disadvantage of setting this to true is that the start up time increases. The default value for this attribute is false.
   • The location parameter points to the location of file store.
   • The maxEntries parameter provides maximum number of entries allowed. The default value is -1 for unlimited entries.
   • The maxKeysInMemory parameter is used to speed up data lookup. The single file store keeps an index of keys and their positions in the file using the maxKeysInMemory parameter. The default value for this parameter is -1.

   <namedCache name="writeThroughToFile">
         <persistence passivation="false">
            <singleFile fetchPersistentState="true" 
                        ignoreModifications="false"
                        purgeOnStartup="false" 
                        shared="false"
                        preload="false"
                        location="/tmp/Another-FileCacheStore-Location"
                        maxEntries="100"
                        maxKeysInMemory="100">
            </singleFile>
         </persistence>
    </namedCache>
   

4. Add the async element to configure the asynchronous settings:
   • The enabled parameter determines whether the file store is asynchronous.
   • The threadPoolSize parameter specifies the number of threads that concurrently apply modifications to the store. The default value for this parameter is 5.
   • The flushLockTimeout parameter specifies the time to acquire the lock which guards the state to be flushed to the cache store periodically. The default value for this parameter is 1.
   • The modificationQueueSize parameter specifies the size of the modification queue for the asynchronous store. If updates are made at a rate that is faster than the underlying cache store can process this queue, then the asynchronous store behaves like a synchronous store for that period, blocking until the queue can accept more elements. The default value for this parameter is 1024 elements.
   • The shutdownTimeout parameter specifies the time to stop the cache store. Default value for this parameter is 25 seconds.

   <namedCache name="writeThroughToFile">
         <persistence passivation="false">
            <singleFile fetchPersistentState="true" 
                        ignoreModifications="false"
                        purgeOnStartup="false" 
                        shared="false"
                        preload="false"
                        location="/tmp/Another-FileCacheStore-Location"
                        maxEntries="100"
                        maxKeysInMemory="100">
               <async enabled="true" 
       	           threadPoolSize="500"
       	           flushLockTimeout="1"
   	           modificationQueueSize="1024"
   	           shutdownTimeout="25000"/>
           </singleFile>
         </persistence>
    </namedCache>
   

Procedure 13.3. Configure the Remote Cache Store

1. The cache parameter defines the name for the remote cache. If left undefined, the default cache is used instead.

   <remote-store cache="default">
   

2. The socket-timeout parameter sets whether the value defined in SO_TIMEOUT (in milliseconds) applies to remote Hot Rod servers on the specified timeout. A timeout value of 0 indicates an infinite timeout.

   <remote-store cache="default" 
                 socket-timeout="60000">
   

3. The tcp-no-delay sets whether TCP_NODELAY applies on socket connections to remote Hot Rod servers.

   <remote-store cache="default" 
                 socket-timeout="60000" 
                 tcp-no-delay="true">
   

4. The hotrod-wrapping sets whether a wrapper is required for Hot Rod on the remote store.

   <remote-store cache="default" 
                 socket-timeout="60000" 
                 tcp-no-delay="true" 
                 hotrod-wrapping="true">
   

5. The single parameter for the remote-server element is as follows:
   1. The outbound-socket-binding parameter sets the outbound socket binding for the remote server.

   <remote-store cache="default" 
                 socket-timeout="60000" 
                 tcp-no-delay="true" 
                 hotrod-wrapping="true">
   	<remote-server outbound-socket-binding="remote-store-hotrod-server" />
   </remote-store>
   

Procedure 13.4. Remote Cache Store Configuration

1. Configure the Persistence Element

   Create a persistence element, with the passivation set to false.

   <persistence passivation="false" />
   
   

2. Create a remoteStore element within the persistence element to configure the attributes for the Remote Cache Store.

   <persistence passivation="false">
   	<remoteStore xmlns="urn:infinispan:config:remote:6.0"
   		     fetchPersistentState="false" 
   		     shared="true" 
   		     preload="false" 
   		     ignoreModifications="false" 
   		     purgeOnStartup="false"
   		     tcpNoDelay="true" 
   		     pingOnStartup="true"
   		     keySizeEstimate="62" 
   		     valueSizeEstimate="512"
   		     forceReturnValues="false">
   	</remoteStore>
   </persistence>
   

   • Add the fetchPersistentState attribute. If set to true, the persistent state is fetched when the remote cache joins the cluster. If multiple cache stores are chained, only one cache store can have this property set to true . The default for this value is false.
   • Add the shared attribute. This is set to true when multiple cache instances share a cache store, which prevents multiple cache instances writing the same modification individually. The default for this attribute is false.
   • Add the preload attribute. When set to true, the cache store data is pre-loaded into memory and becomes immediately accessible after starting up. The disadvantage of setting this to true is that the start up time increases. The default value for this attribute is false.
   • Add the ignoreModifications attribute. When set to true, this attribute prevents cache modification operations such as put, remove, clear, store, etc. from affecting the cache store. As a result, the cache store can become out of sync with the cache. The default value for this attribute is false.
   • Add the purgeOnStartup attribute. If set to true, the cache store is purged during the start up process. The default value for this attribute is false.
   • Add the tcpNoDelay attribute. If set to true, this triggers the TCP NODELAY stack. The default value for this attribute is true.
   • Add the pingOnStartup attribute. If set to true, a ping request is sent to a back end server to fetch the cluster topology. The default value for this attribute is true.
   • Add the keySizeEstimate attribute. This value is the class name of the driver user to connect to the database. The default value for this attribute is 64.
   • Add the valueSizeEstimate attribute. This value is the size of the byte buffers when serializing and deserializing values. The default value for this attribute is 512.
   • Add the forceReturnValues attribute. This attribute sets whether FORCE_RETURN_VALUE is enabled for all calls. The default value for this attribute is false.
3. Create a servers element within the remoteStore element to set up the server information. Add a server element within the general servers element to add the information for a single server.

   <persistence passivation="false">
   	<remoteStore xmlns="urn:infinispan:config:remote:6.0"
   		     fetchPersistentState="false" 
   		     shared="true" 
   		     preload="false" 
   		     ignoreModifications="false" 
   		     purgeOnStartup="false"
   		     tcpNoDelay="true" 
   		     pingOnStartup="true"
   		     keySizeEstimate="62" 
   		     valueSizeEstimate="512"
   		     forceReturnValues="false">
   		<servers>
   			<server host="127.0.0.1" 
   				port="19711"/>
   		</servers>
   	</remoteStore>
   </persistence>
   

   • Add the host attribute to configure the host address.
   • Add the port attribute to configure the port used by the Remote Cache Store.
4. Create a connectionPool element to the remoteStore element.

   <persistence passivation="false">
   	<remoteStore xmlns="urn:infinispan:config:remote:6.0"
   		     fetchPersistentState="false" 
   		     shared="true" 
   		     preload="false" 
   		     ignoreModifications="false" 
   		     purgeOnStartup="false"
   		     tcpNoDelay="true" 
   		     pingOnStartup="true"
   		     keySizeEstimate="62" 
   		     valueSizeEstimate="512"
   		     forceReturnValues="false">
   		<servers>
   			<server host="127.0.0.1" 
   				port="19711"/>
   		</servers>
   		<connectionPool maxActive="99" 
   				maxIdle="97" 
   				maxTotal="98" />
   	</remoteStore>
   </persistence>
   

   • Add a maxActive attribute. This indicates the maximum number of active connections for each server at a time. The default value for this attribute is -1 which indicates an infinite number of active connections.
   • Add a maxIdle attribute. This indicates the maximum number of idle connections for each server at a time. The default value for this attribute is -1 which indicates an infinite number of idle connections.
   • Add a maxTotal attribute. This indicates the maximum number of persistent connections within the combined set of servers. The default setting for this attribute is -1 which indicates an infinite number of connections.

Procedure 13.5. To configure LevelDB Cache Store:

1. Obtain the leveldbjni-all-1.7.jar file from https://github.com/fusesource/leveldbjni and copy it to the modules/system/layers/base/org/fusesource/leveldbjni-all/main directory.
2. Modify the module.xml file to include JAR files in the resources:

   <module xmlns="urn:jboss:module:1.1" name="org.fusesource.leveldbjni-all">
      <properties>
         <property name="jboss.api" value="private"/>
      </properties>
   
      <resources>
         <resource-root path="leveldbjni-all-1.7.jar"/>
           <!-- Insert resources here -->
      </resources>
   
      <dependencies>
      </dependencies>
   </module>
   

3. Add the following to a cache definition in standalone.xml to configure the database:

   <leveldb-store path="/path/to/leveldb/data"
       passivation="false"
       purge="false" >
       <expiration path="/path/to/leveldb/expires/data" />
   </leveldb-store>
   

Procedure 13.6. LevelDB Cache Store programmatic configuration

1. Create a New Configuration Builder

   Use the ConfigurationBuilder to create a new configuration object.

   Configuration cacheConfig = new ConfigurationBuilder().persistence()
   

2. Add the LevelDBStoreConfigurationBuilder Store

   Add the store to the LevelDBCacheStoreConfigurationBuilder instance to build its configuration.

   Configuration cacheConfig = new ConfigurationBuilder().persistence()
                   .addStore(LevelDBStoreConfigurationBuilder.class)
   

3. Set Up Location

   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.

   Configuration cacheConfig = new ConfigurationBuilder().persistence()
                   .addStore(LevelDBStoreConfigurationBuilder.class)
                   .location("/tmp/leveldb/data")
   

4. Set Up Expired Location

   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.

   Configuration cacheConfig = new ConfigurationBuilder().persistence()
                   .addStore(LevelDBStoreConfigurationBuilder.class)
                   .location("/tmp/leveldb/data")
                   .expiredLocation("/tmp/leveldb/expired").build();
   

Procedure 13.7. LevelDB Cache Store Sample XML Configuration

1. Add the namedCache Element

   Specify the LevelDB Cache Store's name using the name parameter in the namedCache element as follows:

   <namedCache name="vehicleCache">
   

2. Add the persistence Element

   Specify the value for passivation parameter in the persistence element as follows. Possible values are true and false.

   <namedCache name="vehicleCache">
       <persistence passivation="false">
   

3. Add the leveldbStore Element

   Specify the location to store the primary cache store date using the location parameter in the leveldbStore element as follows. The directory is automatically created if it does not exist. The following is an example of this step:

   <namedCache name="vehicleCache">
         <persistence passivation="false">
             <leveldbStore location="/path/to/leveldb/data" />
   

4. Set the Expired Value

   Specify the location for expired data using the expiredLocation parameter as follows. The directory stores expired data before it is purged. The directory is automatically created if it does not exist.

   <namedCache name="vehicleCache">
         <persistence passivation="false">
             <leveldbStore location="/path/to/leveldb/data"  
                        expiredLocation="/path/to/expired/data" />
   

5. Set the Shared Parameter

   Specify the value for shared parameter in the leveldbStore element as follows. Possible values are true and false.

   <namedCache name="vehicleCache">
         <persistence passivation="false">
             <leveldbStore location="/path/to/leveldb/data"  
                        expiredLocation="/path/to/expired/data" shared="true" />
   

6. Set the Preload Parameter

   Specify the value for preload parameter in the leveldbStore element as follows. Possible values are true and false.

   <namedCache name="vehicleCache">
         <persistence passivation="false">
             <leveldbStore location="/path/to/leveldb/data"  
                        expiredLocation="/path/to/expired/data" shared="true" preload="true"/>
         </persistence>
      </namedCache>
   

Procedure 14.1. Install a JDBC Driver as a Core Module

1. Create a file path structure under the EAP_HOME/modules/ directory. For example, for a MySQL JDBC driver, create a directory structure as follows: EAP_HOME/modules/com/mysql/main/.
2. Copy the JDBC driver JAR into the main/ subdirectory.
3. In the main/ subdirectory, create a module.xml file. The following is an example of a module.xml file:

   <?xml version="1.0" encoding="UTF-8"?>
   <module xmlns="urn:jboss:module:1.0" name="com.mysql">
     <resources>
       <resource-root path="mysql-connector-java-5.1.15.jar"/>
     </resources>
     <dependencies>
       <module name="javax.api"/>
       <module name="javax.transaction.api"/>
     </dependencies>
   </module>
   

4. Start the Server.
5. Start the Management CLI.
6. Run the following CLI command to add the JDBC driver module as a driver:

   /subsystem=datasources/jdbc-driver=DRIVER_NAME:add(driver-name=DRIVER_NAME,driver-module-name=MODULE_NAME,driver-xa-datasource-class-name=XA_DATASOURCE_CLASS_NAME)

   Example 14.1. Example CLI Command

   /subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource)

Procedure 14.2. Add a Dependency to the Application

• • Configure the MANIFEST.MF file

    1. Open the application's META-INF/MANIFEST.MF file in a text editor.
    2. Add a dependency for the JDBC module and save the file.

       Dependencies: MODULE_NAME

       Example 14.2. Example Dependency

       Dependencies: com.mysql

  • 1. Create a jboss-deployment-structure.xml file

       Create a file called jboss-deployment-structure.xml in the META-INF/ or WEB-INF folder of the application.

       Example 14.3. Example jboss-deployment-structure.xml file

       <jboss-deployment-structure>
         <deployment>
           <dependencies>
             <module name="com.mysql" />
           </dependencies>
         </deployment>
       </jboss-deployment-structure>
       
       

Procedure 14.3. 

• /subsystem=datasources/data-source=ExampleDS/statistics=jdbc:read-resource(include-runtime=true)
  

  /subsystem=datasources/data-source=ExampleDS/statistics=pool:read-resource(include-runtime=true)
  

Procedure 15.1. Configure the JdbcBinaryStore for Remote Client-Server Mode

1. The binary-keyed-jdbc-store Element

   The binary-keyed-jdbc-store element specifies the configuration for a binary keyed cache JDBC store.
   1. The datasource parameter defines the name of a JNDI for the datasource.
   2. The passivation parameter determines whether entries in the cache are passivated (true) or if the cache store retains a copy of the contents in memory (false).
   3. The preload parameter specifies whether to load entries into the cache during start up. Valid values for this parameter are true and false.
   4. The purge parameter specifies whether or not the cache store is purged when it is started. Valid values for this parameter are true and false.

   <local-cache>
   	...
   	<binary-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
   				 passivation="${true/false}" 
   				 preload="${true/false]" 
   				 purge="${true/false}">
   

2. The binary-keyed-table Element

   The binary-keyed-table element specifies information about the database table used to store binary cache entries.
   1. The prefix parameter specifies a prefix string for the database table name.

   <local-cache>
   	...
   	<binary-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
   				 passivation="${true/false}" 
   				 preload="${true/false]" 
   				 purge="${true/false}">
                  	<binary-keyed-table prefix="JDG">
   

3. The id-column Element

   The id-column element specifies information about a database column that holds cache entry IDs.
   1. The name parameter specifies the name of the database column.
   2. The type parameter specifies the type of the database column.

   <local-cache>
   	...
   	<binary-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
   				 passivation="${true/false}" 
   				 preload="${true/false]" 
   				 purge="${true/false}">
                  	<binary-keyed-table prefix="JDG">
                  		<id-column name="id" 
   				   type="${id.column.type}"/>
   

4. The data-column Element

   The data-column element contains information about a database column that holds cache entry data.
   1. The name parameter specifies the name of the database column.
   2. The type parameter specifies the type of the database column.

   <local-cache>
   	...
   	<binary-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
   				 passivation="${true/false}" 
   				 preload="${true/false]" 
   				 purge="${true/false}">
                  	<binary-keyed-table prefix="JDG">
                  		<id-column name="id" 
   				   type="${id.column.type}"/>
                  		<data-column name="datum" 
   				     type="${data.column.type}"/>
   

5. The timestamp-column Element

   The timestamp-column element specifies information about the database column that holds cache entry timestamps.
   1. The name parameter specifies the name of the database column.
   2. The type parameter specifies the type of the database column.

   <local-cache>
   	...
   	<binary-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
   				 passivation="${true/false}" 
   				 preload="${true/false]" 
   				 purge="${true/false}">
                  	<binary-keyed-table prefix="JDG">
                  		<id-column name="id" 
   				   type="${id.column.type}"/>
                  		<data-column name="datum" 
   				     type="${data.column.type}"/>
                 		<timestamp-column name="version" 
   					  type="${timestamp.column.type}"/>
                 	</binary-keyed-table>
          	</binary-keyed-jdbc-store>
   </local-cache>
   
   

Procedure 15.2. Configure the JdbcBinaryStore for Library Mode

1. The binaryKeyedJdbcStore Element

   The binaryKeyedJdbcStore element uses the following parameters to configure the cache store:
   1. The fetchPersistentState parameter determines whether the persistent state is fetched when joining a cluster. Set this to true if using a replication and invalidation in a clustered environment. Additionally, if multiple cache stores are chained, only one cache store can have this property enabled. If a shared cache store is used, the cache does not allow a persistent state transfer despite this property being set to true. The fetchPersistentState parameter is false by default.
   2. The ignoreModifications parameter determines whether operations that modify the cache (e.g. put, remove, clear, store, etc.) do not affect the cache store. As a result, the cache store can become out of sync with the cache.
   3. The purgeOnStartup parameter specifies whether the cache store is purged when initially started.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<binaryKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
   	                      fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false">
   

2. The connectionPool Element

   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.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<binaryKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
   	                      fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false">
   		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
   				username="sa" 
   				driverClass="org.h2.Driver"/>
   

3. The binaryKeyedTable Element

   The binaryKeyedTable element defines the table that stores cache entries. It uses the following parameters to configure the cache store:
   1. The dropOnExit parameter specifies whether the database tables are dropped upon shutdown.
   2. The createOnStart parameter specifies whether the database tables are created by the store on startup.
   3. The prefix parameter defines the string prepended to name of the target cache when composing the name of the cache bucket table.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<binaryKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
   	                      fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false">
   		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
   				username="sa" 
   				driverClass="org.h2.Driver"/>
   		<binaryKeyedTable dropOnExit="true" 
   				  createOnStart="true" 
   				  prefix="ISPN_BUCKET_TABLE">
   

4. The idColumn Element

   The idColumn element defines the column where the cache key or bucket ID is stored. It uses the following parameters:
   1. Use the name parameter to specify the name of the column used.
   2. Use the type parameter to specify the type of the column used.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<binaryKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
   	                      fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false">
   		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
   				username="sa" 
   				driverClass="org.h2.Driver"/>
   		<binaryKeyedTable dropOnExit="true" 
   				  createOnStart="true" 
   				  prefix="ISPN_BUCKET_TABLE">
   			<idColumn name="ID_COLUMN" 
   				  type="VARCHAR(255)" />
   

5. The dataColumn Element

   The dataColumn element specifies the column where the cache entry or bucket is stored.
   1. Use the name parameter to specify the name of the column used.
   2. Use the type parameter to specify the type of the column used.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<binaryKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
   	                      fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false">
   		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
   				username="sa" 
   				driverClass="org.h2.Driver"/>
   		<binaryKeyedTable dropOnExit="true" 
   				  createOnStart="true" 
   				  prefix="ISPN_BUCKET_TABLE">
   			<idColumn name="ID_COLUMN" 
   				  type="VARCHAR(255)" />
   			<dataColumn name="DATA_COLUMN" 
   				    type="BINARY" />
   

6. The timestampColumn Element

   The timestampColumn element specifies the column where the time stamp of the cache entry or bucket is stored.
   1. Use the name parameter to specify the name of the column used.
   2. Use the type parameter to specify the type of the column used.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<binaryKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
   	                      fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false">
   		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
   				username="sa" 
   				driverClass="org.h2.Driver"/>
   		<binaryKeyedTable dropOnExit="true" 
   				  createOnStart="true" 
   				  prefix="ISPN_BUCKET_TABLE">
   			<idColumn name="ID_COLUMN" 
   				  type="VARCHAR(255)" />
   			<dataColumn name="DATA_COLUMN" 
   				    type="BINARY" />
   			<timestampColumn name="TIMESTAMP_COLUMN" 
   					 type="BIGINT" />
   		</binaryKeyedTable>
   	</binaryKeyedJdbcStore>
   </persistence>
   

Procedure 15.3. JdbcBinaryStore Programmatic Configuration (Library Mode)

1. Create a New Configuration Builder

   Use the ConfigurationBuilder to create a new configuration object.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence()
   

2. Add the JdbcBinaryStoreConfigurationBuilder

   Add the JdbcBinaryStore configuration builder to build a specific configuration related to this store.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence()
        .addStore(JdbcBinaryStoreConfigurationBuilder.class)
   

3. Set Up Persistence

   fetchPersistentState 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.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence()
        .addStore(JdbcBinaryStoreConfigurationBuilder.class)
        .fetchPersistentState(false)
   

4. Set Modifications

   ignoreModifications 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.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence()
        .addStore(JdbcBinaryStoreConfigurationBuilder.class)
        .fetchPersistentState(false)
        .ignoreModifications(false)
   

5. Configure Purging

   purgeOnStartup specifies whether the cache is purged when initially started.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence()
        .addStore(JdbcBinaryStoreConfigurationBuilder.class)
        .fetchPersistentState(false)
        .ignoreModifications(false)
        .purgeOnStartup(false)
   

6. Configure the Table

   1. Set Drop Table On Exit Method

      dropOnExit determines if the table will be created when the cache store is stopped. This is set to false by default.

   2. Set Create Table On Start Method

      createOnStart creates the table when starting the cache store if no table currently exists. This method is true by default.

   3. Set the Table Name Prefix

      tableNamePrefix sets the prefix for the name of the table in which the data will be stored.

   4. idColumnName

      The idColumnName property defines the column where the cache key or bucket ID is stored.

   5. dataColumnName

      The dataColumnName property specifies the column where the cache entry or bucket is stored.

   6. timestampColumnName

      The timestampColumnName element specifies the column where the time stamp of the cache entry or bucket is stored.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence()
        .addStore(JdbcBinaryStoreConfigurationBuilder.class)
        .fetchPersistentState(false)
        .ignoreModifications(false)
        .purgeOnStartup(false)
        .table()
           .dropOnExit(true)
           .createOnStart(true)
           .tableNamePrefix("ISPN_BUCKET_TABLE")
           .idColumnName("ID_COLUMN").idColumnType("VARCHAR(255)")
           .dataColumnName("DATA_COLUMN").dataColumnType("BINARY")
           .timestampColumnName("TIMESTAMP_COLUMN").timestampColumnType("BIGINT")
   

7. The connectionPool Element

   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.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence()
        .addStore(JdbcBinaryStoreConfigurationBuilder.class)
        .fetchPersistentState(false)
        .ignoreModifications(false)
        .purgeOnStartup(false)
        .table()
           .dropOnExit(true)
           .createOnStart(true)
           .tableNamePrefix("ISPN_BUCKET_TABLE")
           .idColumnName("ID_COLUMN").idColumnType("VARCHAR(255)")
           .dataColumnName("DATA_COLUMN").dataColumnType("BINARY")
           .timestampColumnName("TIMESTAMP_COLUMN").timestampColumnType("BIGINT")
        .connectionPool()
           .connectionUrl("jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1")
           .username("sa")
           .driverClass("org.h2.Driver");
   
   

Procedure 15.4. Configure JdbcStringBasedStore in Remote Client-Server Mode

1. The string-keyed-jdbc-store Element

   The string-keyed-jdbc-store element specifies the configuration for a string based keyed cache JDBC store.
   1. The datasource parameter defines the name of a JNDI for the datasource.
   2. The passivation parameter determines whether entries in the cache are passivated (true) or if the cache store retains a copy of the contents in memory (false).
   3. The preload parameter specifies whether to load entries into the cache during start up. Valid values for this parameter are true and false.
   4. The purge parameter specifies whether or not the cache store is purged when it is started. Valid values for this parameter are true and false.
   5. The shared parameter is used when multiple cache instances share a cache store. This parameter can be set to prevent multiple cache instances writing the same modification multiple times. Valid values for this parameter are true and false.
   6. The singleton parameter enables a singleton store cache store. SingletonStore is a delegating cache store used when only one instance in a cluster can interact with the underlying store.

   <local-cache> 
   	...
   	<string-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
   				 passivation="true" 
   				 preload="false" 
   				 purge="false"
   				 shared="false"
   				 singleton="true">
   

2. The string-keyed-table Element

   The string-keyed-table element specifies information about the database table used to store string based cache entries.
   1. The prefix parameter specifies a prefix string for the database table name.

   <local-cache> 
   	...
   	<string-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
   				 passivation="true" 
   				 preload="false" 
   				 purge="false"
   				 shared="false"
   				 singleton="true">
                  	<string-keyed-table prefix="JDG">
   

3. The id-column Element

   The id-column element specifies information about a database column that holds cache entry IDs.
   1. The name parameter specifies the name of the ID column.
   2. The type parameter specifies the type of the ID column.

   <local-cache> 
   	...
   	<string-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
   				 passivation="true" 
   				 preload="false" 
   				 purge="false"
   				 shared="false"
   				 singleton="true">
                  	<string-keyed-table prefix="JDG">
                  		<id-column name="id" 
   				   type="${id.column.type}"/>
   

4. The data-column Element

   The data-column element contains information about a database column that holds cache entry data.
   1. The name parameter specifies the name of the database column.
   2. The type parameter specifies the type of the database column.

   <local-cache> 
   	...
   	<string-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
   				 passivation="true" 
   				 preload="false" 
   				 purge="false"
   				 shared="false"
   				 singleton="true">
                  	<string-keyed-table prefix="JDG">
                  		<id-column name="id" 
   				   type="${id.column.type}"/>
   			<data-column name="datum" 
   				     type="${data.column.type}"/>
   

5. The timestamp-column Element

   The timestamp-column element specifies information about the database column that holds cache entry timestamps.
   1. The name parameter specifies the name of the database column.
   2. The type parameter specifies the type of the database column.

   <local-cache> 
   	...
   	<string-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
   				 passivation="true" 
   				 preload="false" 
   				 purge="false"
   				 shared="false"
   				 singleton="true">
                  	<string-keyed-table prefix="JDG">
                  		<id-column name="id" 
   				   type="${id.column.type}"/>
   			<data-column name="datum" 
   				     type="${data.column.type}"/>
   			<timestamp-column name="version" 
   					  type="${timestamp.column.type}"/>
   	        </string-keyed-table>
   	</string-keyed-jdbc-store>
   </local-cache>
   

Procedure 15.5. Configure JdbcStringBasedStore in Library Mode

1. The stringKeyedJdbcStore Element

   The stringKeyedJdbcStore element uses the following parameters to configure the cache store:
   1. The fetchPersistentState parameter determines whether the persistent state is fetched when joining a cluster. Set this to true if using a replication and invalidation in a clustered environment. Additionally, if multiple cache stores are chained, only one cache store can have this property enabled. If a shared cache store is used, the cache does not allow a persistent state transfer despite this property being set to true. The fetchPersistentState parameter is false by default.
   2. The ignoreModifications parameter determines whether operations that modify the cache (e.g. put, remove, clear, store, etc.) do not affect the cache store. As a result, the cache store can become out of sync with the cache.
   3. The purgeOnStartup parameter specifies whether the cache is purged when initially started.
   4. The key2StringMapper parameter specifies the class name of the Key2StringMapper used to map keys to strings for the database tables.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<stringKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
   	                      fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false"
   			      key2StringMapper="org.infinispan.loaders.keymappers.DefaultTwoWayKey2StringMapper">
   

2. The connectionPool Element

   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.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<stringKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
              	            fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false"
   			      key2StringMapper="org.infinispan.loaders.keymappers.DefaultTwoWayKey2StringMapper">
   		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
   				username="sa" 
   				driverClass="org.h2.Driver"/>
   

3. The stringKeyedTable Element

   Add the stringKeyedTable element defines the table that stores cache entries. It uses the following parameters to configure the cache store:
   1. The dropOnExit parameter specifies whether the database tables are dropped upon shutdown.
   2. The createOnStart parameter specifies whether the database tables are created by the store on startup.
   3. The prefix parameter specifies a prefix string for the database table name.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<stringKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
   	                      fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false"
   			      key2StringMapper="org.infinispan.loaders.keymappers.DefaultTwoWayKey2StringMapper">
   		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
   				username="sa" 
   				driverClass="org.h2.Driver"/>
   		<stringKeyedTable dropOnExit="true"
   				  createOnStart="true"
   				  prefix="ISPN_STRING_TABLE">
   

4. The idColumn Element

   The idColumn element defines the column where the cache key or bucket ID is stored. It uses the following parameters:
   1. Use the name parameter to specify the name of the ID column.
   2. Use the type parameter to specify the type of the ID column.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<stringKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
   	                      fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false"
   			      key2StringMapper="org.infinispan.loaders.keymappers.DefaultTwoWayKey2StringMapper">
   		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
   				username="sa" 
   				driverClass="org.h2.Driver"/>
   		<stringKeyedTable dropOnExit="true"
   				  createOnStart="true"
   				  prefix="ISPN_STRING_TABLE">
   			<idColumn name="ID_COLUMN" 
   				  type="VARCHAR(255)" />
   

5. The dataColumn Element

   The dataColumn element specifies the column where the cache entry or bucket is stored.
   1. Use the name parameter to specify the name of the database column.
   2. Use the type parameter to specify the type of the database column.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<stringKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
   	                      fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false"
   			      key2StringMapper="org.infinispan.loaders.keymappers.DefaultTwoWayKey2StringMapper">
   		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
   				username="sa" 
   				driverClass="org.h2.Driver"/>
   		<stringKeyedTable dropOnExit="true"
   				  createOnStart="true"
   				  prefix="ISPN_STRING_TABLE">
   			<idColumn name="ID_COLUMN" 
   				  type="VARCHAR(255)" />
   			<dataColumn name="DATA_COLUMN" 
   				    type="BINARY" />
   

6. The timestampColumn Element

   The timestampColumn element specifies the column where the time stamp of the cache entry or bucket is stored.
   1. Use the name parameter to specify the name of the column used.
   2. Use the type parameter to specify the type of the column used.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<stringKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
   	                      fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false"
   			      key2StringMapper="org.infinispan.loaders.keymappers.DefaultTwoWayKey2StringMapper">
   		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
   				username="sa" 
   				driverClass="org.h2.Driver"/>
   		<stringKeyedTable dropOnExit="true"
   				  createOnStart="true" 
   				  prefix="ISPN_STRING_TABLE">
   			<idColumn name="ID_COLUMN" 
   				  type="VARCHAR(255)" />
   			<dataColumn name="DATA_COLUMN" 
   				    type="BINARY" />
   			<timestampColumn name="TIMESTAMP_COLUMN" 
   					 type="BIGINT" />
   		</stringKeyedTable>
   	</stringKeyedJdbcStore>
   </persistence>
   

Procedure 15.6. JdbcStringBasedStore Multiple Node Configuration for Remote Client-Server Mode

1. The string-keyed-jdbc-store Element

   The string-keyed-jdbc-store element specifies the configuration for a string based keyed cache JDBC store.
   1. The fetch-state parameter determines whether or not to fetch the persistent state of a cache when joining a cluster. If multiple cache stores are chained, only one of them can have this property enabled.
   2. The datasource parameter defines the name of a JNDI for the datasource.
   3. The passivation parameter determines whether entries in the cache are passivated (true) or if the cache store retains a copy of the contents in memory (false).
   4. The preload parameter specifies whether to load entries into the cache during start up. Valid values for this parameter are true and false.
   5. The purge parameter specifies whether or not the cache store is purged when it is started. Valid values for this parameter are true and false.
   6. The shared parameter is used when multiple cache instances share a cache store. This parameter can be set to prevent multiple cache instances writing the same modification multiple times. Valid values for this parameter are true and false.
   7. The singleton parameter enables a singleton store cache store. SingletonStore is a delegating cache store used when only one instance in a cluster should interact with the underlying store.

   <subsystem xmlns="urn:infinispan:server:core:5.2" default-cache-container="default">
   	<cache-container ... >
   		...
         <replicated-cache>
   			...
   	      <string-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS"
   	            		       fetch-state="true"                        
   	            		       passivation="false"
   	            		       preload="false" 
   	            		       purge="false" 
   	            		       shared="false" 
   	            		       singleton="true">
   

2. The string-keyed-table Element

   The string-keyed-table element specifies information about the database table used to store string based cache entries.
   1. The prefix parameter specifies a prefix string for the database table name.

   <subsystem xmlns="urn:infinispan:server:core:5.2" default-cache-container="default">
   	<cache-container ... >
   		...
         <replicated-cache>
   			...
   	      <string-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS"
   	            		       fetch-state="true"                        
   	            		       passivation="false"
   	            		       preload="false" 
   	            		       purge="false" 
   	            		       shared="false" 
   	            		       singleton="true"> 
   	         <string-keyed-table prefix="JDG">
   

3. The id-column Element

   The id-column element specifies information about a database column that holds cache entry IDs.
   1. The name parameter specifies the name of the ID column.
   2. The type parameter specifies the type of the ID column.

   <subsystem xmlns="urn:infinispan:server:core:5.2" default-cache-container="default">
   	<cache-container ... >
   		...
         <replicated-cache>
   			...
   	      <string-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS"
   	            		       fetch-state="true"                        
   	            		       passivation="false"
   	            		       preload="false" 
   	            		       purge="false" 
   	            		       shared="false" 
   	            		       singleton="true"> 
   	         <string-keyed-table prefix="JDG">
   	             <id-column name="id" 
   	                        type="${id.column.type}"/>>
   

4. The data-column Element

   The data-column element contains information about a database column that holds cache entry data.
   1. The name parameter specifies the name of the database column.
   2. The type parameter specifies the type of the database column.

   <subsystem xmlns="urn:infinispan:server:core:5.2" default-cache-container="default">
   	<cache-container ... >
   		...
         <replicated-cache>
   			...
   	      <string-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS"
   	            		       fetch-state="true"                        
   	            		       passivation="false"
   	            		       preload="false" 
   	            		       purge="false" 
   	            		       shared="false" 
   	            		       singleton="true"> 
   	         <string-keyed-table prefix="JDG">
   	             <id-column name="id" 
   	                        type="${id.column.type}"/>
   	             <data-column name="datum" 
   	                          type="${data.column.type}"/>
   

5. The timestamp-column Element

   The timestamp-column element specifies information about the database column that holds cache entry timestamps.
   1. The name parameter specifies the name of the timestamp column.
   2. The type parameter specifies the type of the timestamp column.

   <subsystem xmlns="urn:infinispan:server:core:5.2" default-cache-container="default">
   	<cache-container ... >
   		...
         <replicated-cache>
   			...
   	      <string-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS"
   	            		       fetch-state="true"                        
   	            		       passivation="false"
   	            		       preload="false" 
   	            		       purge="false" 
   	            		       shared="false" 
   	            		       singleton="true"> 
   	         <string-keyed-table prefix="JDG">
   	             <id-column name="id" 
   	                        type="${id.column.type}"/>
   	             <data-column name="datum" 
   	                          type="${data.column.type}"/>
   	             <timestamp-column name="version"
   	                               type="${timestamp.column.type}"/>
   				</string-keyed-table> 
   			</string-keyed-jdbc-store>
   		</replicated-cache>
   	</cache-container>
   </subsystem>
   

Procedure 15.7. Configure the JdbcStringBasedStore Programmatically

1. Create a New Configuration Builder

   Use the ConfigurationBuilder to create a new configuration object.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   

2. Add JdbcStringBasedStoreConfigurationBuilder

   Add the JdbcStringBasedStore configuration builder to build a specific configuration related to this store.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence().addStore(JdbcStringBasedStoreConfigurationBuilder.class)
   

3. Set Up Persistence

   fetchPersistentState 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.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence().addStore(JdbcStringBasedStoreConfigurationBuilder.class)
        .fetchPersistentState(false)
   

4. Set Modifications

   ignoreModifications 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.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence().addStore(JdbcStringBasedStoreConfigurationBuilder.class)
        .fetchPersistentState(false)
        .ignoreModifications(false)
   

5. Configure Purging

   purgeOnStartup specifies whether the cache is purged when initially started.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence().addStore(JdbcStringBasedStoreConfigurationBuilder.class)
        .fetchPersistentState(false)
        .ignoreModifications(false)
        .purgeOnStartup(false)
   

6. Configure the Table

   1. Set Drop Table On Exit Method

      dropOnExit determines if the table will be created when the cache store is stopped. This is set to false by default.

   2. Set Create Table On Start Method

      createOnStart creates the table when starting the cache store if no table currently exists. This method is true by default.

   3. Set the Table Name Prefix

      tableNamePrefix sets the prefix for the name of the table in which the data will be stored.

   4. idColumnName

      The idColumnName property defines the column where the cache key or bucket ID is stored.

   5. dataColumnName

      The dataColumnName property specifies the column where the cache entry or bucket is stored.

   6. timestampColumnName

      The timestampColumnName element specifies the column where the time stamp of the cache entry or bucket is stored.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence().addStore(JdbcStringBasedStoreConfigurationBuilder.class)
        .fetchPersistentState(false)
        .ignoreModifications(false)
        .purgeOnStartup(false)
        .table()
           .dropOnExit(true)
           .createOnStart(true)
           .tableNamePrefix("ISPN_STRING_TABLE")
           .idColumnName("ID_COLUMN").idColumnType("VARCHAR(255)")
           .dataColumnName("DATA_COLUMN").dataColumnType("BINARY")
           .timestampColumnName("TIMESTAMP_COLUMN").timestampColumnType("BIGINT")
   

7. The connectionPool Element

   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.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence().addStore(JdbcStringBasedStoreConfigurationBuilder.class)
        .fetchPersistentState(false)
        .ignoreModifications(false)
        .purgeOnStartup(false)
        .table()
           .dropOnExit(true)
           .createOnStart(true)
           .tableNamePrefix("ISPN_STRING_TABLE")
           .idColumnName("ID_COLUMN").idColumnType("VARCHAR(255)")
           .dataColumnName("DATA_COLUMN").dataColumnType("BINARY")
           .timestampColumnName("TIMESTAMP_COLUMN").timestampColumnType("BIGINT")
        .connectionPool()
           .connectionUrl("jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1")
           .username("sa")
           .driverClass("org.h2.Driver");
   
   

Procedure 15.8. Configure JdbcMixedStore in Remote Client-Server Mode

1. The mixed-keyed-jdbc-store Element

   The mixed-keyed-jdbc-store element specifies the configuration for a mixed keyed cache JDBC store.
   1. The datasource parameter defines the name of a JNDI for the datasource.
   2. The passivation parameter determines whether entries in the cache are passivated (true) or if the cache store retains a copy of the contents in memory (false).
   3. The preload parameter specifies whether to load entries into the cache during start up. Valid values for this parameter are true and false.
   4. The purge parameter specifies whether or not the cache store is purged when it is started. Valid values for this parameter are true and false.

   <local-cache>
                <mixed-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
   				     passivation="true" 
   				     preload="false" 
   				     purge="false">
   

2. The binary-keyed-table Element

   The binary-keyed-table element specifies information about the database table used to store mixed cache entries.
   1. The prefix parameter specifies a prefix string for the database table name.

   <local-cache>
         <mixed-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
   				     passivation="true" 
   				     preload="false" 
   				     purge="false">
   	         <binary-keyed-table prefix="MIX_BKT2">
                        <id-column name="id" 
   		                            type="${id.column.type}"/>
   		                 <data-column name="datum" 
   			                            type="${data.column.type}"/>
   		                 <timestamp-column name="version" 
   				                               type="${timestamp.column.type}"/>
               </binary-keyed-table>
   

3. The string-keyed-table Element

   The string-keyed-table element specifies information about the database table used to store string based cache entries.
   1. The prefix parameter specifies a prefix string for the database table name.

   <local-cache>
         <mixed-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
   				     passivation="true" 
   				     preload="false" 
   				     purge="false">
   	         <binary-keyed-table prefix="MIX_BKT2">
                        <id-column name="id" 
   		                            type="${id.column.type}"/>
   		                 <data-column name="datum" 
   			                            type="${data.column.type}"/>
   		                 <timestamp-column name="version" 
   				                               type="${timestamp.column.type}"/>
               </binary-keyed-table>
               <string-keyed-table prefix="MIX_STR2">
   

4. The id-column Element

   The id-column element specifies information about a database column that holds cache entry IDs.
   1. The name parameter specifies the name of the ID column.
   2. The type parameter specifies the type of the ID column.

   <local-cache>
          <mixed-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
   				     passivation="true" 
   				     preload="false" 
   				     purge="false">
   	         <binary-keyed-table prefix="MIX_BKT2">
                        <id-column name="id" 
   		                            type="${id.column.type}"/>
   		                 <data-column name="datum" 
   			                            type="${data.column.type}"/>
   		                 <timestamp-column name="version" 
   				                               type="${timestamp.column.type}"/>
               </binary-keyed-table>
               <string-keyed-table prefix="MIX_STR2">
                        <id-column name="id" 
   			                          type="${id.column.type}"/>
   

5. The data-column Element

   The data-column element contains information about a database column that holds cache entry data.
   1. The name parameter specifies the name of the database column.
   2. The type parameter specifies the type of the database column.

   <local-cache>
           <mixed-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
   				     passivation="true" 
   				     preload="false" 
   				     purge="false">
   	         <binary-keyed-table prefix="MIX_BKT2">
                        <id-column name="id" 
   		                            type="${id.column.type}"/>
   		                 <data-column name="datum" 
   			                            type="${data.column.type}"/>
   		                 <timestamp-column name="version" 
   				                               type="${timestamp.column.type}"/>
               </binary-keyed-table>
                    <string-keyed-table prefix="MIX_STR2">
                        <id-column name="id" 
   			                          type="${id.column.type}"/>
   		                 <data-column name="datum" 
   			                            type="${data.column.type}"/>
   

6. The timestamp-column Element

   The timestamp-column element specifies information about the database column that holds cache entry timestamps.
   1. The name parameter specifies the name of the timestamp column.
   2. The type parameter specifies the type of the timestamp column.

     <local-cache>
         <mixed-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" 
   				     passivation="true" 
   				     preload="false" 
   				     purge="false">
   	         <binary-keyed-table prefix="MIX_BKT2">
                        <id-column name="id" 
   		                            type="${id.column.type}"/>
   		                 <data-column name="datum" 
   			                            type="${data.column.type}"/>
   		                 <timestamp-column name="version" 
   				                               type="${timestamp.column.type}"/>
               </binary-keyed-table>
                    <string-keyed-table prefix="MIX_STR2">
                        <id-column name="id" 
   			                          type="${id.column.type}"/>
   		                 <data-column name="datum" 
   			                            type="${data.column.type}"/>
   		             <timestamp-column name="version" 
   			  	                         type="${timestamp.column.type}"/>
    	        	 		</string-keyed-table>
           </mixed-keyed-jdbc-store>
   			</local-cache>
       </cache-container>
   </subsystem>
   
   

Procedure 15.9. Configure JdbcMixedStore in Library Mode

1. The mixedKeyedJdbcStore Element

   The mixedKeyedJdbcStore element uses the following parameters to configure the cache store:
   1. The fetchPersistentState parameter determines whether the persistent state is fetched when joining a cluster. Set this to true if using a replication and invalidation in a clustered environment. Additionally, if multiple cache stores are chained, only one cache store can have this property enabled. If a shared cache store is used, the cache does not allow a persistent state transfer despite this property being set to true. The fetchPersistentState parameter is false by default.
   2. The ignoreModifications parameter determines whether operations that modify the cache (for example put, remove, clear, store, etc.) do not affect the cache store. As a result, the cache store can become out of sync with the cache.
   3. The purgeOnStartup parameter specifies whether the cache is purged when initially started.
   4. The key2StringMapper parameter specifies the class name of the Key2StringMapper used to map keys to strings for the database tables.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<mixedKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
   	                      fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false"
   			      key2StringMapper="org.infinispan.persistence.keymappers.DefaultTwoWayKey2StringMapper">
   

2. The binaryKeyedTable and stringKeyedTable Elements

   The binaryKeyedTable and the stringKeyedTable element defines the table that stores cache entries. Each uses the following parameters to configure the cache store:
   1. The dropOnExit parameter specifies whether the database tables are dropped upon shutdown.
   2. The createOnStart parameter specifies whether the database tables are created by the store on startup.
   3. The prefix parameter defines the string prepended to name of the target cache when composing the name of the cache bucket table.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<mixedKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
   	                      fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false"
   			      key2StringMapper="org.infinispan.persistence.keymappers.DefaultTwoWayKey2StringMapper">
   		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
   				username="sa" 
   				driverClass="org.h2.Driver"/>
   		<binaryKeyedTable dropOnExit="true" 
   				  createOnStart="true" 
   				  prefix="ISPN_BUCKET_TABLE_BINARY">
   

3. The idColumn Element

   The idColumn element defines the column where the cache key or bucket ID is stored. It uses the following parameters:
   1. Use the name parameter to specify the name of the column used.
   2. Use the type parameter to specify the type of the column used.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   			<persistence>
   	<mixedKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
   	                      fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false"
   			      key2StringMapper="org.infinispan.persistence.keymappers.DefaultTwoWayKey2StringMapper">
   		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
   				username="sa" 
   				driverClass="org.h2.Driver"/>
   		<binaryKeyedTable dropOnExit="true" 
   				  createOnStart="true" 
   				  prefix="ISPN_BUCKET_TABLE_BINARY">
   			<idColumn name="ID_COLUMN" 
   				  type="VARCHAR(255)" />
   

4. The dataColumn Element

   The dataColumn element specifies the column where the cache entry or bucket is stored.
   1. Use the name parameter to specify the name of the column used.
   2. Use the type parameter to specify the type of the column used.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<mixedKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
   	                      fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false"
   			      key2StringMapper="org.infinispan.persistence.keymappers.DefaultTwoWayKey2StringMapper">
   		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
   				username="sa" 
   				driverClass="org.h2.Driver"/>
   		<binaryKeyedTable dropOnExit="true" 
   				  createOnStart="true" 
   				  prefix="ISPN_BUCKET_TABLE_BINARY">
   			<idColumn name="ID_COLUMN" 
   				  type="VARCHAR(255)" />
   			<dataColumn name="DATA_COLUMN" 
   				    type="BINARY" />
   

5. The timestampColumn Element

   The timestampColumn element specifies the column where the time stamp of the cache entry or bucket is stored.
   1. Use the name parameter to specify the name of the column used.
   2. Use the type parameter to specify the type of the column used.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<mixedKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
   	                      fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false"
   			      key2StringMapper="org.infinispan.persistence.keymappers.DefaultTwoWayKey2StringMapper">
   		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
   				username="sa" 
   				driverClass="org.h2.Driver"/>
   		<binaryKeyedTable dropOnExit="true" 
   				  createOnStart="true" 
   				  prefix="ISPN_BUCKET_TABLE_BINARY">
   			<idColumn name="ID_COLUMN" 
   				  type="VARCHAR(255)" />
   			<dataColumn name="DATA_COLUMN" 
   				    type="BINARY" />
   			<timestampColumn name="TIMESTAMP_COLUMN" 
   					 type="BIGINT" />
   		</binaryKeyedTable>
   

6. The string-keyed-table Element

   The string-keyed-table element specifies information about the database table used to store string based cache entries.
   1. The prefix parameter specifies a prefix string for the database table name.

   <infinispan
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd
               urn:infinispan:config:jdbc:6.0 http://www.infinispan.org/schemas/infinispan-cachestore-jdbc-config-6.0.xsd"
           xmlns="urn:infinispan:config:6.0">
           ...
   <persistence>
   	<mixedKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0"
                             fetchPersistentState="false"
   			      ignoreModifications="false" 
   			      purgeOnStartup="false"
   			      key2StringMapper="org.infinispan.persistence.keymappers.DefaultTwoWayKey2StringMapper">
   		<connectionPool connectionUrl="jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1" 
   				username="sa" 
   				driverClass="org.h2.Driver"/>
   		<binaryKeyedTable dropOnExit="true" 
   				  createOnStart="true" 
   				  prefix="ISPN_BUCKET_TABLE_BINARY">
   			<idColumn name="ID_COLUMN" 
   				  type="VARCHAR(255)" />
   			<dataColumn name="DATA_COLUMN" 
   				    type="BINARY" />
   			<timestampColumn name="TIMESTAMP_COLUMN" 
   					 type="BIGINT" />
   		</binaryKeyedTable>
   		<stringKeyedTable dropOnExit="true" 
   				  createOnStart="true" 
   				  prefix="ISPN_BUCKET_TABLE_STRING">
   			<idColumn name="ID_COLUMN" 
   				  type="VARCHAR(255)" />
   			<dataColumn name="DATA_COLUMN" 
   				    type="BINARY" />
   			<timestampColumn name="TIMESTAMP_COLUMN" 
   					 type="BIGINT" />
   		</stringKeyedTable>
   	</mixedKeyedJdbcStore>
   </persistence>
   

Procedure 15.10. Configure JdbcMixedStore Programmatically

1. Create a New Configuration Builder

   Use the ConfigurationBuilder to create a new configuration object.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   

2. Add JdbcMixedStoreConfigurationBuilder

   Add the JdbcMixedStore configuration builder to build a specific configuration related to this store.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence().addStore(JdbcMixedStoreConfigurationBuilder.class)
   

3. Set Up Persistence

   fetchPersistentState 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 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.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence().addStore(JdbcMixedStoreConfigurationBuilder.class)
        .fetchPersistentState(false)
   

4. Set Modifications

   ignoreModifications 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.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence().addStore(JdbcMixedStoreConfigurationBuilder.class)
        .fetchPersistentState(false)
        .ignoreModifications(false)
   

5. Configure Purging

   purgeOnStartup specifies whether the cache is purged when initially started.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence().addStore(JdbcMixedStoreConfigurationBuilder.class)
        .fetchPersistentState(false)
        .ignoreModifications(false)
        .purgeOnStartup(false)
   

6. Configure the Table

   1. Set Drop Table On Exit Method

      dropOnExit determines if the table will be created when the cache store is stopped. This is set to false by default.

   2. Set Create Table On Start Method

      createOnStart creates the table when starting the cache store if no table currently exists. This method is true by default.

   3. Set the Table Name Prefix

      tableNamePrefix sets the prefix for the name of the table in which the data will be stored.

   4. idColumnName

      The idColumnName property defines the column where the cache key or bucket ID is stored.

   5. dataColumnName

      The dataColumnName property specifies the column where the cache entry or bucket is stored.

   6. timestampColumnName

      The timestampColumnName element specifies the column where the time stamp of the cache entry or bucket is stored.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence().addStore(JdbcMixedStoreConfigurationBuilder.class)
        .fetchPersistentState(false)
        .ignoreModifications(false)
        .purgeOnStartup(false)
        .stringTable()
           .dropOnExit(true)
           .createOnStart(true)
           .tableNamePrefix("ISPN_MIXED_STR_TABLE")
           .idColumnName("ID_COLUMN").idColumnType("VARCHAR(255)")
           .dataColumnName("DATA_COLUMN").dataColumnType("BINARY")
           .timestampColumnName("TIMESTAMP_COLUMN").timestampColumnType("BIGINT")
   

7. The connectionPool Element

   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.

   ConfigurationBuilder builder = new ConfigurationBuilder();
     builder.persistence().addStore(JdbcMixedStoreConfigurationBuilder.class)
        .fetchPersistentState(false)
        .ignoreModifications(false)
        .purgeOnStartup(false)
        .stringTable()
           .dropOnExit(true)
           .createOnStart(true)
           .tableNamePrefix("ISPN_MIXED_STR_TABLE")
           .idColumnName("ID_COLUMN").idColumnType("VARCHAR(255)")
           .dataColumnName("DATA_COLUMN").dataColumnType("BINARY")
           .timestampColumnName("TIMESTAMP_COLUMN").timestampColumnType("BIGINT")
        .binaryTable()
           .dropOnExit(true)
           .createOnStart(true)
           .tableNamePrefix("ISPN_MIXED_BINARY_TABLE")
           .idColumnName("ID_COLUMN").idColumnType("VARCHAR(255)")
           .dataColumnName("DATA_COLUMN").dataColumnType("BINARY")
           .timestampColumnName("TIMESTAMP_COLUMN").timestampColumnType("BIGINT")
        .connectionPool()
           .connectionUrl("jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1")
           .username("sa")
           .driverClass("org.h2.Driver");
   
   

Procedure 16.1. Configure the Cache Loader Using XML

1. Create a New Cache Loader

   Create a new cache loader, specifying passivation, shared, and preload settings.
   1. passivation affects the way in which Red Hat JBoss Data Grid interacts with loaders. Passivation removes an object from in-memory cache and writes it to a secondary data store, such as a system or database. Passivation is false by default.
   2. shared indicates that the cache loader 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 loader by different cache instances.
   3. preload is set to false by default. When set to true the data stored in the cache loader is preloaded into the memory when the cache starts. This allows data in the cache loader 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. Red Hat JBoss Data Grid will only preload up to the maximum configured number of entries in eviction.

   <persistence passivation="false" shared="false" preload="true">
   

2. Set Up Persistence and Purging

   1. fetchPersistentState 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.
   2. purgeSynchronously controls whether expiration occurs in the eviction thread. When set to true, the eviction thread will block until the purge is finished, rather than bring returned immediately. The purgeSychronously property is set to false by default. If the cache loader supports multi-thread purge, purgeThreads are used to purge expired entries. purgeThreads is set to 1 by default. Check cache loader configuration to determine if multi-thread purge is supported.
   3. ignoreModifications 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.

   <persistence passivation="false" shared="false" preload="true">
      <fileStore
              fetchPersistentState="true"
              purgerThreads="3"
              purgeSynchronously="true"
              ignoreModifications="false"
              purgeOnStartup="false"
              location="${java.io.tmpdir}" />
   

3. Asynchronous Settings

   These attributes configure aspects specific to each cache loader. For example, the location attribute points to where the SingleFileStore keeps files containing data. Other loaders may require more complex configuration.

   <persistence passivation="false" shared="false" preload="true">
      <fileStore
              fetchPersistentState="true"
              purgerThreads="3"
              purgeSynchronously="true"
              ignoreModifications="false"
              purgeOnStartup="false"
              location="${java.io.tmpdir}" >
         <async
              enabled="true"
              flushLockTimeout="15000"
              threadPoolSize="5" />
      </fileStore>
   

4. Configure Singletons and Push States

   1. singletonStore 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 singletonStore enabled at the same time. The enabled attribute is false by default.
   2. pushStateWhenCoordinator 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 loader. This parameter is useful where the coordinator has crashed and a new coordinator is elected.

   <persistence passivation="false" shared="false" preload="true">
      <fileStore
              fetchPersistentState="true"
              purgerThreads="3"
              purgeSynchronously="true"
              ignoreModifications="false"
              purgeOnStartup="false"
              location="${java.io.tmpdir}" >
         <async
              enabled="true"
              flushLockTimeout="15000"
              threadPoolSize="5" />
         <singletonStore
              enabled="true"
              pushStateWhenCoordinator="true"
              pushStateTimeout="20000" />
      </fileStore>
   </persistence>
   

Procedure 16.2. Configure the Cache Loader Programatically

1. Create a New Configuration Builder

   Use the ConfigurationBuilder to create a new configuration object.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
   

2. Set Passivation

   passivation affects the way Red Hat JBoss Data Grid interacts with loaders. Passivation removes an object from in-memory cache and writes it to a secondary data loader, such as a system or database. Passivation is false by default.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
       .passivation(false)
   

3. Set Up Sharing

   shared indicates that the cache loader 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 loader by different cache instances.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
       .passivation(false)
       .shared(false)
   

4. Set Up Preloading

   preload is set to false by default. When set to true the data stored in the cache loader is preloaded into the memory when the cache starts. This allows data in the cache loader 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.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
       .passivation(false)
       .shared(false)
       .preload(true)
   

5. Configure the Cache Loader

   addSingleFileStore() adds the SingleFileStore as the cache loader for this configuration. It is possible to create other stores, such as a JDBC Cache Store, which can be added using the addLoader method.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
       .passivation(false)
       .shared(false)
       .preload(true)
       .addSingleFileStore()
   

6. Set Up Persistence

   fetchPersistentState determines whether or not to fetch the persistent state of a cache and apply it to the local cache loader when joining the cluster. If the cache loader is shared the fetch persistent state is ignored, as caches access the same cache loader. 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.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
       .passivation(false)
       .shared(false)
       .preload(true)
       .addSingleFileStore()
           .fetchPersistentState(true)
   

7. Set Up Purging

   purgeSynchronously controls whether expiration occurs in the eviction thread. When set to true, the eviction thread will block until the purge is finished, rather than bring returned immediately. The purgeSychronously property is set to false by default. If the cache loader supports multi-thread purge, purgeThreads are used to purge expired entries. purgeThreads is set to 1 by default. Check cache loader configuration to determine if multi-thread purge is supported.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
       .passivation(false)
       .shared(false)
       .preload(true)
       .addSingleFileStore()
           .fetchPersistentState(true)
           .purgerThreads(3)
           .purgeSynchronously(true)
   

8. Set Modifications

   ignoreModifications 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.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
       .passivation(false)
       .shared(false)
       .preload(true)
       .addSingleFileStore()
           .fetchPersistentState(true)
           .purgerThreads(3)
           .purgeSynchronously(true)
           .ignoreModifications(false)
   

9. Asynchronous Settings

   These attributes configure aspects specific to each cache loader. For example, the location attribute points to where the SingleFileStore will keep files containing data. Other loaders may require more complex configuration.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
       .passivation(false)
       .shared(false)
       .preload(true)
       .addSingleFileStore()
           .fetchPersistentState(true)
           .purgerThreads(3)
           .purgeSynchronously(true)
           .ignoreModifications(false)
           .purgeOnStartup(false)
           .location(System.getProperty("java.io.tmpdir"))
           .async()
               .enabled(true)
               .flushLockTimeout(15000)
               .threadPoolSize(5)
   

10. Configure Singletons

    singletonStore 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 singletonStore enabled at the same time. The enabled attribute is false by default.

    ConfigurationBuilder builder = new ConfigurationBuilder();
    builder.persistence()
        .passivation(false)
        .shared(false)
        .preload(true)
        .addSingleFileStore()
            .fetchPersistentState(true)
            .purgerThreads(3)
            .purgeSynchronously(true)
            .ignoreModifications(false)
            .purgeOnStartup(false)
            .location(System.getProperty("java.io.tmpdir"))
            .async()
                .enabled(true)
                .flushLockTimeout(15000)
                .threadPoolSize(5)
            .singletonStore()
               .enabled(true)
    

11. Set Up Push States

    pushStateWhenCoordinator 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 loader. This parameter is useful where the coordinator has crashed and a new coordinator is elected.

    ConfigurationBuilder builder = new ConfigurationBuilder();
    builder.persistence()
        .passivation(false)
        .shared(false)
        .preload(true)
        .addSingleFileStore()
            .fetchPersistentState(true)
            .purgerThreads(3)
            .purgeSynchronously(true)
            .ignoreModifications(false)
            .purgeOnStartup(false)
            .location(System.getProperty("java.io.tmpdir"))
            .async()
                .enabled(true)
                .flushLockTimeout(15000)
                .threadPoolSize(5)
            .singletonStore()
               .enabled(true)
               .pushStateWhenCoordinator(true)
               .pushStateTimeout(20000);
    

Procedure 18.1. Configure a Write-Through Local File Cache Store

1. Identify the namedCache

   The name parameter specifies the name of the namedCache to use.

   <?xml version="1.0" encoding="UTF-8"?>
   <infinispan xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns="urn:infinispan:config:5.0">
   	<global />
   	<default />
   	<namedCache name="persistentCache">
   

2. Configure the Cache Loader

   The shared parameter is used when multiple cache instances share a cache store. This parameter can be set to prevent multiple cache instances writing the same modification multiple times. Valid values for this parameter are true and false.

   <?xml version="1.0" encoding="UTF-8"?>
   <infinispan xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns="urn:infinispan:config:5.0">
   	<global />
   	<default />
   	<namedCache name="persistentCache">
   		<persistence shared="false">
   

3. Specify the Loader Class

   The class attribute defines the class of the cache loader implementation.

   <?xml version="1.0" encoding="UTF-8"?>
   <infinispan xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns="urn:infinispan:config:5.0">
   	<global />
   	<default />
   	<namedCache name="persistentCache">
   		<persistence shared="false">
   		<store class="org.infinispan.loaders.file.FileCacheStore"
   

4. Configure the fetchPersistentState Parameter

   The fetchPersistentState parameter determines whether the persistent state is fetched when joining a cluster. Set this to true if using a replication and invalidation in a clustered environment. Additionally, if multiple cache stores are chained, only one cache store can have this property enabled. If a shared cache store is used, the cache does not allow a persistent state transfer despite this property being set to true. The fetchPersistentState parameter is false by default.

   <?xml version="1.0" encoding="UTF-8"?>
   <infinispan xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns="urn:infinispan:config:5.0">
   	<global />
   	<default />
   	<namedCache name="persistentCache">
   		<persistence shared="false">
   		<store class="org.infinispan.loaders.file.FileCacheStore" 
   	       			fetchPersistentState="true"
   

5. Set the ignoreModifications Parameter

   The ignoreModifications parameter determines whether operations that modify the cache (e.g. put, remove, clear, store, etc.) do not affect the cache store. As a result, the cache store can become out of sync with the cache.

   <?xml version="1.0" encoding="UTF-8"?>
   <infinispan xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns="urn:infinispan:config:5.0">
   	<global />
   	<default />
   	<namedCache name="persistentCache">
   		<persistence shared="false">
   		<store class="org.infinispan.loaders.file.FileCacheStore" 
   	       			fetchPersistentState="true" 
   	       			ignoreModifications="false"
   

6. Configure Purge On Startup

   The purgeOnStartup parameter specifies whether the cache is purged when initially started.

   <?xml version="1.0" encoding="UTF-8"?>
   <infinispan xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns="urn:infinispan:config:5.0">
   	<global />
   	<default />
   	<namedCache name="persistentCache">
   		<persistence shared="false">
   		<store class="org.infinispan.loaders.file.FileCacheStore" 
   	       			fetchPersistentState="true" 
   	       			ignoreModifications="false"
   	       			purgeOnStartup="false">
   

7. The property Element

   The property element contains information about properties related to the cache store.
   1. The name parameter specifies the name of the property.

   <?xml version="1.0" encoding="UTF-8"?>
   <infinispan xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns="urn:infinispan:config:5.0">
   	<global />
   	<default />
   	<namedCache name="persistentCache">
   		<persistence shared="false">
   		<store class="org.infinispan.loaders.file.FileCacheStore" 
   	       			fetchPersistentState="true" 
   	       			ignoreModifications="false"
   	       			purgeOnStartup="false">
   				<properties>
   					<property name="location" 
   						  value="${java.io.tmpdir}" />
   				</properties>
   			</store>
   		</persistence>
     	</namedCache>
   </infinispan>
   
   

Procedure 18.2. The write-behind Element

1. The modification-queue-size Parameter

   The modification-queue-size parameter sets the modification queue size for the asynchronous store. If updates occur faster than the cache store can process the queue, the asynchronous store behaves like a synchronous store. The store behavior remains synchronous and blocks elements until the queue is able to accept them, after which the store behavior becomes asynchronous again.

   <file-store passivation="false" 
               path="${PATH}" 
               purge="true" 
               shared="false">
       <write-behind modification-queue-size="1024" />
   

2. The shutdown-timeout Parameter

   The shutdown-timeout parameter specifies the time in milliseconds after which the cache store is shut down. When the store is stopped some modifications may still need to be applied. Setting a large timeout value will reduce the chance of data loss. The default value for this parameter is 25000.

   <file-store passivation="false" 
               path="${PATH}" 
               purge="true" 
               shared="false">
       <write-behind modification-queue-size="1024" 
                     shutdown-timeout="25000" />
   

3. The flush-lock-timeout Parameter

   The flush-lock-timeout parameter specifies the time (in milliseconds) to acquire the lock that guards the state to be periodically flushed. The default value for this parameter is 15000.

   <file-store passivation="false" 
               path="${PATH}" 
               purge="true" 
               shared="false">
       <write-behind modification-queue-size="1024" 
                     shutdown-timeout="25000"  
                     flush-lock-timeout="15000" />
   

4. The thread-pool-size Parameter

   The thread-pool-size parameter specifies the size of the thread pool. The threads in this thread pool apply modifications to the cache store. The default value for this parameter is 5.

   <file-store passivation="false" 
               path="${PATH}" 
               purge="true" 
               shared="false">
       <write-behind modification-queue-size="1024" 
                     shutdown-timeout="25000"  
                     flush-lock-timeout="15000" 
                     thread-pool-size="5" />
   </file-store>
   

Procedure 18.3. The async Element

1. The modificationQueueSize parameter sets the modification queue size for the asynchronous store. If updates occur faster than the cache store can process the queue, the asynchronous store behaves like a synchronous store. The store behavior remains synchronous and blocks elements until the queue is able to accept them, after which the store behavior becomes asynchronous again.

   <persistence>
       <fileStore location="${LOCATION}">
           <async enabled="true" 
                       modificationQueueSize="1024" />
   

2. The shutdownTimeout parameter specifies the time in milliseconds after which the cache store is shut down. This provides time for the asynchronous writer to flush data to the store when a cache is shut down. The default value for this parameter is 25000.

   <persistence>
       <fileStore location="${LOCATION}">
           <async enabled="true" 
                       modificationQueueSize="1024" 
                       shutdownTimeout="25000" />
   

3. The flushLockTimeout parameter specifies the time (in milliseconds) to acquire the lock that guards the state to be periodically flushed. The default value for this parameter is 15000.

   <persistence>
       <fileStore location="${LOCATION}">
           <async enabled="true" 
                       modificationQueueSize="1024" 
                       shutdownTimeout="25000" 
                       flushLockTimeout="15000" />
   

4. The threadPoolSize parameter specifies the number of threads that concurrently apply modifications to the store. The default value for this parameter is 5.

   <persistence>
       <fileStore location="${LOCATION}">
           <async enabled="true" 
                       modificationQueueSize="1024" 
                       shutdownTimeout="25000" 
                       flushLockTimeout="15000" 
                       threadPoolSize="5"/>
       </fileStore>
   </persistence>
   

Procedure 20.1. Download JBoss Operations Network

1. Access the Customer Service Portal

   Log in to the Customer Service Portal at https://access.redhat.com

2. Locate the Product

   Mouse over Downloads and navigate to JBoss Enterprise Middleware.

3. Select the Product

   Select JBoss Operations Network for JDG from the menu.

4. Download JBoss Operations Network

   • Select the latest version of JBoss Operations Network Base Distribution and click the Download link.
   • Select the latest JBoss Data Grid Plugin Pack for JBoss Operations Network and click the Download link.

Procedure 20.2. Download Installation Files

1. Open http://access.redhat.com in a web browser.
2. Click Downloads in the menu across the top of the page.
3. Click Downloads in the list under JBoss Enterprise Middleware.
4. Enter your login information.
   You are taken to the Software Downloads page.

5. Download the JBoss Operations Network Plugin

   If you intend to use the JBoss Operations Network plugin for JBoss Data Grid, select JBoss ON for JDG from either the Software Downloads drop-down box, or the menu on the left.
   1. Click the JBoss Operations Network VERSION Base Distribution download link.
   2. Click the Download link to start the Base Distribution download.
   3. Repeat the steps to download the JDG Plugin Pack for JBoss ON VERSION

1. Install the plug-ins

   • Copy the JBoss Data Grid server rhq plug-in to $JON_SERVER_HOME/plugins.
   • Copy the Wildfly 7 plug-in to $JON_SERVER_HOME/plugins.
   The server will automatically discover plug-ins here and deploy them. The plug-ins will be removed from the plug-ins directory after successful deployment.

2. Obtain plug-ins

   Obtain all available plug-ins from the JBoss Operations Network server. To do this, type the following into the agent's console:

   plugins update

3. List installed plug-ins

   Ensure the Wildfly 7 plug-in and the JBoss Data Grid server rhq plug-in are installed correctly using the following:

   plugins info

Procedure 20.3. Install JBoss Operations Network Library Mode Plug-in

1. Open the JBoss Operations Network Console

   1. From the JBoss Operations Network console, select Administration.
   2. Select Agent Plugins from the Configuration options on the left side of the console.
   

   Figure 20.1. JBoss Operations Network Console for JBoss Data Grid

2. Upload the Library Mode Plug-in

   1. Click Browse, locate the InfinispanPlugin on your local file system.
   2. Click Upload to add the plug-in to the JBoss Operations Network Server.
   

   Figure 20.2. Upload the InfinispanPlugin.

3. Scan for Updates

   1. Once the file has successfully uploaded, click Scan For Updates at the bottom of the screen.
   2. The InfinispanPlugin will now appear in the list of installed plug-ins.
   

   Figure 20.3. Scan for Updated Plug-ins.

4. Import the Platform

   1. Navigate to the Inventory and select Discovery Queue from the Resources list on the left of the console.
   2. Select the platform on which the application is running and click Import at the bottom of the screen.
   

   Figure 20.4. Import the Platform from the Discovery Queue.

5. Access the Servers on the Platform

   1. The jdg Platform now appears in the Platforms list.
   2. Click on the Platform to access the servers that are running on it.
   

   Figure 20.5. Open the jdg Platform to view the list of servers.

6. Import the JMX Server

   1. From the Inventory tab, select Child Resources.
   2. Click the Import button at the bottom of the screen and select the JMX Server option from the list.
   

   Figure 20.6. Import the JMX Server

7. Enable JDK Connection Settings

   1. In the Resource Import Wizard window, specify JDK 5 from the list of Connection Settings Template options.
   

   Figure 20.7. Select the JDK 5 Template.

8. Modify the Connector Address

   1. In the Deployment Options menu, modify the supplied Connector Address with the hostname and JMX port of the process containing the Infinispan Library.
   2. Specify the Principal and Credentials information if required.
   3. Click Finish.
   

   Figure 20.8. Modify the values in the Deployment Options screen.

9. View Cache Statistics and Operations

   1. Click Refresh to refresh the list of servers.
   2. The JMX Servers tree in the panel on the left side of the screen contains the Infinispan Cache Managers node, which contains the available cache managers. The available cache managers contain the available caches.
   3. Select a cache from the available caches to view metrics.
   4. Select the Monitoring tab.
   5. The Tables view shows statistics and metrics.
   6. The Operations tab provides access to the various operations that can be performed on the services.
   

   Figure 20.9. Metrics and operational data relayed through JMX is now available in the JBoss Operations Network console.

1. Select Resources > Platforms > localhost > Inventory.
2. At the bottom of the page, open the drop-down menu next to the Manually Add section.
3. Select Infinispan Cache Manager and click Ok.
4. Select the default template on the next page.

5. Manually add the JBoss Data Grid instance

   1. Enter both the JMX connector address of the new JBoss Data Grid instance you want to monitor, and the Cache Manager Mbean object name. For example:
      Connector Address:

      service:jmx:rmi://127.0.0.1/jndi/rmi://127.0.0.1:7997/jmxrmi

   2. Object Name:

      org.infinispan:type=CacheManager,name="<name_of_cache_manager>