Administration and Configuration Guide
For use with Red Hat JBoss Data Grid 6.2.1
Abstract
Chapter 1. Setting up Red Hat JBoss Data Grid
1.1. Prerequisites
1.2. Steps to Set up Red Hat JBoss Data Grid
Procedure 1.1. Set Up JBoss Data Grid
Set Up the Cache Manager
The first step in a JBoss Data Grid configuration is a cache manager. Cache managers can retrieve cache instances and create cache instances quickly and easily using previously specified configuration templates. For details about setting up a cache manager, see Part I, “Set Up a Cache Manager”Set Up JVM Memory Management
An important step in configuring your JBoss Data Grid is to set up memory management for your Java Virtual Machine (JVM). JBoss Data Grid offers features such as eviction and expiration to help manage the JVM memory.Set Up Eviction
Use eviction to specify the logic used to remove entries from the in-memory cache implementation based on how often they are used. JBoss Data Grid offers different eviction strategies for finer control over entry eviction in your data grid. Eviction strategies and instructions to configure them are available in Chapter 3, Set Up Eviction.Set Up Expiration
To set upper limits to an entry's time in the cache, attach expiration information to each entry. Use expiration to set up the maximum period an entry is allowed to remain in the cache and how long the retrieved entry can remain idle before being removed from the cache. For details, see Chapter 4, Set Up Expiration
Monitor Your Cache
JBoss Data Grid uses logging via JBoss Logging to help users monitor their caches.Set Up Logging
It is not mandatory to set up logging for your JBoss Data Grid, but it is highly recommended. JBoss Data Grid uses JBoss Logging, which allows the user to easily set up automated logging for operations in the data grid. Logs can subsequently be used to troubleshoot errors and identify the cause of an unexpected failure. For details, see Chapter 5, Set Up Logging
Set Up Cache Modes
Cache modes are used to specify whether a cache is local (simple, in-memory cache) or a clustered cache (replicates state changes over a small subset of nodes). Additionally, if a cache is clustered, either replication, distribution or invalidation mode must be applied to determine how the changes propagate across the subset of nodes. For details, see Part IV, “Set Up Cache Modes”Set Up Locking for the Cache
When replication or distribution is in effect, copies of entries are accessible across multiple nodes. As a result, copies of the data can be accessed or modified concurrently by different threads. To maintain consistency for all copies across nodes, configure locking. For details, see Part V, “Set Up Locking for the Cache” and Chapter 12, Set Up Isolation LevelsSet Up and Configure a Cache Store
JBoss Data Grid offers the passivation feature (or cache writing strategies if passivation is turned off) to temporarily store entries removed from memory in a persistent, external cache store. To set up passivation or a cache writing strategy, you must first set up a cache store.Set Up a Cache Store
The cache store serves as a connection to the persistent store. Cache stores are primarily used to fetch entries from the persistent store and to push changes back to the persistent store. For details, see Part VI, “Set Up and Configure a Cache Store”Set Up Passivation
Passivation stores entries evicted from memory in a cache store. This feature allows entries to remain available despite not being present in memory and prevents potentially expensive write operations to the persistent cache. For details, see Part VII, “Set Up Passivation”Set Up a Cache Writing Strategy
If passivation is disabled, every attempt to write to the cache results in writing to the cache store. This is the default Write-Through cache writing strategy. Set the cache writing strategy to determine whether these cache store writes occur synchronously or asynchronously. For details, see Part VIII, “Set Up Cache Writing”
Monitor Caches and Cache Managers
JBoss Data Grid includes two primary tools to monitor the cache and cache managers once the data grid is up and running.Set Up JMX
JMX is the standard statistics and management tool used for JBoss Data Grid. Depending on the use case, JMX can be configured at a cache level or a cache manager level or both. For details, see Chapter 19, Set Up Java Management Extensions (JMX)Set Up Red Hat JBoss Operations Network (JON)
Red Hat JBoss Operations Network (JON) is the second monitoring solution available for JBoss Data Grid. JBoss Operations Network (JON) offers a graphical interface to monitor runtime parameters and statistics for caches and cache managers. For details, see Chapter 20, Set Up JBoss Operations Network (JON)
Introduce Topology Information
Optionally, introduce topology information to your data grid to specify where specific types of information or objects in your data grid are located. Server hinting is one of the ways to introduce topology information in JBoss Data Grid.Set Up Server Hinting
When set up, server hinting provides high availability by ensuring that the original and backup copies of data are not stored on the same physical server, rack or data center. This is optional in cases such as a replicated cache, where all data is backed up on all servers, racks and data centers. For details, see Chapter 26, High Availability Using Server Hinting
Part I. Set Up a Cache Manager
Chapter 2. Cache Managers
- it creates multiple cache instances on demand using a provided standard.
- it retrieves existing cache instanced (i.e. caches that have already been created).
2.1. Types of Cache Managers
EmbeddedCacheManager
is a cache manager that runs within the Java Virtual Machine (JVM) used by the client. Currently, JBoss Data Grid offers only theDefaultCacheManager
implementation of theEmbeddedCacheManager
interface.RemoteCacheManager
is used to access remote caches. When started, theRemoteCacheManager
instantiates connections to the Hot Rod server (or multiple Hot Rod servers). It then manages the persistentTCP
connections while it runs. As a result,RemoteCacheManager
is resource-intensive. The recommended approach is to have a singleRemoteCacheManager
instance for each Java Virtual Machine (JVM).
2.2. Creating CacheManagers
2.2.1. Create a New RemoteCacheManager
RemoteCacheManager
:
import org.infinispan.client.hotrod.configuration.Configuration; import org.infinispan.client.hotrod.configuration.ConfigurationBuilder; Configuration conf = new ConfigurationBuilder().addServer().host("localhost").port(11222).build(); RemoteCacheManager manager = new RemoteCacheManager(conf); RemoteCache defaultCache = manager.getCache();
An explanation of each line of the provided configuration is as follows:
- Use the
ConfigurationBuilder()
method to configure a new builder. The.addServer()
property adds a remote server, specified via the.host(<hostname|ip>)
and.port(<port>)
properties.Configuration conf = new ConfigurationBuilder().addServer().host(<hostname|ip>).port(<port>).build();
- Create a new
RemoteCacheManager
using the supplied configuration.RemoteCacheManager manager = new RemoteCacheManager(conf);
- Retrieve the default cache from the remote server.
RemoteCache defaultCache = manager.getCache();
2.2.2. Create a New Embedded Cache Manager
Procedure 2.1. Create a New Embedded Cache Manager
- Create a configuration XML file. For example, create the
my-config.file.xml
file on the classpath (in theresources/
folder) and add the configuration information in this file. - 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();
2.2.3. Create a New Embedded Cache Manager Using CDI
Procedure 2.2. Use CDI to Create a New EmbeddedCacheManager
- Specify a default configuration:
public class Config { @Produces public Configuration defaultEmbeddedConfiguration () { return new ConfigurationBuilder() .eviction() .strategy(EvictionStrategy.LRU) .maxEntries(100) .build(); } }
- Create a clustered or a non-clustered cache.
- Invoke the method to create an EmbeddedCacheManager.
... @Inject EmbeddedCacheManager cacheManager; ...
2.3. Multiple Cache Managers
2.3.1. Create Multiple Caches with a Single Cache Manager
2.3.2. Using Multiple Cache Managers
TCP
protocol and the other uses the UDP
protocol, multiple cache managers must be used.
2.3.3. Create Multiple Cache Managers
infinispan.xml
file to a new configuration file. Edit the new file for the desired configuration and then use the new file for a new cache manager.
Part II. Set Up JVM Memory Management
Chapter 3. Set Up Eviction
3.1. About Eviction
3.2. Eviction Strategies
Strategy Name | Operations | Details |
---|---|---|
EvictionStrategy.NONE | No eviction occurs. | - |
EvictionStrategy.LRU | Least Recently Used eviction strategy. This strategy evicts entries that have not been used for the longest period. This ensures that entries that are reused periodically remain in memory. | |
EvictionStrategy.UNORDERED | Unordered eviction strategy. This strategy evicts entries without any ordered algorithm and may therefore evict entries that are required later. However, this strategy saves resources because no algorithm related calculations are required before eviction. | This strategy is recommended for testing purposes and not for a real work implementation. |
EvictionStrategy.LIRS | Low Inter-Reference Recency Set eviction strategy. | LIRS is Red Hat JBoss Data Grid's default eviction algorithm because it suits a large variety of production use cases. |
3.2.1. LRU Eviction Algorithm Limitations
- Single use access entries are not replaced in time.
- Entries that are accessed first are unnecessarily replaced.
3.3. Using Eviction
eviction
/> element is used to enable eviction without any strategy or maximum entries settings, the following default values are automatically implemented:
- Strategy: If no eviction strategy is specified,
EvictionStrategy.NONE
is assumed as a default. - max-entries/maxEntries: If no value is specified, the
max-entries
/maxEntries value is set to-1
, which allows unlimited entries.
3.3.1. Initialize Eviction
max-entries
attributes value to a number greater than zero. Adjust the value set for max-entries
to discover the optimal value for your configuration. It is important to remember that if too large a value is set for max-entries
, Red Hat JBoss Data Grid runs out of memory.
Procedure 3.1. Initialize Eviction
Add the Eviction Tag
Add the <eviction> tag to your project's <cache> tags as follows:<eviction />
Set the Eviction Strategy
Set thestrategy
value to set the eviction strategy employed. Possible values areLRU
,UNORDERED
andLIRS
(orNONE
if no eviction is required). The following is an example of this step:<eviction strategy="LRU" />
Set the Maximum Entries
Set the maximum number of entries allowed in memory. The default value is-1
for unlimited entries.- In Library mode, set the
maxEntries
parameter as follows:<eviction strategy="LRU" maxEntries="200" />
- In Remote Client Server mode, set the
max-entries
as follows:<eviction strategy="LRU" max-entries="200" />
Eviction is configured for the target cache.
3.3.2. Eviction Configuration Examples
- A sample XML configuration for Library mode is as follows:
<eviction strategy="LRU" maxEntries="2000"/>
- A sample XML configuration for Remote Client Server Mode is as follows:
<eviction strategy="LRU" max-entries="20"/>
- A sample programmatic configuration for Library Mode is as follows:
Configuration c = new ConfigurationBuilder().eviction().strategy(EvictionStrategy.LRU) .maxEntries(2000) .build();
Note
maxEntries
parameter while Remote Client-Server mode uses the max-entries
parameter to configure eviction.
3.3.3. Eviction Configuration Troubleshooting
max-entries
parameter of the configuration
element. This is because although the max-entries
value can be configured to a value that is not a power of two, the underlying algorithm will alter the value to V
, where V
is the closest power of two value that is larger than the max-entries
value. Eviction algorithms are in place to ensure that the size of the cache container will never exceed the value V
.
3.3.4. Eviction and Passivation
Chapter 4. Set Up Expiration
4.1. About Expiration
- A lifespan value.
- A maximum idle time value.
lifespan
or maxIdle
value.
- expiration removes entries based on the period they have been in memory. Expiration only removes entries when the life span period concludes or when an entry has been idle longer than the specified idle time.
- eviction removes entries based on how recently (and often) they are used. Eviction only removes entries when too many entries are present in the memory. If a cache store has been configured, evicted entries are persisted in the cache store.
4.2. Expiration Operations
lifespan
) or maximum idle time (maxIdle
in Library Mode and max-idle
in Remote Client-Server Mode) defined for an individual key/value pair overrides the cache-wide default for the entry in question.
4.3. Eviction and Expiration Comparison
lifespan
) and idle time (maxIdle
in Library Mode and max-idle
in Remote Client-Server Mode) values are replicated alongside each cache entry.
4.4. Cache Entry Expiration Notifications
- A user thread requests an entry and discovers that the entry has expired.
- An entry is passivated/overflowed to disk and is discovered to have expired.
- The eviction maintenance thread discovers that an entry it has found is expired.
4.5. Configure Expiration
Procedure 4.1. Configure Expiration
Add the Expiration Tag
Add the <expiration> tag to your project's <cache> tags as follows:<expiration />
Set the Expiration Lifespan
Set thelifespan
value to set the period of time (in milliseconds) an entry can remain in memory. The following is an example of this step:<expiration lifespan="1000" />
Set the Maximum Idle Time
Set the time that entries are allowed to remain idle (unused) after which they are removed (in milliseconds). The default value is-1
for unlimited time.- In Library mode, set the
maxIdle
parameter as follows:<expiration lifespan="1000" maxIdle="1000" />
- In Remote Client Server mode, set the
max-idle
as follows:<expiration lifespan="1000" max-idle="1000" />
Expiration is now configured for the cache implementation.
4.6. Mortal and Immortal Data
put(key, value)
creates an entry that will never expire, called an immortal entry. Alternatively, an entry created using put(key, value, lifespan, timeunit)
is a mortal entry that has a specified fixed life span, after which it expires.
lifespan
parameter, JBoss Data Grid also provides a maxIdle
parameter used to determine expiration. The maxIdle
and lifespan
parameters can be used in various combinations to set the life span of an entry.
4.7. Troubleshooting Expiration
put()
are passed a life span value as a parameter. This value defines the interval after which the entry must expire. In cases where eviction is not configured and the life span interval expires, it can appear as if Red Hat JBoss Data Grid has not removed the entry. For example, when viewing JMX statistics, such as the number of entries, you may see an out of date count, or the persistent store associated with JBoss Data Grid may still contain this entry. Behind the scenes, JBoss Data Grid has marked it as an expired entry, but has not removed it. Removal of such entries happens in one of two ways:
- Any attempt to use
get()
orcontainsKey()
for the expired entry, causes JBoss Data Grid to detect the entry as an expired one and remove it. - Enabling the eviction feature causes the eviction thread to periodically detect and purge expired entries.
Part III. Monitor Your Cache
Chapter 5. Set Up Logging
5.1. About Logging
5.2. Supported Application Logging Frameworks
- JBoss Logging, which is included with Red Hat JBoss Data Grid 6.
5.2.1. About JBoss Logging
5.2.2. JBoss Logging Features
- Provides an innovative, easy to use typed logger.
- Full support for internationalization and localization. Translators work with message bundles in properties files while developers can work with interfaces and annotations.
- Build-time tooling to generate typed loggers for production, and runtime generation of typed loggers for development.
5.3. Boot Logging
5.3.1. Configure Boot Logging
logging.properties
file to configure the boot log. This file is a standard Java properties file and can be edited in a text editor. Each line in the file has the format of property=value
.
logging.properties
file is available in the $JDG_HOME/standalone/configuration
folder.
5.3.2. Default Log File Locations
Log File | Location | Description |
---|---|---|
boot.log | $JDG_HOME/standalone/log/ | The Server Boot Log. Contains log messages related to the start up of the server. |
server.log | $JDG_HOME/standalone/log/ | The Server Log. Contains all log messages once the server has launched. |
5.4. Logging Attributes
5.4.1. About Log Levels
TRACE
DEBUG
INFO
WARN
ERROR
FATAL
WARN
will only record messages of the levels WARN
, ERROR
and FATAL
.
5.4.2. Supported Log Levels
Log Level | Value | Description |
---|---|---|
FINEST | 300 | - |
FINER | 400 | - |
TRACE | 400 | Used for messages that provide detailed information about the running state of an application. TRACE level log messages are captured when the server runs with the TRACE level enabled. |
DEBUG | 500 | Used for messages that indicate the progress of individual requests or activities of an application. DEBUG level log messages are captured when the server runs with the DEBUG level enabled. |
FINE | 500 | - |
CONFIG | 700 | - |
INFO | 800 | Used for messages that indicate the overall progress of the application. Used for application start up, shut down and other major lifecycle events. |
WARN | 900 | Used to indicate a situation that is not in error but is not considered ideal. Indicates circumstances that can lead to errors in the future. |
WARNING | 900 | - |
ERROR | 1000 | Used to indicate an error that has occurred that could prevent the current activity or request from completing but will not prevent the application from running. |
SEVERE | 1000 | - |
FATAL | 1100 | Used to indicate events that could cause critical service failure and application shutdown and possibly cause JBoss Data Grid to shut down. |
5.4.3. About Log Categories
WARNING
log level results in log values of 900
, 1000
and 1100
are captured.
5.4.4. About the Root Logger
server.log
. This file is sometimes referred to as the server log.
5.4.5. About Log Handlers
Console
File
Periodic
Size
Async
Custom
5.4.6. Log Handler Types
Log Handler Type | Description | Use Case |
---|---|---|
Console | Console log handlers write log messages to either the host operating system’s standard out (stdout ) or standard error (stderr ) stream. These messages are displayed when JBoss Data Grid is run from a command line prompt. | The Console log handler is preferred when JBoss Data Grid is administered using the command line. In such a case, the messages from a Console log handler are not saved unless the operating system is configured to capture the standard out or standard error stream. |
File | File log handlers are the simplest log handlers. Their primary use is to write log messages to a specified file. | File log handlers are most useful if the requirement is to store all log entries according to the time in one place. |
Periodic | Periodic file handlers write log messages to a named file until a specified period of time has elapsed. Once the time period has elapsed, the specified time stamp is appended to the file name. The handler then continues to write into the newly created log file with the original name. | The Periodic file handler can be used to accumulate log messages on a weekly, daily, hourly or other basis depending on the requirements of the environment. |
Size | Size log handlers write log messages to a named file until the file reaches a specified size. When the file reaches a specified size, it is renamed with a numeric prefix and the handler continues to write into a newly created log file with the original name. Each size log handler must specify the maximum number of files to be kept in this fashion. | The Size handler is best suited to an environment where the log file size must be consistent. |
Async | Async log handlers are wrapper log handlers that provide asynchronous behavior for one or more other log handlers. These are useful for log handlers that have high latency or other performance problems such as writing a log file to a network file system. | The Async log handlers are best suited to an environment where high latency is a problem or when writing to a network file system. |
Custom | Custom log handlers enable to you to configure new types of log handlers that have been implemented. A custom handler must be implemented as a Java class that extends java.util.logging.Handler and be contained in a module. | Custom log handlers create customized log handler types and are recommended for advanced users. |
5.4.7. Selecting Log Handlers
- The
Console
log handler is preferred when JBoss Data Grid is administered using the command line. In such a case, errors and log messages appear on the console window and are not saved unless separately configured to do so. - The
File
log handler is used to direct log entries into a specified file. This simplicity is useful if the requirement is to store all log entries according to the time in one place. - The
Periodic
log handler is similar to theFile
handler but creates files according to the specified period. As an example, this handler can be used to accumulate log messages on a weekly, daily, hourly or other basis depending on the requirements of the environment. - The
Size
log handler also writes log messages to a specified file, but only while the log file size is within a specified limit. Once the file size reaches the specified limit, log files are written to a new log file. This handler is best suited to an environment where the log file size must be consistent. - The
Async
log handler is a wrapper that forces other log handlers to operate asynchronously. This is best suited to an environment where high latency is a problem or when writing to a network file system. - The
Custom
log handler creates new, customized types of log handlers. This is an advanced log handler.
5.4.8. About Log Formatters
java.util.Formatter
class.
5.5. Logging Sample Configurations
5.5.1. Sample XML Configuration for the Root Logger
Procedure 5.1. Configure the Root Logger
Set the
level
PropertyThelevel
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"/>
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>
5.5.2. Sample XML Configuration for a Log Category
Procedure 5.2. Configure a Log Category
Define the Category
Use thecategory
property to specify the log category from which log messages will be captured.Theuse-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">
Set the
level
propertyUse thelevel
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"/>
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>
5.5.3. Sample XML Configuration for a Console Log Handler
Procedure 5.3. Configure the Console Log Handler
Add the Log Handler Identifier Information
Thename
property sets the unique identifier for this log handler.Whenautoflush
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">
Set the
level
PropertyThelevel
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"/>
Set the
encoding
OutputUseencoding
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"/>
Define the
target
ValueThetarget
property defines the system output stream where the output of the log handler goes. This can beSystem.err
for the system error stream, orSystem.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"/>
Define the
filter-spec
PropertyThefilter-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("JBAS.*"))"/>
Specify the
formatter
Useformatter
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("JBAS.*"))"/> <formatter> <pattern-formatter pattern="%K{level}%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/> </formatter> </console-handler> </subsystem>
5.5.4. Sample XML Configuration for a File Log Handler
Procedure 5.4. Configure the File Log Handler
Add the File Log Handler Identifier Information
Thename
property sets the unique identifier for this log handler.Whenautoflush
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">
Set the
level
PropertyThelevel
property sets the maximum level of log message that the root logger records.<file-handler name="accounts-rec-trail" autoflush="true"> <level name="INFO"/>
Set the
encoding
OutputUseencoding
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"/>
Set the
file
ObjectThefile
object represents the file where the output of this log handler is written to. It has two configuration properties:relative-to
andpath
.Therelative-to
property is the directory where the log file is written to. JBoss Enterprise Application Platform 6 file path variables can be specified here. Thejboss.server.log.dir
variable points to thelog/
directory of the server.Thepath
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 therelative-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"/>
Specify the
formatter
Useformatter
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>
Set the
append
PropertyWhen theappend
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 toappend
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>
5.5.5. Sample XML Configuration for a Periodic Log Handler
Procedure 5.5. Configure the Periodic Log Handler
Add the Periodic Log Handler Identifier Information
Thename
property sets the unique identifier for this log handler.Whenautoflush
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">
Set the
level
PropertyThelevel
property sets the maximum level of log message that the root logger records.<periodic-rotating-file-handler name="FILE" autoflush="true"> <level name="INFO"/>
Set the
encoding
OutputUseencoding
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"/>
Specify the
formatter
Useformatter
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>
Set the
file
ObjectThefile
object represents the file where the output of this log handler is written to. It has two configuration properties:relative-to
andpath
.Therelative-to
property is the directory where the log file is written to. JBoss Enterprise Application Platform 6 file path variables can be specified here. Thejboss.server.log.dir
variable points to thelog/
directory of the server.Thepath
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 therelative-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"/>
Set the
suffix
ValueThesuffix
is appended to the filename of the rotated logs and is used to determine the frequency of rotation. The format of thesuffix
is a dot (.) followed by a date string, which is parsable by thejava.text.SimpleDateFormat
class. The log is rotated on the basis of the smallest time unit defined by thesuffix
. 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"/>
Set the
append
PropertyWhen theappend
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 toappend
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>
5.5.6. Sample XML Configuration for a Size Log Handler
Procedure 5.6. Configure the Size Log Handler
Add the Size Log Handler Identifier Information
Thename
property sets the unique identifier for this log handler.Whenautoflush
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">
Set the
level
PropertyThelevel
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"/>
Set the
encoding
OutputUseencoding
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"/>
Set the
file
ObjectThefile
object represents the file where the output of this log handler is written to. It has two configuration properties:relative-to
andpath
.Therelative-to
property is the directory where the log file is written to. JBoss Enterprise Application Platform 6 file path variables can be specified here. Thejboss.server.log.dir
variable points to thelog/
directory of the server.Thepath
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 therelative-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"/>
Specify the
rotate-size
ValueThe 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"/>
Set the
max-backup-index
NumberThe 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"/>
Specify the
formatter
Useformatter
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>
Set the
append
PropertyWhen theappend
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 toappend
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>
5.5.7. Sample XML Configuration for a Async Log Handler
Procedure 5.7. Configure the Async Log Handler
Add the Async Log Handler Identifier Information
Thename
property sets the unique identifier for this log handler.<async-handler name="Async_NFS_handlers">
Set the
level
PropertyThelevel
property sets the maximum level of log message that the root logger records.<async-handler name="Async_NFS_handlers"> <level name="INFO"/>
Define the
queue-length
Thequeue-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"/>
Set Overflow Response
Theoverflow-action
defines how this handler responds when its queue length is exceeded. This can be set toBLOCK
orDISCARD
.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"/>
List
subhandlers
Thesubhandlers
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>
Part IV. Set Up Cache Modes
Chapter 6. Cache Modes
- Local mode is the only non-clustered cache mode offered in JBoss Data Grid. In local mode, JBoss Data Grid operates as a simple single-node in-memory data cache. Local mode is most effective when scalability and failover are not required and provides high performance in comparison with clustered modes.
- Clustered mode replicates state changes to a small subset of nodes. The subset size is sufficient for fault tolerance purposes but not large enough to hinder scalability. Before attempting to use clustered mode, it is important to first configure JGroups for a clustered configuration. For details about configuring JGroups, see Section 24.3, “Configure JGroups (Library Mode)”
6.1. About Cache Containers
cache-container
element acts as a parent of one or more (local or clustered) caches. To add clustered caches to the container, transport must be defined.
Procedure 6.1. How to Configure the Cache Container
Specify the Cache Container
Thecache-container
element specifies information about the cache container using the following parameters:<subsystem xmlns="urn:infinispan:server:core:6.0" default-cache-container="default">
Set the Cache Container Name
Thename
parameter defines the name of the cache container.<subsystem xmlns="urn:infinispan:server:core:6.0" default-cache-container="default"> <cache-container name="default" />
Specify the Default Cache
Thedefault-cache
parameter defines the name of the default cache used with the cache container.<subsystem xmlns="urn:infinispan:server:core:6.0" default-cache-container="default"> <cache-container name="default" default-cache="default" />
Enable/Disable Statistics
Thestatistics
attribute is optional and istrue
by default. Statistics are useful in monitoring JBoss Data Grid via JMX or JBoss Operations Network, however they adversely affect performance. Disable this attribute by setting it tofalse
if it is not required.<subsystem xmlns="urn:infinispan:server:core:6.0" default-cache-container="default"> <cache-container name="default" default-cache="default" statistics="true"/>
Define the Listener Executor
Thelistener-executor
defines the executor used for asynchronous cache listener notifications.<subsystem xmlns="urn:infinispan:server:core:6.0" default-cache-container="default"> <cache-container name="default" default-cache="default" statistics="true" listener-executor="infinispan-listener" />
Set the Cache Container Start Mode
Thestart
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 areEAGER
andLAZY
.<subsystem xmlns="urn:infinispan:server:core:6.0" default-cache-container="default"> <cache-container name="default" default-cache="default" statistics="true" listener-executor="infinispan-listener" start="EAGER">
Per-cache Statistics
Ifstatistics
are enabled at the container level, per-cache statistics can be selectively disabled for caches that do not require monitoring by setting thestatistics
attribute tofalse
.<subsystem xmlns="urn:infinispan:server:core:6.0" default-cache-container="default"> <cache-container name="default" default-cache="default" statistics="true" listener-executor="infinispan-listener" start="EAGER"> <local-cache name="default" statistics="true"> ... </local-cache> </cache-container> </subsystem>
6.2. Local Mode
- Write-through and write-behind caching to persist data.
- Entry eviction to prevent the Java Virtual Machine (JVM) running out of memory.
- Support for entries that expire after a defined period.
ConcurrentMap
, resulting in a simple migration process from a map to JBoss Data Grid.
6.2.1. Configure Local Mode (Remote Client-Server Mode)
local-cache
element.
Procedure 6.2. The local-cache
Element
local-cache
element specifies information about the local cache used with the cache container using the following parameters:
Add the Local Cache Name
Thename
parameter specifies the name of the local cache to use.<cache-container name="local" default-cache="default" statistics="true"> <local-cache name="default" >
Set the Cache Container Start Mode
Thestart
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 areEAGER
andLAZY
.<cache-container name="local" default-cache="default" statistics="true"> <local-cache name="default" start="EAGER" >
Configure Batching
Thebatching
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" >
Per-cache Statistics
Ifstatistics
are enabled at the container level, per-cache statistics can be selectively disabled for caches that do not require monitoring by setting thestatistics
attribute tofalse
.<cache-container name="local" default-cache="default" statistics="true"> <local-cache name="default" start="EAGER" batching="false" statistics="true">
Specify Indexing Type
Theindexing
parameter specifies the type of indexing used for the local cache. Valid values for this parameter areNONE
,LOCAL
andALL
.<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>
DefaultCacheManager
with the "no-argument" constructor. Both of these methods create a local default cache.
<transport/>
it can only contain local caches. The container used in the example can only contain local caches as it does not have a <transport/>
.
ConcurrentMap
and is compatible with multiple cache systems.
6.2.2. Configure Local Mode (Library Mode)
mode
parameter to local
equals not specifying a clustering mode at all. In the case of the latter, the cache defaults to local mode, even if its cache manager defines a transport.
<clustering mode="local" />
6.3. Clustered Modes
- Replication Mode replicates any entry that is added across all cache instances in the cluster.
- Invalidation Mode does not share any data, but signals remote caches to initiate the removal of invalid entries.
- Distribution Mode stores each entry on a subset of nodes instead of on all nodes in the cluster.
6.3.1. Asynchronous and Synchronous Operations
6.3.2. Cache Mode Troubleshooting
6.3.2.1. Invalid Data in ReadExternal
readExternal
, it can be because when using Cache.putAsync()
, starting serialization can cause your object to be modified, causing the datastream passed to readExternal
to be corrupted. This can be resolved if access to the object is synchronized.
6.3.2.2. About Asynchronous Communications
local-cache
, distributed-cache
and replicated-cache
elements respectively. Each of these elements contains a mode
property, the value of which can be set to SYNC
for synchronous or ASYNC
for asynchronous communications.
<replicated-cache name="default" start="EAGER" mode="SYNC" batching="false" statistics="true"> ... </replicated-cache>
Note
6.3.2.3. Cluster Physical Address Retrieval
The physical address can be retrieved using an instance method call. For example: AdvancedCache.getRpcManager().getTransport().getPhysicalAddresses()
.
6.4. State Transfer
- In replication mode, the node joining the cluster receives a copy of the data currently on the other nodes in the cache. This occurs when the existing nodes push a part of the current cache state.
- In distribution mode, each node contains a slice of the entire key space, which is determined through consistent hashing. When a new node joins the cluster it receives a slice of the key space that has been taken from each of the existing nodes. State transfer results in the new node receiving a slice of the key space and the existing nodes shedding a portion of the data they were previously responsible for.
6.4.1. Non-Blocking State Transfer
- allows state transfer to occur without a drop in the performance of the cluster. However, if a drop in performance does occur during the state transfer it will not throw an exception, and will allow processes to continue.
- does not add a mechanism for resolving data conflicts after a merge, however it ensures it is feasible to add one in the future.
6.4.2. Suppress State Transfer via JMX
getCache()
call will timeout after stateTransfer.timeout
expires unless rebalancing is re-enabled or stateTransfer.awaitInitialTransfer
is set to false
.
6.4.3. The rebalancingEnabled Attribute
rebalancingEnabled
JMX attribute, and requires no specific configuration.
rebalancingEnabled
attribute can be modified for the entire cluster from the LocalTopologyManager
JMX Mbean on any node. This attribute is true
by default, and is configurable programmatically.
<await-initial-transfer="false"/>
Chapter 7. Set Up Distribution Mode
7.1. About Distribution Mode
7.2. Distribution Mode's Consistent Hash Algorithm
7.3. Locating Entries in Distribution Mode
PUT
operation can result in as many remote calls as specified by the num_copies
parameter, while a GET
operation executed on any node in the cluster results in a single remote call. In the background, the GET
operation results in the same number of remote calls as a PUT
operation (specifically the value of the num_copies
parameter), but these occur in parallel and the returned entry is passed to the caller as soon as one returns.
7.4. Return Values in Distribution Mode
7.5. Configure Distribution Mode (Remote Client-Server Mode)
Procedure 7.1. The distributed-cache
Element
distributed-cache
element configures settings for the distributed cache using the following parameters:
Add the Cache Name
Thename
parameter provides a unique identifier for the cache.<cache-container name="clustered" default-cache="default" statistics="true"> <transport executor="infinispan-transport" lock-timeout="60000"/> <distributed-cache name="default" />
Set the Clustered Cache Start Mode
Themode
parameter sets the clustered cache mode. Valid values areSYNC
(synchronous) andASYNC
(asynchronous).<cache-container name="clustered" default-cache="default" statistics="true"> <transport executor="infinispan-transport" lock-timeout="60000"/> <distributed-cache name="default" mode="SYNC" />
Specify Number of Segments
The (optional)segments
parameter specifies the number of hash space segments per cluster. The recommended value for this parameter is ten multiplied by the cluster size and the default value is80
.<cache-container name="clustered" default-cache="default" statistics="true"> <transport executor="infinispan-transport" lock-timeout="60000"/> <distributed-cache name="default" mode="SYNC" segments="20" />
Set the Cache Start Mode
Thestart
parameter specifies whether the cache starts when the server starts up or when it is requested or deployed.<cache-container name="clustered" default-cache="default" statistics="true"> <transport executor="infinispan-transport" lock-timeout="60000"/> <distributed-cache name="default" mode="SYNC" segments="20" start="EAGER"/>
Per-cache Statistics
Ifstatistics
are enabled at the container level, per-cache statistics can be selectively disabled for caches that do not require monitoring by setting thestatistics
attribute tofalse
.<cache-container name="clustered" default-cache="default" statistics="true"> <transport executor="infinispan-transport" lock-timeout="60000"/> <distributed-cache name="default" mode="SYNC" segments="20" start="EAGER" statistics="true"> ... </distributed-cache> </cache-container>
Important
cache-container
, locking
, and transaction
elements, see the appropriate chapter.
7.6. Configure Distribution Mode (Library Mode)
Procedure 7.2. Distributed Cache Configuration
Set the Clustered Mode
Theclustering
element'smode
parameter's value determines the clustering mode selected for the cache.<clustering mode="dist">
Specify the Remote Call Timeout
Thesync
element'sreplTimeout
parameter specifies the maximum time period in milliseconds for an acknowledgment after a remote call. If the time period ends without any acknowledgment, an exception is thrown.<clustering mode="dist"> <sync replTimeout="${TIME}" />
Define State Transfer Settings
ThestateTransfer
element specifies how state is transferred when a node leaves or joins the cluster. It uses the following parameters:Specify State Transfer Batch Size
ThechunkSize
parameter specifies the size of cache entry state batches to be transferred. If this value is greater than0
, the value set is the size of chunks sent. If the value is less than0
, all states are transferred at the same time.<clustering mode="dist"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" />
Set
fetchInMemoryState
ParameterThefetchInMemoryState
parameter when set totrue
, requests state information from neighboring caches on start up. This impacts the start up time for the cache.<clustering mode="dist"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" />
Define the
awaitInitialTransfer
ParameterTheawaitInitialTransfer
parameter causes the first call to methodCacheManager.getCache()
on the joiner node to block and wait until the joining is complete and the cache has finished receiving state from neighboring caches (iffetchInMemoryState
is enabled). This option applies to distributed and replicated caches only and is enabled by default.<clustering mode="dist"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" />
Set
timeout
ValueThetimeout
parameter specifies the maximum time (in milliseconds) the cache waits for responses from neighboring caches with the requested states. If no response is received within the thetimeout
period, the start up process aborts and an exception is thrown.<clustering mode="dist"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" timeout="${TIME}" />
Specify Transport Configuration
Thetransport
element defines the transport configuration for the cache as follows:Specify the Cluster Name
TheclusterName
parameter specifies the name of the cluster. Nodes can only connect to clusters that share the same name.<clustering mode="dist"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" timeout="${TIME}" /> <transport clusterName="${NAME}" />
Set the
distributedSyncTimeout
ValueThedistributedSyncTimeout
parameter specifies the time to wait to acquire a lock on the distributed lock. This distributed lock ensures that a single cache can transfer state or rehash state at a time.<clustering mode="dist"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" timeout="${TIME}" /> <transport clusterName="${NAME}" distributedSyncTimeout="${TIME}" />
Set the Network Transport
ThetransportClass
parameter specifies a class that represents a network transport for the cache.<clustering mode="dist"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" timeout="${TIME}" /> <transport clusterName="${NAME}" distributedSyncTimeout="${TIME}" transportClass="${CLASS}" /> </clustering>
7.7. Synchronous and Asynchronous Distribution
Example 7.1. Communication Mode example
A
, B
and C
, and a key K
that maps cache A
to B
. Perform an operation on cluster C
that requires a return value, for example Cache.remove(K)
. To execute successfully, the operation must first synchronously forward the call to both cache A
and B
, and then wait for a result returned from either cache A
or B
. If asynchronous communication was used, the usefulness of the returned values cannot be guaranteed, despite the operation behaving as expected.
7.8. GET and PUT Usage in Distribution Mode
GET
command before a write command. This occurs because certain methods (for example, Cache.put()
) return the previous value associated with the specified key according to the java.util.Map
contract. When this is performed on an instance that does not own the key and the entry is not found in the L1 cache, the only reliable way to elicit this return value is to perform a remote GET
before the PUT
.
GET
operation that occurs before the PUT
operation is always synchronous, whether the cache is synchronous or asynchronous, because Red Hat JBoss Data Grid must wait for the return value.
7.8.1. Distributed GET and PUT Operation Resource Usage
GET
operation before executing the desired PUT
operation.
GET
operation does not wait for all responses, which would result in wasted resources. The GET
process accepts the first valid response received, which allows its performance to be unrelated to cluster size.
Flag.SKIP_REMOTE_LOOKUP
flag for a per-invocation setting if return values are not required for your implementation.
java.util.Map
interface contract. The contract breaks because unreliable and inaccurate return values are provided to certain methods. As a result, ensure that these return values are not used for any important purpose on your configuration.
Chapter 8. Set Up Replication Mode
8.1. About Replication Mode
8.2. Optimized Replication Mode Usage
8.3. Configure Replication Mode (Remote Client-Server Mode)
Procedure 8.1. The replicated-cache
Element
replicated-cache
element configures settings for the distributed cache using the following parameters:
Add the Cache Name
Thename
parameter provides a unique identifier for the cache.<cache-container name="local" default-cache="default" statistics="true"> <replicated-cache name="default">
Set the Clustered Cache Start Mode
Themode
parameter sets the clustered cache mode. Valid values areSYNC
(synchronous) andASYNC
(asynchronous).<cache-container name="local" default-cache="default" statistics="true"> <replicated-cache name="default" mode="SYNC">
Set the Cache Start Mode
Thestart
parameter specifies whether the cache starts when the server starts up or when it is requested or deployed.<cache-container name="local" default-cache="default" statistics="true"> <replicated-cache name="default" mode="SYNC" start="EAGER">
Per-cache Statistics
Ifstatistics
are enabled at the container level, per-cache statistics can be selectively disabled for caches that do not require monitoring by setting thestatistics
attribute tofalse
.<cache-container name="local" default-cache="default" statistics="true"> <replicated-cache name="default" mode="SYNC" start="EAGER" statistics="true"> ... </replicated-cache> </cache-container>
Set Up Transactions
Thetransaction
element sets up the transaction mode for the replicated cache.<cache-container name="local" default-cache="default" statistics="true"> <replicated-cache name="default" mode="SYNC" start="EAGER" statistics="true"> <transaction mode="NONE" /> </replicated-cache> </cache-container>
Important
cache-container
, locking
, and transaction
elements, see the appropriate chapter.
8.4. Configure Replication Mode (Library Mode)
Procedure 8.2. Replication Mode Configuration
Set the Clustered Mode
Theclustering
element'smode
parameter's value determines the clustering mode selected for the cache.<clustering mode="repl">
Specify the Remote Call Timeout
Thesync
element'sreplTimeout
parameter specifies the maximum time period in milliseconds for an acknowledgment after a remote call. If the time period ends without any acknowledgment, an exception is thrown.<clustering mode="repl"> <sync replTimeout="${TIME}" />
Define State Transfer Settings
ThestateTransfer
element specifies how state is transferred when a node leaves or joins the cluster. It uses the following parameters:Specify State Transfer Batch Size
ThechunkSize
parameter specifies the size of cache entry state batches to be transferred. If this value is greater than0
, the value set is the size of chunks sent. If the value is less than0
, all states are transferred at the same time.<clustering mode="repl"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" />
Set
fetchInMemoryState
ParameterThefetchInMemoryState
parameter when set totrue
, requests state information from neighboring caches on start up. This impacts the start up time for the cache.<clustering mode="repl"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" />
Define the
awaitInitialTransfer
ParameterTheawaitInitialTransfer
parameter causes the first call to methodCacheManager.getCache()
on the joiner node to block and wait until the joining is complete and the cache has finished receiving state from neighboring caches (iffetchInMemoryState
is enabled). This option applies to distributed and replicated caches only and is enabled by default.<clustering mode="repl"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" />
Set the
timeout
ValueThetimeout
parameter specifies the maximum time (in milliseconds) the cache waits for responses from neighboring caches with the requested states. If no response is received within the thetimeout
period, the start up process aborts and an exception is thrown.<clustering mode="repl"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" timeout="${TIME}" />
Specify Transport Configuration
Thetransport
element defines the transport configuration for the cache as follows:Specify the Cluster Name
TheclusterName
parameter specifies the name of the cluster. Nodes can only connect to clusters that share the same name.<clustering mode="repl"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" timeout="${TIME}" /> <transport clusterName="${NAME}" />
Set the
distributedSyncTimeout
ValueThedistributedSyncTimeout
parameter specifies the time to wait to acquire a lock on the distributed lock. This distributed lock ensures that a single cache can transfer state or rehash state at a time.<clustering mode="repl"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" timeout="${TIME}" /> <transport clusterName="${NAME}" distributedSyncTimeout="${TIME}" />
Set the Network Transport
ThetransportClass
parameter specifies a class that represents a network transport for the cache.<clustering mode="repl"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" timeout="${TIME}" /> <transport clusterName="${NAME}" distributedSyncTimeout="${TIME}" transportClass="${CLASS}" /> </clustering>
8.5. Synchronous and Asynchronous Replication
- Synchronous replication blocks a thread or caller (for example on a
put()
operation) until the modifications are replicated across all nodes in the cluster. By waiting for acknowledgments, synchronous replication ensures that all replications are successfully applied before the operation is concluded. - Asynchronous replication operates significantly faster than synchronous replication because it does not need to wait for responses from nodes. Asynchronous replication performs the replication in the background and the call returns immediately. Errors that occur during asynchronous replication are written to a log. As a result, a transaction can be successfully completed despite the fact that replication of the transaction may not have succeeded on all the cache instances in the cluster.
8.5.1. Troubleshooting Asynchronous Replication Behavior
- Disable state transfer and use a
ClusteredCacheLoader
to lazily look up remote state as and when needed. - Enable state transfer and
REPL_SYNC
. Use the Asynchronous API (for example, thecache.putAsync(k, v)
) to activate 'fire-and-forget' capabilities. - Enable state transfer and
REPL_ASYNC
. All RPCs end up becoming synchronous, but client threads will not be held up if a replication queue is enabled (which is recommended for asynchronous mode).
8.6. The Replication Queue
- Previously set intervals.
- The queue size exceeding the number of elements.
- A combination of previously set intervals and the queue size exceeding the number of elements.
8.6.1. Replication Queue Usage
- Disable asynchronous marshalling; or
- Set the
max-threads
count value to1
for thetransport executor
. Thetransport executor
is defined instandalone.xml
as follows:<transport executor="infinispan-transport"/>
queue-flush-interval
, value is in milliseconds) and queue size (queue-size
) as follows:
<replicated-cache name="asyncCache" start="EAGER" mode="ASYNC" batching="false" indexing="NONE" statistics="true" queue-size="1000" queue-flush-interval="500"> ... </replicated-cache>
8.7. About Replication Guarantees
8.8. Replication Traffic on Internal Networks
IP
addresses than for traffic over public IP
addresses, or do not charge at all for internal network traffic (for example, GoGrid). To take advantage of lower rates, you can configure Red Hat JBoss Data Grid to transfer replication traffic using the internal network. With such a configuration, it is difficult to know the internal IP
address you are assigned. JBoss Data Grid uses JGroups interfaces to solve this problem.
Chapter 9. Set Up Invalidation Mode
9.1. About Invalidation Mode
9.2. Configure Invalidation Mode (Remote Client-Server Mode)
Procedure 9.1. The invalidation-cache
Element
invalidation-cache
element configures settings for the distributed cache using the following parameters:
Add the Cache Name
Thename
parameter provides a unique identifier for the cache.<cache-container name="local" default-cache="default" statistics="true"> <invalidation-cache name="default">
Set the Clustered Cache Start Mode
Themode
parameter sets the clustered cache mode. Valid values areSYNC
(synchronous) andASYNC
(asynchronous).<cache-container name="local" default-cache="default" statistics="true"> <invalidation-cache name="default" mode="ASYNC">
Set the Cache Start Mode
Thestart
parameter specifies whether the cache starts when the server starts up or when it is requested or deployed.<cache-container name="local" default-cache="default" statistics="true"> <invalidation-cache name="default" mode="ASYNC" start="EAGER">
Per-cache Statistics
Ifstatistics
are enabled at the container level, per-cache statistics can be selectively disabled for caches that do not require monitoring by setting thestatistics
attribute tofalse
.<cache-container name="local" default-cache="default" statistics="true"> <invalidation-cache name="default" mode="ASYNC" start="EAGER" statistics="true"> ... </invalidation-cache> </cache-container>
Important
cache-container
, locking
, and transaction
elements, see the appropriate chapter.
9.3. Configure Invalidation Mode (Library Mode)
Procedure 9.2. Invalidation Mode Configuration
Set the Clustered Mode
Theclustering
element'smode
parameter's value determines the clustering mode selected for the cache.<clustering mode="inv">
Specify the Remote Call Timeout
Thesync
element'sreplTimeout
parameter specifies the maximum time period in milliseconds for an acknowledgment after a remote call. If the time period ends without any acknowledgment, an exception is thrown.<clustering mode="inv"> <sync replTimeout="${TIME}" />
Define State Transfer Settings
ThestateTransfer
element specifies how state is transferred when a node leaves or joins the cluster. It uses the following parameters:Specify State Transfer Batch Size
ThechunkSize
parameter specifies the size of cache entry state batches to be transferred. If this value is greater than0
, the value set is the size of chunks sent. If the value is less than0
, all states are transferred at the same time.<clustering mode="inv"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" />
Set
fetchInMemoryState
ParameterThefetchInMemoryState
parameter when set totrue
, requests state information from neighboring caches on start up. This impacts the start up time for the cache.<clustering mode="inv"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" />
Define the
awaitInitialTransfer
ParameterTheawaitInitialTransfer
parameter causes the first call to methodCacheManager.getCache()
on the joiner node to block and wait until the joining is complete and the cache has finished receiving state from neighboring caches (iffetchInMemoryState
is enabled). This option applies to distributed and replicated caches only and is enabled by default.<clustering mode="inv"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" />
Set
timeout
ValueThetimeout
parameter specifies the maximum time (in milliseconds) the cache waits for responses from neighboring caches with the requested states. If no response is received within the thetimeout
period, the start up process aborts and an exception is thrown.<clustering mode="inv"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" timeout="${TIME}" />
Specify Transport Configuration
Thetransport
element defines the transport configuration for the cache as follows:Specify the Cluster Name
TheclusterName
parameter specifies the name of the cluster. Nodes can only connect to clusters that share the same name.<clustering mode="inv"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" timeout="${TIME}" /> <transport clusterName="${NAME}" />
Set the
distributedSyncTimeout
ValueThedistributedSyncTimeout
parameter specifies the time to wait to acquire a lock on the distributed lock. This distributed lock ensures that a single cache can transfer state or rehash state at a time.<clustering mode="inv"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" timeout="${TIME}" /> <transport clusterName="${NAME}" distributedSyncTimeout="${TIME}" />
Set the Network Transport
ThetransportClass
parameter specifies a class that represents a network transport for the cache.<clustering mode="inv"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" timeout="${TIME}" /> <transport clusterName="${NAME}" distributedSyncTimeout="${TIME}" transportClass="${CLASS}" /> </clustering>
9.4. Synchronous/Asynchronous Invalidation
- Synchronous invalidation blocks the thread until all caches in the cluster have received invalidation messages and evicted the obsolete data.
- Asynchronous invalidation operates in a fire-and-forget mode that allows invalidation messages to be broadcast without blocking a thread to wait for responses.
9.5. The L1 Cache and Invalidation
Part V. Set Up Locking for the Cache
Chapter 10. Locking
10.1. Configure Locking (Remote Client-Server Mode)
locking
element within the cache tags (for example, invalidation-cache
, distributed-cache
, replicated-cache
or local-cache
).
Procedure 10.1. Configure Locking (Remote Client-Server Mode)
Define the Isolation Level
Theisolation
parameter defines the isolation level used for the local cache. Valid values for this parameter areREPEATABLE_READ
andREAD_COMMITTED
.<distributed-cache> <locking isolation="REPEATABLE_READ" />
Set the
acquire-timeout
ParameterTheacquire-timeout
parameter specifies the number of milliseconds after which lock acquisition will time out.<distributed-cache> <locking isolation="REPEATABLE_READ" acquire-timeout="30000" />
Set Number of Lock Stripes
Theconcurrency-level
parameter defines the number of lock stripes used by the LockManager.<distributed-cache> <locking isolation="REPEATABLE_READ" acquire-timeout="30000" concurrency-level="1000" />
Set Lock Striping
Thestriping
parameter specifies whether lock striping will be used for the local cache.<distributed-cache> <locking isolation="REPEATABLE_READ" acquire-timeout="30000" concurrency-level="1000" striping="false" /> ... </distributed-cache>
10.2. Configure Locking (Library Mode)
locking
element and its parameters are set within the optional configuration
element on a per cache basis. For example, for the default cache, the configuration
element occurs within the default
element and for each named cache, it occurs within the namedCache
element. The following is an example of this configuration:
Procedure 10.2. Configure Locking (Library Mode)
Set the Concurrency Level
TheconcurrencyLevel
parameter specifies the concurrency level for the lock container. Set this value according to the number of concurrent threads interacting with the data grid.<infinispan> ... <default> <locking concurrencyLevel="${VALUE}" />
Specify the Cache Isolation Level
TheisolationLevel
parameter specifies the cache's isolation level. Valid isolation levels areREAD_COMMITTED
andREPEATABLE_READ
. For details about isolation levels, see Section 12.1, “About Isolation Levels”<infinispan> ... <default> <locking concurrencyLevel="${VALUE}" isolationLevel="${LEVEL}" />
Set the Lock Acquisition Timeout
ThelockAcquisitionTimeout
parameter specifies time (in milliseconds) after which a lock acquisition attempt times out.<infinispan> ... <default> <locking concurrencyLevel="${VALUE}" isolationLevel="${LEVEL}" lockAcquisitionTimeout="${TIME}" />
Configure Lock Striping
TheuseLockStriping
parameter specifies whether a pool of shared locks are maintained for all entries that require locks. If set toFALSE
, locks are created for each entry in the cache. For details, see Section 11.1, “About Lock Striping”<infinispan> ... <default> <locking concurrencyLevel="${VALUE}" isolationLevel="${LEVEL}" lockAcquisitionTimeout="${TIME}" useLockStriping="${TRUE/FALSE}" />
Set
writeSkewCheck
ParameterThewriteSkewCheck
parameter is only valid if theisolationLevel
is set toREPEATABLE_READ
. If this parameter is set toFALSE
, a disparity between a working entry and the underlying entry at write time results in the working entry overwriting the underlying entry. If the parameter is set toTRUE
, such conflicts (namely write skews) throw an exception.<infinispan> ... <default> <locking concurrencyLevel="${VALUE}" isolationLevel="${LEVEL}" lockAcquisitionTimeout="${TIME}" useLockStriping="${TRUE/FALSE}" writeSkewCheck="${TRUE/FALSE}" />
10.3. Locking Types
10.3.1. About Optimistic Locking
writeSkewCheck
enabled, transactions in optimistic locking mode roll back if one or more conflicting modifications are made to the data before the transaction completes.
10.3.2. About Pessimistic Locking
10.3.3. Pessimistic Locking Types
- Explicit Pessimistic Locking, which uses the JBoss Data Grid Lock API to allow cache users to explicitly lock cache keys for the duration of a transaction. The Lock call attempts to obtain locks on specified cache keys across all nodes in a cluster. This attempt either fails or succeeds for all specified cache keys. All locks are released during the commit or rollback phase.
- Implicit Pessimistic Locking ensures that cache keys are locked in the background as they are accessed for modification operations. Using Implicit Pessimistic Locking causes JBoss Data Grid to check and ensure that cache keys are locked locally for each modification operation. Discovering unlocked cache keys causes JBoss Data Grid to request a cluster-wide lock to acquire a lock on the unlocked cache key.
10.3.4. Explicit Pessimistic Locking Example
Procedure 10.3. Transaction with Explicit Pessimistic Locking
- When the line
cache.lock(K)
executes, a cluster-wide lock is acquired onK
.tx.begin() cache.lock(K)
- When the line
cache.put(K,V5)
executes, it guarantees success.tx.begin() cache.lock(K) cache.put(K,V5)
- 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()
10.3.5. Implicit Pessimistic Locking Example
Procedure 10.4. Transaction with Implicit Pessimistic locking
- When the line
cache.put(K,V)
executes, a cluster-wide lock is acquired onK
.tx.begin() cache.put(K,V)
- When the line
cache.put(K2,V2)
executes, a cluster-wide lock is acquired onK2
.tx.begin() cache.put(K,V) cache.put(K2,V2)
- When the line
cache.put(K,V5)
executes, the lock acquisition is non operational because a cluster-wide lock forK
has been previously acquired. Theput
operation will still occur.tx.begin() cache.put(K,V) cache.put(K2,V2) cache.put(K,V5)
- 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()
10.3.6. Configure Locking Mode (Remote Client-Server Mode)
locking
parameter within the transaction
element as follows:
<transaction locking="OPTIMISTIC/PESSIMISTIC" />
10.3.7. Configure Locking Mode (Library Mode)
transaction
element as follows:
<transaction transactionManagerLookupClass="{TransactionManagerLookupClass}" transactionMode="{TRANSACTIONAL,NON_TRANSACTIONAL}" lockingMode="{OPTIMISTIC,PESSIMISTIC}" useSynchronization="true"> </transaction>
lockingMode
value to OPTIMISTIC
or PESSIMISTIC
to configure the locking mode used for the transactional cache.
10.4. Locking Operations
10.4.1. About the LockManager
LockManager
component is responsible for locking an entry before a write process initiates. The LockManager
uses a LockContainer
to locate, hold and create locks. The two types of LockContainers
generally used in such implementations are available. The first type offers support for lock striping while the second type supports one lock per entry.
See Also:
10.4.2. About Lock Acquisition
10.4.3. About Concurrency Levels
ConcurrentHashMap
based collections, such as those internal to DataContainers
.
Chapter 11. Set Up Lock Striping
11.1. About Lock Striping
11.2. Configure Lock Striping (Remote Client-Server Mode)
striping
element to true
.
<locking isolation="REPEATABLE_READ" acquire-timeout="20000" concurrency-level="500" striping="true" />
11.3. Configure Lock Striping (Library Mode)
useLockStriping
parameter as follows:
<infinispan> ... <default> <locking concurrencyLevel="${VALUE}" isolationLevel="${LEVEL}" lockAcquisitionTimeout="${TIME}" useLockStriping="${TRUE/FALSE}" writeSkewCheck="${TRUE/FALSE}" /> ... </default> </infinispan>
useLockStriping
parameter specifies whether a pool of shared locks are maintained for all entries that require locks. If set to FALSE
, locks are created for each entry in the cache. If set to TRUE
, lock striping is enabled and shared locks are used as required from the pool.
concurrencyLevel
is used to specify the size of the shared lock collection use when lock striping is enabled.
isolationLevel
parameter specifies the cache's isolation level. Valid isolation levels are READ_COMMITTED
and REPEATABLE_READ
.
lockAcquisitionTimeout
parameter specifies time (in milliseconds) after which a lock acquisition attempt times out.
writeSkewCheck
check determines if a modification to the entry from a different transaction should roll back the transaction. Write skew set to true requires isolation_level
set to REPEATABLE_READ
. The default value for writeSkewCheck
and isolation_level
are FALSE
and READ_COMMITTED
respectively.
Chapter 12. Set Up Isolation Levels
12.1. About Isolation Levels
READ_COMMITTED
and REPEATABLE_READ
are the two isolation modes offered in Red Hat JBoss Data Grid.
READ_COMMITTED
. This is the default isolation level because it is applicable to a wide variety of requirements.REPEATABLE_READ
. This can be configured using thelocking
configuration element.
- See Section 11.2, “Configure Lock Striping (Remote Client-Server Mode)” for a Remote Client-Server mode configuration sample.
- See Section 11.3, “Configure Lock Striping (Library Mode)” for a Library mode configuration sample.
12.2. About READ_COMMITTED
READ_COMMITTED
is one of two isolation modes available in Red Hat JBoss Data Grid.
READ_COMMITTED
mode, write operations are made to copies of data rather than the data itself. A write operation blocks other data from being written, however writes do not block read operations. As a result, both READ_COMMITTED
and REPEATABLE_READ
modes permit read operations at any time, regardless of when write operations occur.
READ_COMMITTED
mode multiple reads of the same key within a transaction can return different results due to write operations modifying data between reads. This phenomenon is known as non-repeatable reads and is avoided in REPEATABLE_READ
mode.
12.3. About REPEATABLE_READ
REPEATABLE_READ
is one of two isolation modes available in Red Hat JBoss Data Grid.
REPEATABLE_READ
does not allow write operations while read operations are in progress, nor does it allow read operations when write operations occur. This prevents the "non-repeatable read" phenomenon, which occurs when a single transaction has two read operations on the same row but the retrieved values differ (possibly due to a write operating modifying the value between the two read operations).
REPEATABLE_READ
isolation mode preserves the value of a row before a modification occurs. As a result, the "non-repeatable read" phenomenon is avoided because a second read operation on the same row retrieves the preserved value rather than the new modified value. As a result, the two values retrieved by the two read operations will always match, even if a write operation occurs between the two reads.
Part VI. Set Up and Configure a Cache Store
Chapter 13. Cache Stores
- fetch data from the data store when a copy is not in the cache.
- push modifications made to the data in cache back to the data store.
13.1. File System Based Cache Stores
SingleFileCacheStore
.
SingleFileCacheStore
is a simple, file system based implementation and a replacement to the older file system based cache store: the FileCacheStore
.
SingleFileCacheStore
stores all key/value pairs and their corresponding metadata information in a single file. To speed up data location, it also keeps all keys and the positions of their values and metadata in memory. Hence, using the single file cache store slightly increases the memory required, depending on the key size and the amount of keys stored. Hence SingleFileCacheStore
is not recommended for use cases where the keys are too big.
SingleFileCacheStore
can be used in a limited capacity in production environments. It can not be used on shared file system (such as NFS and Windows shares) due to a lack of proper file locking, resulting in data corruption. Furthermore, file systems are not inherently transactional, resulting in file writing failures during the commit phase if the cache is used in a transactional context.
13.1.1. Single File Store Configuration (Remote Client-Server Mode)
Procedure 13.1. Configure the Single File Store
Add the Cache Name
Thename
parameter of thelocal-cache
attribute is used to specify a name for the cache.<local-cache name="default">
Per-cache Statistics
Ifstatistics
are enabled at the container level, per-cache statistics can be selectively disabled for caches that do not require monitoring by setting thestatistics
attribute tofalse
.<local-cache name="default" statistics="true">
Configure the
file-store
ElementThefile-store
element specifies configuration information for the single file store.Thename
parameter of thefile-store
element is used to specify a name for the file store.<local-cache name="default" statistics="true"> <file-store name="myFileStore" />
Set the passivation Parameter
Thepassivation
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" />
Set the
purge
ParameterThepurge
parameter specifies whether or not the cache store is purged when it is started. Valid values for this parameter aretrue
andfalse
.<local-cache name="default" statistics="true"> <file-store name="myFileStore" passivation="true" purge="true" />
Set the
shared
ParameterTheshared
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 aretrue
andfalse
. However, theshared
parameter is not recommended forfile-store
.<local-cache name="default" statistics="true"> <file-store name="myFileStore" passivation="true" purge="true" shared="false" />
Specify the Directory Path Within the
relative-to
ParameterTherelative-to
property is the directory where thefile-store
stores the data. It is used to define a named path.Thepath
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 therelative-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>
Specify the maximum number of entries
ThemaxEntries
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>
Set the fetch-state Parameter
Thefetch-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>
Set the preload Parameter
Thepreload
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>
Set the singleton Parameter
Thesingleton
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 forfile-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>
13.1.2. Single File Store Configuration (Library Mode)
Procedure 13.2. Configuring the Single File Store in Library Mode
infinispan.xml
.
- Add the name value to the
namedCache
element. The following is an example of this step:<namedCache name="writeThroughToFile">
- In the
persistence
element, set thepassivation
parameter tofalse
. Possible values are true and false.<namedCache name="writeThroughToFile"> <persistence passivation="false" />
- Set up a single file configuration using the
singleFile
element:fetchPersistentState
- If set totrue
, the persistent state is fetched when joining a cluster. If multiple cache stores are chained, only one cache store can have this property set totrue
. The default for this value isfalse
.- 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 totrue
when multiple cache instances share a cache store, which prevents multiple cache instances writing the same modification individually. The default for this attribute isfalse
. However, theshared
parameter is not recommended forfile-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 isfalse
. - 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 themaxKeysInMemory
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>
- 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 is5
. - 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 is1
. - 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 is1024
elements. - The
shutdownTimeout
parameter specifies the time to stop the cache store. Default value for this parameter is25
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>
13.1.3. Migrating data from FileCacheStore to SingleFileCacheStore
13.2. Remote Cache Stores
RemoteCacheStore
is an implementation of the cache loader that stores data in a remote Red Hat JBoss Data Grid cluster. The RemoteCacheStore
uses the Hot Rod client-server architecture to communicate with the remote cluster.
RemoteCacheStore
and the cluster.
13.2.1. Remote Cache Store Configuration (Remote Client-Server Mode)
Procedure 13.3. Configure the Remote Cache Store
remote-store
element define the following information:
- The
cache
parameter defines the name for the remote cache. If left undefined, the default cache is used instead.<remote-store cache="default">
- The
socket-timeout
parameter sets whether the value defined inSO_TIMEOUT
(in milliseconds) applies to remote Hot Rod servers on the specified timeout. A timeout value of0
indicates an infinite timeout.<remote-store cache="default" socket-timeout="60000">
- The
tcp-no-delay
sets whetherTCP_NODELAY
applies on socket connections to remote Hot Rod servers.<remote-store cache="default" socket-timeout="60000" tcp-no-delay="true">
- 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">
- The single parameter for the
remote-server
element is as follows:- 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>
13.2.2. Remote Cache Store Configuration (Library Mode)
Procedure 13.4. Remote Cache Store Configuration
Configure the Persistence Element
Create apersistence
element, with thepassivation
set tofalse
.<persistence passivation="false" />
- Create a
remoteStore
element within thepersistence
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 totrue
, 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 totrue
. The default for this value isfalse
. - Add the
shared
attribute. This is set totrue
when multiple cache instances share a cache store, which prevents multiple cache instances writing the same modification individually. The default for this attribute isfalse
. - Add the
preload
attribute. When set totrue
, the cache store data is pre-loaded into memory and becomes immediately accessible after starting up. The disadvantage of setting this totrue
is that the start up time increases. The default value for this attribute isfalse
. - 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 isfalse
. - Add the
purgeOnStartup
attribute. If set totrue
, the cache store is purged during the start up process. The default value for this attribute isfalse
. - Add the
tcpNoDelay
attribute. If set totrue
, this triggers theTCP
NODELAY
stack. The default value for this attribute istrue
. - Add the
pingOnStartup
attribute. If set totrue
, a ping request is sent to a back end server to fetch the cluster topology. The default value for this attribute istrue
. - 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 is64
. - Add the
valueSizeEstimate
attribute. This value is the size of the byte buffers when serializing and deserializing values. The default value for this attribute is512
. - Add the
forceReturnValues
attribute. This attribute sets whetherFORCE_RETURN_VALUE
is enabled for all calls. The default value for this attribute isfalse
.
- Create a
servers
element within theremoteStore
element to set up the server information. Add aserver
element within the generalservers
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.
- Create a
connectionPool
element to theremoteStore
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.
13.2.3. Define the Outbound Socket for the Remote Cache Store
outbound-socket-binding
element in a standalone.xml
file.
standalone.xml
file is as follows:
<server> ... <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}"> ... <outbound-socket-binding name="remote-store-hotrod-server"> <remote-destination host="remote-host" port="11222"/> </outbound-socket-binding> </socket-binding-group> </server>
13.3. Custom Cache Stores
Important
13.3.1. Custom Cache Store Configuration (Remote Client-Server Mode)
<local-cache name="default" statistics="true"> <store class="my.package.CustomCacheStore"> <properties> <property name="customStoreProperty" value="10" /> </properties> </store> </local-cache>
Important
org.jboss.as.clustering.infinispan
module dependencies.
Important
13.3.2. Custom Cache Store Configuration (Library Mode)
<persistence> <store class="org.infinispan.custom.CustomCacheStore" preload="true" shared="true"> <properties> <property name="customStoreProperty" value="10" /> </properties> </store> </persistence>
Important
13.4. About Asynchronous Cache Store Modifications
13.5. LevelDB Cache Store
13.5.1. Configuring LevelDB Cache Store
Procedure 13.5. To configure LevelDB Cache Store:
- Obtain the
leveldbjni-all-1.7.jar
file from https://github.com/fusesource/leveldbjni and copy it to themodules/system/layers/base/org/fusesource/leveldbjni-all/main
directory. - 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>
- 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>
Note
leveldbjni-all-1.7.jar
from https://github.com/fusesource/leveldbjni to your JBoss Data Grid deployment.
13.5.2. LevelDB Cache Store Programmatic Configuration
Procedure 13.6. LevelDB Cache Store programmatic configuration
Create a New Configuration Builder
Use theConfigurationBuilder
to create a new configuration object.Configuration cacheConfig = new ConfigurationBuilder().persistence()
Add the LevelDBStoreConfigurationBuilder Store
Add the store to theLevelDBCacheStoreConfigurationBuilder
instance to build its configuration.Configuration cacheConfig = new ConfigurationBuilder().persistence() .addStore(LevelDBStoreConfigurationBuilder.class)
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")
Set Up Expired Location
Specify the location for expired data using theexpiredLocation
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();
Note
13.5.3. LevelDB Cache Store Sample XML Configuration (Library Mode)
Procedure 13.7. LevelDB Cache Store Sample XML Configuration
Add the namedCache Element
Specify the LevelDB Cache Store's name using thename
parameter in thenamedCache
element as follows:<namedCache name="vehicleCache">
Add the persistence Element
Specify the value forpassivation
parameter in thepersistence
element as follows. Possible values are true and false.<namedCache name="vehicleCache"> <persistence passivation="false">
Add the leveldbStore Element
Specify the location to store the primary cache store date using thelocation
parameter in theleveldbStore
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" />
Set the Expired Value
Specify the location for expired data using theexpiredLocation
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" />
Set the Shared Parameter
Specify the value forshared
parameter in theleveldbStore
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" />
Set the Preload Parameter
Specify the value forpreload
parameter in theleveldbStore
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>
Chapter 14. Datasource Management
14.1. About JDBC
14.2. Types of Datasources
datasources
and XA datasources
.
14.3. Using JDBC Drivers
14.3.1. Install a JDBC Driver as a Core Module
Before performing this task, you need to meet the following prerequisites:
- Download the JDBC driver from your database vendor. JDBC driver download locations are listed here: Section 14.3.2, “JDBC Driver Download Locations”.
- Extract the archive.
Procedure 14.1. Install a JDBC Driver as a Core Module
- 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/
. - Copy the JDBC driver JAR into the
main/
subdirectory. - In the
main/
subdirectory, create amodule.xml
file. The following is an example of amodule.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>
- Start the Server.
- Start the Management CLI.
- 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)
The JDBC driver is now installed and set up as a core module, and is available to be referenced by application datasources.
14.3.2. JDBC Driver Download Locations
Vendor | Download Location |
---|---|
MySQL | |
PostgreSQL | |
Oracle | |
IBM | |
Sybase | |
Microsoft |
14.3.3. Access Vendor Specific Classes
This topic covers the steps required to use the JDBC specific classes. This is necessary when an application uses a vendor specific functionality that is not part of the JDBC API.
Warning
Important
Important
Prerequisites
Procedure 14.2. Add a Dependency to the Application
Configure the
MANIFEST.MF
file- Open the application's
META-INF/MANIFEST.MF
file in a text editor. - Add a dependency for the JDBC module and save the file.
Dependencies: MODULE_NAME
Example 14.2. Example Dependency
Dependencies: com.mysql
Create a
jboss-deployment-structure.xml
fileCreate a file calledjboss-deployment-structure.xml
in theMETA-INF/
orWEB-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>
Example 14.4. Access the Vendor Specific API
import java.sql.Connection; import org.jboss.jca.adapters.jdbc.WrappedConnection; Connection c = ds.getConnection(); WrappedConnection wc = (WrappedConnection)c; com.mysql.jdbc.Connection mc = wc.getUnderlyingConnection();
14.4. Datasource Configuration
14.4.1. Datasource Parameters
Parameter | Description |
---|---|
jndi-name | The unique JNDI name for the datasource. |
pool-name | The name of the management pool for the datasource. |
enabled | Whether or not the datasource is enabled. |
use-java-context |
Whether to bind the datasource to global JNDI.
|
spy |
Enable
spy functionality on the JDBC layer. This logs all JDBC traffic to the datasource. Note that the logging category jboss.jdbc.spy must also be set to the log level DEBUG in the logging subsystem.
|
use-ccm | Enable the cached connection manager. |
new-connection-sql | A SQL statement which executes when the connection is added to the connection pool. |
transaction-isolation |
One of the following:
|
url-delimiter | The delimiter for URLs in a connection-url for High Availability (HA) clustered databases. |
url-selector-strategy-class-name | A class that implements interface org.jboss.jca.adapters.jdbc.URLSelectorStrategy . |
security |
Contains child elements which are security settings. See Table 14.7, “Security parameters”.
|
validation |
Contains child elements which are validation settings. See Table 14.8, “Validation parameters”.
|
timeout |
Contains child elements which are timeout settings. See Table 14.9, “Timeout parameters”.
|
statement |
Contains child elements which are statement settings. See Table 14.10, “Statement parameters”.
|
Parameter | Description |
---|---|
jta | Enable JTA integration for non-XA datasources. Does not apply to XA datasources. |
connection-url | The JDBC driver connection URL. |
driver-class | The fully-qualified name of the JDBC driver class. |
connection-property |
Arbitrary connection properties passed to the method
Driver.connect(url,props) . Each connection-property specifies a string name/value pair. The property name comes from the name, and the value comes from the element content.
|
pool |
Contains child elements which are pooling settings. See Table 14.5, “Pool parameters common to non-XA and XA datasources”.
|
Parameter | Description |
---|---|
xa-datasource-property |
A property to assign to implementation class
XADataSource . Specified by name=value. If a setter method exists, in the format setName , the property is set by calling a setter method in the format of setName(value) .
|
xa-datasource-class |
The fully-qualified name of the implementation class
javax.sql.XADataSource .
|
driver |
A unique reference to the classloader module which contains the JDBC driver. The accepted format is driverName#majorVersion.minorVersion.
|
xa-pool |
Contains child elements which are pooling settings. See Table 14.5, “Pool parameters common to non-XA and XA datasources” and Table 14.6, “XA pool parameters”.
|
recovery |
Contains child elements which are recovery settings. See Table 14.11, “Recovery parameters”.
|
Parameter | Description |
---|---|
min-pool-size | The minimum number of connections a pool holds. |
max-pool-size | The maximum number of connections a pool can hold. |
prefill | Whether to try to prefill the connection pool. An empty element denotes a true value. The default is false . |
use-strict-min | Whether the pool-size is strict. Defaults to false . |
flush-strategy |
Whether the pool is flushed in the case of an error. Valid values are:
The default is
FailingConnectionOnly .
|
allow-multiple-users | Specifies if multiple users will access the datasource through the getConnection(user, password) method, and whether the internal pool type accounts for this behavior. |
Parameter | Description |
---|---|
is-same-rm-override | Whether the javax.transaction.xa.XAResource.isSameRM(XAResource) class returns true or false . |
interleaving | Whether to enable interleaving for XA connection factories. |
no-tx-separate-pools |
Whether to create separate sub-pools for each context. This is required for Oracle datasources, which do not allow XA connections to be used both inside and outside of a JTA transaction.
Using this option will cause your total pool size to be twice
max-pool-size , because two actual pools will be created.
|
pad-xid | Whether to pad the Xid. |
wrap-xa-resource |
Whether to wrap the XAResource in an
org.jboss.tm.XAResourceWrapper instance.
|
Parameter | Description |
---|---|
user-name | The username to use to create a new connection. |
password | The password to use to create a new connection. |
security-domain | Contains the name of a JAAS security-manager which handles authentication. This name correlates to the application-policy/name attribute of the JAAS login configuration. |
reauth-plugin | Defines a reauthentication plug-in to use to reauthenticate physical connections. |
Parameter | Description |
---|---|
valid-connection-checker |
An implementation of interface
org.jboss.jca.adaptors.jdbc.ValidConnectionChecker which provides a SQLException.isValidConnection(Connection e) method to validate a connection. An exception means the connection is destroyed. This overrides the parameter check-valid-connection-sql if it is present.
|
check-valid-connection-sql | An SQL statement to check validity of a pool connection. This may be called when a managed connection is taken from a pool for use. |
validate-on-match |
Indicates whether connection level validation is performed when a connection factory attempts to match a managed connection for a given set.
Specifying "true" for
validate-on-match is typically not done in conjunction with specifying "true" for background-validation . Validate-on-match is needed when a client must have a connection validated prior to use. This parameter is false by default.
|
background-validation |
Specifies that connections are validated on a background thread. Background validation is a performance optimization when not used with
validate-on-match . If validate-on-match is true, using background-validation could result in redundant checks. Background validation does leave open the opportunity for a bad connection to be given to the client for use (a connection goes bad between the time of the validation scan and prior to being handed to the client), so the client application must account for this possibility.
|
background-validation-millis | The amount of time, in milliseconds, that background validation runs. |
use-fast-fail |
If true, fail a connection allocation on the first attempt, if the connection is invalid. Defaults to
false .
|
stale-connection-checker |
An instance of
org.jboss.jca.adapters.jdbc.StaleConnectionChecker which provides a Boolean isStaleConnection(SQLException e) method. If this method returns true , the exception is wrapped in an org.jboss.jca.adapters.jdbc.StaleConnectionException , which is a subclass of SQLException .
|
exception-sorter |
An instance of
org.jboss.jca.adapters.jdbc.ExceptionSorter which provides a Boolean isExceptionFatal(SQLException e) method. This method validates whether an exception is broadcast to all instances of javax.resource.spi.ConnectionEventListener as a connectionErrorOccurred message.
|
Parameter | Description |
---|---|
use-try-lock | Uses tryLock() instead of lock() . This attempts to obtain the lock for the configured number of seconds, before timing out, rather than failing immediately if the lock is unavailable. Defaults to 60 seconds. As an example, to set a timeout of 5 minutes, set <use-try-lock> 300</use-try-lock> . |
blocking-timeout-millis | The maximum time, in milliseconds, to block while waiting for a connection. After this time is exceeded, an exception is thrown. This blocks only while waiting for a permit for a connection, and does not throw an exception if creating a new connection takes a long time. Defaults to 30000, which is 30 seconds. |
idle-timeout-minutes |
The maximum time, in minutes, before an idle connection is closed. The actual maximum time depends upon the idleRemover scan time, which is half of the smallest
idle-timeout-minutes of any pool.
|
set-tx-query-timeout |
Whether to set the query timeout based on the time remaining until transaction timeout. Any configured query timeout is used if no transaction exists. Defaults to
false .
|
query-timeout | Timeout for queries, in seconds. The default is no timeout. |
allocation-retry | The number of times to retry allocating a connection before throwing an exception. The default is 0 , so an exception is thrown upon the first failure. |
allocation-retry-wait-millis |
How long, in milliseconds, to wait before retrying to allocate a connection. The default is 5000, which is 5 seconds.
|
xa-resource-timeout |
If non-zero, this value is passed to method
XAResource.setTransactionTimeout .
|
Parameter | Description |
---|---|
track-statements |
Whether to check for unclosed statements when a connection is returned to a pool and a statement is returned to the prepared statement cache. If false, statements are not tracked.
|
prepared-statement-cache-size | The number of prepared statements per connection, in a Least Recently Used (LRU) cache. |
share-prepared-statements |
Whether asking for the same statement twice without closing it uses the same underlying prepared statement. The default is
false .
|
Parameter | Description |
---|---|
recover-credential | A username/password pair or security domain to use for recovery. |
recover-plugin |
An implementation of the
org.jboss.jca.core.spi.recoveryRecoveryPlugin class, to be used for recovery.
|
14.4.2. Datasource Connection URLs
Datasource | Connection URL |
---|---|
PostgreSQL | jdbc:postgresql://SERVER_NAME:PORT/DATABASE_NAME |
MySQL | jdbc:mysql://SERVER_NAME:PORT/DATABASE_NAME |
Oracle | jdbc:oracle:thin:@ORACLE_HOST:PORT:ORACLE_SID |
IBM DB2 | jdbc:db2://SERVER_NAME:PORT/DATABASE_NAME |
Microsoft SQLServer | jdbc:microsoft:sqlserver://SERVER_NAME:PORT;DatabaseName=DATABASE_NAME |
14.4.3. Datasource Extensions
Datasource Extension | Configuration Parameter | Description |
---|---|---|
org.jboss.jca.adapters.jdbc.spi.ExceptionSorter | <exception-sorter> | Checks whether an SQLException is fatal for the connection on which it was thrown |
org.jboss.jca.adapters.jdbc.spi.StaleConnection | <stale-connection-checker> | Wraps stale SQLExceptions in a org.jboss.jca.adapters.jdbc.StaleConnectionException |
org.jboss.jca.adapters.jdbc.spi.ValidConnection | <valid-connection-checker> | Checks whether a connection is valid for use by the application |
Extension Implementations
- Generic
- org.jboss.jca.adapters.jdbc.extensions.novendor.NullExceptionSorter
- org.jboss.jca.adapters.jdbc.extensions.novendor.NullStaleConnectionChecker
- org.jboss.jca.adapters.jdbc.extensions.novendor.NullValidConnectionChecker
- org.jboss.jca.adapters.jdbc.extensions.novendor.JDBC4ValidConnectionChecker
- PostgreSQL
- org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
- org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
- MySQL
- org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
- org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLReplicationValidConnectionChecker
- org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker
- IBM DB2
- org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter
- org.jboss.jca.adapters.jdbc.extensions.db2.DB2StaleConnectionChecker
- org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker
- Sybase
- org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter
- org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker
- Microsoft SQLServer
- org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker
- Oracle
- org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter
- org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnectionChecker
- org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker
14.4.4. View Datasource Statistics
jdbc
and pool
using appropriately modified versions of the commands below:
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)
Note
include-runtime=true
argument, as all statistics are runtime only information and the default is false
.
14.4.5. Datasource Statistics
The following table contains a list of the supported datasource core statistics:
Name | Description |
---|---|
ActiveCount |
The number of active connections. Each of the connections is either in use by an application or available in the pool
|
AvailableCount |
The number of available connections in the pool.
|
AverageBlockingTime |
The average time spent blocking on obtaining an exclusive lock on the pool. The value is in milliseconds.
|
AverageCreationTime |
The average time spent creating a connection. The value is in milliseconds.
|
CreatedCount |
The number of connections created.
|
DestroyedCount |
The number of connections destroyed.
|
InUseCount |
The number of connections currently in use.
|
MaxCreationTime |
The maximum time it took to create a connection. The value is in milliseconds.
|
MaxUsedCount |
The maximum number of connections used.
|
MaxWaitCount |
The maximum number of requests waiting for a connection at the same time.
|
MaxWaitTime |
The maximum time spent waiting for an exclusive lock on the pool.
|
TimedOut |
The number of timed out connections.
|
TotalBlockingTime |
The total time spent waiting for an exclusive lock on the pool. The value is in milliseconds.
|
TotalCreationTime |
The total time spent creating connections. The value is in milliseconds.
|
WaitCount |
The number of requests that had to wait for a connection.
|
The following table contains a list of the supported datasource JDBC statistics:
Name | Description |
---|---|
PreparedStatementCacheAccessCount |
The number of times that the statement cache was accessed.
|
PreparedStatementCacheAddCount |
The number of statements added to the statement cache.
|
PreparedStatementCacheCurrentSize |
The number of prepared and callable statements currently cached in the statement cache.
|
PreparedStatementCacheDeleteCount |
The number of statements discarded from the cache.
|
PreparedStatementCacheHitCount |
The number of times that statements from the cache were used.
|
PreparedStatementCacheMissCount |
The number of times that a statement request could not be satisfied with a statement from the cache.
|
14.5. Example Datasources
14.5.1. Example PostgreSQL Datasource
Example 14.5.
<datasources> <datasource jndi-name="java:jboss/PostgresDS" pool-name="PostgresDS"> <connection-url>jdbc:postgresql://localhost:5432/postgresdb</connection-url> <driver>postgresql</driver> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <background-validation>true</background-validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"></valid-connection-checker> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"></exception-sorter> </validation> </datasource> <drivers> <driver name="postgresql" module="org.postgresql"> <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
module.xml
file for the PostgreSQL datasource above.
<module xmlns="urn:jboss:module:1.1" name="org.postgresql"> <resources> <resource-root path="postgresql-9.1-902.jdbc4.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
14.5.2. Example PostgreSQL XA Datasource
Example 14.6.
<datasources> <xa-datasource jndi-name="java:jboss/PostgresXADS" pool-name="PostgresXADS"> <driver>postgresql</driver> <xa-datasource-property name="ServerName">localhost</xa-datasource-property> <xa-datasource-property name="PortNumber">5432</xa-datasource-property> <xa-datasource-property name="DatabaseName">postgresdb</xa-datasource-property> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <background-validation>true</background-validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"> </valid-connection-checker> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"> </exception-sorter> </validation> </xa-datasource> <drivers> <driver name="postgresql" module="org.postgresql"> <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
module.xml
file for the PostgreSQL XA datasource above.
<module xmlns="urn:jboss:module:1.1" name="org.postgresql"> <resources> <resource-root path="postgresql-9.1-902.jdbc4.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
14.5.3. Example MySQL Datasource
Example 14.7.
<datasources> <datasource jndi-name="java:jboss/MySqlDS" pool-name="MySqlDS"> <connection-url>jdbc:mysql://mysql-localhost:3306/jbossdb</connection-url> <driver>mysql</driver> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <background-validation>true</background-validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"></valid-connection-checker> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"></exception-sorter> </validation> </datasource> <drivers> <driver name="mysql" module="com.mysql"> <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
module.xml
file for the MySQL datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.mysql"> <resources> <resource-root path="mysql-connector-java-5.0.8-bin.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
14.5.4. Example MySQL XA Datasource
Example 14.8.
<datasources> <xa-datasource jndi-name="java:jboss/MysqlXADS" pool-name="MysqlXADS"> <driver>mysql</driver> <xa-datasource-property name="ServerName">localhost</xa-datasource-property> <xa-datasource-property name="DatabaseName">mysqldb</xa-datasource-property> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <background-validation>true</background-validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"></valid-connection-checker> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"></exception-sorter> </validation> </xa-datasource> <drivers> <driver name="mysql" module="com.mysql"> <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
module.xml
file for the MySQL XA datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.mysql"> <resources> <resource-root path="mysql-connector-java-5.0.8-bin.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
14.5.5. Example Oracle Datasource
Note
Example 14.9.
<datasources> <datasource jndi-name="java:/OracleDS" pool-name="OracleDS"> <connection-url>jdbc:oracle:thin:@localhost:1521:XE</connection-url> <driver>oracle</driver> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <background-validation>true</background-validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"></valid-connection-checker> <stale-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnectionChecker"></stale-connection-checker> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"></exception-sorter> </validation> </datasource> <drivers> <driver name="oracle" module="com.oracle"> <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
module.xml
file for the Oracle datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.oracle"> <resources> <resource-root path="ojdbc6.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
14.5.6. Example Oracle XA Datasource
Note
Important
user
is the user defined to connect from JBoss to Oracle:
- GRANT SELECT ON sys.dba_pending_transactions TO user;
- GRANT SELECT ON sys.pending_trans$ TO user;
- GRANT SELECT ON sys.dba_2pc_pending TO user;
- GRANT EXECUTE ON sys.dbms_xa TO user; (If using Oracle 10g R2 (patched) or Oracle 11g)ORGRANT EXECUTE ON sys.dbms_system TO user; (If using an unpatched Oracle version prior to 11g)
Example 14.10.
<datasources> <xa-datasource jndi-name="java:/XAOracleDS" pool-name="XAOracleDS"> <driver>oracle</driver> <xa-datasource-property name="URL">jdbc:oracle:oci8:@tc</xa-datasource-property> <security> <user-name>admin</user-name> <password>admin</password> </security> <xa-pool> <is-same-rm-override>false</is-same-rm-override> <no-tx-separate-pools /> </xa-pool> <validation> <background-validation>true</background-validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"></valid-connection-checker> <stale-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnectionChecker"></stale-connection-checker> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"></exception-sorter> </validation> </xa-datasource> <drivers> <driver name="oracle" module="com.oracle"> <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
module.xml
file for the Oracle XA datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.oracle"> <resources> <resource-root path="ojdbc6.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
14.5.7. Example Microsoft SQLServer Datasource
Example 14.11.
<datasources> <datasource jndi-name="java:/MSSQLDS" pool-name="MSSQLDS"> <connection-url>jdbc:microsoft:sqlserver://localhost:1433;DatabaseName=MyDatabase</connection-url> <driver>sqlserver</driver> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <background-validation>true</background-validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"></valid-connection-checker> </validation> </datasource> <drivers> <driver name="sqlserver" module="com.microsoft"> <xa-datasource-class>com.microsoft.sqlserver.jdbc.SQLServerXADataSource</xa-datasource-class> </driver> </datasources>
module.xml
file for the Microsoft SQLServer datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.microsoft"> <resources> <resource-root path="sqljdbc4.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
14.5.8. Example Microsoft SQLServer XA Datasource
Example 14.12.
<datasources> <xa-datasource jndi-name="java:/MSSQLXADS" pool-name="MSSQLXADS"> <driver>sqlserver</driver> <xa-datasource-property name="ServerName">localhost</xa-datasource-property> <xa-datasource-property name="DatabaseName">mssqldb</xa-datasource-property> <xa-datasource-property name="SelectMethod">cursor</xa-datasource-property> <security> <user-name>admin</user-name> <password>admin</password> </security> <xa-pool> <is-same-rm-override>false</is-same-rm-override> </xa-pool> <validation> <background-validation>true</background-validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"></valid-connection-checker> </validation> </xa-datasource> <drivers> <driver name="sqlserver" module="com.microsoft"> <xa-datasource-class>com.microsoft.sqlserver.jdbc.SQLServerXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
module.xml
file for the Microsoft SQLServer XA datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.microsoft"> <resources> <resource-root path="sqljdbc4.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
14.5.9. Example IBM DB2 Datasource
Example 14.13.
<datasources> <datasource jndi-name="java:/DB2DS" pool-name="DB2DS"> <connection-url>jdbc:db2:ibmdb2db</connection-url> <driver>ibmdb2</driver> <pool> <min-pool-size>0</min-pool-size> <max-pool-size>50</max-pool-size> </pool> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <background-validation>true</background-validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker"></valid-connection-checker> <stale-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2StaleConnectionChecker"></stale-connection-checker> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter"></exception-sorter> </validation> </datasource> <drivers> <driver name="ibmdb2" module="com.ibm"> <xa-datasource-class>com.ibm.db2.jdbc.DB2XADataSource</xa-datasource-class> </driver> </drivers> </datasources>
module.xml
file for the IBM DB2 datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.ibm"> <resources> <resource-root path="db2jcc4.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
14.5.10. Example IBM DB2 XA Datasource
Example 14.14.
<datasources> <xa-datasource jndi-name="java:/DB2XADS" pool-name="DB2XADS"> <driver>ibmdb2</driver> <xa-datasource-property name="DatabaseName">ibmdb2db</xa-datasource-property> <security> <user-name>admin</user-name> <password>admin</password> </security> <xa-pool> <is-same-rm-override>false</is-same-rm-override> </xa-pool> <validation> <background-validation>true</background-validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker"></valid-connection-checker> <stale-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2StaleConnectionChecker"></stale-connection-checker> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter"></exception-sorter> </validation> <recovery> <recover-plugin class-name="org.jboss.jca.core.recovery.ConfigurableRecoveryPlugin"> <config-property name="EnableIsValid">false</config-property> <config-property name="IsValidOverride">false</config-property> <config-property name="EnableClose">false</config-property> </recover-plugin> </recovery> </xa-datasource> <drivers> <driver name="ibmdb2" module="com.ibm"> <xa-datasource-class>com.ibm.db2.jcc.DB2XADataSource</xa-datasource-class> </driver> </drivers> </datasources>
module.xml
file for the IBM DB2 XA datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.ibm"> <resources> <resource-root path="db2jcc4.jar"/> <resource-root path="db2jcc_license_cisuz.jar"/> <resource-root path="db2jcc_license_cu.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
14.5.11. Example Sybase Datasource
Example 14.15.
<datasources> <datasource jndi-name="java:jboss/SybaseDB" pool-name="SybaseDB" enabled="true"> <connection-url>jdbc:sybase:Tds:localhost:5000/DATABASE?JCONNECT_VERSION=6</connection-url> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <background-validation>true</background-validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker"></valid-connection-checker> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter"></exception-sorter> </validation> </datasource> <drivers> <driver name="sybase" module="com.sybase"> <datasource-class>com.sybase.jdbc2.jdbc.SybDataSource</datasource-class> <xa-datasource-class>com.sybase.jdbc3.jdbc.SybXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
module.xml
file for the Sybase datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.sybase"> <resources> <resource-root path="jconn2.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
14.5.12. Example Sybase XA Datasource
Example 14.16.
<datasources> <xa-datasource jndi-name="java:jboss/SybaseXADS" pool-name="SybaseXADS" enabled="true"> <xa-datasource-property name="NetworkProtocol">Tds</xa-datasource-property> <xa-datasource-property name="ServerName">myserver</xa-datasource-property> <xa-datasource-property name="PortNumber">4100</xa-datasource-property> <xa-datasource-property name="DatabaseName">mydatabase</xa-datasource-property> <security> <user-name>admin</user-name> <password>admin</password> </security> <validation> <background-validation>true</background-validation> <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker"></valid-connection-checker> <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter"></exception-sorter> </validation> </xa-datasource> <drivers> <driver name="sybase" module="com.sybase"> <datasource-class>com.sybase.jdbc2.jdbc.SybDataSource</datasource-class> <xa-datasource-class>com.sybase.jdbc3.jdbc.SybXADataSource</xa-datasource-class> </driver> </drivers> </datasources>
module.xml
file for the Sybase XA datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.sybase"> <resources> <resource-root path="jconn2.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
Chapter 15. JDBC Based Cache Stores
JdbcBinaryStore
.JdbcStringBasedStore
.JdbcMixedStore
.
15.1. JdbcBinaryStores
JdbcBinaryStore
supports all key types. It stores all keys with the same hash value (hashCode
method on the key) in the same table row/blob. The hash value common to the included keys is set as the primary key for the table row/blob. As a result of this hash value, JdbcBinaryStore
offers excellent flexibility but at the cost of concurrency and throughput.
k1
, k2
and k3
) have the same hash code, they are stored in the same table row. If three different threads attempt to concurrently update k1
, k2
and k3
, they must do it sequentially because all three keys share the same row and therefore cannot be simultaneously updated.
15.1.1. JdbcBinaryStore Configuration (Remote Client-Server Mode)
JdbcBinaryStore
using Red Hat JBoss Data Grid's Remote Client-Server mode with Passivation enabled.
Procedure 15.1. Configure the JdbcBinaryStore for Remote Client-Server Mode
The binary-keyed-jdbc-store Element
Thebinary-keyed-jdbc-store
element specifies the configuration for a binary keyed cache JDBC store.- The
datasource
parameter defines the name of a JNDI for the datasource. - 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
). - The
preload
parameter specifies whether to load entries into the cache during start up. Valid values for this parameter aretrue
andfalse
. - The
purge
parameter specifies whether or not the cache store is purged when it is started. Valid values for this parameter aretrue
andfalse
.
<local-cache> ... <binary-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" passivation="${true/false}" preload="${true/false]" purge="${true/false}">
The binary-keyed-table Element
Thebinary-keyed-table
element specifies information about the database table used to store binary cache entries.- 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">
The id-column Element
Theid-column
element specifies information about a database column that holds cache entry IDs.- The
name
parameter specifies the name of the database column. - 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}"/>
The data-column Element
Thedata-column
element contains information about a database column that holds cache entry data.- The
name
parameter specifies the name of the database column. - 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}"/>
The timestamp-column Element
Thetimestamp-column
element specifies information about the database column that holds cache entry timestamps.- The
name
parameter specifies the name of the database column. - 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>
15.1.2. JdbcBinaryStore Configuration (Library Mode)
JdbcBinaryStore
:
Procedure 15.2. Configure the JdbcBinaryStore for Library Mode
The binaryKeyedJdbcStore Element
ThebinaryKeyedJdbcStore
element uses the following parameters to configure the cache store:- The
fetchPersistentState
parameter determines whether the persistent state is fetched when joining a cluster. Set this totrue
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 totrue
. ThefetchPersistentState
parameter isfalse
by default. - 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.
<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">
The connectionPool Element
TheconnectionPool
element specifies a connection pool for the JDBC driver using the following parameters:- The
connectionUrl
parameter specifies the JDBC driver-specific connection URL. - The
username
parameter contains the username used to connect via theconnectionUrl
. - 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"/>
The binaryKeyedTable Element
ThebinaryKeyedTable
element defines the table that stores cache entries. It uses the following parameters to configure the cache store:- The
dropOnExit
parameter specifies whether the database tables are dropped upon shutdown. - The
createOnStart
parameter specifies whether the database tables are created by the store on startup. - 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">
The idColumn Element
TheidColumn
element defines the column where the cache key or bucket ID is stored. It uses the following parameters:- Use the
name
parameter to specify the name of the column used. - 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)" />
The dataColumn Element
ThedataColumn
element specifies the column where the cache entry or bucket is stored.- Use the
name
parameter to specify the name of the column used. - 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" />
The timestampColumn Element
ThetimestampColumn
element specifies the column where the time stamp of the cache entry or bucket is stored.- Use the
name
parameter to specify the name of the column used. - 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>
15.1.3. JdbcBinaryStore Programmatic Configuration
JdbcBinaryStore
:
Procedure 15.3. JdbcBinaryStore Programmatic Configuration (Library Mode)
Create a New Configuration Builder
Use theConfigurationBuilder
to create a new configuration object.ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence()
Add the
JdbcBinaryStoreConfigurationBuilder
Add theJdbcBinaryStore
configuration builder to build a specific configuration related to this store.ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence() .addStore(JdbcBinaryStoreConfigurationBuilder.class)
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 totrue
. ThefetchPersistentState
property isfalse
by default.ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence() .addStore(JdbcBinaryStoreConfigurationBuilder.class) .fetchPersistentState(false)
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
isfalse
by default.ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence() .addStore(JdbcBinaryStoreConfigurationBuilder.class) .fetchPersistentState(false) .ignoreModifications(false)
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)
Configure the Table
Set Drop Table On Exit Method
dropOnExit
determines if the table will be created when the cache store is stopped. This is set tofalse
by default.Set Create Table On Start Method
createOnStart
creates the table when starting the cache store if no table currently exists. This method istrue
by default.Set the Table Name Prefix
tableNamePrefix
sets the prefix for the name of the table in which the data will be stored.idColumnName
TheidColumnName
property defines the column where the cache key or bucket ID is stored.dataColumnName
ThedataColumnName
property specifies the column where the cache entry or bucket is stored.timestampColumnName
ThetimestampColumnName
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")
The connectionPool Element
TheconnectionPool
element specifies a connection pool for the JDBC driver using the following parameters:- The
connectionUrl
parameter specifies the JDBC driver-specific connection URL. - The
username
parameter contains the user name used to connect via theconnectionUrl
. - 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");
Note
15.2. JdbcStringBasedStores
JdbcStringBasedStore
stores each entry in its own row in the table, instead of grouping multiple entries into each row, resulting in increased throughput under a concurrent load. It also uses a (pluggable) bijection that maps each key to a String
object. The Key2StringMapper
interface defines the bijection.
DefaultTwoWayKey2StringMapper
that handles primitive types.
15.2.1. JdbcStringBasedStore Configuration (Remote Client-Server Mode)
JdbcStringBasedStore
for Red Hat JBoss Data Grid's Remote Client-Server mode with Passivation enabled.
Procedure 15.4. Configure JdbcStringBasedStore in Remote Client-Server Mode
The string-keyed-jdbc-store Element
Thestring-keyed-jdbc-store
element specifies the configuration for a string based keyed cache JDBC store.- The
datasource
parameter defines the name of a JNDI for the datasource. - 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
). - The
preload
parameter specifies whether to load entries into the cache during start up. Valid values for this parameter aretrue
andfalse
. - The
purge
parameter specifies whether or not the cache store is purged when it is started. Valid values for this parameter aretrue
andfalse
. - 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 aretrue
andfalse
. - 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">
The string-keyed-table Element
Thestring-keyed-table
element specifies information about the database table used to store string based cache entries.- 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">
The id-column Element
Theid-column
element specifies information about a database column that holds cache entry IDs.- The
name
parameter specifies the name of the ID column. - 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}"/>
The data-column Element
Thedata-column
element contains information about a database column that holds cache entry data.- The
name
parameter specifies the name of the database column. - 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}"/>
The timestamp-column Element
Thetimestamp-column
element specifies information about the database column that holds cache entry timestamps.- The
name
parameter specifies the name of the database column. - 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>
15.2.2. JdbcStringBasedStore Configuration (Library Mode)
JdbcStringBasedStore
:
Procedure 15.5. Configure JdbcStringBasedStore in Library Mode
The stringKeyedJdbcStore Element
ThestringKeyedJdbcStore
element uses the following parameters to configure the cache store:- The
fetchPersistentState
parameter determines whether the persistent state is fetched when joining a cluster. Set this totrue
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 totrue
. ThefetchPersistentState
parameter isfalse
by default. - 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 is purged when initially started. - 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">
The connectionPool Element
TheconnectionPool
element specifies a connection pool for the JDBC driver using the following parameters:- The
connectionUrl
parameter specifies the JDBC driver-specific connection URL. - The
username
parameter contains the user name used to connect via theconnectionUrl
. - 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"/>
The stringKeyedTable Element
Add thestringKeyedTable
element defines the table that stores cache entries. It uses the following parameters to configure the cache store:- The
dropOnExit
parameter specifies whether the database tables are dropped upon shutdown. - The
createOnStart
parameter specifies whether the database tables are created by the store on startup. - 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">
The idColumn Element
TheidColumn
element defines the column where the cache key or bucket ID is stored. It uses the following parameters:- Use the
name
parameter to specify the name of the ID column. - 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)" />
The dataColumn Element
ThedataColumn
element specifies the column where the cache entry or bucket is stored.- Use the
name
parameter to specify the name of the database column. - 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" />
The timestampColumn Element
ThetimestampColumn
element specifies the column where the time stamp of the cache entry or bucket is stored.- Use the
name
parameter to specify the name of the column used. - 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>
15.2.3. JdbcStringBasedStore Multiple Node Configuration (Remote Client-Server Mode)
JdbcStringBasedStore
in Red Hat JBoss Data Grid's Remote Client-Server mode. This configuration is used when multiple nodes must be used.
Procedure 15.6. JdbcStringBasedStore Multiple Node Configuration for Remote Client-Server Mode
The string-keyed-jdbc-store Element
Thestring-keyed-jdbc-store
element specifies the configuration for a string based keyed cache JDBC store.- 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. - The
datasource
parameter defines the name of a JNDI for the datasource. - 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
). - The
preload
parameter specifies whether to load entries into the cache during start up. Valid values for this parameter aretrue
andfalse
. - The
purge
parameter specifies whether or not the cache store is purged when it is started. Valid values for this parameter aretrue
andfalse
. - 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 aretrue
andfalse
. - 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">
The string-keyed-table Element
Thestring-keyed-table
element specifies information about the database table used to store string based cache entries.- 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">
The id-column Element
Theid-column
element specifies information about a database column that holds cache entry IDs.- The
name
parameter specifies the name of the ID column. - 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}"/>>
The data-column Element
Thedata-column
element contains information about a database column that holds cache entry data.- The
name
parameter specifies the name of the database column. - 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}"/>
The timestamp-column Element
Thetimestamp-column
element specifies information about the database column that holds cache entry timestamps.- The
name
parameter specifies the name of the timestamp column. - 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>
15.2.4. JdbcStringBasedStore Programmatic Configuration
JdbcStringBasedStore
:
Procedure 15.7. Configure the JdbcStringBasedStore Programmatically
Create a New Configuration Builder
Use theConfigurationBuilder
to create a new configuration object.ConfigurationBuilder builder = new ConfigurationBuilder();
Add
JdbcStringBasedStoreConfigurationBuilder
Add theJdbcStringBasedStore
configuration builder to build a specific configuration related to this store.ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence().addStore(JdbcStringBasedStoreConfigurationBuilder.class)
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 totrue
. ThefetchPersistentState
property isfalse
by default.ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence().addStore(JdbcStringBasedStoreConfigurationBuilder.class) .fetchPersistentState(false)
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
isfalse
by default.ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence().addStore(JdbcStringBasedStoreConfigurationBuilder.class) .fetchPersistentState(false) .ignoreModifications(false)
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)
Configure the Table
Set Drop Table On Exit Method
dropOnExit
determines if the table will be created when the cache store is stopped. This is set tofalse
by default.Set Create Table On Start Method
createOnStart
creates the table when starting the cache store if no table currently exists. This method istrue
by default.Set the Table Name Prefix
tableNamePrefix
sets the prefix for the name of the table in which the data will be stored.idColumnName
TheidColumnName
property defines the column where the cache key or bucket ID is stored.dataColumnName
ThedataColumnName
property specifies the column where the cache entry or bucket is stored.timestampColumnName
ThetimestampColumnName
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")
The connectionPool Element
TheconnectionPool
element specifies a connection pool for the JDBC driver using the following parameters:- The
connectionUrl
parameter specifies the JDBC driver-specific connection URL. - The
username
parameter contains the username used to connect via theconnectionUrl
. - 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");
Note
15.3. JdbcMixedStores
JdbcMixedStore
is a hybrid implementation that delegates keys based on their type to either the JdbcBinaryStore
or JdbcStringBasedStore
.
15.3.1. JdbcMixedStore Configuration (Remote Client-Server Mode)
JdbcMixedStore
for Red Hat JBoss Data Grid's Remote Client-Server mode with Passivation enabled.
Procedure 15.8. Configure JdbcMixedStore in Remote Client-Server Mode
The mixed-keyed-jdbc-store Element
Themixed-keyed-jdbc-store
element specifies the configuration for a mixed keyed cache JDBC store.- The
datasource
parameter defines the name of a JNDI for the datasource. - 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
). - The
preload
parameter specifies whether to load entries into the cache during start up. Valid values for this parameter aretrue
andfalse
. - The
purge
parameter specifies whether or not the cache store is purged when it is started. Valid values for this parameter aretrue
andfalse
.
<local-cache> <mixed-keyed-jdbc-store datasource="java:jboss/datasources/JdbcDS" passivation="true" preload="false" purge="false">
The binary-keyed-table Element
Thebinary-keyed-table
element specifies information about the database table used to store mixed cache entries.- 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>
The string-keyed-table Element
Thestring-keyed-table
element specifies information about the database table used to store string based cache entries.- 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">
The id-column Element
Theid-column
element specifies information about a database column that holds cache entry IDs.- The
name
parameter specifies the name of the ID column. - 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}"/>
The data-column Element
Thedata-column
element contains information about a database column that holds cache entry data.- The
name
parameter specifies the name of the database column. - 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}"/>
The timestamp-column Element
Thetimestamp-column
element specifies information about the database column that holds cache entry timestamps.- The
name
parameter specifies the name of the timestamp column. - 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>
15.3.2. JdbcMixedStore Configuration (Library Mode)
mixedKeyedJdbcStore
:
Procedure 15.9. Configure JdbcMixedStore in Library Mode
The mixedKeyedJdbcStore Element
ThemixedKeyedJdbcStore
element uses the following parameters to configure the cache store:- The
fetchPersistentState
parameter determines whether the persistent state is fetched when joining a cluster. Set this totrue
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 totrue
. ThefetchPersistentState
parameter isfalse
by default. - 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. - The
purgeOnStartup
parameter specifies whether the cache is purged when initially started. - 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">
The binaryKeyedTable and stringKeyedTable Elements
ThebinaryKeyedTable
and thestringKeyedTable
element defines the table that stores cache entries. Each uses the following parameters to configure the cache store:- The
dropOnExit
parameter specifies whether the database tables are dropped upon shutdown. - The
createOnStart
parameter specifies whether the database tables are created by the store on startup. - 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">
The idColumn Element
TheidColumn
element defines the column where the cache key or bucket ID is stored. It uses the following parameters:- Use the
name
parameter to specify the name of the column used. - 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)" />
The dataColumn Element
ThedataColumn
element specifies the column where the cache entry or bucket is stored.- Use the
name
parameter to specify the name of the column used. - 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" />
The timestampColumn Element
ThetimestampColumn
element specifies the column where the time stamp of the cache entry or bucket is stored.- Use the
name
parameter to specify the name of the column used. - 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>
The string-keyed-table Element
Thestring-keyed-table
element specifies information about the database table used to store string based cache entries.- 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>
15.3.3. JdbcMixedStore Programmatic Configuration
JdbcMixedStore
:
Procedure 15.10. Configure JdbcMixedStore Programmatically
Create a New Configuration Builder
Use theConfigurationBuilder
to create a new configuration object.ConfigurationBuilder builder = new ConfigurationBuilder();
Add
JdbcMixedStoreConfigurationBuilder
Add theJdbcMixedStore
configuration builder to build a specific configuration related to this store.ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence().addStore(JdbcMixedStoreConfigurationBuilder.class)
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 totrue
. ThefetchPersistentState
property isfalse
by default.ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence().addStore(JdbcMixedStoreConfigurationBuilder.class) .fetchPersistentState(false)
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
isfalse
by default.ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence().addStore(JdbcMixedStoreConfigurationBuilder.class) .fetchPersistentState(false) .ignoreModifications(false)
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)
Configure the Table
Set Drop Table On Exit Method
dropOnExit
determines if the table will be created when the cache store is stopped. This is set tofalse
by default.Set Create Table On Start Method
createOnStart
creates the table when starting the cache store if no table currently exists. This method istrue
by default.Set the Table Name Prefix
tableNamePrefix
sets the prefix for the name of the table in which the data will be stored.idColumnName
TheidColumnName
property defines the column where the cache key or bucket ID is stored.dataColumnName
ThedataColumnName
property specifies the column where the cache entry or bucket is stored.timestampColumnName
ThetimestampColumnName
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")
The connectionPool Element
TheconnectionPool
element specifies a connection pool for the JDBC driver using the following parameters:- The
connectionUrl
parameter specifies the JDBC driver-specific connection URL. - The
username
parameter contains the username used to connect via theconnectionUrl
. - 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");
Note
15.4. Cache Store Troubleshooting
15.4.1. IOExceptions with JdbcStringBasedStore
JdbcStringBasedStore
indicates that your data column type is set to VARCHAR
, CLOB
or something similar instead of the correct type, BLOB
or VARBINARY
. Despite its name, JdbcStringBasedStore
only requires that the keys are strings while the values can be any data type, so that they can be stored in a binary column.
Chapter 16. Cache Loaders
16.1. Cache Loaders and Cache Stores
CacheLoader
interface and a number of implementations. Red Hat JBoss Data Grid has divided these into two distinct interfaces, a CacheLoader
and a CacheStore
. The CacheLoader
loads a previously existing state from another location, while the CacheStore
(which extends CacheLoader
) exposes methods to store states as well as loading them. This division allows easier definition of read-only sources.
16.2. Cache Loader Configuration
16.2.1. Configuring the Cache Loader
ignoreModifications
element has been set to "true"
for a specific cache loader.
16.2.2. Configure the Cache Loader using XML
Procedure 16.1. Configure the Cache Loader Using XML
Create a New Cache Loader
Create a new cache loader, specifyingpassivation
,shared
, andpreload
settings.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 isfalse
by default.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
isfalse
by default. When set totrue
, it prevents duplicate data being written to the cache loader by different cache instances.preload
is set tofalse
by default. When set totrue
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">
Set Up Persistence and Purging
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 totrue
. ThefetchPersistentState
property isfalse
by default.purgeSynchronously
controls whether expiration occurs in the eviction thread. When set totrue
, the eviction thread will block until the purge is finished, rather than bring returned immediately. ThepurgeSychronously
property is set tofalse
by default. If the cache loader supports multi-thread purge,purgeThreads
are used to purge expired entries.purgeThreads
is set to1
by default. Check cache loader configuration to determine if multi-thread purge is supported.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
isfalse
by default.
<persistence passivation="false" shared="false" preload="true"> <fileStore fetchPersistentState="true" purgerThreads="3" purgeSynchronously="true" ignoreModifications="false" purgeOnStartup="false" location="${java.io.tmpdir}" />
Asynchronous Settings
These attributes configure aspects specific to each cache loader. For example, thelocation
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>
Configure Singletons and Push States
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 theenabled
attribute totrue
in all nodes. Theshared
parameter cannot be defined withsingletonStore
enabled at the same time. Theenabled
attribute isfalse
by default.pushStateWhenCoordinator
is set totrue
by default. Iftrue
, 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>
16.2.3. Configure the Cache Loader Programmatically
Procedure 16.2. Configure the Cache Loader Programatically
Create a New Configuration Builder
Use theConfigurationBuilder
to create a new configuration object.ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence()
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 isfalse
by default.ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence() .passivation(false)
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
isfalse
by default. When set totrue
, it prevents duplicate data being written to the cache loader by different cache instances.ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence() .passivation(false) .shared(false)
Set Up Preloading
preload
is set tofalse
by default. When set totrue
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)
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 theaddLoader
method.ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence() .passivation(false) .shared(false) .preload(true) .addSingleFileStore()
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 totrue
. ThefetchPersistentState
property isfalse
by default.ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence() .passivation(false) .shared(false) .preload(true) .addSingleFileStore() .fetchPersistentState(true)
Set Up Purging
purgeSynchronously
controls whether expiration occurs in the eviction thread. When set totrue
, the eviction thread will block until the purge is finished, rather than bring returned immediately. ThepurgeSychronously
property is set tofalse
by default. If the cache loader supports multi-thread purge,purgeThreads
are used to purge expired entries.purgeThreads
is set to1
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)
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
isfalse
by default.ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence() .passivation(false) .shared(false) .preload(true) .addSingleFileStore() .fetchPersistentState(true) .purgerThreads(3) .purgeSynchronously(true) .ignoreModifications(false)
Asynchronous Settings
These attributes configure aspects specific to each cache loader. For example, thelocation
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)
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 theenabled
attribute totrue
in all nodes. Theshared
parameter cannot be defined withsingletonStore
enabled at the same time. Theenabled
attribute isfalse
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)
Set Up Push States
pushStateWhenCoordinator
is set totrue
by default. Iftrue
, 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);
16.4. Connection Factories
ConnectionFactory
implementation to obtain a database connection. This process is also known as connection management or pooling.
ConnectionFactoryClass
configuration attribute. JBoss Data Grid includes the following ConnectionFactory
implementations:
- ManagedConnectionFactory
- SimpleConnectionFactory.
16.4.1. About ManagedConnectionFactory
ManagedConnectionFactory
is a connection factory that is ideal for use within managed environments such as application servers. This connection factory can explore a configured location in the JNDI tree and delegate connection management to the DataSource
. ManagedConnectionFactory
is used within a managed environment that contains a DataSource
. This Datasource
is delegated the connection pooling.
16.4.2. About SimpleConnectionFactory
SimpleConnectionFactory
is a connection factory that creates database connections on a per invocation basis. This connection factory is not designed for use in a production environment.
Part VII. Set Up Passivation
Chapter 17. Activation and Passivation Modes
17.1. Passivation Mode Benefits
17.2. Configure Passivation
passivation
parameter to the cache store element to toggle passivation for it:
<local-cache> ... <file-store passivation="true" ... /> ... </local-cache>
passivation
parameter to the loaders
element to toggle passivation:
<persistence passivation="true" ... /> ... </persistence>
17.3. Eviction and Passivation
17.3.1. Eviction and Passivation Usage
- A notification regarding the passivated entry is emitted to the cache listeners.
- The evicted entry is stored.
17.3.2. Eviction Example when Passivation is Disabled
Step | Key in Memory | Key on Disk |
---|---|---|
Insert keyOne | Memory: keyOne | Disk: keyOne |
Insert keyTwo | Memory: keyOne , keyTwo | Disk: keyOne , keyTwo |
Eviction thread runs, evicts keyOne | Memory: keyTwo | Disk: keyOne , keyTwo |
Read keyOne | Memory: keyOne , keyTwo | Disk: keyOne , keyTwo |
Eviction thread runs, evicts keyTwo | Memory: keyOne | Disk: keyOne , keyTwo |
Remove keyTwo | Memory: keyOne | Disk: keyOne |
17.3.3. Eviction Example when Passivation is Enabled
Step | Key in Memory | Key on Disk |
---|---|---|
Insert keyOne | Memory: keyOne | Disk: |
Insert keyTwo | Memory: keyOne , keyTwo | Disk: |
Eviction thread runs, evicts keyOne | Memory: keyTwo | Disk: keyOne |
Read keyOne | Memory: keyOne , keyTwo | Disk: |
Eviction thread runs, evicts keyTwo | Memory: keyOne | Disk: keyTwo |
Remove keyTwo | Memory: keyOne | Disk: |
Part VIII. Set Up Cache Writing
Chapter 18. Cache Writing Modes
- Write-Through (Synchronous)
- Write-Behind (Asynchronous)
18.1. Write-Through Caching
Cache.put()
invocation), the call does not return until JBoss Data Grid has located and updated the underlying cache store. This feature allows updates to the cache store to be concluded within the client thread boundaries.
18.1.1. Write-Through Caching Benefits
18.1.2. Write-Through Caching Configuration (Library Mode)
Procedure 18.1. Configure a Write-Through Local File Cache Store
Identify the
namedCache
Thename
parameter specifies the name of thenamedCache
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">
Configure the Cache Loader
Theshared
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 aretrue
andfalse
.<?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">
Specify the Loader Class
Theclass
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"
Configure the
fetchPersistentState
ParameterThefetchPersistentState
parameter determines whether the persistent state is fetched when joining a cluster. Set this totrue
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 totrue
. ThefetchPersistentState
parameter isfalse
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"
Set the
ignoreModifications
ParameterTheignoreModifications
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"
Configure Purge On Startup
ThepurgeOnStartup
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">
The
property
ElementTheproperty
element contains information about properties related to the cache store.- 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>
18.2. Write-Behind Caching
18.2.1. About Unscheduled Write-Behind Strategy
18.2.2. Unscheduled Write-Behind Strategy Configuration (Remote Client-Server Mode)
write-behind
element to the target cache store configuration as follows:
Procedure 18.2. The write-behind
Element
write-behind
element uses the following configuration parameters:
The
modification-queue-size
ParameterThemodification-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" />
The
shutdown-timeout
ParameterTheshutdown-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 is25000
.<file-store passivation="false" path="${PATH}" purge="true" shared="false"> <write-behind modification-queue-size="1024" shutdown-timeout="25000" />
The
flush-lock-timeout
ParameterTheflush-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 is15000
.<file-store passivation="false" path="${PATH}" purge="true" shared="false"> <write-behind modification-queue-size="1024" shutdown-timeout="25000" flush-lock-timeout="15000" />
The
thread-pool-size
ParameterThethread-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 is5
.<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>
18.2.3. Unscheduled Write-Behind Strategy Configuration (Library Mode)
async
element to the store configuration as follows:
Procedure 18.3. The async
Element
async
element uses the following configuration parameters:
- 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" />
- 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 is25000
.<persistence> <fileStore location="${LOCATION}"> <async enabled="true" modificationQueueSize="1024" shutdownTimeout="25000" />
- 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 is15000
.<persistence> <fileStore location="${LOCATION}"> <async enabled="true" modificationQueueSize="1024" shutdownTimeout="25000" flushLockTimeout="15000" />
- The
threadPoolSize
parameter specifies the number of threads that concurrently apply modifications to the store. The default value for this parameter is5
.<persistence> <fileStore location="${LOCATION}"> <async enabled="true" modificationQueueSize="1024" shutdownTimeout="25000" flushLockTimeout="15000" threadPoolSize="5"/> </fileStore> </persistence>
Part IX. Monitor Caches and Cache Managers
Chapter 19. Set Up Java Management Extensions (JMX)
19.1. About Java Management Extensions (JMX)
MBeans
.
19.2. Using JMX with Red Hat JBoss Data Grid
19.3. JMX Statistic Levels
- At the cache level, where management information is generated by individual cache instances.
- At the
CacheManager
level, where theCacheManager
is the entity that governs all cache instances created from it. As a result, the management information is generated for all these cache instances instead of individual caches.
Important
19.4. Enable JMX for Cache Instances
Add the following snippet within either the <default> element for the default cache instance, or under the target <namedCache> element for a specific named cache:
<jmxStatistics enabled="true"/>
Add the following code to programmatically enable JMX at the cache level:
Configuration configuration = ... configuration.setExposeJmxStatistics(true);
19.5. Enable JMX for CacheManagers
CacheManager
level, JMX statistics can be enabled either declaratively or programmatically, as follows.
Add the following in the <global> element to enable JMX declaratively at the CacheManager
level:
<globalJmxStatistics enabled="true"/>
Add the following code to programmatically enable JMX at the CacheManager
level:
GlobalConfiguration globalConfiguration = ... globalConfiguration.setExposeGlobalJmxStatistics(true);
19.6. Disabling the CacheStore via JMX
disconnectSource
operation on the RollingUpgradeManager
MBean.
See Also:
19.7. Multiple JMX Domains
CacheManager
instances exist on a single virtual machine, or if the names of cache instances in different CacheManagers
clash.
CacheManager
in manner that allows it to be easily identified and used by monitoring tools such as JMX and JBoss Operations Network.
Add the following snippet to the relevant CacheManager
configuration:
<globalJmxStatistics enabled="true" cacheManagerName="Hibernate2LC"/>
Add the following code to set the CacheManager
name programmatically:
GlobalConfiguration globalConfiguration = ... globalConfiguration.setExposeGlobalJmxStatistics(true); globalConfiguration.setCacheManagerName("Hibernate2LC");
19.8. MBeans
MBean
represents a manageable resource such as a service, component, device or an application.
MBeans
that monitor and manage multiple aspects. For example, MBeans
that provide statistics on the transport layer are provided. If a JBoss Data Grid server is configured with JMX statistics, an MBean
that provides information such as the hostname, port, bytes read, bytes written and the number of worker threads exists at the following location:
jboss.infinispan:type=Server,name=<Memcached|Hotrod>,component=Transport
Note
19.8.1. Understanding MBeans
MBeans
are available:
- If Cache Manager-level JMX statistics are enabled, an
MBean
namedjboss.infinispan:type=CacheManager,name="DefaultCacheManager"
exists, with properties specified by the Cache ManagerMBean
. - If the cache-level JMX statistics are enabled, multiple
MBeans
display depending on the configuration in use. For example, if a write behind cache store is configured, anMBean
that exposes properties that belong to the cache store component is displayed. All cache-levelMBeans
use the same format:jboss.infinispan:type=Cache,name="<name-of-cache>(<cache-mode>)",manager="<name-of-cache-manager>",component=<component-name>
In this format:- Specify the default name for the cache using the
cache-container
element'sdefault-cache
attribute. - The
cache-mode
is replaced by the cache mode of the cache. The lower case version of the possible enumeration values represents the cache mode. - The
component-name
is replaced by one of the JMX component names from the JMX reference documentation.
MBean
for a default cache configured for synchronous distribution would be named as follows:
jboss.infinispan:type=Cache,name="default(dist_sync)", manager="default",component=CacheStore
19.8.2. Registering MBeans in Non-Default MBean Servers
getMBeanServer()
method returns the desired (non default) MBeanServer.
Add the following snippet:
<globalJmxStatistics enabled="true" mBeanServerLookup="com.acme.MyMBeanServerLookup"/>
Add the following code:
GlobalConfiguration globalConfiguration = ... globalConfiguration.setExposeGlobalJmxStatistics(true); globalConfiguration.setMBeanServerLookup("com.acme.MyMBeanServerLookup")
Chapter 20. Set Up JBoss Operations Network (JON)
20.1. About JBoss Operations Network (JON)
Important
20.2. Download JBoss Operations Network (JON)
20.2.1. Prerequisites for Installing JBoss Operations Network (JON)
- A Linux, Windows, or Mac OSX operating system, and an x86_64, i686, or ia64 processor.
- Java 6 or higher is required to run both the JBoss Operations Network Server and the JBoss Operations Network Agent.
- Synchronized clocks on JBoss Operations Network Servers and Agents.
- An external database must be installed.
20.2.2. Download JBoss Operations Network
Procedure 20.1. Download JBoss Operations Network
Access the Customer Service Portal
Log in to the Customer Service Portal at https://access.redhat.comLocate the Product
Mouse overand navigate to .Select the Product
Selectfrom the menu.Download JBoss Operations Network
- Select the latest version of JBoss Operations Network Base Distribution and click thelink.
- Select the latest JBoss Data Grid Plugin Pack for JBoss Operations Network and click the link.
20.2.3. Remote JMX Port Values
20.2.4. Download JBoss Operations Network (JON) Plugin
Procedure 20.2. Download Installation Files
- Open http://access.redhat.com in a web browser.
- Clickin the menu across the top of the page.
- Clickin the list under JBoss Enterprise Middleware.
- Enter your login information.You are taken to the Software Downloads page.
Download the JBoss Operations Network Plugin
If you intend to use the JBoss Operations Network plugin for JBoss Data Grid, selectJBoss ON for JDG
from either the Software Downloads drop-down box, or the menu on the left.- Click the
JBoss Operations Network VERSION Base Distribution
download link. - Click thelink to start the Base Distribution download.
- Repeat the steps to download the
JDG Plugin Pack for JBoss ON VERSION
20.3. JBoss Operations Network Server Installation
Note
20.4. JBoss Operations Network Agent
init.d
script in a UNIX environment.
Note
20.5. JBoss Operations Network for Remote Client-Server Mode
- initiate and perform installation and configuration operations.
- monitor resources and their metrics.
20.5.1. Installing the JBoss Operations Network Plug-in (Remote Client-Server Mode)
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.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
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
20.6. JBoss Operations Network for Library Mode
- initiate and perform installation and configuration operations.
- monitor resources and their metrics.
20.6.1. Installing the JBoss Operations Network Plug-in (Library Mode)
Procedure 20.3. Install JBoss Operations Network Library Mode Plug-in
Open the JBoss Operations Network Console
- From the JBoss Operations Network console, select.
- Selectfrom the options on the left side of the console.
Figure 20.1. JBoss Operations Network Console for JBoss Data Grid
Upload the Library Mode Plug-in
- Click, locate the
InfinispanPlugin
on your local file system. - Clickto add the plug-in to the JBoss Operations Network Server.
Figure 20.2. Upload the
InfinispanPlugin
.Scan for Updates
- Once the file has successfully uploaded, clickat the bottom of the screen.
- The
InfinispanPlugin
will now appear in the list of installed plug-ins.
Figure 20.3. Scan for Updated Plug-ins.
Import the Platform
- Navigate to theand select from the list on the left of the console.
- Select the platform on which the application is running and clickat the bottom of the screen.
Figure 20.4. Import the Platform from the
.Access the Servers on the Platform
- The
jdg
Platform now appears in the Platforms list. - 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.Import the JMX Server
- From thetab, select .
- Click thebutton at the bottom of the screen and select the option from the list.
Figure 20.6. Import the JMX Server
Enable JDK Connection Settings
- In thewindow, specify from the list of options.
Figure 20.7. Select the JDK 5 Template.
Modify the Connector Address
- In themenu, modify the supplied with the hostname and JMX port of the process containing the Infinispan Library.
- Specify theand information if required.
- Click.
Figure 20.8. Modify the values in the Deployment Options screen.
View Cache Statistics and Operations
- Clickto refresh the list of servers.
- Thetree in the panel on the left side of the screen contains the node, which contains the available cache managers. The available cache managers contain the available caches.
- Select a cache from the available caches to view metrics.
- Select thetab.
- Theview shows statistics and metrics.
- Thetab 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.
20.6.2. Manually Adding JBoss Data Grid Instances in Library Mode
- Select> > > .
- At the bottom of the page, open the drop-down menu next to thesection.
- Selectand click .
- Select the
default
template on the next page. Manually add the JBoss Data Grid instance
- 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
- Object Name:
org.infinispan:type=CacheManager,name="<name_of_cache_manager>
Note
-Dcom.sun.management.jmxremote.port=7997 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false
20.7. JBoss Operations Network Remote-Client Server Plugin
20.7.1. JBoss Operations Network Plugin Metrics
Metric Name | Display Name | Description |
---|---|---|
cache-manager-status | Cache Container Status | The current runtime status of a cache container. |
cluster-name | Cluster Name | The name of the cluster. |
coordinator-address | Coordinator Address | The coordinator node's address. |
local-address | Local Address | The local node's address. |
Metric Name | Display Name | Description |
---|---|---|
cache-status | Cache Status | The current runtime status of a cache. |
number-of-locks-available | [LockManager] Number of locks available | The number of exclusive locks that are currently available. |
concurrency-level | [LockManager] Concurrency level | The LockManager's configured concurrency level. |
average-read-time | [Statistics] Average read time | Average number of milliseconds required for a read operation on the cache to complete. |
hit-ratio | [Statistics] Hit ratio | The result (in percentage) when the number of hits (successful attempts) is divided by the total number of attempts. |
elapsed-time | [Statistics] Seconds since cache started | The number of seconds since the cache started. |
read-write-ratio | [Statistics] Read/write ratio | The read/write ratio (in percentage) for the cache. |
average-write-time | [Statistics] Average write time | Average number of milliseconds a write operation on a cache requires to complete. |
hits | [Statistics] Number of cache hits | Number of cache hits. |
evictions | [Statistics] Number of cache evictions | Number of cache eviction operations. |
remove-misses | [Statistics] Number of cache removal misses | Number of cache removals where the key was not found. |
time-since-reset | [Statistics] Seconds since cache statistics were reset | Number of seconds since the last cache statistics reset. |
number-of-entries | [Statistics] Number of current cache entries | Number of entries currently in the cache. |
stores | [Statistics] Number of cache puts | Number of cache put operations |
remove-hits | [Statistics] Number of cache removal hits | Number of cache removal operation hits. |
misses | [Statistics] Number of cache misses | Number of cache misses. |
success-ratio | [RpcManager] Successful replication ratio | Successful replications as a ratio of total replications in numeric double format. |
replication-count | [RpcManager] Number of successful replications | Number of successful replications |
replication-failures | [RpcManager] Number of failed replications | Number of failed replications |
average-replication-time | [RpcManager] Average time spent in the transport layer | The average time (in milliseconds) spent in the transport layer. |
commits | [Transactions] Commits | Number of transaction commits performed since the last reset. |
prepares | [Transactions] Prepares | Number of transaction prepares performed since the last reset. |
rollbacks | [Transactions] Rollbacks | Number of transaction rollbacks performed since the last reset. |
invalidations | [Invalidation] Number of invalidations | Number of invalidations. |
passivations | [Passivation] Number of cache passivations | Number of passivation events. |
activations | [Activations] Number of cache entries activated | Number of activation events. |
cache-loader-loads | [Activation] Number of cache store loads | Number of entries loaded from the cache store. |
cache-loader-misses | [Activation] Number of cache store misses | Number of entries that did not exist in the cache store. |
cache-loader-stores | [CacheStore] Number of cache store stores | Number of entries stored in the cache stores. |
Note
The metrics provided by the JBoss Operations Network (JON) plugin for Red Hat JBoss Data Grid are for REST and Hot Rod endpoints only. For the REST protocol, the data must be taken from the Web subsystem metrics. For details about each of these endpoints, see the Getting Started Guide.
Metric Name | Display Name | Description |
---|---|---|
bytesRead | Bytes Read | Number of bytes read. |
bytesWritten | Bytes Written | Number of bytes written. |
Note
20.7.2. JBoss Operations Network Plugin Operations
Operation Name | Description |
---|---|
Clear Cache | Clears the cache contents. |
Reset Statistics | Resets statistics gathered by the cache. |
Reset Activation Statistics | Resets activation statistics gathered by the cache. |
Reset Invalidation Statistics | Resets invalidations statistics gathered by the cache. |
Reset Passivation Statistics | Resets passivation statistics gathered by the cache. |
Reset Rpc Statistics | Resets replication statistics gathered by the cache. |
Remove Cache | Removes the given cache from the cache-container. |
The cache backups used for these operations are configured using cross-datacenter replication. In the JBoss Operations Network (JON) User Interface, each cache backup is the child of a cache. For more information about cross-datacenter replication, see Section 27.1, “About Cross-Datacenter Replication”
Operation Name | Description |
---|---|
status | Display the site status. |
bring-site-online | Brings the site online. |
take-site-offline | Takes the site offline. |
Red Hat JBoss Data Grid does not support using Transactions in Remote Client-Server mode. As a result, none of the endpoints can use transactions.
20.7.3. JBoss Operations Network Plugin Attributes
Attribute Name | Type | Description |
---|---|---|
cluster | string | The name of the group communication cluster. |
executor | string | The executor used for the transport. |
lock-timeout | long | The timeout period for locks on the transport. The default value is 240000 . |
machine | string | A machine identifier for the transport. |
rack | string | A rack identifier for the transport. |
site | string | A site identifier for the transport. |
stack | string | The JGroups stack used for the transport. |
20.8. Monitor JBoss Enterprise Application Platform 6 Applications Using Library Mode
20.8.1. Prerequisites
- A correctly configured instance of JBoss Operations Network (JON) 3.1.x or better.
- A running instance of JBoss Operations Network (JON) Agent on the server where the application will run. For more information, see Section 20.4, “JBoss Operations Network Agent”
- An operational instance of the RHQ agent with a full JDK. Ensure that the agent has access to the
tools.jar
file from the JDK in particular. In the JBoss Operations Network (JON) agent's environment file (bin/
rhq-env.sh
), set the value of theRHQ_AGENT_JAVA_HOME
property to a full JDK. - The RHQ agent must have been initiated using the same user as the JBoss Enterprise Application Platform instance. As an example, running the JBoss Operations Network (JON) agent as a user with root privileges and the JBoss Enterprise Application Platform process under a different user does not work as expected and must be avoided.
- An installed JBoss Operations Network (JON) plugin for Library Mode. For more information, see Section 20.6.1, “Installing the JBoss Operations Network Plug-in (Library Mode)”
- A custom application using Red Hat JBoss Data Grid's Library mode. This application must have
jmxStatistics
enabled (either declaratively or programmatically). For more information, see Section 19.4, “Enable JMX for Cache Instances” - The Java Virtual Machine (JVM) must be configured to expose the JMX MBean Server. For the Oracle/Sun JDK, see http://docs.oracle.com/javase/1.5.0/docs/guide/management/agent.html
- A correctly added and configured management user for JBoss Enterprise Application Platform.
20.8.2. Monitor an Application Deployed in Standalone Mode
Procedure 20.4. Monitor an Application Deployed in Standalone Mode
Start the JBoss Enterprise Application Platform Instance
Start the JBoss Enterprise Application Platform instance as follows:- Enter the following command at the command line to add a new option to the standalone configuration file (
/bin/
standalone.conf
):JAVA_OPTS="$JAVA_OPTS -Dorg.rhq.resourceKey=MyEAP"
- Start the JBoss Enterprise Application Platform instance in standalone mode as follows:
$JBOSS_HOME/bin/standalone.sh
Run JBoss Operations Network (JON) Discovery
Run thediscovery --full
command in the JBoss Operations Network (JON) agent.Locate Application Server Process
In the JBoss Operations Network (JON) web interface, the JBoss Enterprise Application Platform 6 process is listed as a JMX server.Import the Process Into Inventory
Import the process into the JBoss Operations Network (JON) inventory.Deploy the Red Hat JBoss Data Grid Application
Deploy the WAR file that contains the JBoss Data Grid Library mode application withglobalJmxStatistics
andjmxStatistics
enabled.Optional: Run Discovery Again
If required, run thediscovery --full
command again to discover the new resources.
The JBoss Data Grid Library mode application is now deployed in JBoss Enterprise Application Platform's standalone mode and can be monitored using the JBoss Operations Network (JON).
20.8.3. Monitor an Application Deployed in Domain Mode
Procedure 20.5. Monitor an Application Deployed in Domain Mode
Edit the Host Configuration
Edit thedomain/configuration/
host.xml
file to replace theserver
element with the following configuration:<servers> <server name="server-one" group="main-server-group"> <jvm name="default"> <jvm-options> <option value="-Dorg.rhq.resourceKey=EAP1"/> </jvm-options> </jvm> </server> <server name="server-two" group="main-server-group" auto-start="true"> <socket-bindings port-offset="150"/> <jvm name="default"> <jvm-options> <option value="-Dorg.rhq.resourceKey=EAP2"/> </jvm-options> </jvm> </server> </servers>
Start JBoss Enterprise Application Platform 6
Start JBoss Enterprise Application Platform 6 in domain mode:$JBOSS_HOME/bin/domain.sh
Deploy the Red Hat JBoss Data Grid Application
Deploy the WAR file that contains the JBoss Data Grid Library mode application withglobalJmxStatistics
andjmxStatistics
enabled.Run Discovery in JBoss Operations Network (JON)
If required, run thediscovery --full
command for the JBoss Operations Network (JON) agent to discover the new resources.
The JBoss Data Grid Library mode application is now deployed in JBoss Enterprise Application Platform's domain mode and can be monitored using the JBoss Operations Network (JON).
20.9. JBoss Operations Network Plug-in Quickstart
20.10. Other Management Tools and Operations
20.10.1. Accessing Data via URLs
put()
and post()
methods place data in the cache, and the URL used determines the cache name and key(s) used. The data is the value placed into the cache, and is placed in the body of the request.
GET
and HEAD
methods are used for data retrieval while other headers control cache settings and behavior.
Note
20.10.2. Limitations of Map Methods
Map
methods, such as size()
, values()
, keySet()
and entrySet()
, can be used with certain limitations with Red Hat JBoss Data Grid as they are unreliable. These methods do not acquire locks (global or local) and concurrent modification, additions and removals are excluded from consideration in these calls. Furthermore, the listed methods are only operational on the local data container and do not provide a global view of state.
Part X. Command Line Tools
Chapter 21. Red Hat JBoss Data Grid CLI
infinispan-cli-server-$VERSION.jar
) includes an interpreter for commands and must be included in the application.
21.1. Start the CLI (Server)
standalone
and cluster
files. For Linux, use the standlaone.sh
or clustered.sh
script and for Windows, use the standalone.bat
or clustered.bat
file.
21.2. Start the CLI (Client)
ispn-cli
file at bin/
. For Linux, run bin/ispn-cli.sh
and for Windows, run bin/ispn-cli.bat
.
21.3. CLI Client Switches for the Command Line
Short Option | Long Option | Description |
---|---|---|
-c | --connect=${URL} | Connects to a running Red Hat JBoss Data Grid instance. For example, for JMX over RMI use jmx://[username[:password]]@host:port[/container[/cache]] and for JMX over JBoss Remoting use remoting://[username[:password]]@host:port[/container[/cache]] |
-f | --file=${FILE} | Read the input from the specified file rather than using interactive mode. If the value is set to - then the stdin is used as the input. |
-h | --help | Displays the help information. |
-v | --version | Displays the CLI version information. |
21.4. Connect to the Application
[disconnected//]> connect jmx://localhost:12000 [jmx://localhost:12000/MyCacheManager/>
Note
12000
depends on the value the JVM is started with. For example, starting the JVM with the -Dcom.sun.management.jmxremote.port=12000
command line parameter uses this port, but otherwise a random port is chosen. When the remoting protocol (remoting://localhost:9999
) is used, the Red Hat JBoss Data Grid server administration port is used (the default is port 9999
).
CacheManager
.
cache
command to select a cache before performing cache operations. The CLI supports tab completion, therefore using the cache
and pressing the tab button displays a list of active caches:
[[jmx://localhost:12000/MyCacheManager/> cache ___defaultcache namedCache [jmx://localhost:12000/MyCacheManager/]> cache ___defaultcache [jmx://localhost:12000/MyCacheManager/___defaultcache]>
21.5. Stopping a Red Hat JBoss Data Grid Instance with the CLI
When running a Red Hat JBoss Data Grid instance in a container as a library mode deployment, the life cycle of JBoss Data Grid is bound to the life cycle of the user deployment.
A remote client-server JBoss Data Grid instance can be stopped using the following script:
jboss-datagrid-6.2.0-server/bin/init.d/jboss-datagrid.sh stop
kill
commands directly:
kill -15 $pid # send the TERM signal
PID
is still there, use the following:
kill -9 $pid
21.6. CLI Commands
21.6.1. The abort Command
abort
command aborts a running batch initiated using the start
command. Batching must be enabled for the specified cache. The following is a usage example:
[jmx://localhost:12000/MyCacheManager/namedCache]> start [jmx://localhost:12000/MyCacheManager/namedCache]> put a a [jmx://localhost:12000/MyCacheManager/namedCache]> abort [jmx://localhost:12000/MyCacheManager/namedCache]> get a null
21.6.2. The begin Command
begin
command starts a transaction. This command requires transactions enabled for the cache it targets. An example of this command's usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> begin [jmx://localhost:12000/MyCacheManager/namedCache]> put a a [jmx://localhost:12000/MyCacheManager/namedCache]> put b b [jmx://localhost:12000/MyCacheManager/namedCache]> commit
21.6.3. The cache Command
cache
command specifies the default cache used for all subsequent operations. If invoked without any parameters, it shows the currently selected cache. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> cache ___defaultcache [jmx://localhost:12000/MyCacheManager/___defaultcache]> cache ___defaultcache [jmx://localhost:12000/MyCacheManager/___defaultcache]>
21.6.4. The clear Command
clear
command clears all content from the cache. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> put a a [jmx://localhost:12000/MyCacheManager/namedCache]> clear [jmx://localhost:12000/MyCacheManager/namedCache]> get a null
21.6.5. The commit Command
commit
command commits changes to an ongoing transaction. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> begin [jmx://localhost:12000/MyCacheManager/namedCache]> put a a [jmx://localhost:12000/MyCacheManager/namedCache]> put b b [jmx://localhost:12000/MyCacheManager/namedCache]> commit
21.6.6. The container Command
container
command selects the default cache container (cache manager). When invoked without any parameters, it lists all available containers. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> container MyCacheManager OtherCacheManager [jmx://localhost:12000/MyCacheManager/namedCache]> container OtherCacheManager [jmx://localhost:12000/OtherCacheManager/]>
21.6.7. The create Command
create
command creates a new cache based on the configuration of an existing cache definition. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> create newCache like namedCache [jmx://localhost:12000/MyCacheManager/namedCache]> cache newCache [jmx://localhost:12000/MyCacheManager/newCache]>
21.6.8. The disconnect Command
disconnect
command disconnects the currently active connection, which allows the CLI to connect to another instance. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> disconnect [disconnected//]
21.6.9. The encoding Command
encoding
command sets a default codec to use when reading and writing entries to and from a cache. If invoked with no arguments, the currently selected codec is displayed. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> encoding none [jmx://localhost:12000/MyCacheManager/namedCache]> encoding --list memcached hotrod none rest [jmx://localhost:12000/MyCacheManager/namedCache]> encoding hotrod
21.6.10. The end Command
end
command ends a running batch initiated using the start
command. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> start [jmx://localhost:12000/MyCacheManager/namedCache]> put a a [jmx://localhost:12000/MyCacheManager/namedCache]> end [jmx://localhost:12000/MyCacheManager/namedCache]> get a a
21.6.11. The evict Command
evict
command evicts an entry associated with a specific key from the cache. An example of it usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> put a a [jmx://localhost:12000/MyCacheManager/namedCache]> evict a
21.6.12. The get Command
get
command shows the value associated with a specified key. For primitive types and Strings, the get
command prints the default representation. For other objects, a JSON representation of the object is printed. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> put a a [jmx://localhost:12000/MyCacheManager/namedCache]> get a a
21.6.13. The info Command
info
command displaysthe configuration of a selected cache or container. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> info GlobalConfiguration{asyncListenerExecutor=ExecutorFactoryConfiguration{factory=org.infinispan.executors.DefaultExecutorFactory@98add58}, asyncTransportExecutor=ExecutorFactoryConfiguration{factory=org.infinispan.executors.DefaultExecutorFactory@7bc9c14c}, evictionScheduledExecutor=ScheduledExecutorFactoryConfiguration{factory=org.infinispan.executors.DefaultScheduledExecutorFactory@7ab1a411}, replicationQueueScheduledExecutor=ScheduledExecutorFactoryConfiguration{factory=org.infinispan.executors.DefaultScheduledExecutorFactory@248a9705}, globalJmxStatistics=GlobalJmxStatisticsConfiguration{allowDuplicateDomains=true, enabled=true, jmxDomain='jboss.infinispan', mBeanServerLookup=org.jboss.as.clustering.infinispan.MBeanServerProvider@6c0dc01, cacheManagerName='local', properties={}}, transport=TransportConfiguration{clusterName='ISPN', machineId='null', rackId='null', siteId='null', strictPeerToPeer=false, distributedSyncTimeout=240000, transport=null, nodeName='null', properties={}}, serialization=SerializationConfiguration{advancedExternalizers={1100=org.infinispan.server.core.CacheValue$Externalizer@5fabc91d, 1101=org.infinispan.server.memcached.MemcachedValue$Externalizer@720bffd, 1104=org.infinispan.server.hotrod.ServerAddress$Externalizer@771c7eb2}, marshaller=org.infinispan.marshall.VersionAwareMarshaller@6fc21535, version=52, classResolver=org.jboss.marshalling.ModularClassResolver@2efe83e5}, shutdown=ShutdownConfiguration{hookBehavior=DONT_REGISTER}, modules={}, site=SiteConfiguration{localSite='null'}}
21.6.14. The locate Command
locate
command displays the physical location of a specified entry in a distributed cluster. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> locate a [host/node1,host/node2]
21.6.15. The put Command
put
command inserts an entry into the cache. If a mapping exists for a key, the put
command overwrites the old value. The CLI allows control over the type of data used to store the key and value. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> put a a [jmx://localhost:12000/MyCacheManager/namedCache]> put b 100 [jmx://localhost:12000/MyCacheManager/namedCache]> put c 4139l [jmx://localhost:12000/MyCacheManager/namedCache]> put d true [jmx://localhost:12000/MyCacheManager/namedCache]> put e { "package.MyClass": {"i": 5, "x": null, "b": true } }
put
can specify a life span and maximum idle time value as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> put a a expires 10s [jmx://localhost:12000/MyCacheManager/namedCache]> put a a expires 10m maxidle 1m
21.6.16. The replace Command
replace
command replaces an existing entry in the cache with a specified new value. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> put a a [jmx://localhost:12000/MyCacheManager/namedCache]> replace a b [jmx://localhost:12000/MyCacheManager/namedCache]> get a b [jmx://localhost:12000/MyCacheManager/namedCache]> replace a b c [jmx://localhost:12000/MyCacheManager/namedCache]> get a c [jmx://localhost:12000/MyCacheManager/namedCache]> replace a b d [jmx://localhost:12000/MyCacheManager/namedCache]> get a c
21.6.17. The rollback Command
rollback
command rolls back any changes made by an ongoing transaction. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> begin [jmx://localhost:12000/MyCacheManager/namedCache]> put a a [jmx://localhost:12000/MyCacheManager/namedCache]> put b b [jmx://localhost:12000/MyCacheManager/namedCache]> rollback
21.6.18. The site Command
site
command performs administration tasks related to cross-datacenter replication. This command also retrieves information about the status of a site and toggles the status of a site. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> site --status NYC online [jmx://localhost:12000/MyCacheManager/namedCache]> site --offline NYC ok [jmx://localhost:12000/MyCacheManager/namedCache]> site --status NYC offline [jmx://localhost:12000/MyCacheManager/namedCache]> site --online NYC
21.6.19. The start Command
start
command initiates a batch of operations. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> start [jmx://localhost:12000/MyCacheManager/namedCache]> put a a [jmx://localhost:12000/MyCacheManager/namedCache]> put b b [jmx://localhost:12000/MyCacheManager/namedCache]> end
21.6.20. The stats Command
stats
command displays statistics for the cache. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> stats Statistics: { averageWriteTime: 143 evictions: 10 misses: 5 hitRatio: 1.0 readWriteRatio: 10.0 removeMisses: 0 timeSinceReset: 2123 statisticsEnabled: true stores: 100 elapsedTime: 93 averageReadTime: 14 removeHits: 0 numberOfEntries: 100 hits: 1000 } LockManager: { concurrencyLevel: 1000 numberOfLocksAvailable: 0 numberOfLocksHeld: 0 }
21.6.21. The upgrade Command
upgrade
command implements the rolling upgrade procedure. For details about rolling upgrades, see the Rolling Upgrades chapter in the Red Hat JBoss Data Grid Developer Guide.
upgrade
command's use is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> upgrade --synchronize=hotrod --all [jmx://localhost:12000/MyCacheManager/namedCache]> upgrade --disconnectsource=hotrod --all
21.6.22. The version Command
version
command displays version information for the CLI client and server. An example of its usage is as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> version Client Version 5.2.1.Final Server Version 5.2.1.Final