Administration and Configuration Guide
For use with Red Hat JBoss Data Grid 6.3.2
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 VI, “Set Up Locking for the Cache” and Chapter 16, 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 VII, “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 VIII, “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 IX, “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 21, 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 22, 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 28, 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 instances (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
Example 2.1. Configure a New RemoteCacheManager
import org.infinispan.client.hotrod.configuration.Configuration; import org.infinispan.client.hotrod.configuration.ConfigurationBuilder; Configuration conf = new ConfigurationBuilder().addServer().host("localhost").port(11222).build(); RemoteCacheManager manager = new RemoteCacheManager(conf); RemoteCache defaultCache = manager.getCache();
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 EmbeddedCacheManager defaultCacheManager() { Configuration configuration = new ConfigurationBuilder(); builder.eviction().strategy(EvictionStrategy.LRU).maxEntries(100).build(); return new DefaultCacheManager(configuration); } }
- Inject the default cache manager.
... @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
Table 3.1. Eviction Strategies
Strategy Name | Operations | Details |
---|---|---|
EvictionStrategy.NONE | No eviction occurs. | This is the default eviction strategy in Red Hat JBoss Data Grid. |
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 an eviction algorithm that 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
- 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 as follows:
- Enabling the eviction feature causes the eviction thread to periodically detect and purge expired entries.
get()
or containsKey()
for the expired entry causes JBoss Data Grid to return a null value. The expired entry is later removed by the eviction thread.
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
Table 5.1. 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
Table 5.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
Table 5.3. 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 26.2, “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.1" 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.1" 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.1" 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.1" 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.1" 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.1" 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.1" 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.
Example 6.1. Asynchronous Communications Example Configuration
<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
numOwners
copies of each key in the cache (as determined through consistent hashing). In invalidation mode the initial state transfer is similar to replication mode, the only difference being that the nodes are not guaranteed to have the same state. When a node leaves, a replicated mode or invalidation mode cache does not perform any state transfer. A distributed cache needs to make additional copies of the keys that were stored on the leaving nodes, again to keep numOwners
copies of each key.
6.4.1. Non-Blocking State Transfer
- Minimize the interval(s) where the entire cluster cannot respond to requests because of a state transfer in progress.
- Minimize the interval(s) where an existing member stops responding to requests because of a state transfer in progress.
- Allow state transfer to occur with a drop in the performance of the cluster. However, the drop in the performance during the state transfer does not throw any exception, and allows processes to continue.
- The blocking protocol queues the transaction delivery during the state transfer.
- State transfer control messages (such as CacheTopologyControlCommand) are sent according to the total order information.
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
numSegments
and cannot be changed without restarting the cluster. The mapping of keys to segments is also fixed — a key maps to the same segment, regardless of how the topology of the cluster changes.
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 is20
.<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="distribution">
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="distribution"> <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 is the number of cache entries to be transferred in one chunk. The defaultchunkSize
value is 512. ThechunkSize
depends on many parameters (for example, size of entries) and the best setting needs to be measured. To change the value for larger cache entries, smaller chunks are advisable and for smaller cache entries, increasing thechunkSize
offers better performance.<clustering mode="distribution"> <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="distribution"> <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="distribution"> <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="distribution"> <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 container 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.<global> <transport clusterName="${NAME}" /> </global>
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.<global> <transport clusterName="${NAME}" distributedSyncTimeout="${TIME}" /> </global>
Set the Network Transport
ThetransportClass
parameter specifies a class that represents a network transport for the cache container.<global> <transport clusterName="${NAME}" distributedSyncTimeout="${TIME}" transportClass="${CLASS}" /> </global>
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="clustered" 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="clustered" 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="clustered" 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="clustered" 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.Important
In Remote Client-Server mode, the transactions element is set toNONE
unless JBoss Data Grid is used in a compatibility mode where the cluster contains both JBoss Data Grid server and library instances. In this case, if transactions are configured in the library mode instance, they must also be configured in the server instance.<cache-container name="clustered" 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
and locking
, 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="replication">
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="replication"> <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 is the number of cache entries to be transferred in one chunk. The defaultchunkSize
value is 512. ThechunkSize
depends on many parameters (for example, size of entries) and the best setting needs to be measured. To change the value for larger cache entries, smaller chunks are advisable and for smaller cache entries, increasing thechunkSize
offers better performance.<clustering mode="replication"> <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="replication"> <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="replication"> <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="replication"> <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 container 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.<global> <transport clusterName="${NAME}" /> </global>
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.<global> <transport clusterName="${NAME}" distributedSyncTimeout="${TIME}" /> </global>
Set the Network Transport
ThetransportClass
parameter specifies a class that represents a network transport for the cache container.<global> <transport clusterName="${NAME}" distributedSyncTimeout="${TIME}" transportClass="${CLASS}" /> </global>
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.
- 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:
Example 8.1. Replication Queue in Asynchronous Mode
<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="invalidation">
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="invalidation"> <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="invalidation"> <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="invalidation"> <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="invalidation"> <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="invalidation"> <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 container 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.<global> <transport clusterName="${NAME}" /> </global>
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.<global> <transport clusterName="${NAME}" distributedSyncTimeout="${TIME}" /> </global>
Set the Network Transport
ThetransportClass
parameter specifies a class that represents a network transport for the cache container.<global> <transport clusterName="${NAME}" distributedSyncTimeout="${TIME}" transportClass="${CLASS}" /> </global>
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. Remote Client-Server Mode Interfaces
- The Asynchronous API (can only be used in conjunction with the Hot Rod Client in Remote Client-Server Mode)
- The REST Interface
- The Memcached Interface
- The Hot Rod Interface
- The RemoteCache API
Chapter 10. The Asynchronous API
Async
appended to each method name. Asynchronous methods return a Future that contains the result of the operation.
Cache(String, String)
, Cache.put(String key, String value)
returns a String, while Cache.putAsync(String key, String value)
returns a Future(String)
.
10.1. Asynchronous API Benefits
- The guarantee of synchronous communication, with the added ability to handle failures and exceptions.
- Not being required to block a thread's operations until the call completes.
Example 10.1. Using the Asynchronous API
Set<Future<?>> futures = new HashSet<Future<?>>(); futures.add(cache.putAsync("key1", "value1")); futures.add(cache.putAsync("key2", "value2")); futures.add(cache.putAsync("key3", "value3"));
futures.add(cache.putAsync(key1, value1));
futures.add(cache.putAsync(key2, value2));
futures.add(cache.putAsync(key3, value3));
10.2. About Asynchronous Processes
- Network calls
- Marshalling
- Writing to a cache store (optional)
- Locking
10.3. Return Values and the Asynchronous API
Future
or the NotifyingFuture
in order to query the previous value.
Note
NotifyingFutures
are only available in JBoss Data Grid Library mode.
Future.get()
Chapter 11. The REST Interface
11.1. Ruby Client Code
Example 11.1. Using the REST API with Ruby
require 'net/http' http = Net::HTTP.new('localhost', 8080) #An example of how to create a new entry http.post('/rest/MyData/MyKey', 'DATA_HERE', {"Content-Type" => "text/plain"}) #An example of using a GET operation to retrieve the key puts http.get('/rest/MyData/MyKey').body #An Example of using a PUT operation to overwrite the key http.put('/rest/MyData/MyKey', 'MORE DATA', {"Content-Type" => "text/plain"}) #An example of Removing the remote copy of the key http.delete('/rest/MyData/MyKey') #An example of creating binary data http.put('/rest/MyImages/Image.png', File.read('/Users/michaelneale/logo.png'), {"Content-Type" => "image/png"})
11.2. Using JSON with Ruby Example
To use JavaScript Object Notation (JSON) with ruby to interact with Red Hat JBoss Data Grid's REST Interface, install the JSON Ruby library (see your platform's package manager or the Ruby documentation) and declare the requirement using the following code:
require 'json'
The following code is an example of how to use JavaScript Object Notation (JSON) in conjunction with Ruby to send specific data, in this case the name and age of an individual, using the PUT
function.
data = {:name => "michael", :age => 42 } http.put('/infinispan/rest/Users/data/0', data.to_json, {"Content-Type" => "application/json"})
11.3. Python Client Code
Example 11.2. Using the REST API with Python
import httplib #How to insert data conn = httplib.HTTPConnection("localhost:8080") data = "SOME DATA HERE \!" #could be string, or a file... conn.request("POST", "/rest/Bucket/0", data, {"Content-Type": "text/plain"}) response = conn.getresponse() print response.status #How to retrieve data import httplib conn = httplib.HTTPConnection("localhost:8080") conn.request("GET", "/rest/Bucket/0") response = conn.getresponse() print response.status print response.read()
11.4. Java Client Code
Example 11.3. Defining Imports
import java.io.BufferedReader;import java.io.IOException; import java.io.InputStreamReader;import java.io.OutputStreamWriter; import java.net.HttpURLConnection;import java.net.URL;
Example 11.4. Adding a String Value to a Cache
public class RestExample { /** * Method that puts a String value in cache. * @param urlServerAddress * @param value * @throws IOException */ public void putMethod(String urlServerAddress, String value) throws IOException { System.out.println("----------------------------------------"); System.out.println("Executing PUT"); System.out.println("----------------------------------------"); URL address = new URL(urlServerAddress); System.out.println("executing request " + urlServerAddress); HttpURLConnection connection = (HttpURLConnection) address.openConnection(); System.out.println("Executing put method of value: " + value); connection.setRequestMethod("PUT"); connection.setRequestProperty("Content-Type", "text/plain"); connection.setDoOutput(true); OutputStreamWriter outputStreamWriter = new OutputStreamWriter(connection.getOutputStream()); outputStreamWriter.write(value); connection.connect(); outputStreamWriter.flush(); System.out.println("----------------------------------------"); System.out.println(connection.getResponseCode() + " " + connection.getResponseMessage()); System.out.println("----------------------------------------"); connection.disconnect(); }
Example 11.5. Get a String Value from a Cache
/** * Method that gets an value by a key in url as param value. * @param urlServerAddress * @return String value * @throws IOException */ public String getMethod(String urlServerAddress) throws IOException { String line = new String(); StringBuilder stringBuilder = new StringBuilder(); System.out.println("----------------------------------------"); System.out.println("Executing GET"); System.out.println("----------------------------------------"); URL address = new URL(urlServerAddress); System.out.println("executing request " + urlServerAddress); HttpURLConnection connection = (HttpURLConnection) address.openConnection(); connection.setRequestMethod("GET"); connection.setRequestProperty("Content-Type", "text/plain"); connection.setDoOutput(true); BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(connection.getInputStream())); connection.connect(); while ((line = bufferedReader.readLine()) != null) { stringBuilder.append(line + '\n'); } System.out.println("Executing get method of value: " + stringBuilder.toString()); System.out.println("----------------------------------------"); System.out.println(connection.getResponseCode() + " " + connection.getResponseMessage()); System.out.println("----------------------------------------"); connection.disconnect(); return stringBuilder.toString(); }
Example 11.6. Using a Java Main Method
/** * Main method example. * @param args * @throws IOException */ public static void main(String[] args) throws IOException { //Note that the cache name is "cacheX" RestExample restExample = new RestExample(); restExample.putMethod("http://localhost:8080/rest/cacheX/1", "Infinispan REST Test"); restExample.getMethod("http://localhost:8080/rest/cacheX/1"); } } }
11.5. The REST Interface Connector
- The
hotrod-connector
element, which defines the configuration for a Hot Rod based connector. - The
memcached-connector
element, which defines the configuration for a memcached based connector. - The
rest-connector
element, which defines the configuration for a REST interface based connector.
<socket-binding-group />
, and exposing the caches declared in the local
container, using defaults for all other settings. The following examples show how to connect to Hot Rod, Memcached, and REST servers.
<rest-connector virtual-server="default-host" cache-container="local" security-domain="other" auth-method="BASIC"/>
11.5.1. Configure REST Connectors
rest-connector
element in Red Hat JBoss Data Grid's Remote Client-Server mode.
Procedure 11.1. Configuring REST Connectors for Remote Client-Server Mode
rest-connector
element specifies the configuration information for the REST connector.
The
virtual-server
ParameterThevirtual-server
parameter specifies the virtual server used by the REST connector. The default value for this parameter isdefault-host
. This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <rest-connector virtual-server="default-host" /> </subsystem>
The
cache-container
ParameterThecache-container
parameter names the cache container used by the REST connector. This is a mandatory parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <rest-connector virtual-server="default-host" cache-container="local" /> </subsystem>
The
context-path
ParameterThecontext-path
parameter specifies the context path for the REST connector. The default value for this parameter is an empty string (""
). This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <rest-connector virtual-server="default-host" cache-container="local" context-path="${CONTEXT_PATH}" /> </subsystem>
The
security-domain
ParameterThesecurity-domain
parameter specifies that the specified domain, declared in the security subsystem, should be used to authenticate access to the REST endpoint. This is an optional parameter. If this parameter is omitted, no authentication is performed.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <rest-connector virtual-server="default-host" cache-container="local" context-path="${CONTEXT_PATH}" security-domain="${SECURITY_DOMAIN}" /> </subsystem>
The
auth-method
ParameterTheauth-method
parameter specifies the method used to retrieve credentials for the end point. The default value for this parameter isBASIC
. Supported alternate values includeBASIC
,DIGEST
, andCLIENT-CERT
. This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <rest-connector virtual-server="default-host" cache-container="local" context-path="${CONTEXT_PATH}" security-domain="${SECURITY_DOMAIN}" auth-method="${METHOD}" /> </subsystem>
The
security-mode
ParameterThesecurity-mode
parameter specifies whether authentication is required only for write operations (such as PUT, POST and DELETE) or for read operations (such as GET and HEAD) as well. Valid values for this parameter areWRITE
for authenticating write operations only, orREAD_WRITE
to authenticate read and write operations. The default value for this parameter isREAD_WRITE
.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <rest-connector virtual-server="default-host" cache-container="local" context-path="${CONTEXT_PATH}" security-domain="${SECURITY_DOMAIN}" auth-method="${METHOD}" security-mode="${MODE}" /> </subsystem>
11.6. Using the REST Interface
- Adding data
- Retrieving data
- Removing data
11.6.1. Adding Data Using REST
- HTTP
PUT
method - HTTP
POST
method
PUT
and POST
methods are used, the body of the request contains this data, which includes any information added by the user.
PUT
and POST
methods require a Content-Type header.
11.6.1.1. About PUT /{cacheName}/{cacheKey}
PUT
request from the provided URL form places the payload, from the request body in the targeted cache using the provided key. The targeted cache must exist on the server for this task to successfully complete.
hr
is the cache name and payRoll%2F3
is the key. The value %2F
indicates that a /
was used in the key.
http://someserver/rest/hr/payRoll%2F3
Time-To-Live
and Last-Modified
values are updated, if an update is required.
Note
%2F
to represent a /
in the key (as in the provided example) can be successfully run if the server is started using the following argument:
-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true
11.6.1.2. About POST /{cacheName}/{cacheKey}
POST
method from the provided URL form places the payload (from the request body) in the targeted cache using the provided key. However, in a POST
method, if a value in a cache/key exists, a HTTP CONFLICT
status is returned and the content is not updated.
11.6.2. Retrieving Data Using REST
- HTTP
GET
method. - HTTP
HEAD
method.
11.6.2.1. About GET /{cacheName}/{cacheKey}
GET
method returns the data located in the supplied cacheName
, matched to the relevant key, as the body of the response. The Content-Type header provides the type of the data. A browser can directly access the cache.
11.6.2.2. About HEAD /{cacheName}/{cacheKey}
HEAD
method operates in a manner similar to the GET
method, however returns no content (header fields are returned).
11.6.3. Removing Data Using REST
DELETE
method to retrieve data from the cache. The DELETE
method can:
- Remove a cache entry/value. (
DELETE /{cacheName}/{cacheKey}
) - Remove all entries from a cache. (
DELETE /{cacheName}
)
11.6.3.1. About DELETE /{cacheName}/{cacheKey}
DELETE /{cacheName}/{cacheKey}
), the DELETE
method removes the key/value from the cache for the provided key.
11.6.3.2. About DELETE /{cacheName}
DELETE /{cacheName}
), the DELETE
method removes all entries in the named cache. After a successful DELETE
operation, the HTTP status code 200
is returned.
11.6.3.3. Background Delete Operations
performAsync
header to true
to ensure an immediate return while the removal operation continues in the background.
11.6.4. REST Interface Operation Headers
Table 11.1. Header Types
Headers | Mandatory/Optional | Values | Default Value | Details |
---|---|---|---|---|
Content-Type | Mandatory | - | - | If the Content-Type is set to application/x-java-serialized-object , it is stored as a Java object. |
performAsync | Optional | True/False | - | If set to true , an immediate return occurs, followed by a replication of data to the cluster on its own. This feature is useful when dealing with bulk data inserts and large clusters. |
timeToLiveSeconds | Optional | Numeric (positive and negative numbers) | -1 (This value prevents expiration as a direct result of timeToLiveSeconds. Expiration values set elsewhere override this default value.) | Reflects the number of seconds before the entry in question is automatically deleted. Setting a negative value for timeToLiveSeconds provides the same result as the default value. |
maxIdleTimeSeconds | Optional | Numeric (positive and negative numbers) | -1 (This value prevents expiration as a direct result of maxIdleTimeSeconds. Expiration values set elsewhere override this default value.) | Contains the number of seconds after the last usage when the entry will be automatically deleted. Passing a negative value provides the same result as the default value. |
timeToLiveSeconds
and maxIdleTimeSeconds
headers:
- If both the
timeToLiveSeconds
andmaxIdleTimeSeconds
headers are assigned the value0
, the cache uses the defaulttimeToLiveSeconds
andmaxIdleTimeSeconds
values configured either using XML or programatically. - If only the
maxIdleTimeSeconds
header value is set to0
, thetimeToLiveSeconds
value should be passed as the parameter (or the default-1
, if the parameter is not present). Additionally, themaxIdleTimeSeconds
parameter value defaults to the values configured either using XML or programatically. - If only the
timeToLiveSeconds
header value is set to0
, expiration occurs immediately and themaxIdleTimeSeconds
value is set to the value passed as a parameter (or the default-1
if no parameter was supplied).
ETags (Entity Tags) are returned for each REST Interface entry, along with a Last-Modified
header that indicates the state of the data at the supplied URL. ETags are used in HTTP operations to request data exclusively in cases where the data has changed to save bandwidth. The following headers support ETags (Entity Tags) based optimistic locking:
Table 11.2. Entity Tag Related Headers
Header | Algorithm | Example | Details |
---|---|---|---|
If-Match | If-Match = "If-Match" ":" ( "*" | 1#entity-tag ) | - | Used in conjunction with a list of associated entity tags to verify that a specified entity (that was previously obtained from a resource) remains current. |
If-None-Match | - | Used in conjunction with a list of associated entity tags to verify that none of the specified entities (that was previously obtained from a resource) are current. This feature facilitates efficient updates of cached information when required and with minimal transaction overhead. | |
If-Modified-Since | If-Modified-Since = "If-Modified-Since" ":" HTTP-date | If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT | Compares the requested variant's last modification time and date with a supplied time and date value. If the requested variant has not been modified since the specified time and date, a 304 (not modified) response is returned without a message-body instead of an entity. |
If-Unmodified-Since | If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date | If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT | Compares the requested variant's last modification time and date with a supplied time and date value. If the requested resources has not been modified since the supplied date and time, the specified operation is performed. If the requested resource has been modified since the supplied date and time, the operation is not performed and a 412 (Precondition Failed) response is returned. |
11.7. REST Interface Security
11.7.1. Publish REST Endpoints as a Public Interface
interface
parameter in the socket-binding
element from management
to public
as follows:
<socket-binding name="http" interface="public" port="8080"/>
11.7.2. Enable Security for the REST Endpoint
Note
Procedure 11.2. Enable Security for the REST Endpoint
standalone.xml
:
Specify Security Parameters
Ensure that the rest endpoint specifies a valid value for thesecurity-domain
andauth-method
parameters. Recommended settings for these parameters are as follows:<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <rest-connector virtual-server="default-host" cache-container="local" security-domain="other" auth-method="BASIC"/> </subsystem>
Check Security Domain Declaration
Ensure that the security subsystem contains the corresponding security-domain declaration. For details about setting up security-domain declarations, see the JBoss Enterprise Application Platform 6 documentation.Add an Application User
Run the relevant script and enter the configuration settings to add an application user.- Run the
adduser.sh
script (located in$JDG_HOME/bin
).- On a Windows system, run the
adduser.bat
file (located in$JDG_HOME/bin
) instead.
- When prompted about the type of user to add, select
Application User (application-users.properties)
by enteringb
. - Accept the default value for realm (
ApplicationRealm
) by pressing the return key. - Specify a username and password.
- When prompted for a role for the created user, enter
REST
. - Ensure the username and application realm information is correct when prompted and enter "yes" to continue.
Verify the Created Application User
Ensure that the created application user is correctly configured.- Check the configuration listed in the
application-users.properties
file (located in$JDG_HOME/standalone/configuration/
). The following is an example of what the correct configuration looks like in this file:user1=2dc3eacfed8cf95a4a31159167b936fc
- Check the configuration listed in the
application-roles.properties
file (located in$JDG_HOME/standalone/configuration/
). The following is an example of what the correct configuration looks like in this file:user1=REST
Test the Server
Start the server and enter the following link in a browser window to access the REST endpoint:http://localhost:8080/rest/namedCache
Note
If testing using a GET request, a405
response code is expected and indicates that the server was successfully authenticated.
Chapter 12. The Memcached Interface
12.1. About Memcached Servers
- Standalone, where each server acts independently without communication with any other memcached servers.
- Clustered, where servers replicate and distribute data to other memcached servers.
12.2. Memcached Statistics
Table 12.1. Memcached Statistics
Statistic | Data Type | Details |
---|---|---|
uptime | 32-bit unsigned integer. | Contains the time (in seconds) that the memcached instance has been available and running. |
time | 32-bit unsigned integer. | Contains the current time. |
version | String | Contains the current version. |
curr_items | 32-bit unsigned integer. | Contains the number of items currently stored by the instance. |
total_items | 32-bit unsigned integer. | Contains the total number of items stored by the instance during its lifetime. |
cmd_get | 64-bit unsigned integer | Contains the total number of get operation requests (requests to retrieve data). |
cmd_set | 64-bit unsigned integer | Contains the total number of set operation requests (requests to store data). |
get_hits | 64-bit unsigned integer | Contains the number of keys that are present from the keys requested. |
get_misses | 64-bit unsigned integer | Contains the number of keys that were not found from the keys requested. |
delete_hits | 64-bit unsigned integer | Contains the number of keys to be deleted that were located and successfully deleted. |
delete_misses | 64-bit unsigned integer | Contains the number of keys to be deleted that were not located and therefore could not be deleted. |
incr_hits | 64-bit unsigned integer | Contains the number of keys to be incremented that were located and successfully incremented |
incr_misses | 64-bit unsigned integer | Contains the number of keys to be incremented that were not located and therefore could not be incremented. |
decr_hits | 64-bit unsigned integer | Contains the number of keys to be decremented that were located and successfully decremented. |
decr_misses | 64-bit unsigned integer | Contains the number of keys to be decremented that were not located and therefore could not be decremented. |
cas_hits | 64-bit unsigned integer | Contains the number of keys to be compared and swapped that were found and successfully compared and swapped. |
cas_misses | 64-bit unsigned integer | Contains the number of keys to be compared and swapped that were not found and therefore not compared and swapped. |
cas_badval | 64-bit unsigned integer | Contains the number of keys where a compare and swap occurred but the original value did not match the supplied value. |
evictions | 64-bit unsigned integer | Contains the number of eviction calls performed. |
bytes_read | 64-bit unsigned integer | Contains the total number of bytes read by the server from the network. |
bytes_written | 64-bit unsigned integer | Contains the total number of bytes written by the server to the network. |
12.3. The Memcached Interface Connector
- The
hotrod-connector
element, which defines the configuration for a Hot Rod based connector. - The
memcached-connector
element, which defines the configuration for a memcached based connector. - The
rest-connector
element, which defines the configuration for a REST interface based connector.
<socket-binding-group />
, and exposing the caches declared in the local
container, using defaults for all other settings. The following examples show how to connect to Hot Rod, Memcached, and REST servers.
memcached
socket binding, and exposes the memcachedCache
cache declared in the local
container, using defaults for all other settings.
<memcached-connector socket-binding="memcached" cache-container="local"/>
12.3.1. Configure Memcached Connectors
connectors
element in Red Hat JBoss Data Grid's Remote Client-Server Mode.
Procedure 12.1. Configuring the Memcached Connector in Remote Client-Server Mode
memcached-connector
element defines the configuration elements for use with memcached.
The
socket-binding
ParameterThesocket-binding
parameter specifies the socket binding port used by the memcached connector. This is a mandatory parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <memcached-connector socket-binding="memcached" />
The
cache-container
ParameterThecache-container
parameter names the cache container used by the memcached connector. This is a mandatory parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <memcached-connector socket-binding="memcached" cache-container="local" />
The
worker-threads
ParameterTheworker-threads
parameter specifies the number of worker threads available for the memcached connector. The default value for this parameter is 160. This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <memcached-connector socket-binding="memcached" cache-container="local" worker-threads="${VALUE}" />
The
idle-timeout
ParameterTheidle-timeout
parameter specifies the time (in milliseconds) the connector can remain idle before the connection times out. The default value for this parameter is-1
, which means that no timeout period is set. This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <memcached-connector socket-binding="memcached" cache-container="local" worker-threads="${VALUE}" idle-timeout="${VALUE}" />
The
tcp-nodelay
ParameterThetcp-nodelay
parameter specifies whether TCP packets will be delayed and sent out in batches. Valid values for this parameter aretrue
andfalse
. The default value for this parameter istrue
. This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <memcached-connector socket-binding="memcached" cache-container="local" worker-threads="${VALUE}" idle-timeout="{VALUE}" tcp-nodelay="{TRUE/FALSE}"/>
The
send-buffer-size
ParameterThesend-buffer-size
parameter indicates the size of the send buffer for the memcached connector. The default value for this parameter is the size of the TCP stack buffer. This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <memcached-connector socket-binding="memcached" cache-container="local" worker-threads="${VALUE}" idle-timeout="{VALUE}" tcp-nodelay="{TRUE/FALSE}" send-buffer-size="{VALUE}" />
The
receive-buffer-size
ParameterThereceive-buffer-size
parameter indicates the size of the receive buffer for the memcached connector. The default value for this parameter is the size of the TCP stack buffer. This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <memcached-connector socket-binding="memcached" cache-container="local" worker-threads="${VALUE}" idle-timeout="{VALUE}" tcp-nodelay="{TRUE/FALSE}" send-buffer-size="{VALUE}" receive-buffer-size="${VALUE}" /> </subsystem>
12.4. Memcached Interface Security
12.4.1. Publish Memcached Endpoints as a Public Interface
interface
parameter in the socket-binding
element from management
to public
as follows:
<socket-binding name="memcached" interface="public" port="11211" />
Chapter 13. The Hot Rod Interface
13.1. About Hot Rod
13.2. The Benefits of Using Hot Rod over Memcached
- Memcached
- The memcached protocol causes the server endpoint to use the memcached text wire protocol. The memcached wire protocol has the benefit of being commonly used, and is available for almost any platform. All of JBoss Data Grid's functions, including clustering, state sharing for scalability, and high availability, are available when using memcached.However the memcached protocol lacks dynamicity, resulting in the need to manually update the list of server nodes on your clients in the event one of the nodes in a cluster fails. Also, memcached clients are not aware of the location of the data in the cluster. This means that they will request data from a non-owner node, incurring the penalty of an additional request from that node to the actual owner, before being able to return the data to the client. This is where the Hot Rod protocol is able to provide greater performance than memcached.
- Hot Rod
- JBoss Data Grid's Hot Rod protocol is a binary wire protocol that offers all the capabilities of memcached, while also providing better scaling, durability, and elasticity.The Hot Rod protocol does not need the hostnames and ports of each node in the remote cache, whereas memcached requires these parameters to be specified. Hot Rod clients automatically detect changes in the topology of clustered Hot Rod servers; when new nodes join or leave the cluster, clients update their Hot Rod server topology view. Consequently, Hot Rod provides ease of configuration and maintenance, with the advantage of dynamic load balancing and failover.Additionally, the Hot Rod wire protocol uses smart routing when connecting to a distributed cache. This involves sharing a consistent hash algorithm between the server nodes and clients, resulting in faster read and writing capabilities than memcached.
13.3. Hot Rod Hash Functions
13.4. The Hot Rod Interface Connector
- The
hotrod-connector
element, which defines the configuration for a Hot Rod based connector. - The
memcached-connector
element, which defines the configuration for a memcached based connector. - The
rest-connector
element, which defines the configuration for a REST interface based connector.
<socket-binding-group />
, and exposing the caches declared in the local
container, using defaults for all other settings. The following examples show how to connect to Hot Rod, Memcached, and REST servers.
hotrod
socket binding.
<hotrod-connector socket-binding="hotrod" cache-container="local" />
<topology-state-transfer />
child element to the connector as follows:
<hotrod-connector socket-binding="hotrod" cache-container="local"> <topology-state-transfer lazy-retrieval="false" lock-timeout="1000" replication-timeout="5000" /> </hotrod-connector>
Note
13.4.1. Configure Hot Rod Connectors
hotrod-connector
and topology-state-transfer
elements must be configured based on the following procedure.
Procedure 13.1. Configuring Hot Rod Connectors for Remote Client-Server Mode
The
hotrod-connector
ElementThehotrod-connector
element defines the configuration elements for use with Hot Rod.The
socket-binding
ParameterThesocket-binding
parameter specifies the socket binding port used by the Hot Rod connector. This is a mandatory parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <hotrod-connector socket-binding="hotrod" />
The
cache-container
ParameterThecache-container
parameter names the cache container used by the Hot Rod connector. This is a mandatory parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <hotrod-connector socket-binding="hotrod" cache-container="local" />
The
worker-threads
ParameterTheworker-threads
parameter specifies the number of worker threads available for the Hot Rod connector. The default value for this parameter is160
. This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <hotrod-connector socket-binding="hotrod" cache-container="local" worker-threads="${VALUE}" />
The
idle-timeout
ParameterTheidle-timeout
parameter specifies the time (in milliseconds) the connector can remain idle before the connection times out. The default value for this parameter is-1
, which means that no timeout period is set. This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <hotrod-connector socket-binding="hotrod" cache-container="local" worker-threads="${VALUE}" idle-timeout="${VALUE}"/>
The
tcp-nodelay
ParameterThetcp-nodelay
parameter specifies whether TCP packets will be delayed and sent out in batches. Valid values for this parameter aretrue
andfalse
. The default value for this parameter istrue
. This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <hotrod-connector socket-binding="hotrod" cache-container="local" worker-threads="${VALUE}" idle-timeout="${VALUE}" tcp-nodelay="${TRUE/FALSE}" />
The
send-buffer-size
ParameterThesend-buffer-size
parameter indicates the size of the send buffer for the Hot Rod connector. The default value for this parameter is the size of the TCP stack buffer. This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <hotrod-connector socket-binding="hotrod" cache-container="local" worker-threads="${VALUE}" idle-timeout="${VALUE}" tcp-nodelay="${TRUE/FALSE}" send-buffer-size="${VALUE}"/>
The
receive-buffer-size
ParameterThereceive-buffer-size
parameter indicates the size of the receive buffer for the Hot Rod connector. The default value for this parameter is the size of the TCP stack buffer. This is an optional parameter.subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <hotrod-connector socket-binding="hotrod" cache-container="local" worker-threads="${VALUE}" idle-timeout="${VALUE}" tcp-nodelay="${TRUE/FALSE}" send-buffer-size="${VALUE}" receive-buffer-size="${VALUE}" />
The
topology-state-transfer
ElementThetopology-state-transfer
element specifies the topology state transfer configurations for the Hot Rod connector. This element can only occur once within ahotrod-connector
element.The
lock-timeout
ParameterThelock-timeout
parameter specifies the time (in milliseconds) after which the operation attempting to obtain a lock times out. The default value for this parameter is10
seconds. This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <hotrod-connector socket-binding="hotrod" cache-container="local" worker-threads="${VALUE}" idle-timeout="${VALUE}" tcp-nodelay="${TRUE/FALSE}" send-buffer-size="${VALUE}" receive-buffer-size="${VALUE}" /> <topology-state-transfer lock-timeout"="${MILLISECONDS}" />
The
replication-timeout
ParameterThereplication-timeout
parameter specifies the time (in milliseconds) after which the replication operation times out. The default value for this parameter is10
seconds. This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <hotrod-connector socket-binding="hotrod" cache-container="local" worker-threads="${VALUE}" idle-timeout="${VALUE}" tcp-nodelay="${TRUE/FALSE}" send-buffer-size="${VALUE}" receive-buffer-size="${VALUE}" /> <topology-state-transfer lock-timeout"="${MILLISECONDS}" replication-timeout="${MILLISECONDS}" />
The
external-host
ParameterTheexternal-host
parameter specifies the hostname sent by the Hot Rod server to clients listed in the topology information. The default value for this parameter is the host address. This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <hotrod-connector socket-binding="hotrod" cache-container="local" worker-threads="${VALUE}" idle-timeout="${VALUE}" tcp-nodelay="${TRUE/FALSE}" send-buffer-size="${VALUE}" receive-buffer-size="${VALUE}" /> <topology-state-transfer lock-timeout"="${MILLISECONDS}" replication-timeout="${MILLISECONDS}" external-host="${HOSTNAME}" />
The
external-port
ParameterTheexternal-port
parameter specifies the port sent by the Hot Rod server to clients listed in the topology information. The default value for this parameter is the configured port. This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <hotrod-connector socket-binding="hotrod" cache-container="local" worker-threads="${VALUE}" idle-timeout="${VALUE}" tcp-nodelay="${TRUE/FALSE}" send-buffer-size="${VALUE}" receive-buffer-size="${VALUE}" /> <topology-state-transfer lock-timeout"="${MILLISECONDS}" replication-timeout="${MILLISECONDS}" external-host="${HOSTNAME}" external-port="${PORT}" />
The
lazy-retrieval
ParameterThelazy-retrieval
parameter indicates whether the Hot Rod connector will carry out retrieval operations lazily. The default value for this parameter istrue
. This is an optional parameter.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <hotrod-connector socket-binding="hotrod" cache-container="local" worker-threads="${VALUE}" idle-timeout="${VALUE}" tcp-nodelay="${TRUE/FALSE}" send-buffer-size="${VALUE}" receive-buffer-size="${VALUE}" /> <topology-state-transfer lock-timeout"="${MILLISECONDS}" replication-timeout="${MILLISECONDS}" external-host="${HOSTNAME}" external-port="${PORT}" lazy-retrieval="${TRUE/FALSE}" /> </subsystem>
The
await-initial-transfer
ParameterTheawait-initial-transfer
parameter specifies whether the initial state retrieval happens immediately at startup. This parameter only applies whenlazy-retrieval
is set tofalse
. This default value for this parameter istrue
.<subsystem xmlns="urn:infinispan:server:endpoint:6.1"> <hotrod-connector socket-binding="hotrod" cache-container="local" worker-threads="${VALUE}" idle-timeout="${VALUE}" tcp-nodelay="${TRUE/FALSE}" send-buffer-size="${VALUE}" receive-buffer-size="${VALUE}" /> <topology-state-transfer lock-timeout"="${MILLISECONDS}" replication-timeout="${MILLISECONDS}" external-host="${HOSTNAME}" external-port="${PORT}" lazy-retrieval="${TRUE/FALSE}" await-initial-transfer="${TRUE/FALSE}" /> </subsystem>
13.5. Hot Rod Headers
13.5.1. Hot Rod Header Data Types
Table 13.1. Header Data Types
Data Type | Size | Details |
---|---|---|
vInt | Between 1-5 bytes. | Unsigned variable length integer values. |
vLong | Between 1-9 bytes. | Unsigned variable length long values. |
string | - | Strings are always represented using UTF-8 encoding. |
13.5.2. Request Header
Table 13.2. Request Header Fields
Field Name | Data Type/Size | Details |
---|---|---|
Magic | 1 byte | Indicates whether the header is a request header or response header. |
Message ID | vLong | Contains the message ID. Responses use this unique ID when responding to a request. This allows Hot Rod clients to implement the protocol in an asynchronous manner. |
Version | 1 byte | Contains the Hot Rod server version. |
Opcode | 1 byte | Contains the relevant operation code. In a request header, opcode can only contain the request operation codes. |
Cache Name Length | vInt | Stores the length of the cache name. If Cache Name Length is set to 0 and no value is supplied for Cache Name, the operation interacts with the default cache. |
Cache Name | string | Stores the name of the target cache for the specified operation. This name must match the name of a predefined cache in the cache configuration file. |
Flags | vInt | Contains a numeric value of variable length that represents flags passed to the system. Each bit represents a flag, except the most significant bit, which is used to determine whether more bytes must be read. Using a bit to represent each flag facilitates the representation of flag combinations in a condensed manner. |
Client Intelligence | 1 byte | Contains a value that indicates the client capabilities to the server. |
Topology ID | vInt | Contains the last known view ID in the client. Basic clients supply the value 0 for this field. Clients that support topology or hash information supply the value 0 until the server responds with the current view ID, which is subsequently used until a new view ID is returned by the server to replace the current view ID. |
Transaction Type | 1 byte | Contains a value that represents one of two known transaction types. Currently, the only supported value is 0 . |
Transaction ID | byte-array | Contains a byte array that uniquely identifies the transaction associated with the call. The transaction type determines the length of this byte array. If the value for Transaction Type was set to 0 , no Transaction ID is present. |
13.5.3. Response Header
Table 13.3. Response Header Fields
Field Name | Data Type | Details |
---|---|---|
Magic | 1 byte | Indicates whether the header is a request or response header. |
Message ID | vLong | Contains the message ID. This unique ID is used to pair the response with the original request. This allows Hot Rod clients to implement the protocol in an asynchronous manner. |
Opcode | 1 byte | Contains the relevant operation code. In a response header, opcode can only contain the response operation codes. |
Status | 1 byte | Contains a code that represents the status of the response. |
Topology Change Marker | 1 byte | Contains a marker byte that indicates whether the response is included in the topology change information. |
13.5.4. Topology Change Headers
topology ID
and the topology ID
sent by the client and, if the two differ, it returns a new topology ID
.
13.5.4.1. Topology Change Marker Values
Topology Change Marker
field in a response header:
Table 13.4. Topology Change Marker Field Values
Value | Details |
---|---|
0 | No topology change information is added. |
1 | Topology change information is added. |
13.5.4.2. Topology Change Headers for Topology-Aware Clients
Table 13.5. Topology Change Header Fields
Response Header Fields | Data Type/Size | Details |
---|---|---|
Response Header with Topology Change Marker | - | - |
Topology ID | vInt | - |
Num Servers in Topology | vInt | Contains the number of Hot Rod servers running in the cluster. This value can be a subset of the entire cluster if only some nodes are running Hot Rod servers. |
mX: Host/IP Length | vInt | Contains the length of the hostname or IP address of an individual cluster member. Variable length allows this element to include hostnames, IPv4 and IPv6 addresses. |
mX: Host/IP Address | string | Contains the hostname or IP address of an individual cluster member. The Hot Rod client uses this information to access the individual cluster member. |
mX: Port | Unsigned Short. 2 bytes | Contains the port used by Hot Rod clients to communicate with the cluster member. |
mX
, are repeated for each server in the topology. The first server in the topology's information fields will be prefixed with m1
and the numerical value is incremented by one for each additional server till the value of X
equals the number of servers specified in the num servers in topology
field.
13.5.4.3. Topology Change Headers for Hash Distribution-Aware Clients
Table 13.6. Topology Change Header Fields
Field | Data Type/Size | Details |
---|---|---|
Response Header with Topology Change Marker | - | - |
Topology ID | vInt | - |
Number Key Owners | Unsigned short. 2 bytes. | Contains the number of globally configured copies for each distributed key. Contains the value 0 if distribution is not configured on the cache. |
Hash Function Version | 1 byte | Contains a pointer to the hash function in use. Contains the value 0 if distribution is not configured on the cache. |
Hash Space Size | vInt | Contains the modulus used by JBoss Data Grid for all module arithmetic related to hash code generation. Clients use this information to apply the correct hash calculations to the keys. Contains the value 0 if distribution is not configured on the cache. |
Number servers in topology | vInt | Contains the number of Hot Rod servers running in the cluster. This value can be a subset of the entire cluster if only some nodes are running Hot Rod servers. This value also represents the number of host to port pairings included in the header. |
Number Virtual Nodes Owners | vInt | Contains the number of configured virtual nodes. Contains the value 0 if no virtual nodes are configured or if distribution is not configured on the cache. |
mX: Host/IP Length | vInt | Contains the length of the hostname or IP address of an individual cluster member. Variable length allows this element to include hostnames, IPv4 and IPv6 addresses. |
mX: Host/IP Address | string | Contains the hostname or IP address of an individual cluster member. The Hot Rod client uses this information to access the individual cluster member. |
mX: Port | Unsigned short. 2 bytes. | Contains the port used by Hot Rod clients to communicate with the cluster member. |
mX: Hashcode | 4 bytes. |
mX
, are repeated for each server in the topology. The first server in the topology's information fields will be prefixed with m1
and the numerical value is incremented by one for each additional server till the value of X
equals the number of servers specified in the num servers in topology
field.
13.6. Hot Rod Operations
- BulkGetKeys
- BulkGet
- Clear
- ContainsKey
- Get
- GetWithMetadata
- Ping
- PutIfAbsent
- Put
- Query
- RemoveIfUnmodified
- Remove
- ReplaceIfUnmodified
- Replace
- Stats
Important
Put
, PutIfAbsent
, Replace
, and ReplaceWithVersion
operations, if lifespan is set to a value greater than 30 days, the value is treated as UNIX time and represents the number of seconds since the date 1/1/1970.
13.6.1. Hot Rod BulkGet Operation
BulkGet
operation uses the following request format:
Table 13.7. BulkGet Operation Request Format
Field | Data Type | Details |
---|---|---|
Header | - | - |
Entry Count | vInt | Contains the maximum number of Red Hat JBoss Data Grid entries to be returned by the server. The entry is the key and value pair. |
Table 13.8. BulkGet Operation Response Format
Field | Data Type | Details |
---|---|---|
Header | - | - |
More | vInt | Represents if more entries must be read from the stream. While More is set to 1 , additional entries follow until the value of More is set to 0 , which indicates the end of the stream. |
Key Size | - | Contains the size of the key. |
Key | - | Contains the key value. |
Value Size | - | Contains the size of the value. |
Value | - | Contains the value. |
More
, Key Size
, Key
, Value Size
and Value
entry is appended to the response.
13.6.2. Hot Rod BulkGetKeys Operation
BulkGetKeys
operation uses the following request format:
Table 13.9. BulkGetKeys Operation Request Format
Field | Data Type | Details |
---|---|---|
Header | variable | Request header. |
Scope | vInt |
|
Table 13.10. BulkGetKeys Operation Response Format
Field | Data Type | Details |
---|---|---|
Header | variable | Response header |
Response status | 1 byte | 0x00 = success, data follows. |
More | 1 byte | One byte representing whether more keys need to be read from the stream. When set to 1 an entry follows, when set to 0 , it is the end of stream and no more entries are left to read. |
Key 1 Length | vInt | Length of key |
Key 1 | Byte array | Retrieved key. |
More | 1 byte | - |
Key 2 Length | vInt | - |
Key 2 | byte array | - |
...etc |
13.6.3. Hot Rod Clear Operation
clear
operation format includes only a header.
Table 13.11. Clear Operation Response
Response Status | Details |
---|---|
0x00 | Red Hat JBoss Data Grid was successfully cleared. |
13.6.4. Hot Rod ContainsKey Operation
ContainsKey
operation uses the following request format:
Table 13.12. ContainsKey Operation Request Format
Field | Data Type | Details |
---|---|---|
Header | - | - |
Key Length | vInt | Contains the length of the key. The vInt data type is used because of its size (up to 5 bytes), which is larger than the size of Integer.MAX_VALUE . However, Java disallows single array sizes to exceed the size of Integer.MAX_VALUE . As a result, this vInt is also limited to the maximum size of Integer.MAX_VALUE . |
Key | Byte array | Contains a key, the corresponding value of which is requested. |
Table 13.13. ContainsKey Operation Response Format
Response Status | Details |
---|---|
0x00 | Successful operation. |
0x02 | The key does not exist. |
13.6.5. Hot Rod Get Operation
Get
operation uses the following request format:
Table 13.14. Get Operation Request Format
Field | Data Type | Details |
---|---|---|
Header | - | - |
Key Length | vInt | Contains the length of the key. The vInt data type is used because of its size (up to 5 bytes), which is larger than the size of Integer.MAX_VALUE . However, Java disallows single array sizes to exceed the size of Integer.MAX_VALUE . As a result, this vInt is also limited to the maximum size of Integer.MAX_VALUE . |
Key | Byte array | Contains a key, the corresponding value of which is requested. |
Table 13.15. Get Operation Response Format
Response Status | Details |
---|---|
0x00 | Successful operation. |
0x02 | The key does not exist. |
get
operation's response when the key is found is as follows:
Table 13.16. Get Operation Response Format
Field | Data Type | Details |
---|---|---|
Header | - | - |
Value Length | vInt | Contains the length of the value. |
Value | Byte array | Contains the requested value. |
13.6.6. Hot Rod GetWithMetadata Operation
GetWithMetadata
operation uses the following request format:
Table 13.17. GetWithMetadata Operation Request Format
Field | Data Type | Details |
---|---|---|
Header | variable | Request header. |
Key Length | vInt | Length of key. Note that the size of a vInt can be up to five bytes, which theoretically can produce bigger numbers than Integer.MAX_VALUE . However, Java cannot create a single array that is bigger than Integer.MAX_VALUE , hence the protocol limits vInt array lengths to Integer.MAX_VALUE . |
Key | byte array | Byte array containing the key whose value is being requested. |
Table 13.18. GetWithMetadata Operation Response Format
Field | Data Type | Details |
---|---|---|
Header | variable | Response header. |
Response status | 1 byte | 0x00 = success, if key retrieved.
0x02 = if key does not exist.
|
Flag | 1 byte | A flag indicating whether the response contains expiration information. The value of the flag is obtained as a bitwise OR operation between INFINITE_LIFESPAN (0x01) and INFINITE_MAXIDLE (0x02) . |
Created | Long | (optional) a Long representing the timestamp when the entry was created on the server. This value is returned only if the flag's INFINITE_LIFESPAN bit is not set. |
Lifespan | vInt | (optional) a vInt representing the lifespan of the entry in seconds. This value is returned only if the flag's INFINITE_LIFESPAN bit is not set. |
LastUsed | Long | (optional) a Long representing the timestamp when the entry was last accessed on the server. This value is returned only if the flag's INFINITE_MAXIDLE bit is not set. |
MaxIdle | vInt | (optional) a vInt representing the maxIdle of the entry in seconds. This value is returned only if the flag's INFINITE_MAXIDLE bit is not set. |
Entry Version | 8 bytes | Unique value of an existing entry modification. The protocol does not mandate that entry_version values are sequential, however they need to be unique per update at the key level. |
Value Length | vInt | If success, length of value. |
Value | byte array | If success, the requested value. |
13.6.7. Hot Rod Ping Operation
ping
is an application level request to check for server availability.
Table 13.19. Ping Operation Response
Response Status | Details |
---|---|
0x00 | Successful ping without any errors. |
13.6.8. Hot Rod Put Operation
put
operation request format includes the following:
Table 13.20.
Field | Data Type | Details |
---|---|---|
Header | - | - |
Key Length | - | Contains the length of the key. |
Key | Byte array | Contains the key value. |
Lifespan | vInt | Contains the number of seconds before the entry expires. If the number of seconds exceeds thirty days, the value is treated as UNIX time (i.e. the number of seconds since the date 1/1/1970 ) as the entry lifespan. When set to the value 0 , the entry will never expire. |
Max Idle | vInt | Contains the number of seconds an entry is allowed to remain idle before it is evicted from the cache. If this entry is set to 0 , the entry is allowed to remain idle indefinitely without being evicted due to the max idle value. |
Value Length | vInt | Contains the length of the value. |
Value | Byte array | The requested value. |
Table 13.21.
Response Status | Details |
---|---|
0x00 | The value was successfully stored. |
ForceReturnPreviousValue
is passed, the previous value and key are returned. If the previous key and value do not exist, the value length would contain the value 0
.
Important
Put
, PutIfAbsent
, Replace
, and ReplaceWithVersion
operations, if lifespan is set to a value greater than 30 days, the value is treated as UNIX time and represents the number of seconds since the date 1/1/1970.
13.6.9. Hot Rod PutIfAbsent Operation
putIfAbsent
operation request format includes the following:
Table 13.22. PutIfAbsent Operation Request Fields
Field | Data Type | Details |
---|---|---|
Header | - | - |
Key Length | vInt | Contains the length of the key. |
Key | Byte array | Contains the key value. |
Lifespan | vInt | Contains the number of seconds before the entry expires. If the number of seconds exceeds thirty days, the value is treated as UNIX time (i.e. the number of seconds since the date 1/1/1970 ) as the entry lifespan. When set to the value 0 , the entry will never expire. |
Max Idle | vInt | Contains the number of seconds an entry is allowed to remain idle before it is evicted from the cache. If this entry is set to 0 , the entry is allowed to remain idle indefinitely without being evicted due to the max idle value. |
Value Length | vInt | Contains the length of the value. |
Value | Byte array | Contains the requested value. |
Table 13.23.
Response Status | Details |
---|---|
0x00 | The value was successfully stored. |
0x01 | The key was present, therefore the value was not stored. The current value of the key is returned. |
ForceReturnPreviousValue
is passed, the previous value and key are returned. If the previous key and value do not exist, the value length would contain the value 0
.
Important
Put
, PutIfAbsent
, Replace
, and ReplaceWithVersion
operations, if lifespan is set to a value greater than 30 days, the value is treated as UNIX time and represents the number of seconds since the date 1/1/1970.
13.6.10. Hot Rod Query Operation
Query
operation request format includes the following:
Table 13.24. Query Operation Request Fields
Field | Data Type | Details |
---|---|---|
Header | variable | Request header. |
Query Length | vInt | The length of the Protobuf encoded query object. |
Query | Byte array | Byte array containing the Protobuf encoded query object, having a length specified by previous field. |
Table 13.25. Query Operation Response
Response Status | Data | Details |
---|---|---|
Header | variable | Response header. |
Response payload Length | vInt | The length of the Protobuf encoded response object. |
Response payload | Byte array | Byte array containing the Protobuf encoded response object, having a length specified by previous field. |
13.6.11. Hot Rod Remove Operation
Hot Rod
Remove
operation uses the following request format:
Table 13.26. Remove Operation Request Format
Field | Data Type | Details |
---|---|---|
Header | - | - |
Key Length | vInt | Contains the length of the key. The vInt data type is used because of its size (up to 5 bytes), which is larger than the size of Integer.MAX_VALUE . However, Java disallows single array sizes to exceed the size of Integer.MAX_VALUE . As a result, this vInt is also limited to the maximum size of Integer.MAX_VALUE . |
Key | Byte array | Contains a key, the corresponding value of which is requested. |
Table 13.27. Remove Operation Response Format
Response Status | Details |
---|---|
0x00 | Successful operation. |
0x02 | The key does not exist. |
ForceReturnPreviousValue
is passed, the response header contains either:
- The value and length of the previous key.
- The value length
0
and the response status0x02
to indicate that the key does not exist.
ForceReturnPreviousValue
is passed. If the key does not exist or the previous value was null, the value length is 0
.
13.6.12. Hot Rod RemoveIfUnmodified Operation
RemoveIfUnmodified
operation request format includes the following:
Table 13.28. RemoveIfUnmodified Operation Request Fields
Field | Data Type | Details |
---|---|---|
Header | - | - |
Key Length | vInt | Contains the length of the key. |
Key | Byte array | Contains the key value. |
Entry Version | 8 bytes | The version number for the entry. |
Table 13.29. RemoveIfUnmodified Operation Response
Response Status | Details |
---|---|
0x00 | Returned status if the entry was replaced or removed. |
0x01 | Returns status if the entry replace or remove was unsuccessful because the key was modified. |
0x02 | Returns status if the key does not exist. |
ForceReturnPreviousValue
is passed, the previous value and key are returned. If the previous key and value do not exist, the value length would contain the value 0
.
13.6.13. Hot Rod Replace Operation
replace
operation request format includes the following:
Table 13.30. Replace Operation Request Fields
Field | Data Type | Details |
---|---|---|
Header | - | - |
Key Length | vInt | Contains the length of the key. |
Key | Byte array | Contains the key value. |
Lifespan | vInt | Contains the number of seconds before the entry expires. If the number of seconds exceeds thirty days, the value is treated as UNIX time (i.e. the number of seconds since the date 1/1/1970 ) as the entry lifespan. When set to the value 0 , the entry will never expire. |
Max Idle | vInt | Contains the number of seconds an entry is allowed to remain idle before it is evicted from the cache. If this entry is set to 0 , the entry is allowed to remain idle indefinitely without being evicted due to the max idle value. |
Value Length | vInt | Contains the length of the value. |
Value | Byte array | Contains the requested value. |
Table 13.31. Replace Operation Response
Response Status | Details |
---|---|
0x00 | The value was successfully stored. |
0x01 | The value was not stored because the key does not exist. |
ForceReturnPreviousValue
is passed, the previous value and key are returned. If the previous key and value do not exist, the value length would contain the value 0
.
Important
Put
, PutIfAbsent
, Replace
, and ReplaceWithVersion
operations, if lifespan is set to a value greater than 30 days, the value is treated as UNIX time and represents the number of seconds since the date 1/1/1970.
13.6.14. Hot Rod ReplaceWithVersion Operation
ReplaceWithVersion
operation request format includes the following:
Note
ReplaceWithVersion
operation uses the ReplaceIfUnmodified
operation. As a result, these two operations are exactly the same in JBoss Data Grid.
Table 13.32. ReplaceWithVersion Operation Request Fields
Field | Data Type | Details |
---|---|---|
Header | - | - |
Key Length | vInt | Contains the length of the key. |
Key | Byte array | Contains the key value. |
Lifespan | vInt | Contains the number of seconds before the entry expires. If the number of seconds exceeds thirty days, the value is treated as UNIX time (i.e. the number of seconds since the date 1/1/1970 ) as the entry lifespan. When set to the value 0 , the entry will never expire. |
Max Idle | vInt | Contains the number of seconds an entry is allowed to remain idle before it is evicted from the cache. If this entry is set to 0 , the entry is allowed to remain idle indefinitely without being evicted due to the max idle value. |
Entry Version | 8 bytes | The version number for the entry. |
Value Length | vInt | Contains the length of the value. |
Value | Byte array | Contains the requested value. |
Table 13.33. ReplaceWithVersion Operation Response
Response Status | Details |
---|---|
0x00 | Returned status if the entry was replaced or removed. |
0x01 | Returns status if the entry replace or remove was unsuccessful because the key was modified. |
0x02 | Returns status if the key does not exist. |
ForceReturnPreviousValue
is passed, the previous value and key are returned. If the previous key and value do not exist, the value length would contain the value 0
.
13.6.15. Hot Rod Stats Operation
Table 13.34. Stats Operation Request Fields
Name | Details |
---|---|
timeSinceStart | Contains the number of seconds since Hot Rod started. |
currentNumberOfEntries | Contains the number of entries that currently exist in the Hot Rod server. |
totalNumberOfEntries | Contains the total number of entries stored in the Hot Rod server. |
stores | Contains the number of put operations attempted. |
retrievals | Contains the number of get operations attempted. |
hits | Contains the number of get hits. |
misses | Contains the number of get misses. |
removeHits | Contains the number of remove hits. |
removeMisses | Contains the number of removal misses. |
Table 13.35. Stats Operation Response
Name | Data Type | Details |
---|---|---|
Header | - | - |
Number of Stats | vInt | Contains the number of individual statistics returned. |
Name Length | vInt | Contains the length of the named statistic. |
Name | string | Contains the name of the statistic. |
Value Length | vInt | Contains the length of the value. |
Value | string | Contains the statistic value. |
Name Length
, Name
, Value Length
and Value
recur for each statistic requested.
13.7. Hot Rod Operation Values
opcode
values for a request header and their corresponding response header values:
Table 13.36. Opcode Request and Response Header Values
Operation | Request Operation Code | Response Operation Code |
---|---|---|
put | 0x01 | 0x02 |
get | 0x03 | 0x04 |
putIfAbsent | 0x05 | 0x06 |
replace | 0x07 | 0x08 |
replaceIfUnmodified | 0x09 | 0x0A |
remove | 0x0B | 0x0C |
removeIfUnmodified | 0x0D | 0x0E |
containsKey | 0x0F | 0x10 |
clear | 0x13 | 0x14 |
stats | 0x15 | 0x16 |
ping | 0x17 | 0x18 |
bulkGet | 0x19 | 0x1A |
getWithMetadata | 0x1B | 0x1C |
bulkKeysGet | 0x1D | 0x1E |
query | 0x1F | 0x20 |
opcode
value is 0x50
, it indicates an error response.
13.7.1. Magic Values
Magic
field in request and response headers:
Table 13.37. Magic Field Values
Value | Details |
---|---|
0xA0 | Cache request marker. |
0xA1 | Cache response marker. |
13.7.2. Status Values
Status
field in a response header:
Table 13.38. Status Values
Value | Details |
---|---|
0x00 | No error. |
0x01 | Not put/removed/replaced. |
0x02 | Key does not exist. |
0x81 | Invalid Magic value or Message ID. |
0x82 | Unknown command. |
0x83 | Unknown version. |
0x84 | Request parsing error. |
0x85 | Server error. |
0x86 | Command timed out. |
13.7.3. Transaction Type Values
Transaction Type
in a request header:
Table 13.39. Transaction Type Field Values
Value | Details |
---|---|
0 | Indicates a non-transactional call or that the client does not support transactions. If used, the TX_ID field is omitted. |
1 | Indicates X/Open XA transaction ID (XID). This value is currently not supported. |
13.7.4. Client Intelligence Values
Client Intelligence
in a request header:
Table 13.40. Client Intelligence Field Values
Value | Details |
---|---|
0x01 | Indicates a basic client that does not require any cluster or hash information. |
0x02 | Indicates a client that is aware of topology and requires cluster information. |
0x03 | Indicates a client that is aware of hash and distribution and requires both the cluster and hash information. |
13.7.5. Flag Values
flag
values in the request header:
Table 13.41. Flag Field Values
Value | Details |
---|---|
0x0001 | ForceReturnPreviousValue |
13.7.6. Hot Rod Error Handling
Table 13.42. Hot Rod Error Handling using Response Header Fields
Field | Data Type | Details |
---|---|---|
Error Opcode | - | Contains the error operation code. |
Error Status Number | - | Contains a status number that corresponds to the error opcode . |
Error Message Length | vInt | Contains the length of the error message. |
Error Message | string | Contains the actual error message. If an 0x84 error code returns, which indicates that there was an error in parsing the request, this field contains the latest version supported by the Hot Rod server. |
13.8. Put Request Example
put
request using Hot Rod:
Table 13.43. Put Request Example
Byte | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
---|---|---|---|---|---|---|---|---|
8 | 0xA0 | 0x09 | 0x41 | 0x01 | 0x07 | 0x4D ('M') | 0x79 ('y') | 0x43 ('C') |
16 | 0x61 ('a') | 0x63 ('c') | 0x68 ('h') | 0x65 ('e') | 0x00 | 0x03 | 0x00 | 0x00 |
24 | 0x00 | 0x05 | 0x48 ('H') | 0x65 ('e') | 0x6C ('l') | 0x6C ('l') | 0x6F ('o') | 0x00 |
32 | 0x00 | 0x05 | 0x57 ('W') | 0x6F ('o') | 0x72 ('r') | 0x6C ('l') | 0x64 ('d') | - |
Table 13.44. Example Request Field Names and Values
Field Name | Byte | Value |
---|---|---|
Magic | 0 | 0xA0 |
Version | 2 | 0x41 |
Cache Name Length | 4 | 0x07 |
Flag | 12 | 0x00 |
Topology ID | 14 | 0x00 |
Transaction ID | 16 | 0x00 |
Key | 18-22 | 'Hello' |
Max Idle | 24 | 0x00 |
Value | 26-30 | 'World' |
Message ID | 1 | 0x09 |
Opcode | 3 | 0x01 |
Cache Name | 5-11 | 'MyCache' |
Client Intelligence | 13 | 0x03 |
Transaction Type | 15 | 0x00 |
Key Field Length | 17 | 0x05 |
Lifespan | 23 | 0x00 |
Value Field Length | 25 | 0x05 |
put
request:
Table 13.45. Coded Response for the Sample Put Request
Byte | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
---|---|---|---|---|---|---|---|---|
8 | 0xA1 | 0x09 | 0x01 | 0x00 | 0x00 | - | - | - |
Table 13.46. Example Response Field Names and Values
Field Name | Byte | Value |
---|---|---|
Magic | 0 | 0xA1 |
Opcode | 2 | 0x01 |
Topology Change Marker | 4 | 0x00 |
Message ID | 1 | 0x09 |
Status | 3 | 0x00 |
13.9. Hot Rod Java Client
13.9.1. Hot Rod Java Client Download
Procedure 13.2. Download Hot Rod Java Client
- Log into the Customer Portal at https://access.redhat.com.
- Click the Downloads button near the top of the page.
- In the Product Downloads page, click Red Hat JBoss Data Grid.
- Select the appropriate JBoss Data Grid version from the Version: drop down menu.
- Locate the Red Hat JBoss Data Grid ${VERSION} Hot Rod Java Client entry and click the corresponding Download link.
13.9.2. Hot Rod Java Client Configuration
Example 13.1. Client Instance Creation
org.infinispan.client.hotrod.configuration.ConfigurationBuilder cb = new org.infinispan.client.hotrod.configuration.ConfigurationBuilder(); cb.tcpNoDelay(true) .connectionPool() .numTestsPerEvictionRun(3) .testOnBorrow(false) .testOnReturn(false) .testWhileIdle(true) .addServer() .host("localhost") .port(11222); RemoteCacheManager rmc = new RemoteCacheManager(cb.build());
To configure the Hot Rod Java client, edit the hotrod-client.properties
file on the classpath.
hotrod-client.properties
file.
Example 13.2. Configuration
infinispan.client.hotrod.transport_factory = org.infinispan.client.hotrod.impl.transport.tcp.TcpTransportFactory infinispan.client.hotrod.server_list = 127.0.0.1:11222 infinispan.client.hotrod.marshaller = org.infinispan.commons.marshall.jboss.GenericJBossMarshaller infinispan.client.hotrod.async_executor_factory = org.infinispan.client.hotrod.impl.async.DefaultAsyncExecutorFactory infinispan.client.hotrod.default_executor_factory.pool_size = 1 infinispan.client.hotrod.default_executor_factory.queue_size = 10000 infinispan.client.hotrod.hash_function_impl.1 = org.infinispan.client.hotrod.impl.consistenthash.ConsistentHashV1 infinispan.client.hotrod.tcp_no_delay = true infinispan.client.hotrod.ping_on_startup = true infinispan.client.hotrod.request_balancing_strategy = org.infinispan.client.hotrod.impl.transport.tcp.RoundRobinBalancingStrategy infinispan.client.hotrod.key_size_estimate = 64 infinispan.client.hotrod.value_size_estimate = 512 infinispan.client.hotrod.force_return_values = false infinispan.client.hotrod.tcp_keep_alive = true ## below is connection pooling config maxActive=-1 maxTotal = -1 maxIdle = -1 whenExhaustedAction = 1 timeBetweenEvictionRunsMillis=120000 minEvictableIdleTimeMillis=300000 testWhileIdle = true minIdle = 1
Note
TCP
KEEPALIVE
configuration is enabled/disabled on the Hot Rod Java client either through a config property as seen in the example (infinispan.client.hotrod.tcp_keep_alive = true/false
or programmatically through the org.infinispan.client.hotrod.ConfigurationBuilder.tcpKeepAlive()
method.
new RemoteCacheManager(boolean start)
new RemoteCacheManager()
13.9.3. Hot Rod Java Client Basic API
localhost:11222
.
Example 13.3. Basic API
//API entry point, by default it connects to localhost:11222 CacheContainer cacheContainer = new RemoteCacheManager(); //obtain a handle to the remote default cache Cache<String, String> cache = cacheContainer.getCache(); //now add something to the cache and make sure it is there cache.put("car", "ferrari");] assert cache.get("car").equals("ferrari"); //remove the data cache.remove("car"); assert !cache.containsKey("car") : "Value must have been removed!";
RemoteCacheManager
corresponds to DefaultCacheManager
, and both implement CacheContainer
.
DefaultCacheManager
and RemoteCacheManager
, which is simplified by the common CacheContainer
interface.
keySet()
method. If the remote cache is a distributed cache, the server will start a Map/Reduce job to retrieve all keys from clustered nodes and return all keys to the client.
Set keys = remoteCache.keySet();
13.9.4. Hot Rod Java Client Versioned API
getVersioned
, clients can retrieve the value associated with the key as well as the current version.
RemoteCacheManager
provides instances of the RemoteCache
interface that accesses the named or default cache on the remote cluster. This extends the Cache
interface to which it adds new methods, including the versioned API.
Example 13.4. Using Versioned Methods
// To use the versioned API, remote classes are specifically needed RemoteCacheManager remoteCacheManager = new RemoteCacheManager(); RemoteCache<String, String> cache = remoteCacheManager.getCache(); remoteCache.put("car", "ferrari"); VersionedValue valueBinary = remoteCache.getVersioned("car"); // removal only takes place only if the version has not been changed // in between. (a new version is associated with 'car' key on each change) assert remoteCache.remove("car", valueBinary.getVersion()); assert !cache.containsKey("car");
Example 13.5. Using Replace
remoteCache.put("car", "ferrari"); VersionedValue valueBinary = remoteCache.getVersioned("car"); assert remoteCache.replace("car", "lamborghini", valueBinary.getVersion());
13.10. Hot Rod C ++ Client
- Red Hat Enterprise Linux 5, 64-bit
- Red Hat Enterprise Linux 6, 64-bit
13.10.1. Hot Rod C ++ Client Formats
- Static library
- Shared/Dynamic library
The static library is statically linked to an application. This increases the size of the final executable. The application is self-contained and it does not need to ship a separate library.
Shared/Dynamic libraries are dynamically linked to an application at runtime. The library is stored in a separate file and can be upgraded separately from the application, without recompiling the application.
Note
13.10.2. Hot Rod C ++ Client Prerequisites
- C++ 03 compiler with support for shared_ptr TR1 (GCC 4.0+, Visual Studio C++ 2010).
- Red Hat JBoss Data Grid Server 6.1.0 or higher version.
13.10.3. Hot Rod C ++ Client Download
jboss-datagrid-<version>-hotrod-cpp-client-<platform>.zip
under Red Hat JBoss Data Grid binaries on the Red Hat Customer Portal at https://access.redhat.com. Download the appropriate Hot Rod C++ client which applies to your operating system.
13.10.4. Hot Rod C ++ Client Configuration
- The initial set of servers to connect to.
- Connection pooling attributes.
- Connection/Socket timeouts and TCP nodelay.
- Hot Rod protocol version.
The following example shows how to use the ConfigurationBuilder to configure a RemoteCacheManager
and how to obtain the default remote cache:
Example 13.6. SimpleMain.cpp
#include "infinispan/hotrod/ConfigurationBuilder.h" #include "infinispan/hotrod/RemoteCacheManager.h" #include "infinispan/hotrod/RemoteCache.h" #include <stdlib.h> using namespace infinispan::hotrod; int main(int argc, char** argv) { ConfigurationBuilder b; b.addServer().host("127.0.0.1").port(11222); RemoteCacheManager cm(builder.build()); RemoteCache<std::string, std::string> cache = cm.getCache<std::string, std::string>(); return 0; }
13.10.5. Hot Rod C ++ Client API
Example 13.7. SimpleMain.cpp
RemoteCache<std::string, std::string> rc = cm.getCache<std::string, std::string>(); std::string k1("key13"); std::string v1("boron"); // put rc.put(k1, v1); std::auto_ptr<std::string> rv(rc.get(k1)); rc.putIfAbsent(k1, v1); std::auto_ptr<std::string> rv2(rc.get(k1)); std::map<HR_SHARED_PTR<std::string>,HR_SHARED_PTR<std::string> > map = rc.getBulk(0); std::cout << "getBulk size" << map.size() << std::endl; .. . cm.stop();
13.11. Hot Rod C# Client
Warning
13.11.1. Hot Rod C# Client Download and Installation
jboss-datagrid-<version>-hotrod-dotnet-client.msi
packed for download with Red Hat JBoss Data Grid . To install the Hot Rod C# client, execute the following instructions.
Procedure 13.3. Installing the Hot Rod C# Client
- As an administrator, navigate to the location where the Hot Rod C# .msi file is downloaded. Run the .msi file to launch the windows installer and then click Next.
Figure 13.1. Hot Rod C# Client Setup Welcome
- Review the end-user license agreement. Select the I accept the terms in the License Agreement check box and then click Next.
Figure 13.2. Hot Rod C# Client End-User License Agreement
- To change the default directory, click Change... or click Next to install in the default directory.
Figure 13.3. Hot Rod C# Client Destination Folder
- Click Finish to complete the Hot Rod C# client installation.
Figure 13.4. Hot Rod C# Client Setup Completion
13.11.2. Hot Rod C# Client Configuration
The following example shows how to use the ConfigurationBuilder to configure a RemoteCacheManager
.
Example 13.8. C# configuration
using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Threading.Tasks; using Infinispan.HotRod; using Infinispan.HotRod.Config; namespace simpleapp { class Program { static void Main(string[] args) { ConfigurationBuilder builder = new ConfigurationBuilder(); builder.AddServer() .Host(args.Length > 1 ? args[0] : "127.0.0.1") .Port(args.Length > 2 ? int.Parse(args[1]) : 11222); Configuration config = builder.Build(); RemoteCacheManager cacheManager = new RemoteCacheManager(config); [...] } } }
13.11.3. Hot Rod C# Client API
RemoteCacheManager
is a starting point to obtain a reference to a RemoteCache.
Example 13.9.
using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Threading.Tasks; using Infinispan.HotRod; using Infinispan.HotRod.Config; namespace simpleapp { class Program { static void Main(string[] args) { ConfigurationBuilder builder = new ConfigurationBuilder(); builder.AddServer() .Host(args.Length > 1 ? args[0] : "127.0.0.1") .Port(args.Length > 2 ? int.Parse(args[1]) : 11222); Configuration config = builder.Build(); RemoteCacheManager cacheManager = new RemoteCacheManager(config); cacheManager.Start(); // Retrieve a reference to the default cache. IRemoteCache<String, String> cache = cacheManager.GetCache<String, String>(); // Add entries. cache.Put("key1", "value1"); cache.PutIfAbsent("key1", "anotherValue1"); cache.PutIfAbsent("key2", "value2"); cache.PutIfAbsent("key3", "value3"); // Retrive entries. Console.WriteLine("key1 -> " + cache.Get("key1")); // Bulk retrieve key/value pairs. int limit = 10; IDictionary<String, String> result = cache.GetBulk(limit); foreach (KeyValuePair<String, String> kv in result) { Console.WriteLine(kv.Key + " -> " + kv.Value); } // Remove entries. cache.Remove("key2"); Console.WriteLine("key2 -> " + cache.Get("key2")); cacheManager.Stop(); } } }
13.12. Interoperability Between Hot Rod C++ and Hot Rod Java Client
Person
object structured and serialized using Protobuf, and the Java C++ client can read the same Person
object structured as Protobuf.
Example 13.10. Using Interoperability Between Languages
package sample; message Person { required int32 age = 1; required string name = 2; }
Part VI. Set Up Locking for the Cache
Chapter 14. Locking
14.1. Configure Locking (Remote Client-Server Mode)
locking
element within the cache tags (for example, invalidation-cache
, distributed-cache
, replicated-cache
or local-cache
).
Note
READ_COMMITTED
. If the isolation
attribute is included to explicitly specify an isolation mode, it is ignored, a warning is thrown, and the default value is used instead.
Procedure 14.1. Configure Locking (Remote Client-Server Mode)
Set the
acquire-timeout
ParameterTheacquire-timeout
parameter specifies the number of milliseconds after which lock acquisition will time out.<distributed-cache> <locking acquire-timeout="30000" />
Set Number of Lock Stripes
Theconcurrency-level
parameter defines the number of lock stripes used by the LockManager.<distributed-cache> <locking 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 acquire-timeout="30000" concurrency-level="1000" striping="false" /> ... </distributed-cache>
14.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 14.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 16.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 15.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}" />
14.3. Locking Types
14.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.
14.3.2. About Pessimistic Locking
14.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.
14.3.4. Explicit Pessimistic Locking Example
Procedure 14.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()
14.3.5. Implicit Pessimistic Locking Example
Procedure 14.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()
14.3.6. Configure Locking Mode (Remote Client-Server Mode)
transaction
element as follows:
<transaction locking="OPTIMISTIC/PESSIMISTIC" />
14.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.
14.4. Locking Operations
14.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:
14.4.2. About Lock Acquisition
14.4.3. About Concurrency Levels
ConcurrentHashMap
based collections, such as those internal to DataContainers
.
Chapter 15. Set Up Lock Striping
15.1. About Lock Striping
15.2. Configure Lock Striping (Remote Client-Server Mode)
striping
element to true
.
Example 15.1. Lock Striping (Remote Client-Server Mode)
<locking acquire-timeout="20000" concurrency-level="500" striping="true" />
Note
READ_COMMITTED
. If the isolation
attribute is included to explicitly specify an isolation mode, it is ignored, a warning is thrown, and the default value is used instead.
locking
element uses the following attributes:
- The
acquire-timeout
attribute specifies the maximum time to attempt a lock acquisition. The default value for this attribute is15000
milliseconds. - The
concurrency-level
attribute specifies the concurrency level for lock containers. Adjust this value according to the number of concurrent threads interacting with JBoss Data Grid. The default value for this attribute is1000
. - The
striping
attribute specifies whether a shared pool of locks is maintained for all entries that require locking (true
). If set tofalse
, a lock is created for each entry. Lock striping controls the memory footprint but can reduce concurrency in the system. The default value for this attribute isfalse
.
15.3. Configure Lock Striping (Library Mode)
useLockStriping
parameter as demonstrated in the following procedure.
Procedure 15.1. Configure Lock Striping (Library Mode)
Set the Concurrency Level
TheconcurrencyLevel
is used to specify the size of the shared lock collection use when lock striping is enabled.<infinispan> ... <default> <locking concurrencyLevel="${VALUE}" />
Set Isolation Level
TheisolationLevel
parameter specifies the cache's isolation level. Valid isolation levels areREAD_COMMITTED
andREPEATABLE_READ
.<infinispan> ... <default> <locking concurrencyLevel="${VALUE}" isolationLevel="${LEVEL}"/>
Specify 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. If set toTRUE
, lock striping is enabled and shared locks are used as required from the pool.<infinispan> ... <default> <locking concurrencyLevel="${VALUE}" isolationLevel="${LEVEL}" lockAcquisitionTimeout="${TIME}" useLockStriping="${TRUE/FALSE}"/>
Configure Write Skew Check
ThewriteSkewCheck
check determines if a modification to the entry from a different transaction should roll back the transaction. Write skew set to true requiresisolation_level
set toREPEATABLE_READ
. The default value forwriteSkewCheck
andisolation_level
areFALSE
andREAD_COMMITTED
respectively.<infinispan> ... <default> <locking concurrencyLevel="${VALUE}" isolationLevel="${LEVEL}" lockAcquisitionTimeout="${TIME}" useLockStriping="${TRUE/FALSE}" writeSkewCheck="${TRUE/FALSE}" /> ... </default> </infinispan>
Chapter 16. Set Up Isolation Levels
16.1. About Isolation Levels
READ_COMMITTED
and REPEATABLE_READ
are the two isolation modes offered in Red Hat JBoss Data Grid.
READ_COMMITTED
. This isolation level is applicable to a wide variety of requirements. This is the default value in Remote Client-Server and Library modes.REPEATABLE_READ
.Important
The only valid value for locks in Remote Client-Server mode is the defaultREAD_COMMITTED
value. The value explicitly specified with theisolation
value is ignored.If thelocking
element is not present in the configuration, the default isolation value isREAD_COMMITTED
.
- See Section 15.2, “Configure Lock Striping (Remote Client-Server Mode)” for a Remote Client-Server mode configuration sample.
- See Section 15.3, “Configure Lock Striping (Library Mode)” for a Library mode configuration sample.
16.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.
16.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 an entry before a modification occurs. As a result, the "non-repeatable read" phenomenon is avoided because a second read operation on the same entry 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 VII. Set Up and Configure a Cache Store
Chapter 17. Cache Stores
17.1. Cache Loaders and Cache Writers
org.infinispan.persistence.spi
:
CacheLoader
CacheWriter
AdvancedCacheLoader
AdvancedCacheWriter
CacheLoader
and CacheWriter
provide basic methods for reading and writing to a store. CacheLoader
retrieves data from a data store when the required data is not present in the cache.
AdvancedCacheLoader
and AdvancedCacheWriter
provide operations to manipulate the underlaying storage in bulk: parallel iteration and purging of expired entries, clear and size.
org.infinispan.persistence.file.SingleFileStore
can be used as a starting point when writing a custom interface.
Note
CacheLoader
, extended by CacheStore
), which is also still available.
17.2. Cache Store Configuration
17.2.1. Configuring the Cache Store
ignoreModifications
element has been set to "true"
for a specific cache store.
17.2.2. Configure the Cache Store using XML (Library Mode)
<persistence passivation="false"> <singleFile shared="false" preload="true" fetchPersistentState="true" ignoreModifications="false" purgeOnStartup="false" location="${java.io.tmpdir}" > <async enabled="true" flushLockTimeout="15000" threadPoolSize="5" /> <singleton enabled="true" pushStateWhenCoordinator="true" pushStateTimeout="20000" /> </singleFile> </persistence>
17.2.3. Configure the Cache Store Programmatically
ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence() .passivation(false) .addSingleFileStore() .shared(false) .preload(true) .fetchPersistentState(true) .ignoreModifications(false) .purgeOnStartup(false) .location(System.getProperty("java.io.tmpdir")) .async() .enabled(true) .flushLockTimeout(15000) .threadPoolSize(5) .singleton() .enabled(true) .pushStateWhenCoordinator(true) .pushStateTimeout(20000);
Procedure 17.1. Configure the Cache store Programatically
Create a New Configuration Builder
Use theConfigurationBuilder
to create a new configuration object.Set Passivation
passivation
affects the way Red Hat JBoss Data Grid interacts with stores. 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.Configure the Cache Store
addSingleFileStore()
adds the SingleFileStore as the cache store for this configuration. It is possible to create other stores, such as a JDBC Cache Store, which can be added using theaddStore
method.Set Up Sharing
shared
indicates that the cache store 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 store by different cache instances.Set Up Preloading
preload
is set tofalse
by default. When set totrue
the data stored in the cache store is preloaded into the memory when the cache starts. This allows data in the cache store 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.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 store has this property set totrue
. ThefetchPersistentState
property isfalse
by default.Set Modifications
ignoreModifications
determines whether write methods are pushed to the specific cache store by allowing write operations to the local file cache store, but not the shared cache store. In some cases, transient application data should only reside in a file-based cache store on the same server as the in-memory cache. For example, this would apply with a further JDBC based cache store used by all servers in the network.ignoreModifications
isfalse
by default.Set Up Purging
purgeOnStartup
controls whether cache store is purged when it starts up.Set Up Location
location
configuration element sets a location on disk where the store can write.Asynchronous Settings
These attributes configure aspects specific to each cache store. For example, thelocation
attribute points to where the SingleFileStore will keep files containing data. Other stores may require more complex configuration.Configure Singletons
singleton
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 withsingleton
enabled at the same time. Theenabled
attribute isfalse
by default.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 store. This parameter is useful where the coordinator has crashed and a new coordinator is elected.
17.2.4. About SKIP_CACHE_LOAD Flag
SKIP_CACHE_LOAD
flag.
17.3. Shared Cache Stores
17.3.1. Invalidation Mode and Shared Cache Stores
- Compared to replication messages, which contain the updated data, invalidation messages are much smaller and result in reduced network traffic.
- The remaining cluster caches look up modified data from the shared cache store lazily and only when required to do so, resulting in further reduced network traffic.
17.3.2. The Cache Store and Cache Passivation
17.3.3. Application Cachestore Registration
17.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.
17.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.
17.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.
Chapter 18. Cache Store Implementations
18.1. Cache Store Comparison
- The Single File Cache Store is a local file cache store. It persists data locally for each node of the clustered cache. The Single File Cache Store provides superior read and write performance, but keeps keys in memory which limits its use when persisting large data sets at each node. See Section 18.4, “Single File Cache Store” for details.
- The LevelDB file cache store is a local file cache store which provides high read and write performance. It does not have the limitation of Single File Cache Store of keeping keys in memory. See Section 18.5, “LevelDB Cache Store” for details.
- The JDBC cache store is a cache store that may be shared, if required. When using it, all nodes of a clustered cache persist to a single database or a local JDBC database for every node in the cluster. The shared cache store lacks the scalability and performance of a local cache store such as the LevelDB cache store, but it provides a single location for persisted data. The JDBC cache store persists entries as binary blobs, which are not readable outside JBoss Data Grid. See Section 18.6, “JDBC Based Cache Stores” for details.
- The JPA Cache Store (supported in Library mode only) is a shared cache store like JDBC cache store, but preserves schema information when persisting to the database. Therefore, the persisted entries can be read outside JBoss Data Grid. See Section 18.8, “JPA Cache Store” for details.
18.2. Cache Store Configuration Details (Library Mode)
- Add the name value to the
name
parameter to set the name of the cache store.
- The
passivation
parameter affects the way in which Red Hat JBoss Data Grid interacts with stores. Passivation removes an object from in-memory cache and writes it to a secondary data store, such as a system or database. Valid values for this parameter aretrue
andfalse
butpassivation
is set tofalse
by default.
- The
shared
parameter indicates that the cache store 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 store by different cache instances. For the LevelDB cache stores, this parameter must be excluded from the configuration, or set tofalse
because sharing this cache store is not supported. - The
preload
parameter is set tofalse
by default. When set totrue
the data stored in the cache store is preloaded into the memory when the cache starts. This allows data in the cache store 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. - The
fetchPersistentState
parameter 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 store has this property set totrue
. ThefetchPersistentState
property isfalse
by default. - The
ignoreModifications
parameter determines whether write methods are pushed to the specific cache store by allowing write operations to the local file cache store, but not the shared cache store. In some cases, transient application data should only reside in a file-based cache store on the same server as the in-memory cache. For example, this would apply with a further JDBC based cache store used by all servers in the network.ignoreModifications
isfalse
by default. - 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. - The
purgeOnStartup
parameter controls whether cache store is purged when it starts up. - The
location
configuration element sets a location on disk where the store can write.
The async
element contains parameters that configure various aspects of the cache store.
- 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.
The singleton
element 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. The shared
element cannot be defined with singleton
enabled at the same time.
- The
enabled
attribute determines whether this feature is enabled. Valid values for this parameter aretrue
andfalse
. Theenabled
attribute is set tofalse
by default. - The
pushStateWhenCoordinator
parameter is set totrue
by default. Iftrue
, this property causes a node that has become the coordinator to transfer in-memory state to the underlying cache store. This parameter is useful where the coordinator has crashed and a new coordinator is elected. - When
pushStateWhenCoordinator
is set totrue
, thepushStateTimeout
parameter sets the maximum number of milliseconds that the process pushing the in-memory state to the underlying cache loader can take. The default time for this parameter is 10 seconds.
- The
remoteCacheName
attribute specifies the name of the remote cache to which it intends to connect in the remote Infinispan cluster. The default cache will be used if the remote cache name is unspecified. - The
fetchPersistentState
attribute, when set totrue
, ensures that 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
. - The
shared
attribute 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
. - The
preload
attribute ensures that the cache store data is pre-loaded into memory and is 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
. - The
ignoreModifications
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
. - The
purgeOnStartup
attribute ensures that the cache store is purged during the start up process. The default value for this attribute isfalse
. - The
tcpNoDelay
attribute triggers theTCP
NODELAY
stack. The default value for this attribute istrue
. - The
pingOnStartup
attribute sends a ping request to a back end server to fetch the cluster topology. The default value for this attribute istrue
. - The
keySizeEstimate
attribute specifies the class name of the driver used to connect to the database. The default value for this attribute is64
. - The
valueSizeEstimate
attribute specifies the size of the byte buffers when serializing and deserializing values. The default value for this attribute is512
. - The
forceReturnValues
attribute sets whetherFORCE_RETURN_VALUE
is enabled for all calls. The default value for this attribute isfalse
.
Create a servers
element within the remoteStore
element to set up the server information.for multiple servers. Add a server
element within the general servers
element to add the information for a single server.
- The
host
attribute configures the host address. - The
port
attribute configures the port used by the Remote Cache Store.
- The
maxActive
attribute 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. - The
maxIdle
attribute 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. - The
maxTotal
attribute 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. - 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.
- The
location
parameter specifies the location to store the primary cache store. The directory is automatically created if it does not exist. - The
expiredLocation
parameter specifies the location for expired data using. The directory stores expired data before it is purged. The directory is automatically created if it does not exist. - The
shared
parameter specifies whether the cache store is shared. The only supported value for this parameter in the LevelDB cache store isfalse
. - The
preload
parameter specifies whether the cache store will be pre-loaded. Valid values aretrue
andfalse
.
- The
persistenceUnitName
attribute specifies the name of the JPA cache store. - The
entityClassName
attribute specifies the fully qualified class name of the JPA entity used to store the cache entry value. - The
batchSize
(optional) attribute specifies the batch size for cache store streaming. The default value for this attribute is100
. - The
storeMetadata
(optional) attribute specifies whether the cache store keeps the metadata (for example expiration and versioning information) with the entries. The default value for this attribute istrue
.
- 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. - The
key2StringMapper
parameter specifies the class name of the Key2StringMapper used to map keys to strings for the database tables.
- 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.
- The
name
parameter specifies the name of the column used. - The
type
parameter specifies the type of the column used.
- The
class
parameter specifies the class name of the cache store implementation. - The
preload
parameter specifies whether to load entries into the cache during start up. Valid values for this parameter aretrue
andfalse
. - The
shared
parameter specifies whether the cache store is shared. This is used when multiple cache instances share a cache store. Valid values for this parameter aretrue
andfalse
.
- The
name
parameter specifies the name of the property. - The
value
parameter specifies the value of the property.
18.3. Cache Store Configuration Details (Remote Client-Server Mode)
- The
name
parameter of thelocal-cache
attribute is used to specify a name for the cache. - The
statistics
parameter specifies whether statistics are enabled at the container level. Enable or disable statistics on a per-cache basis by setting thestatistics
attribute tofalse
.
- The
name
parameter of thefile-store
element is used to specify a name for the file store. - 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
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
. However, theshared
parameter is not recommended for the LevelDB cache store because this cache store cannot be shared. - The
relative-to
property is the directory where thefile-store
stores the data. It is used to define a named path. - The
path
property is the name of the file where the data is stored. It is a relative path name that is appended to the value of therelative-to
property to determine the complete path. - The
maxEntries
parameter provides maximum number of entries allowed. The default value is -1 for unlimited entries. - The
fetch-state
parameter when set to true fetches the persistent state when joining a cluster. If multiple cache stores are chained, only one of them can have this property enabled. Persistent state transfer with a shared cache store does not make sense, as the same persistent store that provides the data will just end up receiving it. Therefore, if a shared cache store is used, the cache does not allow a persistent state transfer even if a cache store has this property set totrue
. It is recommended to set this property to true only in a clustered environment. The default value for this parameter is false. - The
preload
parameter when set to true, loads the data stored in the cache store into memory when the cache starts. However, setting this parameter to true affects the performance as the startup time is increased. The default value for this parameter is false. - The
singleton
parameter enables a singleton store cache store. SingletonStore is a delegating cache store used when only one instance in a cluster can interact with the underlying store. However,singleton
parameter is not recommended forfile-store
.
- The
class
parameter specifies the class name of the cache store implementation.
- The
name
parameter specifies the name of the property. - The
value
parameter specifies the value assigned to the property.
- The
cache
parameter defines the name for the remote cache. If left undefined, the default cache is used instead. - 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. - The
tcp-no-delay
sets whetherTCP_NODELAY
applies on socket connections to remote Hot Rod servers. - The
hotrod-wrapping
sets whether a wrapper is required for Hot Rod on the remote store.
- The
outbound-socket-binding
parameter sets the outbound socket binding for the remote server.
- 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
- The
prefix
parameter specifies a prefix string for the database table name.
- The
name
parameter specifies the name of the database column. - The
type
parameter specifies the type of the database column.
- The
path
parameter The directory within the path specified in therelative-to
parameter where the cache state is stored. If undefined, the path defaults to the cache container name. - The
passivation
parameter specifies whether passivation is enabled for the LevelDB cache store. Valid values aretrue
andfalse
. - The
purge
parameter specifies whether the cache store is purged when it starts up. Valid values aretrue
andfalse
.
18.4. Single File Cache Store
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.
18.4.1. Single File Store Configuration (Remote Client-Server Mode)
<local-cache name="default" statistics="true"> <file-store name="myFileStore" passivation="true" purge="true" relative-to="{PATH}" path="{DIRECTORY}" max-entries="10000" fetch-state="true" preload="false" /> </local-cache>
18.4.2. Single File Store Configuration (Library Mode)
<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>
18.4.3. Migrating data from FileCacheStore to SingleFileCacheStore
18.5. LevelDB Cache Store
18.5.1. Configuring LevelDB Cache Store (Remote Client-Server Mode)
Procedure 18.1. To configure LevelDB Cache Store:
- Add the following elements 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" /> <implementation type="JNI" /> </leveldb-store>
18.5.2. LevelDB Cache Store Programmatic Configuration
Configuration cacheConfig = new ConfigurationBuilder().persistence() .addStore(LevelDBStoreConfigurationBuilder.class) .location("/tmp/leveldb/data") .expiredLocation("/tmp/leveldb/expired").build();
Procedure 18.2. LevelDB Cache Store programmatic configuration
- Use the
ConfigurationBuilder
to create a new configuration object. - Add the store to the
LevelDBCacheStoreConfigurationBuilder
instance to build its configuration. - 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.
- Specify the location for expired data using the
expiredLocation
parameter for the LevelDB Store. The specified path stores expired data before it is purged. The directory is automatically created if it does not exist.
Note
18.5.3. LevelDB Cache Store Sample XML Configuration (Library Mode)
<namedCache name="vehicleCache"> <persistence passivation="false"> <leveldbStore location="/path/to/leveldb/data" expiredLocation="/path/to/expired/data" shared="false" preload="true"/> </persistence> </namedCache>
18.5.4. Configure a LevelDB Cache Store Using JBoss Operations Network
Procedure 18.3.
- Ensure that Red Hat JBoss Operations Network 3.2 or better is installed and started.
- Install the Red Hat JBoss Data Grid Plugin Pack for JBoss Operations Network 3.2.0.
- Ensure that JBoss Data Grid is installed and started.
- Import JBoss Data Grid server into the inventory.
- Configure the JBoss Data Grid connection settings.
- Create a new LevelDB cache store as follows:
Figure 18.1. Create a new LevelDB Cache Store
- Right-click the
default
cache. - In the menu, mouse over the Create Child option.
- In the submenu, click LevelDB Store.
- Name the new LevelDB cache store as follows:
Figure 18.2. Name the new LevelDB Cache Store
- In the Resource Create Wizard that appears, add a name for the new LevelDB Cache Store.
- Click Next to continue.
- Configure the LevelDB Cache Store settings as follows:
Figure 18.3. Configure the LevelDB Cache Store Settings
- Use the options in the configuration window to configure a new LevelDB cache store.
- Click Finish to complete the configuration.
- Schedule a restart operation as follows:
Figure 18.4. Schedule a Restart Operation
- In the screen's left panel, expand the JBossAS7 Standalone Servers entry, if it is not currently expanded.
- Click JDG (0.0.0.0:9990) from the expanded menu items.
- In the screen's right panel, details about the selected server display. Click the Operations tab.
- In the Operation drop-down box, select the Restart operation.
- Select the radio button for the Now entry.
- Click Schedule to restart the server immediately.
- Discover the new LevelDB cache store as follows:
Figure 18.5. Discover the New LevelDB Cache Store
- In the screen's left panel, select each of the following items in the specified order to expand them: JBossAS7 Standalong Servers → JDG (0.0.0.0:9990) → infinispan → Cache Containers → local → Caches → default → LevelDB Stores
- Click the name of your new LevelDB Cache Store to view its configuration information in the right panel.
18.6. JDBC Based Cache Stores
JdbcBinaryStore
.JdbcStringBasedStore
.JdbcMixedStore
.
18.6.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.
18.6.1.1. JdbcBinaryStore Configuration (Remote Client-Server Mode)
JdbcBinaryStore
using Red Hat JBoss Data Grid's Remote Client-Server mode with Passivation enabled:
<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>
18.6.1.2. JdbcBinaryStore Configuration (Library Mode)
JdbcBinaryStore
:
<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>
18.6.1.3. JdbcBinaryStore Programmatic Configuration
JdbcBinaryStore
:
ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence() .addStore(JdbcBinaryStoreConfigurationBuilder.class) .fetchPersistentState(false) .ignoreModifications(false) .purgeOnStartup(false) .table() .dropOnExit(true) .createOnStart(true) .tableNamePrefix("ISPN_BUCKET_TABLE") .idColumnName("ID_COLUMN").idColumnType("VARCHAR(255)") .dataColumnName("DATA_COLUMN").dataColumnType("BINARY") .timestampColumnName("TIMESTAMP_COLUMN").timestampColumnType("BIGINT") .connectionPool() .connectionUrl("jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1") .username("sa") .driverClass("org.h2.Driver");
Procedure 18.4. JdbcBinaryStore Programmatic Configuration (Library Mode)
Create a New Configuration Builder
Use theConfigurationBuilder
to create a new configuration object.Add the
JdbcBinaryStoreConfigurationBuilder
Add theJdbcBinaryStore
configuration builder to build a specific configuration related to this store.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.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.Configure Purging
purgeOnStartup
specifies whether the cache is purged when initially started.Configure the Table
Configure the table as follows:dropOnExit
determines if the table will be dropped when the cache store is stopped. This is set tofalse
by default.createOnStart
creates the table when starting the cache store if no table currently exists. This method istrue
by default.tableNamePrefix
sets the prefix for the name of the table in which the data will be stored.- The
idColumnName
property defines the column where the cache key or bucket ID is stored. - The
dataColumnName
property specifies the column where the cache entry or bucket is stored. - The
timestampColumnName
element specifies the column where the time stamp of the cache entry or bucket is stored.
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.
Note
18.6.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.
18.6.2.1. JdbcStringBasedStore Configuration (Remote Client-Server Mode)
JdbcStringBasedStore
for Red Hat JBoss Data Grid's Remote Client-Server mode:
<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>
18.6.2.2. JdbcStringBasedStore Configuration (Library Mode)
JdbcStringBasedStore
:
<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>
18.6.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.
<subsystem xmlns="urn:infinispan:server:core:6.1" 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>
18.6.2.4. JdbcStringBasedStore Programmatic Configuration
JdbcStringBasedStore
:
ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence().addStore(JdbcStringBasedStoreConfigurationBuilder.class) .fetchPersistentState(false) .ignoreModifications(false) .purgeOnStartup(false) .table() .dropOnExit(true) .createOnStart(true) .tableNamePrefix("ISPN_STRING_TABLE") .idColumnName("ID_COLUMN").idColumnType("VARCHAR(255)") .dataColumnName("DATA_COLUMN").dataColumnType("BINARY") .timestampColumnName("TIMESTAMP_COLUMN").timestampColumnType("BIGINT") .connectionPool() .connectionUrl("jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1") .username("sa") .driverClass("org.h2.Driver");
Procedure 18.5. Configure the JdbcStringBasedStore Programmatically
Create a New Configuration Builder
Use theConfigurationBuilder
to create a new configuration object.Add
JdbcStringBasedStoreConfigurationBuilder
Add theJdbcStringBasedStore
configuration builder to build a specific configuration related to this store.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.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.Configure Purging
purgeOnStartup
specifies whether the cache is purged when initially started.Configure the Table
dropOnExit
determines if the table will be dropped when the cache store is stopped. This is set tofalse
by default.createOnStart
creates the table when starting the cache store if no table currently exists. This method istrue
by default.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.
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.
Note
18.6.3. JdbcMixedStores
JdbcMixedStore
is a hybrid implementation that delegates keys based on their type to either the JdbcBinaryStore
or JdbcStringBasedStore
.
18.6.3.1. JdbcMixedStore Configuration (Remote Client-Server Mode)
JdbcMixedStore
for Red Hat JBoss Data Grid's Remote Client-Server mode:
<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>
18.6.3.2. JdbcMixedStore Configuration (Library Mode)
mixedKeyedJdbcStore
:
<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>
18.6.3.3. JdbcMixedStore Programmatic Configuration
JdbcMixedStore
:
ConfigurationBuilder builder = new ConfigurationBuilder(); builder.persistence().addStore(JdbcMixedStoreConfigurationBuilder.class) .fetchPersistentState(false) .ignoreModifications(false) .purgeOnStartup(false) .stringTable() .dropOnExit(true) .createOnStart(true) .tableNamePrefix("ISPN_MIXED_STR_TABLE") .idColumnName("ID_COLUMN").idColumnType("VARCHAR(255)") .dataColumnName("DATA_COLUMN").dataColumnType("BINARY") .timestampColumnName("TIMESTAMP_COLUMN").timestampColumnType("BIGINT") .binaryTable() .dropOnExit(true) .createOnStart(true) .tableNamePrefix("ISPN_MIXED_BINARY_TABLE") .idColumnName("ID_COLUMN").idColumnType("VARCHAR(255)") .dataColumnName("DATA_COLUMN").dataColumnType("BINARY") .timestampColumnName("TIMESTAMP_COLUMN").timestampColumnType("BIGINT") .connectionPool() .connectionUrl("jdbc:h2:mem:infinispan_binary_based;DB_CLOSE_DELAY=-1") .username("sa") .driverClass("org.h2.Driver");
Procedure 18.6. Configure JdbcMixedStore Programmatically
Create a New Configuration Builder
Use theConfigurationBuilder
to create a new configuration object.Add
JdbcMixedStoreConfigurationBuilder
Add theJdbcMixedStore
configuration builder to build a specific configuration related to this store.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.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.Configure Purging
purgeOnStartup
specifies whether the cache is purged when initially started.Configure the Table
Configure the table as follows:dropOnExit
determines if the table will be dropped when the cache store is stopped. This is set tofalse
by default.createOnStart
creates the table when starting the cache store if no table currently exists. This method istrue
by default.tableNamePrefix
sets the prefix for the name of the table in which the data will be stored.- The
idColumnName
property defines the column where the cache key or bucket ID is stored. - The
dataColumnName
property specifies the column where the cache entry or bucket is stored. - The
timestampColumnName
element specifies the column where the time stamp of the cache entry or bucket is stored.
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.
Note
18.6.4. Cache Store Troubleshooting
18.6.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.
18.7. The Remote Cache Store
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.
18.7.1. Remote Cache Store Configuration (Remote Client-Server Mode)
<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>
18.7.2. Remote Cache Store Configuration (Library Mode)
<persistence passivation="false"> <remoteStore xmlns="urn:infinispan:config:remote:6.0" remoteCacheName="default" 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>
18.7.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:
Example 18.1. Define the Outbound Socket
<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>
18.8. JPA Cache Store
Important
18.8.1. JPA Cache Store Sample XML Configuration (Library Mode)
persistence.xml
file:
<persistence passivation="false" shared="true" preload="true"> <jpaStore persistenceUnitName="MyPersistenceUnit" entityClassName="org.infinispan.loaders.jpa.entity.User" /> </persistence>
18.8.2. JPA Cache Store Sample Programmatic Configuration
Configuration cacheConfig = new ConfigurationBuilder().persistence().addStore(JpaStoreConfigurationBuilder.class).persistenceUnitName("org.infinispan.loaders.jpa.configurationTest") .entityClass(User.class) .build();
- The
persistenceUnitName
parameter specifies the name of the JPA cache store in the configuration file (persistence.xml
) that contains the JPA entity class. - The
entityClass
parameter specifies the JPA entity class that is stored in this cache. Only one class can be specified for each configuration.
18.8.3. Storing Metadata in the Database
storeMetadata
is set to true
(default value), meta information about the entries such as expiration, creation and modification timestamps, and versioning is stored in the database. JBoss Data Grid stores the metadata in an additional table named __ispn_metadata__
because the entity table has a fixed layout that cannot accommodate the metadata.
Procedure 18.7. Configure persistence.xml for Metadata Entities
- Using Hibernate as the JPA implementation allows automatic creation of these tables using the property
hibernate.hbm2ddl.auto
inpersistence.xml
as follows:<property name="hibernate.hbm2ddl.auto" value="update"/>
- Declare the metadata entity class to the JPA provider by adding the following to
persistence.xml
:<class>org.infinispan.persistence.jpa.impl.MetadataEntity</class>
storeMetadata
attribute to false
in the JPA Store configuration.
18.8.4. Deploying JPA Cache Stores in Various Containers
Procedure 18.8. Deploy JPA Cache Stores in JBoss EAP
- To add dependencies from the JBoss Data Grid modules to the application's classpath, provide the JBoss EAP deployer a list of dependencies in one of the following ways:
- Add a dependency configuration to the
MANIFEST.MF
file:Manifest-Version: 1.0 Dependencies: org.infinispan:jdg-6.3 services, org.infinispan.persistence.jpa:jdg-6.3 services
- Add a dependency configuration to the
jboss-deployment-structure.xml
file:<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2"> <deployment> <dependencies> <module name="org.infinispan" slot="jdg-6.3" services="export"/> </dependencies> </deployment> </jboss-deployment-structure>
Important
18.9. Custom Cache Stores
CacheLoader
CacheWriter
AdvancedCacheLoader
AdvancedCacheWriter
Note
AdvancedCacheWriter
is not implemented, the expired entries cannot be purged or cleared using the given writer.
Note
AdvancedCacheLoader
is not implemented, the entries stored in the given loader will not be used for preloading and map/reduce iterations.
SingleFileStore
as an example. To view the SingleFileStore
example code, download the JBoss Data Grid source code.
SingleFileStore
example code from the Customer Portal:
Procedure 18.9. Download JBoss Data Grid Source Code
- To access the Red Hat Customer Portal, navigate to https://access.redhat.com/home in a browser.
- Click Downloads.
- In the box labeled Red Hat JBoss Middleware, click the Download Software button.
- Enter the relevant credentials in the Red Hat Login and Password fields and click Log In.
- In the Software Downloads page, select Data Grid from the list of drop down values.
- From the list of downloadable files, locate Red Hat JBoss Data Grid ${VERSION} Source Code and click Download. Save and unpack it in a desired location.
- Locate the
SingleFileStore
source code by navigating throughjboss-datagrid-6.3.0-sourcesinfinispan-6.1.0.Final-redhat-4-src/core/src/main/java/org/infinispan/persistence/file/SingleFileStore.java
.
18.9.1. Custom Cache Store Configuration (Remote Client-Server Mode)
Example 18.2. Custom Cache Store Configuration
<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.
18.9.2. Custom Cache Store Configuration (Library Mode)
Example 18.3. Custom Cache Store Configuration
<persistence> <store class="org.infinispan.custom.CustomCacheStore" preload="true" shared="true"> <properties> <property name="customStoreProperty" value="10" /> </properties> </store> </persistence>
Part VIII. Set Up Passivation
Chapter 19. Activation and Passivation Modes
19.1. Passivation Mode Benefits
19.2. Configure Passivation
passivation
parameter to the cache store element to toggle passivation for it:
Example 19.1. Toggle Passivation in Remote Client-Server Mode
<local-cache> ... <file-store passivation="true" ... /> ... </local-cache>
passivation
parameter to the persistence
element to toggle passivation:
Example 19.2. Toggle Passivation in Library Mode
<persistence passivation="true" ... > ... </persistence>
19.3. Eviction and Passivation
19.3.1. Eviction and Passivation Usage
- A notification regarding the passivated entry is emitted to the cache listeners.
- The evicted entry is stored.
19.3.2. Eviction Example when Passivation is Disabled
Table 19.1. Eviction 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 |
19.3.3. Eviction Example when Passivation is Enabled
Table 19.2. Eviction 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 IX. Set Up Cache Writing
Chapter 20. Cache Writing Modes
- Write-Through (Synchronous)
- Write-Behind (Asynchronous)
20.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.
20.1.1. Write-Through Caching Benefits
20.1.2. Write-Through Caching Configuration (Library Mode)
Procedure 20.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:6.1"> <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:6.1"> <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:6.1"> <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:6.1"> <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:6.1"> <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:6.1"> <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:6.1"> <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>
20.2. Write-Behind Caching
20.2.1. About Unscheduled Write-Behind Strategy
20.2.2. Unscheduled Write-Behind Strategy Configuration (Remote Client-Server Mode)
write-behind
element to the target cache store configuration as follows:
Procedure 20.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>
20.2.3. Unscheduled Write-Behind Strategy Configuration (Library Mode)
async
element to the store configuration as follows:
Procedure 20.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 X. Monitor Caches and Cache Managers
Chapter 21. Set Up Java Management Extensions (JMX)
21.1. About Java Management Extensions (JMX)
MBeans
.
21.2. Using JMX with Red Hat JBoss Data Grid
21.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
21.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);
21.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);
21.6. Disabling the CacheStore via JMX
disconnectSource
operation on the RollingUpgradeManager
MBean.
See Also:
21.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");
21.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
21.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
21.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 22. Set Up JBoss Operations Network (JON)
22.1. About JBoss Operations Network (JON)
Important
Important
Update 02
or higher version. For information on upgrading the JBoss Operations Network, see the Upgrading JBoss ON section in the JBoss Operations Network Installation Guide.
22.2. Download JBoss Operations Network (JON)
22.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.
22.2.2. Download JBoss Operations Network
Procedure 22.1. Download JBoss Operations Network
- To access the Red Hat Customer Portal, navigate to https://access.redhat.com/home in a browser.
- Click Downloads.
- In the box labeled Red Hat JBoss Middleware, click the Download Software button.
- Enter the relevant credentials in the Red Hat Login and Password fields and click Log In.
- In the Software Downloads page, select JBoss Operations Network from the list of drop down values.
- Select the appropriate version in the Version drop down menu list.
- Click the Download button next to the desired download file.
22.2.3. Remote JMX Port Values
22.2.4. Download JBoss Operations Network (JON) Plugin
Procedure 22.2. Download Installation Files
- Open http://access.redhat.com in a web browser.
- Click Downloads in the menu across the top of the page.
- Click Downloads in 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 the Download link to start the Base Distribution download.
- Repeat the steps to download the
JDG Plugin Pack for JBoss ON VERSION
22.3. JBoss Operations Network Server Installation
Note
22.4. JBoss Operations Network Agent
init.d
script in a UNIX environment.
Note
22.5. JBoss Operations Network for Remote Client-Server Mode
- initiate and perform installation and configuration operations.
- monitor resources and their metrics.
22.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 JBoss Enterprise Application Platform 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 JBoss Enterprise Application Platform plug-in and the JBoss Data Grid server rhq plug-in are installed correctly using the following:plugins info
22.6. JBoss Operations Network Remote-Client Server Plugin
22.6.1. JBoss Operations Network Plugin Metrics
Table 22.1. JBoss Operations Network Traits for the Cache Container (Cache Manager)
Trait 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. |
members | Cluster Members | The names of the members of the cluster. |
coordinator-address | Coordinator Address | The coordinator node's address. |
local-address | Local Address | The local node's address. |
version | Version | The cache manager version. |
defined-cache-names | Defined Cache Names | The caches that have been defined for this manager. |
Table 22.2. JBoss Operations Network Metrics for the Cache Container (Cache Manager)
Metric Name | Display Name | Description |
---|---|---|
cluster-size | Cluster Size | How many members are in the cluster. |
defined-cache-count | Defined Cache Count | How many caches that have been defined for this manager. |
running-cache-count | Running Cache Count | How many caches are running under this manager. |
created-cache-count | Created Cache Count | How many caches have actually been created under this manager. |
Table 22.3. JBoss Operations Network Traits for the Cache
Trait Name | Display Name | Description |
---|---|---|
cache-status | Cache Status | The current runtime status of a cache. |
cache-name | Cache Name | The current name of the cache. |
version | Version | The cache version. |
Table 22.4. JBoss Operations Network Metrics for the Cache
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.
Table 22.5. JBoss Operations Network Metrics for the Connectors
Metric Name | Display Name | Description |
---|---|---|
bytesRead | Bytes Read | Number of bytes read. |
bytesWritten | Bytes Written | Number of bytes written. |
Note
22.6.2. JBoss Operations Network Plugin Operations
Table 22.6. JBoss ON Plugin Operations for the Cache
Operation Name | Description |
---|---|
Start Cache | Starts the cache. |
Stop Cache | Stops the cache. |
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. |
Record Known Global Keyset | Records the global known keyset to a well-known key for retrieval by the upgrade process. |
Synchronize Data | Synchronizes data from the old cluster to this using the specified migrator. |
Disconnect Source | Disconnects the target cluster from the source cluster according to the specified migrator. |
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 Chapter 29, Set Up Cross-Datacenter Replication
Table 22.7. JBoss Operations Network Plugin Operations for the Cache Backups
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.
22.6.3. JBoss Operations Network Plugin Attributes
Table 22.8. JBoss ON Plugin Attributes for the Cache (Transport)
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. |
22.7. JBoss Operations Network for Library Mode
- initiate and perform installation and configuration operations.
- monitor resources and their metrics.
22.7.1. Installing the JBoss Operations Network Plug-in (Library Mode)
Procedure 22.3. Install JBoss Operations Network Library Mode Plug-in
Open the JBoss Operations Network Console
- From the JBoss Operations Network console, select Administration.
- Select Agent Plugins from the Configuration options on the left side of the console.
Figure 22.1. JBoss Operations Network Console for JBoss Data Grid
Upload the Library Mode Plug-in
- Click Browse, locate the
InfinispanPlugin
on your local file system. - Click Upload to add the plug-in to the JBoss Operations Network Server.
Figure 22.2. Upload the
InfinispanPlugin
.Scan for Updates
- Once the file has successfully uploaded, click Scan For Updates at the bottom of the screen.
- The
InfinispanPlugin
will now appear in the list of installed plug-ins.
Figure 22.3. Scan for Updated Plug-ins.
22.7.2. Monitoring Of JBoss Data Grid Instances in Library Mode
22.7.2.1. Prerequisites
- A correctly configured instance of JBoss Operations Network (JON) 3.2.0 with patch
Update 02
or higher version. - A running instance of JON Agent on the server where the application will run. For more information, see Section 22.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 JON agent's environment file (bin/rhq-env.sh
), set the value of theRHQ_AGENT_JAVA_HOME
property to point to a full JDK home. - The RHQ agent must have been initiated using the same user as the JBoss Enterprise Application Platform instance. As an example, running the 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 JON plugin for JBoss Data Grid Library Mode. For more information, see Section 22.7.1, “Installing the JBoss Operations Network Plug-in (Library Mode)”
Generic JMX plugin
from JBoss Operation Networks 3.2.0 with patchUpdate 02
or better version in use.- A custom application using Red Hat JBoss Data Grid's Library mode with enabled JMX statistics for library mode caches in order to make statistics and monitoring working. For details how to enable JMX statistics for cache instances, see Section 21.4, “Enable JMX for Cache Instances” and to enable JMX for cache managers see Section 21.5, “Enable JMX for CacheManagers”
- 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.
22.7.2.2. Manually Adding JBoss Data Grid Instances in Library Mode
22.7.2.2.1. Manually Adding JBoss Data Grid Instances in Library Mode
Procedure 22.4. Add JBoss Data Grid Instances in Library Mode
Import the Platform
- Navigate to the Inventory and select Discovery Queue from the Resources list on the left of the console.
- Select the platform on which the application is running and click Import at the bottom of the screen.
Figure 22.4. Import the Platform from the Discovery Queue.
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 22.5. Open the
jdg
Platform to view the list of servers.Import the JMX Server
- From the Inventory tab, select Child Resources.
- Click the Import button at the bottom of the screen and select the JMX Server option from the list.
Figure 22.6. Import the JMX Server
Enable JDK Connection Settings
- In the Resource Import Wizard window, specify JDK 5 from the list of Connection Settings Template options.
Figure 22.7. Select the JDK 5 Template.
Modify the Connector Address
- In the Deployment Options menu, modify the supplied Connector Address with the hostname and JMX port of the process containing the Infinispan Library.
- Enter the JMX connector address of the new JBoss Data Grid instance you want to monitor. For example:Connector Address:
service:jmx:rmi://127.0.0.1/jndi/rmi://127.0.0.1:7997/jmxrmi
Note
The connector address varies depending on the host and the JMX port assigned to the new instance. In this case, instances require the following system properties at start up:-Dcom.sun.management.jmxremote.port=7997 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false
- Specify the Principal and Credentials information if required.
- Click Finish.
Figure 22.8. Modify the values in the Deployment Options screen.
View Cache Statistics and Operations
- Click Refresh to refresh the list of servers.
- The JMX Servers tree in the panel on the left side of the screen contains the Infinispan Cache Managers node, which contains the available cache managers. The available cache managers contain the available caches.
- Select a cache from the available caches to view metrics.
- Select the Monitoring tab.
- The Tables view shows statistics and metrics.
- The Operations tab provides access to the various operations that can be performed on the services.
Figure 22.9. Metrics and operational data relayed through JMX is now available in the JBoss Operations Network console.
22.7.2.3. Monitor Custom Applications Using Library Mode Deployed On JBoss Enterprise Application Platform
22.7.2.3.1. Monitor an Application Deployed in Standalone Mode
Procedure 22.5. 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 or change standalone configuration file (
/bin/standalone.conf
) respectively: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
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 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 process is listed as a JMX server.Import the Process Into Inventory
Import the process into the JBoss Operations Network (JON) inventory.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).
22.7.2.3.2. Monitor an Application Deployed in Domain Mode
Procedure 22.6. 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).
22.8. JBoss Operations Network Plug-in Quickstart
Part XI. Command Line Tools
- The JBoss Data Grid Library CLI. For more information, see Section 23.1, “Red Hat JBoss Data Grid Library Mode CLI”.
- The JBoss Data Grid Server CLI. For more information, see Section 23.2, “Red Hat Data Grid Server CLI”.
Chapter 23. Red Hat JBoss Data Grid CLIs
23.1. Red Hat JBoss Data Grid Library Mode CLI
infinispan-cli-server-$VERSION.jar
) includes an interpreter for commands and must be included in the application.
23.1.1. Start the Library Mode 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.
23.1.2. Start the Library Mode CLI (Client)
cli
files in the bin
directory. For Linux, run bin/cli.sh
and for Windows, run bin\cli.bat
.
23.1.3. CLI Client Switches for the Command Line
Table 23.1. CLI Client Command Line Switches
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. |
23.1.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]>
23.1.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-{VERSION}-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
23.2. Red Hat Data Grid Server CLI
- configuration
- management
- obtaining metrics
23.2.1. Start the Server Mode CLI
$ JDG_HOME/bin/cli.sh
C:\>JDG_HOME\bin\cli.bat
23.3. CLI Commands
deny
(see Section 23.3.8, “The deny Command”), grant
(see Section 23.3.14, “The grant Command”), and roles
(see Section 23.3.19, “The roles command”) commands are only available on the Server Mode CLI.
23.3.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
23.3.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
23.3.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]>
23.3.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
23.3.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
23.3.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/]>
23.3.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]>
23.3.8. The deny Command
deny
command can be used to deny roles previously assigned to a principal:
[remoting://localhost:9999]> deny supervisor to user1
Note
deny
command is only available to the JBoss Data Grid Server Mode CLI.
23.3.9. 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//]
23.3.10. 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
23.3.11. 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
23.3.12. 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
23.3.13. 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
23.3.14. The grant Command
ClusterRoleMapper
, the principal to role mappings are stored within the cluster registry (a replicated cache available to all nodes). The grant
command can be used to grant new roles to a principal as follows:
[remoting://localhost:9999]> grant supervisor to user1
Note
grant
command is only available to the JBoss Data Grid Server Mode CLI.
23.3.15. 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'}}
23.3.16. 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]
23.3.17. 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
23.3.18. 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
23.3.19. The roles command
ClusterRoleMapper
, the principal to role mappings are stored within the cluster registry (a replicated cache available to all nodes). The roles
command can be used to list the roles associated to a specific user, or to all users if one is not given:
[remoting://localhost:9999]> roles user1 [supervisor, reader]
Note
roles
command is only available to the JBoss Data Grid Server Mode CLI.
23.3.20. 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
23.3.21. 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
23.3.22. 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
23.3.23. 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 }
23.3.24. 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
23.3.25. 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
Part XII. Other Red Hat JBoss Data Grid Functions
Chapter 24. Set Up the L1 Cache
24.1. About the L1 Cache
24.2. L1 Cache Configuration
24.2.1. L1 Cache Configuration (Library Mode)
Example 24.1. L1 Cache Configuration in Library Mode
<clustering mode="distribution"> <sync/> <l1 enabled="true" lifespan="60000" /> </clustering>
l1
element configures the cache behavior in distributed cache instances. If used with non-distributed caches, this element is ignored.
- The
enabled
parameter enables the L1 cache. - The
lifespan
parameter sets the maximum life span of an entry when it is placed in the L1 cache.
24.2.2. L1 Cache Configuration (Remote Client-Server Mode)
Example 24.2. L1 Cache Configuration for Remote Client-Server Mode
<distributed-cache l1-lifespan="${VALUE}"> ... </distributed-cache>
l1-lifespan
element is added to a distributed-cache
element to enable L1 caching and to set the life span of the L1 cache entries for the cache. This element is only valid for distributed caches.
l1-lifespan
is set to 0
or a negative number (-1
), L1 caching is disabled. L1 caching is enabled when the l1-lifespan
value is greater than 0
.
Note
Note
l1-lifespan
attribute is not set. The default lifespan value was 10 minutes. Since JBoss Data Grid 6.3, the default lifespan is 0 which disables the L1 cache. Set a non-zero value for the l1-lifespan
parameter to enable the L1 cache.
Chapter 25. Set Up Transactions
25.1. About Transactions
25.1.1. About the Transaction Manager
- initiating and concluding transactions
- managing information about each transaction
- coordinating transactions as they operate over multiple resources
- recovering from a failed transaction by rolling back changes
25.1.2. XA Resources and Synchronizations
OK
or ABORT
. If the Transaction Manager receives OK
votes from all XA Resources, the transaction is committed, otherwise it is rolled back.
25.1.3. Optimistic and Pessimistic Transactions
- less messages being sent during the transaction execution
- locks held for shorter periods
- improved throughput
Note
FORCE_WRITE_LOCK
flag with the operation.
25.1.4. Write Skew Checks
REPEATABLE_READ
isolation level. Also, in clustered mode (distributed or replicated modes), set up entry versioning. For local mode, entry versioning is not required.
Important
25.1.5. Transactions Spanning Multiple Cache Instances
25.2. Configure Transactions
25.2.1. Configure Transactions (Library Mode)
Procedure 25.1. Configure Transactions in Library Mode (XML Configuration)
Set the Transaction Mode
See the table below this procedure for a list of available lookup classes.<namedCache ...> <transaction transactionMode="{TRANSACTIONAL,NON_TRANSACTIONAL}"> ... </namedCache>
Configure the Transaction Manager
ThetransactionMode
element configures whether or not the cache is transactional.<namedCache ...> <transaction transactionMode="TRANSACTIONAL" transactionManagerLookupClass="{TransactionManagerLookupClass}"> </namedCache>
Configure Locking Mode
ThelockingMode
parameter determines if the optimistic or pessimistic locking method is used. If the cache is non-transactional, the locking mode is ignored. The default value for this parameter isOPTIMISTIC
.<namedCache ...> <transaction transactionMode="TRANSACTIONAL" transactionManagerLookupClass="{TransactionManagerLookupClass}" lockingMode="{OPTIMISTIC,PESSIMISTIC}"> </namedCache>
Specify Synchronization
TheuseSynchronization
element configures the cache to register a synchronization with the transaction manager, or register itself as an XA resource. The default value for this element istrue
(use synchronization).<namedCache ...> <transaction transactionMode="TRANSACTIONAL" transactionManagerLookupClass="{TransactionManagerLookupClass}" lockingMode="{OPTIMISTIC,PESSIMISTIC}" useSynchronization="{true,false}"> </namedCache>
Configure Recovery
Therecovery
element enables recovery for the cache when set totrue
.TherecoveryInfoCacheName
parameter sets the name of the cache where recovery information is held. The default name of the cache is__recoveryInfoCacheName__
.<namedCache ...> <transaction transactionMode="TRANSACTIONAL" transactionManagerLookupClass="{TransactionManagerLookupClass}" lockingMode="{OPTIMISTIC,PESSIMISTIC}" useSynchronization="{true,false}"> <recovery enabled="true" recoveryInfoCacheName="{CacheName}" /> </namedCache>
Configure the Write Skew Check
ThewriteSkew
check determines if a modification to the entry from a different transaction should roll back the transaction. Write skew set totrue
requiresisolation_level
set toREPEATABLE_READ
. The default value forwriteSkew
andisolation_level
arefalse
andREAD_COMMITTED
respectively.<namedCache ...> <transaction ...> <locking isolation_level="{READ_COMMITTED,REPEATABLE_READ}" writeSkew="{true,false}" /> ... </namedCache>
Configure Entry Versioning
For clustered caches, enable write skew check by enabling entry versioning and setting its value toSIMPLE
.<namedCache ...> <transaction ...> <locking ...> <versioning enabled="{true,false}" versioningScheme="{NONE|SIMPLE}"/> ... </namedCache>
Procedure 25.2. Configure Transactions in Library Mode (Programmatic Configuration)
Set the Transaction Mode
Set the transaction mode as follows:Configuration config = new ConfigurationBuilder()/* ... */.transaction() .transactionMode(TransactionMode.TRANSACTIONAL);
Configure the Transaction Manager
See the table below this procedure for a list of available lookup classes.Configuration config = new ConfigurationBuilder()/* ... */.transaction() .transactionMode(TransactionMode.TRANSACTIONAL) .transactionManagerLookup(new GenericTransactionManagerLookup());
Configure Locking Mode
ThelockingMode
value determines whether optimistic or pessimistic locking is used. If the cache is non-transactional, the locking mode is ignored. The default value isOPTIMISTIC
.Configuration config = new ConfigurationBuilder()/* ... */.transaction() .transactionMode(TransactionMode.TRANSACTIONAL) .transactionManagerLookup(new GenericTransactionManagerLookup()); .lockingMode(LockingMode.OPTIMISTIC);
Specify Synchronization
TheuseSynchronization
value configures the cache to register a synchronization with the transaction manager, or register itself as an XA resource. The default value istrue
(use synchronization).Configuration config = new ConfigurationBuilder()/* ... */.transaction() .transactionMode(TransactionMode.TRANSACTIONAL) .transactionManagerLookup(new GenericTransactionManagerLookup()); .lockingMode(LockingMode.OPTIMISTIC) .useSynchronization(true);
Configure Recovery
Therecovery
parameter enables recovery for the cache when set totrue
.TherecoveryInfoCacheName
sets the name of the cache where recovery information is held. The default name of the cache is specified byRecoveryConfiguration.DEFAULT_RECOVERY_INFO_CACHE
.Configuration config = new ConfigurationBuilder()/* ... */.transaction() .transactionMode(TransactionMode.TRANSACTIONAL) .transactionManagerLookup(new GenericTransactionManagerLookup()); .lockingMode(LockingMode.OPTIMISTIC) .useSynchronization(true) .recovery() .recoveryInfoCacheName("anotherRecoveryCacheName");
Configure Write Skew Check
ThewriteSkew
check determines if a modification to the entry from a different transaction should roll back the transaction. Write skew set totrue
requiresisolation_level
set toREPEATABLE_READ
. The default value forwriteSkew
andisolation_level
arefalse
andREAD_COMMITTED
respectively.Configuration config = new ConfigurationBuilder()/* ... */.locking() .isolationLevel(IsolationLevel.REPEATABLE_READ).writeSkewCheck(true);
Configure Entry Versioning
For clustered caches, enable write skew check by enabling entry versioning and setting its value toSIMPLE
.Configuration config = new ConfigurationBuilder()/* ... */.versioning() .enable() .scheme(VersioningScheme.SIMPLE);
Table 25.1. Transaction Manager Lookup Classes
Class Name | Details |
---|---|
org.infinispan.transaction.lookup.DummyTransactionManagerLookup | Used primarily for testing environments. This testing transaction manager is not for use in a production environment and is severely limited in terms of functionality, specifically for concurrent transactions and recovery. |
org.infinispan.transaction.lookup.JBossStandaloneJTAManagerLookup | The default transaction manager when Red Hat JBoss Data Grid runs in a standalone environment. It is a fully functional JBoss Transactions based transaction manager that overcomes the functionality limits of the DummyTransactionManager . |
org.infinispan.transaction.lookup.GenericTransactionManagerLookup | GenericTransactionManagerLookup is used by default when no transaction lookup class is specified. This lookup class is recommended when using JBoss Data Grid with Java EE-compatible environment that provides a TransactionManager interface, and is capable of locating the Transaction Manager in most Java EE application servers. If no transaction manager is located, it defaults to DummyTransactionManager . |
org.infinispan.transaction.lookup.JBossTransactionManagerLookup | The JbossTransactionManagerLookup finds the standard transaction manager running in the application server. This lookup class uses JNDI to look up the TransactionManager instance, and is recommended when custom caches are being used in JTA transactions. |
25.2.2. Configure Transactions (Remote Client-Server Mode)
Example 25.1. Transaction Configuration in Remote Client-Server Mode
<cache> ... <transaction mode="NONE" /> ... </cache>
Important
NONE
unless JBoss Data Grid is used in a compatibility mode where the cluster contains both JBoss Data Grid server and library instances. In this case, if transactions are configured in the library mode instance, they must also be configured in the server instance.
25.3. Transaction Recovery
25.3.1. Transaction Recovery Process
Procedure 25.3. The Transaction Recovery Process
- The Transaction Manager creates a list of transactions that require intervention.
- The system administrator, connected to JBoss Data Grid using JMX, is presented with the list of transactions (including transaction IDs) using email or logs. The status of each transaction is either
COMMITTED
orPREPARED
. If some transactions are in bothCOMMITTED
andPREPARED
states, it indicates that the transaction was committed on some nodes while in the preparation state on others. - The System Administrator visually maps the XID received from the Transaction Manager to a JBoss Data Grid internal ID. This step is necessary because the XID (a byte array) cannot be conveniently passed to the JMX tool and then reassembled by JBoss Data Grid without this mapping.
- The system administrator forces the commit or rollback process for a transaction based on the mapped internal ID.
25.3.2. Transaction Recovery Example
Example 25.2. Money Transfer from an Account Stored in a Database to an Account in JBoss Data Grid
- The
TransactionManager.commit()
method is invoked to run the two phase commit protocol between the source (the database) and the destination (JBoss Data Grid) resources. - The
TransactionManager
tells the database and JBoss Data Grid to initiate the prepare phase (the first phase of a Two Phase Commit).
Note
25.4. Deadlock Detection
disabled
by default.
25.4.1. Enable Deadlock Detection
disabled
by default but can be enabled and configured for each cache using the namedCache
configuration element by adding the following:
<deadlockDetection enabled="true" spinDuration="100"/>
spinDuration
attribute defines how often lock acquisition is attempted within the maximum time allowed to acquire a particular lock (in milliseconds).
Chapter 26. Configure JGroups
26.1. Configure Red Hat JBoss Data Grid Interface Binding (Remote Client-Server Mode)
26.1.1. Interfaces
link-local
: Uses a169.x.x.x
or254.x.x.x
address. This suits the traffic within one box.<interfaces> <interface name="link-local"> <link-local-address/> </interface> ... </interfaces>
site-local
: Uses a private IP address, for example192.168.x.x
. This prevents extra bandwidth charged from GoGrid, and similar providers.<interfaces> <interface name="site-local"> <site-local-address/> </interface> ... </interfaces>
global
: Picks a public IP address. This should be avoided for replication traffic.<interfaces> <interface name="global"> <any-address/> </interface> ... </interfaces>
non-loopback
: Uses the first address found on an active interface that is not a127.x.x.x
address.<interfaces> <interface name="non-loopback"> <not> <loopback /> </not> </interface> </interfaces>
26.1.2. Binding Sockets
26.1.2.1. Binding a Single Socket Example
socket-binding
element.
Example 26.1. Socket Binding
<socket-binding name="jgroups-udp" ... interface="site-local"/>
26.1.2.2. Binding a Group of Sockets Example
socket-binding-group
element:
Example 26.2. Bind a Group
<socket-binding-group name="ha-sockets" default-interface="global"> ... <socket-binding name="jgroups-tcp" port="7600"/> <socket-binding name="jgroups-tcp-fd" port="57600"/> ... </socket-binding-group>
default-interface
(global
), therefore the interface attribute does not need to be specified.
26.1.3. Configure JGroups Socket Binding
Example 26.3. JGroups Socket Binding Configuration
<subsystem xmlns="urn:jboss:domain:jgroups:1.2" default-stack="udp"> <stack name="udp"> <transport type="UDP" socket-binding="jgroups-udp"> ... </transport> <!-- rest of protocols --> </stack> </subsystem>
Important
26.2. Configure JGroups (Library Mode)
Example 26.4. JGroups Programmatic Configuration
GlobalConfiguration gc = new GlobalConfigurationBuilder() .transport() .defaultTransport() .addProperty("configurationFile","jgroups.xml") .build();
Example 26.5. JGroups XML Configuration
<infinispan> <global> <transport> <properties> <property name="configurationFile" value="jgroups.xml" /> </properties> </transport> </global> ... </infinispan>
jgroups.xml
in the classpath before searching for an absolute path name if it is not found in the classpath.
26.2.1. JGroups Transport Protocols
26.2.1.1. The UDP Transport Protocol
- IP multicasting to send messages to all members of a cluster.
- UDP datagrams for unicast messages, which are sent to a single member.
26.2.1.2. The TCP Transport Protocol
- When sending multicast messages, TCP sends multiple unicast messages.
- When using TCP, each message to all cluster members is sent as multiple unicast messages, or one to each member.
26.2.1.3. Using the TCPPing Protocol
jgroups-tcp.xml
includes the MPING
protocol, which uses UDP
multicast for discovery. When UDP
multicast is not available, the MPING
protocol, has to be replaced by a different mechanism. The recommended alternative is the TCPPING
protocol. The TCPPING
configuration contains a static list of IP addresses which are contacted for node discovery.
Example 26.6. Configure the JGroups Subsystem to Use TCPPING
<TCP bind_port="7800" /> <TCPPING timeout="3000" initial_hosts="${jgroups.tcpping.initial_hosts:HostA[7800],HostB[7801]}" port_range="1" num_initial_members="3"/>
26.2.2. Pre-Configured JGroups Files
infinispan-core.jar
, and are available on the classpath by default. In order to use one of these files, specify one of these file names instead of using jgroups.xml
.
jgroups-udp.xml
jgroups-tcp.xml
jgroups-ec2.xml
26.2.2.1. jgroups-udp.xml
jgroups-udp.xml
is a pre-configured JGroups file in Red Hat JBoss Data Grid. The jgroups-udp.xml
configuration
- uses UDP as a transport and UDP multicast for discovery.
- is suitable for large clusters (over 8 nodes).
- is suitable if using Invalidation or Replication modes.
Table 26.1. jgroups-udp.xml System Properties
System Property | Description | Default | Required? |
---|---|---|---|
jgroups.udp.mcast_addr | IP address to use for multicast (both for communications and discovery). Must be a valid Class D IP address, suitable for IP multicast. | 228.6.7.8 | No |
jgroups.udp.mcast_port | Port to use for multicast socket | 46655 | No |
jgroups.udp.ip_ttl | Specifies the time-to-live (TTL) for IP multicast packets. The value here refers to the number of network hops a packet is allowed to make before it is dropped | 2 | No |
26.2.2.2. jgroups-tcp.xml
jgroups-tcp.xml
is a pre-configured JGroups file in Red Hat JBoss Data Grid. The jgroups-tcp.xml
configuration
- uses TCP as a transport and UDP multicast for discovery.
- is generally only used where multicast UDP is not an option.
- TCP does not perform as well as UDP for clusters of eight or more nodes. Clusters of four nodes or fewer result in roughly the same level of performance for both UDP and TCP.
Table 26.2. jgroups-udp.xml System Properties
System Property | Description | Default | Required? |
---|---|---|---|
jgroups.tcp.address | IP address to use for the TCP transport. | 127.0.0.1 | No |
jgroups.tcp.port | Port to use for TCP socket | 7800 | No |
jgroups.udp.mcast_addr | IP address to use for multicast (for discovery). Must be a valid Class D IP address, suitable for IP multicast. | 228.6.7.8 | No |
jgroups.udp.mcast_port | Port to use for multicast socket | 46655 | No |
jgroups.udp.ip_ttl | Specifies the time-to-live (TTL) for IP multicast packets. The value here refers to the number of network hops a packet is allowed to make before it is dropped | 2 | No |
26.2.2.3. jgroups-ec2.xml
jgroups-ec2.xml
is a pre-configured JGroups file in Red Hat JBoss Data Grid. The jgroups-ec2.xml
configuration
- uses TCP as a transport and S3_PING for discovery.
- is suitable on Amazon EC2 nodes where UDP multicast isn't available.
Table 26.3. jgroups-ec2.xml System Properties
System Property | Description | Default | Required? |
---|---|---|---|
jgroups.tcp.address | IP address to use for the TCP transport. | 127.0.0.1 | No |
jgroups.tcp.port | Port to use for TCP socket | 7800 | No |
jgroups.s3.access_key | The Amazon S3 access key used to access an S3 bucket | Yes | |
jgroups.s3.secret_access_key | The Amazon S3 secret key used to access an S3 bucket | Yes | |
jgroups.s3.bucket | Name of the Amazon S3 bucket to use. Must be unique and must already exist | Yes | |
jgroups.s3.pre_signed_delete_url | The pre-signed URL to be used for the DELETE operation. | Yes | |
jgroups.s3.pre_signed_put_url | The pre-signed URL to be used for the PUT operation. | Yes | |
jgroups.s3.prefix | If set, S3_PING searches for a bucket with a name that starts with the prefix value. | No |
26.3. Test Multicast Using JGroups
26.3.1. Testing With Different Red Hat JBoss Data Grid Versions
Table 26.4. Testing with Different JBoss Data Grid Versions
Version | Test Case | Details |
---|---|---|
JBoss Data Grid 6.0.0 | Not Available | This version of JBoss Data Grid is based on JBoss Enterprise Application Server 6.0, which does not include the test classes used for this test. |
JBoss Data Grid 6.0.1 | Not Available | This version of JBoss Data Grid is based on JBoss Enterprise Application Platform 6.0, which does not include the test classes used for this test. |
JBoss Data Grid 6.1.0 | Available | This version of JBoss Data Grid is based on JBoss Enterprise Application Platform 6.0.1, but contains a newer version of the JGroups JAR file than the JAR file included in JBoss Enterprise Application Platform. As a result, the test class required for this test is available in the $JBOSS_HOME/modules/org/jgroups/main directory for JBoss Data Grid 6.1. |
JBoss Data Grid 6.2.0 | Available | This version of JBoss Data Grid is based on JBoss Enterprise Application Platform 6.1. The JAR file is named according to the version, for example jgroups-3.2.7.Final-redhat-1.jar and is available in the $JBOSS_HOME/modules/system/layers/base/org/jgroups/main directory. |
JBoss Data Grid 6.2.1 | Available | This version of JBoss Data Grid is based on JBoss Enterprise Application Platform 6.1.1 The JAR file is named according to the version (jgroups-3.4.3.Final-redhat-1.jar and is available in the $JBOSS_HOME/modules/system/layers/base/org/jgroups/main directory. |
JBoss Data Grid 6.3.0 | Available | This version of JBoss Data Grid is based on JBoss Enterprise Application Platform 6.2.4. The JAR file is named according to the version (jgroups-3.4.4.Final-redhat-5.jar and is available in the $JBOSS_HOME/modules/system/layers/base/org/jgroups/main directory. |
26.3.2. Testing Multicast Using JGroups
Ensure that the following prerequisites are met before starting the testing procedure.
- Set the
bind_addr
value to the appropriate IP address for the instance. - For added accuracy, set
mcast_addr
andport
values that are the same as the cluster communication values. - Start two command line terminal windows. Navigate to the location of the JGroups JAR file for one of the two nodes in the first terminal and the same location for the second node in the second terminal.
Procedure 26.1. Test Multicast Using JGroups
Run the Multicast Server on Node One
Run the following command on the command line terminal for the first node:java -cp jgroups.jar org.jgroups.tests.McastReceiverTest -mcast_addr 230.1.2.3 -port 5555 -bind_addr $YOUR_BIND_ADDRESS
Run the Multicast Server on Node Two
Run the following command on the command line terminal for the second node:java -cp jgroups.jar org.jgroups.tests.McastSenderTest -mcast_addr 230.1.2.3 -port 5555 -bind_addr $YOUR_BIND_ADDRESS
Transmit Information Packets
Enter information on instance for node two (the node sending packets) and press enter to send the information.View Receives Information Packets
View the information received on the node one instance. The information entered in the previous step should appear here.Confirm Information Transfer
Repeat steps 3 and 4 to confirm all transmitted information is received without dropped packets.Repeat Test for Other Instances
Repeat steps 1 to 4 for each combination of sender and receiver. Repeating the test identifies other instances that are incorrectly configured.
All information packets transmitted from the sender node must appear on the receiver node. If the sent information does not appear as expected, multicast is incorrectly configured in the operating system or the network.
Chapter 27. Use Red Hat Data Grid with Amazon Web Services
27.1. The S3_PING JGroups Discovery Protocol
S3_PING
is a discovery protocol that is ideal for use with Amazon's Elastic Compute Cloud (EC2) because EC2 does not allow multicast and therefore MPING
is not allowed.
27.2. S3_PING Configuration Options
- In Library mode, use JGroups'
jgroups-ec2.xml
file (see Section 26.2.2.3, “jgroups-ec2.xml” for details) or use theS3_PING
protocol. - In Remote Client-Server mode, use JGroups'
S3_PING
protocol.
S3_PING
protocol for clustering to work in Amazon AWS:
- Use Private S3 Buckets. These buckets use Amazon AWS credentials.
- Use Pre-Signed URLs. These pre-assigned URLs are assigned to buckets with private write and public read rights.
- Use Public S3 Buckets. These buckets do not have any credentials.
27.2.1. Using Private S3 Buckets
- List
- Upload/Delete
- View Permissions
- Edit Permissions
S3_PING
configuration includes the following properties:
- either the
location
or theprefix
property to specify the bucket, but not both. If theprefix
property is set,S3_PING
searches for a bucket with a name that starts with the prefix value. If a bucket with the prefix at the beginning of the name is found,S3_PING
uses that bucket. If a bucket with the prefix is not found,S3_PING
creates a bucket using the AWS credentials and names it based on the prefix and a UUID (the naming format is {prefix value}-{UUID}). - the
access_key
andsecret_access_key
properties for the AWS user.
Note
403
error displays when using this configuration, verify that the properties have the correct values. If the problem persists, confirm that the system time in the EC2 node is correct. Amazon S3 rejects requests with a time stamp that is more than 15
minutes old compared to their server's times for security purposes.
Example 27.1. Start the Red Hat JBoss Data Grid Server with a Private Bucket
bin/clustered.sh -Djboss.bind.address={server_ip_address} -Djboss.bind.address.management={server_ip_address} -Djboss.default.jgroups.stack=s3 -Djgroups.s3.bucket={s3_bucket_name} -Djgroups.s3.access_key={access_key} -Djgroups.s3.secret_access_key={secret_access_key}
- Replace {server_ip_address} with the server's IP address.
- Replace {s3_bucket_name} with the appropriate bucket name.
- Replace {access_key} with the user's access key.
- Replace {secret_access_key} with the user's secret access key.
27.2.2. Using Pre-Signed URLs
S3_PING
protocol. This URL points to a unique file and can include a folder path within the bucket.
Note
S3_PING
. For example, a path such as my_bucket/DemoCluster/node1
works while a longer path such as my_bucket/Demo/Cluster/node1
will not.
27.2.2.1. Generating Pre-Signed URLs
S3_PING
class includes a utility method to generate pre-signed URLs. The last argument for this method is the time when the URL expires expressed in the number of seconds since the Unix epoch (January 1, 1970).
String Url = S3_PING.generatePreSignedUrl("{access_key}", "{secret_access_key}", "{operation}", "{bucket_name}", "{path}", {seconds});
- Replace {operation} with either
PUT
orDELETE
. - Replace {access_key} with the user's access key.
- Replace {secret_access_key} with the user's secret access key.
- Replace {bucket_name} with the name of the bucket.
- Replace {path} with the desired path to the file within the bucket.
- Replace {seconds} with the number of seconds since the Unix epoch (January 1, 1970) that the path remains valid.
Example 27.2. Generate a Pre-Signed URL
String putUrl = S3_PING.generatePreSignedUrl("access_key", "secret_access_key", "put", "my_bucket", "DemoCluster/node1", 1234567890);
S3_PING
configuration includes the pre_signed_put_url
and pre_signed_delete_url
properties generated by the call to S3_PING.generatePreSignedUrl()
. This configuration is more secure than one using private S3 buckets, because the AWS credentials are not stored on each node in the cluster
Note
&
characters in the URL must be replaced with its XML entity (&
).
27.2.2.2. Set Pre-Signed URLs Using the Command Line
- Enclose the URL in double quotation marks (
"
"
). - In the URL, each occurrence of the ampersand (
&
) character must be escaped with a backslash (\
)
Example 27.3. Start a JBoss Data Grid Server with a Pre-Signed URL
bin/clustered.sh -Djboss.bind.address={server_ip_address} -Djboss.bind.address.management={server_ip_address} -Djboss.default.jgroups.stack=s3 -Djgroups.s3.pre_signed_put_url="http://{s3_bucket_name}.s3.amazonaws.com/ node1?AWSAccessKeyId={access_key}\&Expires={expiration_time}\&Signature={signature}"-Djgroups.s3.pre_signed_delete_url="http://{s3_bucket_name}.s3.amazonaws.com/ node1?AWSAccessKeyId={access_key}\&Expires={expiration_time}\&Signature={signature}"
{signatures}
values are generated by the S3_PING.generatePreSignedUrl()
method. Additionally, the {expiration_time} values are the expiration time for the URL that are passed into the S3_PING.generatePreSignedUrl()
method.
27.2.3. Using Public S3 Buckets
location
property must be specified with the bucket name for this configuration. This configuration method is the least secure because any user who knows the name of the bucket can upload and store data in the bucket and the bucket creator's account is charged for this data.
bin/clustered.sh -Djboss.bind.address={server_ip_address} -Djboss.bind.address.management={server_ip_address} -Djboss.default.jgroups.stack=s3 -Djgroups.s3.bucket={s3_bucket_name}
27.2.4. Troubleshooting S3_PING Warnings
S3_PING
configuration type used, the following warnings may appear when starting the JBoss Data Grid Server:
15:46:03,468 WARN [org.jgroups.conf.ProtocolConfiguration] (MSC service thread 1-7) variable "${jgroups.s3.pre_signed_put_url}" in S3_PING could not be substituted; pre_signed_put_url is removed from properties
15:46:03,469 WARN [org.jgroups.conf.ProtocolConfiguration] (MSC service thread 1-7) variable "${jgroups.s3.prefix}" in S3_PING could not be substituted; prefix is removed from properties
15:46:03,469 WARN [org.jgroups.conf.ProtocolConfiguration] (MSC service thread 1-7) variable "${jgroups.s3.pre_signed_delete_url}" in S3_PING could not be substituted; pre_signed_delete_url is removed from properties
S3_PING
configuration.
Chapter 28. High Availability Using Server Hinting
machineId
, rackId
, or siteId
in the transport configuration will trigger the use of TopologyAwareConsistentHashFactory
, which is the equivalent of the DefaultConsistentHashFactory
with Server Hinting enabled.
28.1. Establishing Server Hinting with JGroups
28.2. Configure Server Hinting (Remote Client-Server Mode)
transport
element for the default stack, as follows:
Procedure 28.1. Configure Server Hinting in Remote Client-Server Mode
Find the JGroups Subsystem Configuration
<subsystem xmlns="urn:jboss:domain:jgroups:1.1" default-stack="${jboss.default.jgroups.stack:udp}"> <stack name="udp">
Enable Server Hinting via the
transport
ElementSet the Site ID
<subsystem xmlns="urn:jboss:domain:jgroups:1.1" default-stack="${jboss.default.jgroups.stack:udp}"> <stack name="udp"> <transport type="UDP" socket-binding="jgroups-udp" site="${jboss.jgroups.transport.site:s1}">
Set the Rack ID
<subsystem xmlns="urn:jboss:domain:jgroups:1.1" default-stack="${jboss.default.jgroups.stack:udp}"> <stack name="udp"> <transport type="UDP" socket-binding="jgroups-udp" site="${jboss.jgroups.transport.site:s1}" rack="${jboss.jgroups.transport.rack:r1}">
Set the Machine ID
<subsystem xmlns="urn:jboss:domain:jgroups:1.1" default-stack="${jboss.default.jgroups.stack:udp}"> <stack name="udp"> <transport type="UDP" socket-binding="jgroups-udp" site="${jboss.jgroups.transport.site:s1}" rack="${jboss.jgroups.transport.rack:r1}" machine="${jboss.jgroups.transport.machine:m1}"> ... </transport> </stack> </subsystem>
28.3. Configure Server Hinting (Library Mode)
Procedure 28.2. Configure Server Hinting for Library Mode
Set the
clusterName
AttributeTheclusterName
attribute specifies the name assigned to the cluster.<transport clusterName = "MyCluster" />
Add the
machineId
ThemachineId
attribute specifies the JVM instance that contains the original data. This is particularly useful for nodes with multiple JVMs and physical hosts with multiple virtual hosts.<transport clusterName = "MyCluster" machineId = "LinuxServer01" />
Add the
rackId
TherackId
parameter specifies the rack that contains the original data, so that other racks are used for backups.<transport clusterName = "MyCluster" machineId = "LinuxServer01" rackId = "Rack01" />
Add the
siteId
ThesiteId
parameter differentiates between nodes in different data centers replicating to each other.<transport clusterName = "MyCluster" machineId = "LinuxServer01" rackId = "Rack01" siteId = "US-WestCoast" />
machineId
, rackId
, or siteId
are included in the configuration, TopologyAwareConsistentHashFactory
is selected automatically, enabling Server Hinting. However, if Server Hinting is not configured, JBoss Data Grid's distribution algorithms are allowed to store replications in the same physical machine/rack/data center as the original data.
28.4. ConsistentHashFactories
DefaultConsistentHashFactory
- keeps segments balanced evenly across all the nodes, however the key mapping is not guaranteed to be same across caches,as this depends on the history of each cache.SyncConsistentHashFactory
- guarantees that the key mapping is the same for each cache, provided the current membership is the same. This has a drawback in that a node joining the cache can cause the existing nodes to also exchange segments, resulting in either additional state transfer traffic, the distribution of the data becoming less even, or both.TopologyAwareConsistentHashFactory
- equivalent ofDefaultConsistentHashFactory
, but with server hinting enabled.TopologyAwareSyncConsistentHashFactory
- equivalent ofSyncConsistentHashFactory
, but with server hinting enabled.
<hash consistentHashFactory="org.infinispan.distribution.ch.TopologyAwareSyncConsistentHashFactory"/>
machineId
, rackId
, or siteId
attributes are specified in the transport configuration it also spreads backup copies across physical machines/racks/data centers.
28.4.1. Implementing a ConsistentHashFactory
ConsistentHashFactory
must implement the org.infinispan.distribution.ch.ConsistenHashFactory
interface with the following methods (all of which return an implementation of org.infinispan.distribution.ch.ConsistentHash
):
Example 28.1. ConsistentHashFactory Methods
create(Hash hashFunction, int numOwners, int numSegments, List<Address> members,Map<Address, Float> capacityFactors) updateMembers(ConsistentHash baseCH, List<Address> newMembers, Map<Address, Float> capacityFactors) rebalance(ConsistentHash baseCH) union(ConsistentHash ch1, ConsistentHash ch2)
ConsistentHashFactory
implementations.
28.5. Key Affinity Service
Example 28.2. Key Affinity Service
EmbeddedCacheManager cacheManager = getCacheManager(); Cache cache = cacheManager.getCache(); KeyAffinityService keyAffinityService = KeyAffinityServiceFactory.newLocalKeyAffinityService( cache, new RndKeyGenerator(), Executors.newSingleThreadExecutor(), 100); Object localKey = keyAffinityService.getKeyForAddress(cacheManager.getAddress()); cache.put(localKey, "yourValue");
Procedure 28.3. Using the Key Affinity Service
Obtain a reference to a cache manager and cache
EmbeddedCacheManager cacheManager = getCacheManager(); Cache cache = cacheManager.getCache();
Create the affinity service
This starts the service, then uses the suppliedExecutor
to generate and queue keys.KeyAffinityService keyAffinityService = KeyAffinityServiceFactory.newLocalKeyAffinityService( cache, new RndKeyGenerator(), Executors.newSingleThreadExecutor(), 100);
Obtain a key to be mapped to a certain address
Obtain a key from the service which will be mapped to the local node (cacheManager.getAddress()
returns the local address).Object localKey = keyAffinityService.getKeyForAddress(cacheManager.getAddress());
Put the value on the node
The entry with a key obtained from theKeyAffinityService
is always stored on the node with the provided address. In this case, it is the local node.cache.put(localKey, "yourValue");
28.5.1. Lifecycle
KeyAffinityService
extends Lifecycle
, which allows the key affinity service to be stopped, started, and restarted.
Example 28.3. Key Affinity Service Lifecycle Parameter
public interface Lifecycle { void start(); void stop(); }
KeyAffinityServiceFactory
. All factory methods have an Executor
, that is used for asynchronous key generation, so that this does not occur in the caller's thread. The user controls the shutting down of this Executor
.
KeyAffinityService
must be explicitly stopped when it is no longer required. This stops the background key generation, and releases other held resources. The KeyAffinityServce
will only stop itself when the cache manager with which it is registered is shut down.
28.5.2. Topology Changes
KeyAffinityService
key ownership may change when a topology change occurs. The key affinity service monitors topology changes and updates so that it doesn't return stale keys, or keys that would map to a different node than the one specified. However, this does not guarantee that a node affinity hasn't changed when a key is used. For example:
- Thread (
T1
) reads a key (K1
) that maps to a node (A
). - A topology change occurs, resulting in
K1
mapping to nodeB
. T1
usesK1
to add something to the cache. At this point,K1
maps toB
, a different node to the one requested at the time of read.
KeyAffinityService
provides an access proximity optimization for stable clusters, which does not apply during the instability of topology changes.
Chapter 29. Set Up Cross-Datacenter Replication
RELAY2
protocol.
29.1. Cross-Datacenter Replication Operations
Example 29.1. Cross-Datacenter Replication Example
Figure 29.1. Cross-Datacenter Replication Example
LON
, NYC
and SFO
. Each site hosts a running JBoss Data Grid cluster made up of three to four physical nodes.
Users
cache is active in all three sites. Changes to the Users
cache at the LON
site is replicated at the other two sites. The Orders
cache, however, is only available locally at the LON
site because it is not replicated to the other sites.
Users
cache can use different replication mechanisms each site. For example, it can back up data synchronously to SFO
and asynchronously to NYC
and LON
.
Users
cache can also have a different configuration from one site to another. For example, it can be configured as a distributed cache with numOwners
set to 2
in the LON
site, as a replicated cache in the NYC
site and as a distributed cache with numOwners
set to 1
in the SFO
site.
RELAY2
facilitates communication between sites. For more information, see Section C.4, “About RELAY2”
29.2. Configure Cross-Datacenter Replication
29.2.1. Configure Cross-Datacenter Replication (Remote Client-Server Mode)
Procedure 29.1. Set Up Cross-Datacenter Replication
Set Up RELAY
Add the following configuration to thestandalone.xml
file to set upRELAY
:<subsystem xmlns="urn:jboss:domain:jgroups:1.2" default-stack="udp"> <stack name="udp"> <transport type="UDP" socket-binding="jgroups-udp"/> ... <relay site="LON"> <remote-site name="NYC" stack="tcp" cluster="global"/> <remote-site name="SFO" stack="tcp" cluster="global"/> <property name="relay_multicasts">false</property> </relay> </stack> </subsystem>
TheRELAY
protocol creates an additional stack (running parallel to the existingTCP
stack) to communicate with the remote site. If aTCP
based stack is used for the local cluster, twoTCP
based stack configurations are required: one for local communication and one to connect to the remote site. For an illustration, see Section 29.1, “Cross-Datacenter Replication Operations”Set Up Sites
Use the following configuration in thestandalone.xml
file to set up sites for each distributed cache in the cluster:<distributed-cache> ... <backups> <backup site="{FIRSTSITENAME}" strategy="{SYNC/ASYNC}" /> <backup site="{SECONDSITENAME}" strategy="{SYNC/ASYNC}" /> </backups> </distributed-cache>
Configure Local Site Transport
Add the name of the local site in thetransport
element to configure transport:<transport executor="infinispan-transport" lock-timeout="60000" cluster="LON" stack="udp"/>
29.2.2. Configure Cross-Data Replication (Library Mode)
29.2.2.1. Configure Cross-Datacenter Replication Declaratively
relay.RELAY2
protocol creates an additional stack (running parallel to the existing TCP
stack) to communicate with the remote site. If a TCP
-based stack is used for the local cluster, two TCP
based stack configurations are required: one for local communication and one to connect to the remote site.
Procedure 29.2. Setting Up Cross-Datacenter Replication
Configure the Local Site
Add thesite
element to theglobal
element to add the local site (in this example, the local site is namedLON
).<infinispan> <global> ... <site local="LON" /> ... </global> </infinispan>
Configure JGroups for the Local Site
Cross-site replication requires a non-default JGroups configuration. Add thetransport
element and set up the path to the configuration file as theconfigurationFile
property. In this example, the JGroups configuration file is namedjgroups-with-relay.xml
.<infinispan> <global> ... <site local="LON" /> <transport clusterName="default"> <properties> <property name="configurationFile" value="jgroups-with-relay.xml" /> </properties> </transport> ... </global> </infinispan>
Configure the LON Cache
Configure the cache in siteLON
to back up to the sitesNYC
andSFO
:<infinispan> <global> <site local="LON" /> <transport clusterName="default"> <properties> <property name="configurationFile" value="jgroups-with-relay.xml" /> </properties> </transport> ... </global> ... <namedCache name="lon"> <sites> <backups> <backup site="NYC" strategy="SYNC" backupFailurePolicy="WARN" /> <backup site="SFO" strategy="ASYNC" backupFailurePolicy="IGNORE"/> </backups> </sites> </namedCache> </infinispan>
Configure the Back Up Caches
- Configure the cache in site
NYC
to receive back up data fromLON
:<infinispan> <global> <site local="NYC" /> <transport clusterName="default"> <properties> <property name="configurationFile" value="jgroups-with-relay.xml"/> </properties> </transport> ... </global> ... <namedCache name="lonBackup"> <sites> <backupFor remoteSite="LON" remoteCache="lon" /> </sites> </namedCache> </infinispan>
- Configure the cache in site
SFO
to receive back up data fromLON
:<infinispan> <global> <site local="SFO" /> <transport clusterName="default"> <properties> <property name="configurationFile" value="jgroups-with-relay.xml"/> </properties> </transport> ... </global> ... <namedCache name="lonBackup"> <sites> <backupFor remoteSite="LON" remoteCache="lon" /> </sites> </namedCache> </infinispan>
Add the Contents of the Configuration File
As a default, Red Hat JBoss Data Grid includes JGroups configuration files such asjgroups-tcp.xml
andjgroups-udp.xml
in theinfinispan-core-{VERSION}.jar
package.Copy the JGroups configuration to a new file (in this example, it is namedjgroups-with-relay.xml
) and add the provided configuration information to this file. Note that therelay.RELAY2
protocol configuration must be the last protocol in the configuration stack.<config> ... <relay.RELAY2 site="LON" config="relay.xml" relay_multicasts="false" /> </config>
Configure the relay.xml File
Set up therelay.RELAY2
configuration in therelay.xml
file. This file describes the global cluster configuration.<RelayConfiguration> <sites> <site name="LON" id="0"> <bridges> <bridge config="jgroups-global.xml" name="global"/> </bridges> </site> <site name="NYC" id="1"> <bridges> <bridge config="jgroups-global.xml" name="global"/> </bridges> </site> <site name="SFO" id="2"> <bridges> <bridge config="jgroups-global.xml" name="global"/> </bridges> </site> </sites> </RelayConfiguration>
Configure the Global Cluster
The filejgroups-global.xml
referenced inrelay.xml
contains another JGroups configuration which is used for the global cluster: communication between sites.The global cluster configuration is usuallyTCP
-based and uses theTCPPING
protocol (instead ofPING
orMPING
) to discover members. Copy the contents ofjgroups-tcp.xml
intojgroups-global.xml
and add the following configuration in order to configureTCPPING
:<config> <TCP bind_port="7800" ... /> <TCPPING initial_hosts="lon.hostname[7800],nyc.hostname[7800],sfo.hostname[7800]" num_initial_members="3" ergonomics="false" /> <!-- Rest of the protocols --> </config>
Replace the hostnames (or IP addresses) inTCPPING.initial_hosts
with those used for your site masters. The ports (7800
in this example) must match theTCP.bind_port
.For more information about theTCPPING
protocol, see Section 26.2.1.3, “Using the TCPPing Protocol”
29.2.2.2. Configure Cross-Datacenter Replication Programmatically
Procedure 29.3. Configure Cross-Datacenter Replication Programmatically
Identify the Node Location
Declare the site the node resides in:globalConfiguration.site().localSite("LON");
Configure JGroups
Configure JGroups to use theRELAY
protocol:globalConfiguration.transport().addProperty("configurationFile", jgroups-with-relay.xml);
Set Up the Remote Site
Set up JBoss Data Grid caches to replicate to the remote site:ConfigurationBuilder lon = new ConfigurationBuilder(); lon.sites().addBackup() .site("NYC") .backupFailurePolicy(BackupFailurePolicy.WARN) .strategy(BackupConfiguration.BackupStrategy.SYNC) .replicationTimeout(12000) .sites().addInUseBackupSite("NYC") .sites().addBackup() .site("SFO") .backupFailurePolicy(BackupFailurePolicy.IGNORE) .strategy(BackupConfiguration.BackupStrategy.ASYNC) .sites().addInUseBackupSite("SFO")
Optional: Configure the Backup Caches
JBoss Data Grid implicitly replicates data to a cache with same name as the remote site. If a backup cache on the remote site has a different name, users must specify abackupFor
cache to ensure data is replicated to the correct cache.Note
This step is optional and only required if the remote site's caches are named differently from the original caches.- Configure the cache in site
NYC
to receive backup data fromLON
:ConfigurationBuilder NYCbackupOfLon = new ConfigurationBuilder(); lonBackup.sites().backupFor().remoteCache("lon").remoteSite("LON");
- Configure the cache in site
SFO
to receive backup data fromLON
:ConfigurationBuilder SFObackupOfLon = new ConfigurationBuilder(); lonBackup.sites().backupFor().remoteCache("lon").remoteSite("LON");
Add the Contents of the Configuration File
As a default, Red Hat JBoss Data Grid includes JGroups configuration files such asjgroups-tcp.xml
andjgroups-udp.xml
in theinfinispan-core-{VERSION}.jar
package.Copy the JGroups configuration to a new file (in this example, it is namedjgroups-with-relay.xml
) and add the provided configuration information to this file. Note that therelay.RELAY2
protocol configuration must be the last protocol in the configuration stack.<config> ... <relay.RELAY2 site="LON" config="relay.xml" relay_multicasts="false" /> </config>
Configure the relay.xml File
Set up therelay.RELAY2
configuration in therelay.xml
file. This file describes the global cluster configuration.<RelayConfiguration> <sites> <site name="LON" id="0"> <bridges> <bridge config="jgroups-global.xml" name="global"/> </bridges> </site> <site name="NYC" id="1"> <bridges> <bridge config="jgroups-global.xml" name="global"/> </bridges> </site> <site name="SFO" id="2"> <bridges> <bridge config="jgroups-global.xml" name="global"/> </bridges> </site> </sites> </RelayConfiguration>
Configure the Global Cluster
The filejgroups-global.xml
referenced inrelay.xml
contains another JGroups configuration which is used for the global cluster: communication between sites.The global cluster configuration is usuallyTCP
-based and uses theTCPPING
protocol (instead ofPING
orMPING
) to discover members. Copy the contents ofjgroups-tcp.xml
intojgroups-global.xml
and add the following configuration in order to configureTCPPING
:<config> <TCP bind_port="7800" ... /> <TCPPING initial_hosts="lon.hostname[7800],nyc.hostname[7800],sfo.hostname[7800]" num_initial_members="3" ergonomics="false" /> <!-- Rest of the protocols --> </config>
Replace the hostnames (or IP addresses) inTCPPING.initial_hosts
with those used for your site masters. The ports (7800
in this example) must match theTCP.bind_port
.For more information about theTCPPING
protocol, see Section 26.2.1.3, “Using the TCPPing Protocol”
29.3. Taking a Site Offline
- Configure automatically taking a site offline:
- Declaratively in Remote Client-Server mode.
- Declaratively in Library mode.
- Using the programmatic method.
- Manually taking a site offline:
- Using JBoss Operations Network (JON).
- Using the JBoss Data Grid Command Line Interface (CLI).
29.3.1. Taking a Site Offline (Remote Client-Server Mode)
take-offline
element is added to the backup
element to configure when a site is automatically taken offline.
Example 29.2. Taking a Site Offline in Remote Client-Server Mode
<backup> <take-offline after-failures="${NUMBER}" min-wait="${PERIOD}" /> </backup>
take-offline
element use the following parameters to configure when to take a site offline:
- The
after-failures
parameter specifies the number of times attempts to contact a site can fail before the site is taken offline. - The
min-wait
parameter specifies the number (in milliseconds) to wait to mark an unresponsive site as offline. The site is offline when themin-wait
period elapses after the first attempt, and the number of failed attempts specified in theafter-failures
parameter occur.
29.3.2. Taking a Site Offline (Library Mode)
backupFor
element after defining all back up sites within the backups
element:
Example 29.3. Taking a Site Offline in Library Mode
<backup> <takeOffline afterFailures="${NUM}" minTimeToWait="${PERIOD}"/> </backup>
takeOffline
element to the backup
element to configure automatically taking a site offline.
- The
afterFailures
parameter specifies the number of times attempts to contact a site can fail before the site is taken offline. The default value (0
) allows an infinite number of failures ifminTimeToWait
is less than0
. If theminTimeToWait
is not less than0
,afterFailures
behaves as if the value is negative. A negative value for this parameter indicates that the site is taken offline after the time specified byminTimeToWait
elapses. - The
minTimeToWait
parameter specifies the number (in milliseconds) to wait to mark an unresponsive site as offline. The site is taken offline after the number attempts specified in theafterFailures
parameter conclude and the time specified byminTimeToWait
after the first failure has elapsed. If this parameter is set to a value smaller than or equal to0
, this parameter is disregarded and the site is taken offline based solely on theafterFailures
parameter.
29.3.3. Taking a Site Offline (Programmatically)
Example 29.4. Taking a Site Offline Programmatically
lon.sites().addBackup() .site("NYC") .backupFailurePolicy(BackupFailurePolicy.FAIL) .strategy(BackupConfiguration.BackupStrategy.SYNC) .takeOffline() .afterFailures(500) .minTimeToWait(10000);
29.3.4. Taking a Site Offline via JBoss Operations Network (JON)
29.3.5. Taking a Site Offline via the CLI
site
command.
site
command can be used to check the status of a site as follows:
[jmx://localhost:12000/MyCacheManager/namedCache]> site --status ${SITENAME}
online
or offline
according to the current status of the named site.
[jmx://localhost:12000/MyCacheManager/namedCache]> site --offline ${SITENAME}
[jmx://localhost:12000/MyCacheManager/namedCache]> site --online ${SITENAME}
ok
displays after the command.
29.3.6. Bring a Site Back Online
bringSiteOnline(siteName)
operation on the XSiteAdmin
MBean. For details about this MBean, see Section A.21, “XSiteAdmin”
29.4. Configure Multiple Site Masters
29.4.1. Multiple Site Master Operations
29.4.2. Configure Multiple Site Masters (Remote Client-Server Mode)
Configure Cross-Datacenter Replication for Red Hat JBoss Data Grid's Remote Client-Server Mode.
Procedure 29.4. Set Multiple Site Masters in Remote Client-Server Mode
Locate the Target Configuration
Locate the target site's configuration in theclustered-xsite.xml
example configuration file. The sample configuration looks like the following example:<relay site="LON"> <remote-site name="NYC" stack="tcp" cluster="global"/> <remote-site name="SFO" stack="tcp" cluster="global"/> <property name="relay_multicasts">false</property> </relay>
Configure Maximum Sites
Use themax_site_masters
property to determine the maximum number of master nodes within the site. Set this value to the number of nodes in the site to make every node a master.<relay site="LON"> <remote-site name="NYC" stack="tcp" cluster="global"/> <remote-site name="SFO" stack="tcp" cluster="global"/> <property name="relay_multicasts">false</property> <property name="max_site_masters">16</property> </relay>
Configure Site Master
Use thecan_become_site_master
property to allow the node to become the site master. This flag is set totrue
as a default. Setting this flag tofalse
prevents the node from becoming a site master. This is required in situations where the node does not have a network interface connected to the external network.<relay site="LON"> <remote-site name="NYC" stack="tcp" cluster="global"/> <remote-site name="SFO" stack="tcp" cluster="global"/> <property name="relay_multicasts">false</property> <property name="max_site_masters">16</property> <property name="can_become_site_master">true</property> </relay>
29.4.3. Configure Multiple Site Masters (Library Mode)
Procedure 29.5. Configure Multiple Site Masters (Library Mode)
Configure Cross-Datacenter Replication
Configure Cross-Datacenter Replication in JBoss Data Grid. Use the instructions in Section 29.2.2.1, “Configure Cross-Datacenter Replication Declaratively” for an XML configuration or the instructions in Section 29.2.2.2, “Configure Cross-Datacenter Replication Programmatically” for a programmatic configuration.Add the Contents of the Configuration File
Add thecan_become_site_master
andmax_site_masters
parameters to the configuration as follows:<config> ... <relay.RELAY2 site="LON" config="relay.xml" relay_multicasts="false" can_become_site_master="true" max_site_masters="16"/> </config>
Set themax_site_masters
value to the number of nodes in the cluster to make all nodes masters.
Chapter 30. Rolling Upgrades
30.1. Rolling Upgrades Using REST
Procedure 30.1. Perform Rolling Upgrades Using REST
Configure the Target Cluster
Use either different network settings or a different JGroups cluster name to set the Target Cluster (consisting of nodes with new JBoss Data Grid) apart from the Source Cluster. For each cache, configure aRestCacheStore
with the following settings:- Ensure that the host and port values point to the Source Cluster.
- Ensure that the path value points to the Source Cluster's REST endpoint.
Start the Target Cluster
Start the Target Cluster's nodes. Configure each client to point to the Target Cluster instead of the Source Cluster. Eventually, the Target Cluster handles all requests instead of the Source Cluster. The Target Cluster then lazily loads data from the Source Cluster on demand using theRestCacheStore
.Dump the Key Set
When all connections have shifted to the Target Cluster, remove the Source Cluster key set. This is done either using JMX or the CLI as follows:Using JMX
Invoke therecordKnownGlobalKeyset
operation on theRollingUpgradeManager
MBean on the Source Cluster for all caches to be migrated.Using the CLI
Run theupgrade --dumpkeys
command on the Source Cluster for all caches to be migrated. Optionally, use the--all
switch to dump all the caches in the cluster.
Fetch the Remaining Data
The Target Cluster must fetch all the remaining data from the Source Cluster. This is done either using JMX or the CLI as follows:Using JMX
Invoke thesynchronizeData
operation with therest
parameter specified on theRollingUpgradeManager
MBean on the Target Cluster for all caches to be migrated.Using the CLI
Run theupgrade --synchronize=rest
on the Target Cluster for all caches to be migrated. Optionally, use the--all
switch to synchronize all caches in the cluster.
Disable the RestCacheStore
Disable theRestCacheStore
on the Target Cluster using either JMX or the CLI as follows:Using JMX
Invoke thedisconnectSource
operation with therest
parameter specified on theRollingUpgradeManager
MBean on the Target Cluster.Using the CLI
Run theupgrade --disconnectsource=rest
command on the Target Cluster. Optionally, use the--all
switch to disconnect all caches in the cluster.
Migration to the Target Cluster is complete. The Source Cluster can now be decommissioned.
30.2. Rolling Upgrades Using Hot Rod
Important
- For JBoss Data Grid 6.1, use Hot Rod protocol version 1.2
- For JBoss Data Grid 6.2, use Hot Rod protocol version 1.3
- For JBoss Data Grid 6.3, use Hot Rod protocol version 2.0
This procedure assumes that a cluster is already configured and running, and that it is using an older version of JBoss Data Grid. This cluster is referred to below as the Source Cluster and the Target Cluster refers to the new cluster to which data will be migrated.
Configure the Target Cluster
Use either different network settings or a different JGroups cluster name to set the Target Cluster (consisting of nodes with new JBoss Data Grid) apart from the Source Cluster. For each cache, configure aRemoteCacheStore
with the following settings:- Ensure that
remote-server
points to the Source Cluster. - Ensure that the cache name matches the name of the cache on the Source Cluster.
- Ensure that
hotrod-wrapping
is enabled (set totrue
). - Ensure that
purge
is disabled (set tofalse
). - Ensure that
passivation
is disabled (set tofalse
).
Figure 30.1. Configure the Target Cluster with a RemoteCacheStore
Note
See the$JDG_HOME/docs/examples/configs/
standalone-hotrod-rolling-upgrade.xml
file for a full example of the Target Cluster configuration for performing Rolling Upgrades.Start the Target Cluster
Start the Target Cluster's nodes. Configure each client to point to the Target Cluster instead of the Source Cluster. Eventually, the Target Cluster handles all requests instead of the Source Cluster. The Target Cluster then lazily loads data from the Source Cluster on demand using theRemoteCacheStore
.Figure 30.2. Clients point to the Target Cluster with the Source Cluster as
RemoteCacheStore
for the Target Cluster.Dump the Source Cluster keyset
When all connections are using the Target Cluster, the keyset on the Source Cluster must be dumped. This can be done using either JMX or the CLI:JMX
Invoke therecordKnownGlobalKeyset
operation on theRollingUpgradeManager
MBean on the Source Cluster for every cache that must be migrated.CLI
Invoke theupgrade --dumpkeys
command on the Source Cluster for every cache that must be migrated, or use the--all
switch to dump all caches in the cluster.
Fetch remaining data from the Source Cluster
The Target Cluster fetches all remaining data from the Source Cluster. Again, this can be done using either JMX or CLI:JMX
Invoke thesynchronizeData
operation and specify thehotrod
parameter on theRollingUpgradeManager
MBean on the Target Cluster for every cache that must be migrated.CLI
Invoke theupgrade --synchronize=hotrod
command on the Target Cluster for every cache that must be migrated, or use the--all
switch to synchronize all caches in the cluster.
Disabling the
RemoteCacheStore
Once the Target Cluster has obtained all data from the Source Cluster, theRemoteCacheStore
on the Target Cluster must be disabled. This can be done as follows:JMX
Invoke thedisconnectSource
operation specifying thehotrod
parameter on theRollingUpgradeManager
MBean on the Target Cluster.CLI
Invoke theupgrade --disconnectsource=hotrod
command on the Target Cluster.
Decommission the Source Cluster
As a final step, decommission the Source Cluster.
30.3. RollingUpgradeManager Operations
RollingUpgradeManager
Mbean handles the operations that allow data to be migrated from one version of Red Hat JBoss Data Grid to another when performing rolling upgrades. The RollingUpgradeManager
operations are:
recordKnownGlobalKeyset
retrieves the entire keyset from the cluster running on the old version of JBoss Data Grid.synchronizeData
performs the migration of data from the Source Cluster to the Target Cluster, which is running the new version of JBoss Data Grid.disconnectSource
disables the Source Cluster, the older version of JBoss Data Grid, once data migration to the Target Cluster is complete.
30.4. RemoteCacheStore Parameters for Rolling Upgrades
30.4.1. rawValues and RemoteCacheStore
rawValues
parameter causes the raw values to be stored instead for interoperability with direct access by RemoteCacheManagers.
rawValues
must be enabled in order to interact with a Hot Rod cache via both RemoteCacheStore and RemoteCacheManager.
30.4.2. hotRodWrapping
hotRodWrapping
parameter is a shortcut that enables rawValues and sets an appropriate marshaller and entry wrapper for performing Rolling Upgrades.
Appendix A. JMX MBeans in RedHat JBoss Data Grid
A.1. Activation
org.infinispan.eviction.ActivationManagerImpl
Table A.1. Attributes
Name | Description | Type | Writable |
---|---|---|---|
activations | Number of activation events. | String | No |
statisticsEnabled | Enables or disables the gathering of statistics by this component. | boolean | Yes |
Table A.2. Operations
Name | Description | Signature |
---|---|---|
resetStatistics | Resets statistics gathered by this component. | void resetStatistics() |
A.2. Cache
org.infinispan.CacheImpl
Table A.3. Attributes
Name | Description | Type | Writable |
---|---|---|---|
cacheName | Returns the cache name. | String | No |
cacheStatus | Returns the cache status. | String | No |
configurationAsProperties | Returns the cache configuration in form of properties. | java.util.Properties | No |
version | Returns the version of Infinispan | java.lang.String | No |
Table A.4. Operations
Name | Description | Signature |
---|---|---|
start | Starts the cache. | void start() |
stop | Stops the cache. | void stop() |
clear | Clears the cache. | void clear() |
A.3. CacheLoader
org.infinispan.interceptors.CacheLoaderInterceptor
Table A.5. Attributes
Name | Description | Type | Writable |
---|---|---|---|
cacheLoaderLoads | Number of entries loaded from the cache store. | long | No |
cacheLoaderMisses | Number of entries that did not exist in cache store. | long | No |
stores | Returns a collection of cache loader types which are configured and enabled. | Collection | No |
statisticsEnabled | Enables or disables the gathering of statistics by this component. | boolean | Yes |
Table A.6. Operations
Name | Description | Signature |
---|---|---|
disableStore | Disable all cache loaders of a given type, where type is a fully qualified class name of the cache loader to disable. | void disableStore(String storeType) |
resetStatistics | Resets statistics gathered by this component. | void resetStatistics() |
A.4. CacheManager
org.infinispan.manager.DefaultCacheManager
Table A.7. Attributes
Name | Description | Type | Writable |
---|---|---|---|
cacheManagerStatus | The status of the cache manager instance. | String | No |
clusterMembers | Lists members in the cluster. | String | No |
clusterName | Cluster name. | String | No |
clusterSize | Size of the cluster in the number of nodes. | int | No |
createdCacheCount | The total number of created caches, including the default cache. | String | No |
definedCacheCount | The total number of defined caches, excluding the default cache. | String | No |
definedCacheNames | The defined cache names and their statuses. The default cache is not included in this representation. | String | No |
name | The name of this cache manager. | String | No |
nodeAddress | The network address associated with this instance. | String | No |
physicalAddresses | The physical network addresses associated with this instance. | String | No |
runningCacheCount | The total number of running caches, including the default cache. | String | No |
version | Infinispan version. | String | No. |
Table A.8. Operations
Name | Description | Signature |
---|---|---|
startCache | Starts the default cache associated with this cache manager. | void startCache() |
startCache | Starts a named cache from this cache manager. | void startCache (String p0) |
A.5. CacheStore
org.infinispan.interceptors.CacheWriterInterceptor
Table A.9. Attributes
Name | Description | Type | Writable |
---|---|---|---|
writesToTheStores | Number of writes to the store. | long | No |
statisticsEnabled | Enables or disables the gathering of statistics by this component. | boolean | Yes |
Table A.10. Operations
Name | Description | Signature |
---|---|---|
resetStatistics | Resets statistics gathered by this component. | void resetStatistics() |
A.6. DeadlockDetectingLockManager
org.infinispan.util.concurrent.locks.DeadlockDetectingLockManager
Table A.11. Attributes
Name | Description | Type | Writable |
---|---|---|---|
detectedLocalDeadlocks | Number of local transactions that were rolled back due to deadlocks. | long | No |
detectedRemoteDeadlocks | Number of remote transactions that were rolled back due to deadlocks. | long | No |
overlapWithNotDeadlockAwareLockOwners | Number of situations when we try to determine a deadlock and the other lock owner is NOT a transaction. In this scenario we cannot run the deadlock detection mechanism. | long | No |
totalNumberOfDetectedDeadlocks | Total number of local detected deadlocks. | long | No |
concurrencyLevel | The concurrency level that the MVCC Lock Manager has been configured with. | int | No |
numberOfLocksAvailable | The number of exclusive locks that are available. | int | No |
numberOfLocksHeld | The number of exclusive locks that are held. | int | No |
Table A.12. Operations
Name | Description | Signature |
---|---|---|
resetStatistics | Resets statistics gathered by this component. | void resetStatistics() |
A.7. DistributionManager
org.infinispan.distribution.DistributionManagerImpl
Note
Table A.13. Operations
Name | Description | Signature |
---|---|---|
isAffectedByRehash | Determines whether a given key is affected by an ongoing rehash. | boolean isAffectedByRehash(Object p0) |
isLocatedLocally | Indicates whether a given key is local to this instance of the cache. Only works with String keys. | boolean isLocatedLocally(String p0) |
locateKey | Locates an object in a cluster. Only works with String keys. | List locateKey(String p0) |
A.8. Interpreter
org.infinispan.cli.interpreter.Interpreter
Table A.14. Attributes
Name | Description | Type | Writable |
---|---|---|---|
cacheNames | Retrieves a list of caches for the cache manager. | String[] | No |
Table A.15. Operations
Name | Description | Signature |
---|---|---|
createSessionId | Creates a new interpreter session. | String createSessionId(String cacheName) |
execute | Parses and executes IspnCliQL statements. | String execute(String p0, String p1) |
A.9. Invalidation
org.infinispan.interceptors.InvalidationInterceptor
Table A.16. Attributes
Name | Description | Type | Writable |
---|---|---|---|
invalidations | Number of invalidations. | long | No |
statisticsEnabled | Enables or disables the gathering of statistics by this component. | boolean | Yes |
Table A.17. Operations
Name | Description | Signature |
---|---|---|
resetStatistics | Resets statistics gathered by this component. | void resetStatistics() |
A.10. LockManager
org.infinispan.util.concurrent.locks.LockManagerImpl
Table A.18. Attributes
Name | Description | Type | Writable |
---|---|---|---|
concurrencyLevel | The concurrency level that the MVCC Lock Manager has been configured with. | int | No |
numberOfLocksAvailable | The number of exclusive locks that are available. | int | No |
numberOfLocksHeld | The number of exclusive locks that are held. | int | No |
A.11. LocalTopologyManager
org.infinispan.topology.LocalTopologyManagerImpl
Note
Table A.19. Attributes
Name | Description | Type | Writable |
---|---|---|---|
rebalancingEnabled | If false, newly started nodes will not join the existing cluster nor will the state be transferred to them. If any of the current cluster members are stopped when rebalancing is disabled, the nodes will leave the cluster but the state will not be rebalanced among the remaining nodes. This will result in fewer copies than specified by the numOwners attribute until rebalancing is enabled again. | boolean | Yes |
A.12. MassIndexer
org.infinispan.query.MassIndexer
Table A.20. Operations
Name | Description | Signature |
---|---|---|
start | Starts rebuilding the index. | void start() |
Note
A.13. Passivation
org.infinispan.interceptors.PassivationInterceptor
Table A.21. Attributes
Name | Description | Type | Writable |
---|---|---|---|
passivations | Number of passivation events. | String | No |
statisticsEnabled | Enables or disables the gathering of statistics by this component | boolean | Yes |
Table A.22. Operations
Name | Description | Signature |
---|---|---|
resetStatistics | Resets statistics gathered by this component. | void resetStatistics() |
A.14. RecoveryAdmin
org.infinispan.transaction.xa.recovery.RecoveryAdminOperations
Table A.23. Operations
Name | Description | Signature |
---|---|---|
forceCommit | Forces the commit of an in-doubt transaction. | String forceCommit(long p0) |
forceCommit | Forces the commit of an in-doubt transaction | String forceCommit(int p0, byte[] p1, byte[] p2) |
forceRollback | Forces the rollback of an in-doubt transaction. | String forceRollback(long p0) |
forceRollback | Forces the rollback of an in-doubt transaction | String forceRollback(int p0, byte[] p1, byte[] p2) |
forget | Removes recovery info for the given transaction. | String forget(long p0) |
forget | Removes recovery info for the given transaction. | String forget(int p0, byte[] p1, byte[] p2) |
showInDoubtTransactions | Shows all the prepared transactions for which the originating node crashed. | String showInDoubtTransactions() |
A.15. RollingUpgradeManager
org.infinispan.upgrade.RollingUpgradeManager
Table A.24. Operations
Name | Description | Signature |
---|---|---|
disconnectSource | Disconnects the target cluster from the source cluster according to the specified migrator. | void disconnectSource(String p0) |
recordKnownGlobalKeyset | Dumps the global known keyset to a well-known key for retrieval by the upgrade process. | void recordKnownGlobalKeyset() |
synchronizeData | Synchronizes data from the old cluster to this using the specified migrator. | long synchronizeData(String p0) |
A.16. RpcManager
org.infinispan.remoting.rpc.RpcManagerImpl
Note
Table A.25. Attributes
Name | Description | Type | Writable |
---|---|---|---|
averageReplicationTime | The average time spent in the transport layer, in milliseconds. | long | No |
committedViewAsString | Retrieves the committed view. | String | No |
pendingViewAsString | Retrieves the pending view. | String | No |
replicationCount | Number of successful replications. | long | No |
replicationFailures | Number of failed replications. | long | No |
successRatio | Successful replications as a ratio of total replications. | String | No |
successRatioFloatingPoint | Successful replications as a ratio of total replications in numeric double format. | double | No |
statisticsEnabled | Enables or disables the gathering of statistics by this component. | boolean | Yes |
Table A.26. Operations
Name | Description | Signature |
---|---|---|
resetStatistics | Resets statistics gathered by this component. | void resetStatistics() |
setStatisticsEnabled | Whether statistics should be enabled or disabled (true/false) | void setStatisticsEnabled(boolean enabled) |
A.17. StateTransferManager
org.infinispan.statetransfer.StateTransferManager
Note
Table A.27. Attributes
Name | Description | Type | Writable |
---|---|---|---|
joinComplete | If true, the node has successfully joined the grid and is considered to hold state. If false, the join process is still in progress.. | boolean | No |
stateTransferInProgress | Checks whether there is a pending inbound state transfer on this cluster member. | boolean | No |
A.18. Statistics
org.infinispan.interceptors.CacheMgmtInterceptor
Table A.28. Attributes
Name | Description | Type | Writable |
---|---|---|---|
averageReadTime | Average number of milliseconds for a read operation on the cache. | long | No |
averageWriteTime | Average number of milliseconds for a write operation in the cache. | long | No |
elapsedTime | Number of seconds since cache started. | long | No |
evictions | Number of cache eviction operations. | long | No |
hitRatio | Percentage hit/(hit+miss) ratio for the cache. | double | No |
hits | Number of cache attribute hits. | long | No |
misses | Number of cache attribute misses. | long | No |
numberOfEntries | Number of entries currently in the cache. | int | No |
readWriteRatio | Read/writes ratio for the cache. | double | No |
removeHits | Number of cache removal hits. | long | No |
removeMisses | Number of cache removals where keys were not found. | long | No |
stores | Number of cache attribute PUT operations. | long | No |
timeSinceReset | Number of seconds since the cache statistics were last reset. | long | No |
Table A.29. Operations
Name | Description | Signature |
---|---|---|
resetStatistics | Resets statistics gathered by this component. | void resetStatistics() |
A.19. Transactions
org.infinispan.interceptors.TxInterceptor
Table A.30. Attributes
Name | Description | Type | Writable |
---|---|---|---|
commits | Number of transaction commits performed since last reset. | long | No |
prepares | Number of transaction prepares performed since last reset. | long | No |
rollbacks | Number of transaction rollbacks performed since last reset. | long | No |
statisticsEnabled | Enables or disables the gathering of statistics by this component. | boolean | Yes |
Table A.31. Operations
Name | Description | Signature |
---|---|---|
resetStatistics | Resets statistics gathered by this component. | void resetStatistics() |
A.20. Transport
org.infinispan.server.core.transport.NettyTransport
Table A.32. Attributes
Name | Description | Type | Writable |
---|---|---|---|
hostName | Returns the host to which the transport binds. | String | No |
idleTimeout | Returns the idle timeout. | String | No |
numberOfGlobalConnections | Returns a count of active connections in the cluster. This operation will make remote calls to aggregate results, so latency may have an impact on the speed of calculation for this attribute. | Integer | false |
numberOfLocalConnections | Returns a count of active connections this server. | Integer | No |
numberWorkerThreads | Returns the number of worker threads. | String | No |
port | Returns the port to which the transport binds. | String | |
receiveBufferSize | Returns the receive buffer size. | String | No |
sendBufferSize | Returns the send buffer size. | String | No |
totalBytesRead | Returns the total number of bytes read by the server from clients, including both protocol and user information. | String | No |
totalBytesWritten | Returns the total number of bytes written by the server back to clients, including both protocol and user information. | String | No |
tcpNoDelay | Returns whether TCP no delay was configured or not. | String | No |
A.21. XSiteAdmin
org.infinispan.xsite.XSiteAdminOperations
Table A.33. Operations
Name | Description | Signature |
---|---|---|
bringSiteOnline | Brings the given site back online on all the cluster. | String bringSiteOnline(String p0) |
amendTakeOffline | Amends the values for 'TakeOffline' functionality on all the nodes in the cluster. | String amendTakeOffline(String p0, int p1, long p2) |
getTakeOfflineAfterFailures | Returns the value of the 'afterFailures' for the 'TakeOffline' functionality. | String getTakeOfflineAfterFailures(String p0) |
getTakeOfflineMinTimeToWait | Returns the value of the 'minTimeToWait' for the 'TakeOffline' functionality. | String getTakeOfflineMinTimeToWait(String p0) |
setTakeOfflineAfterFailures | Amends the values for 'afterFailures' for the 'TakeOffline' functionality on all the nodes in the cluster. | String setTakeOfflineAfterFailures(String p0, int p1) |
setTakeOfflineMinTimeToWait | Amends the values for 'minTimeToWait' for the 'TakeOffline' functionality on all the nodes in the cluster. | String setTakeOfflineMinTimeToWait(String p0, long p1) |
siteStatus | Check whether the given backup site is offline or not. | String siteStatus(String p0) |
status | Returns the the status(offline/online) of all the configured backup sites. | String status() |
takeSiteOffline | Takes this site offline in all nodes in the cluster. | String takeSiteOffline(String p0) |
Appendix B. Configuration Recommendations
B.1. Timeout Values
Table B.1. Timeout Value Recommendations for JBoss Data Grid
Timeout Value | Parent Element | Default Value | Recommended Value |
---|---|---|---|
distributedSyncTimeout | transport | 240,000 (4 minutes) | Same as default |
lockAcquisitionTimeout | locking | 10,000 (10 seconds) | Same as default |
cacheStopTimeout | transaction | 30,000 (30 seconds) | Same as default |
completedTxTimeout | transaction | 60,000 (60 seconds) | Same as default |
replTimeout | sync | 15,000 (15 seconds) | Same as default |
timeout | stateTransfer | 240,000 (4 minutes) | Same as default |
timeout | backup | 10,000 (10 seconds) | Same as default |
flushLockTimeout | async | 1 (1 millisecond) | Same as default. Note that this value applies to asynchronous cache stores, but not asynchronous caches. |
shutdownTimeout | async | 25,000 (25 seconds) | Same as default. Note that this value applies to asynchronous cache stores, but not asynchronous caches. |
pushStateTimeout | singletonStore | 10,000 (10 seconds) | Same as default. |
backup | replicationTimeout | 10,000 (10 seconds) | |
remoteCallTimeout | clusterLoader | 0 | For most requirements, same as default. This value is usually set to the same as the sync.replTimeout value. |
Appendix C. References
C.1. About Consistency
C.2. About Consistency Guarantee
- If Key
K
is hashed to nodes{A,B}
and transactionTX1
acquires a lock forK
on, for example, nodeA
and - If another cache access occurs on node
B
, or any other node, andTX2
attempts to lockK
, this access attempt fails with a timeout because the transactionTX1
already holds a lock onK.
K
is always deterministically acquired on the same node of the cluster, irrespective of the transaction's origin.
C.3. About JBoss Cache
C.4. About RELAY2
RELAY
protocol bridges two remote clusters by creating a connection between one node in each site. This allows multicast messages sent out in one site to be relayed to the other and vice versa.
RELAY2
protocol, which is used for communication between sites in Red Hat JBoss Data Grid's Cross-Site Replication.
RELAY2
protocol works similarly to RELAY
but with slight differences. Unlike RELAY
, the RELAY2
protocol:
- connects more than two sites.
- connects sites that operate autonomously and are unaware of each other.
- offers both unicasts and multicast routing between sites.
C.5. About Return Values
C.6. About Runnable Interfaces
run()
method, which executes the active part of the class' code. The Runnable object can be executed in its own thread after it is passed to a thread constructor.
C.7. About Two Phase Commit (2PC)
C.8. About Key-Value Pairs
- A key is unique to a particular data entry. It consists of entry data attributes from the related entry.
- A value is the data assigned to and identified by the key.
C.9. The Externalizer
C.9.1. About Externalizer
Externalizer
is a class that can:
- Marshall a given object type to a byte array.
- Unmarshall the contents of a byte array into an instance of the object type.
C.9.2. Internal Externalizer Implementation Access
public static class ABCMarshallingExternalizer implements AdvancedExternalizer<ABCMarshalling> { @Override public void writeObject(ObjectOutput output, ABCMarshalling object) throws IOException { MapExternalizer ma = new MapExternalizer(); ma.writeObject(output, object.getMap()); } @Override public ABCMarshalling readObject(ObjectInput input) throws IOException, ClassNotFoundException { ABCMarshalling hi = new ABCMarshalling(); MapExternalizer ma = new MapExternalizer(); hi.setMap((ConcurrentHashMap<Long, Long>) ma.readObject(input)); return hi; } ...
public static class ABCMarshallingExternalizer implements AdvancedExternalizer<ABCMarshalling> { @Override public void writeObject(ObjectOutput output, ABCMarshalling object) throws IOException { output.writeObject(object.getMap()); } @Override public ABCMarshalling readObject(ObjectInput input) throws IOException, ClassNotFoundException { ABCMarshalling hi = new ABCMarshalling(); hi.setMap((ConcurrentHashMap<Long, Long>) input.readObject()); return hi; } ... }
C.10. Hash Space Allocation
C.10.1. About Hash Space Allocation
C.10.2. Locating a Key in the Hash Space
C.10.3. Requesting a Full Byte Array
As a default, JBoss Data Grid only partially prints byte arrays to logs to avoid unnecessarily printing large byte arrays. This occurs when either:
- JBoss Data Grid caches are configured for lazy deserialization. Lazy deserialization is not available in JBoss Data Grid's Remote Client-Server mode.
- A
Memcached
orHot Rod
server is run.
-Dinfinispan.arrays.debug=true
system property at start up.
Example C.1. Partial Byte Array Log
2010-04-14 15:46:09,342 TRACE [ReadCommittedEntry] (HotRodWorker-1-1) Updating entry (key=CacheKey{data=ByteArray{size=19, hashCode=1b3278a, array=[107, 45, 116, 101, 115, 116, 82, 101, 112, 108, ..]}} removed=false valid=true changed=true created=true value=CacheValue{data=ByteArray{size=19, array=[118, 45, 116, 101, 115, 116, 82, 101, 112, 108, ..]}, version=281483566645249}] And here's a log message where the full byte array is shown: 2010-04-14 15:45:00,723 TRACE [ReadCommittedEntry] (Incoming-2,Infinispan-Cluster,eq-6834) Updating entry (key=CacheKey{data=ByteArray{size=19, hashCode=6cc2a4, array=[107, 45, 116, 101, 115, 116, 82, 101, 112, 108, 105, 99, 97, 116, 101, 100, 80, 117, 116]}} removed=false valid=true changed=true created=true value=CacheValue{data=ByteArray{size=19, array=[118, 45, 116, 101, 115, 116, 82, 101, 112, 108, 105, 99, 97, 116, 101, 100, 80, 117, 116]}, version=281483566645249}]
Appendix D. Revision History
Revision History | |||||
---|---|---|---|---|---|
Revision 6.3.0-27 | Tue Feb 24 2015 | Rakesh Ghatvisave | |||
| |||||
Revision 6.3.0-26 | Mon Jan 12 2015 | Misha Husnain Ali | |||
| |||||
Revision 6.3.0-25 | Tue Jan 06 2015 | Misha Husnain Ali | |||
| |||||
Revision 6.3.0-24 | Fri Dec 05 2014 | Misha Husnain Ali | |||
| |||||
Revision 6.3.0-23 | Mon Nov 17 2014 | Misha Husnain Ali | |||
| |||||
Revision 6.3.0-22 | Fri Oct 31 2014 | Misha Husnain Ali | |||
| |||||
Revision 6.3.0-21 | Tue Oct 28 2014 | Misha Husnain Ali | |||
| |||||
Revision 6.3.0-21 | Tue Oct 28 2014 | Misha Husnain Ali | |||
| |||||
Revision 6.3.0-20 | Fri Sep 26 2014 | Misha Husnain Ali | |||
| |||||
Revision 6.3.0-19 | Mon Sep 15 2014 | Misha Husnain Ali | |||
| |||||
Revision 6.3.0-18 | Wed Sep 03 2014 | Rakesh Ghatvisave | |||
| |||||
Revision 6.3.0-16 | Wed Aug 27 2014 | Misha Husnain Ali | |||
| |||||
Revision 6.3.0-15 | Thu Aug 07 2014 | Gemma Sheldon | |||
| |||||
Revision 6.3.0-14 | Fri Aug 01 2014 | Rakesh Ghatvisave | |||
| |||||
Revision 6.3.0-13 | Fri Jul 25 2014 | Rakesh Ghatvisave | |||
| |||||
Revision 6.3.0-12 | Tue Jul 15 2014 | Rakesh Ghatvisave | |||
|