Administration and Configuration Guide
For use with Red Hat JBoss Data Grid 6.6.1
Abstract
Chapter 1. Setting up Red Hat JBoss Data Grid
1.1. Prerequisites
1.2. Steps to Set up Red Hat JBoss Data Grid
Procedure 1.1. Set Up JBoss Data Grid
Set Up the Cache Manager
The first step in a JBoss Data Grid configuration is a cache manager. Cache managers can retrieve cache instances and create cache instances quickly and easily using previously specified configuration templates. For details about setting up a cache manager, see Part I, “Set Up a Cache Manager”Set Up JVM Memory Management
An important step in configuring your JBoss Data Grid is to set up memory management for your Java Virtual Machine (JVM). JBoss Data Grid offers features such as eviction and expiration to help manage the JVM memory.Set Up Eviction
Use eviction to specify the logic used to remove entries from the in-memory cache implementation based on how often they are used. JBoss Data Grid offers different eviction strategies for finer control over entry eviction in your data grid. Eviction strategies and instructions to configure them are available in Chapter 3, Set Up Eviction.Set Up Expiration
To set upper limits to an entry's time in the cache, attach expiration information to each entry. Use expiration to set up the maximum period an entry is allowed to remain in the cache and how long the retrieved entry can remain idle before being removed from the cache. For details, see Chapter 4, Set Up Expiration
Monitor Your Cache
JBoss Data Grid uses logging via JBoss Logging to help users monitor their caches.Set Up Logging
It is not mandatory to set up logging for your JBoss Data Grid, but it is highly recommended. JBoss Data Grid uses JBoss Logging, which allows the user to easily set up automated logging for operations in the data grid. Logs can subsequently be used to troubleshoot errors and identify the cause of an unexpected failure. For details, see Chapter 5, Set Up Logging
Set Up Cache Modes
Cache modes are used to specify whether a cache is local (simple, in-memory cache) or a clustered cache (replicates state changes over a small subset of nodes). Additionally, if a cache is clustered, either replication, distribution or invalidation mode must be applied to determine how the changes propagate across the subset of nodes. For details, see Part IV, “Set Up Cache Modes”Set Up Locking for the Cache
When replication or distribution is in effect, copies of entries are accessible across multiple nodes. As a result, copies of the data can be accessed or modified concurrently by different threads. To maintain consistency for all copies across nodes, configure locking. For details, see Part 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 30, High Availability Using Server Hinting
Part I. Set Up a Cache Manager
Chapter 2. Cache Managers
- it creates cache instances on demand.
- 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
Procedure 2.1. Configure a New RemoteCacheManager
import org.infinispan.client.hotrod.RemoteCache; import org.infinispan.client.hotrod.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();
- Use the
ConfigurationBuilder()
constructor to create a new configuration builder. The.addServer()
method adds a remote server, configured via the.host(<hostname|ip>)
and.port(<port>)
properties. - Create a new
RemoteCacheManager
using the supplied configuration. - Retrieve the default cache from the remote server.
2.2.2. Create a New Embedded Cache Manager
Procedure 2.2. 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();
my-config-file.xml
.
2.2.3. Create a New Embedded Cache Manager Using CDI
Procedure 2.3. Use CDI to Create a New EmbeddedCacheManager
- Specify a default configuration:
public class Config @Produces public EmbeddedCacheManager defaultCacheManager() { ConfigurationBuilder builder = new ConfigurationBuilder(); Configuration configuration = builder.eviction().strategy(EvictionStrategy.LRU).maxEntries(100).build(); return new DefaultCacheManager(configuration); } }
- Inject the default cache manager.
<!-- Additional configuration information here --> @Inject EmbeddedCacheManager cacheManager; <!-- Additional configuration information here -->
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. Changing the Maximum Entries Value at Runtime
- Invoking the setMaxEntries operation sets maximum number of entries in the data container.
- If the data container does not support eviction, setting it will raise an exception.
- Defining a value less than 0 will throw an error.
3.3.4. Eviction Configuration Troubleshooting
max-entries
parameter of the eviction
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.5. Eviction and Passivation
Chapter 4. Set Up Expiration
4.1. About Expiration
- A lifespan value.
- A maximum idle time value.
lifespan
or maxIdle
value.
lifespan
or maxIdle
defined are mortal, as they will eventually be removed from the cache once one of these conditions are met.
- 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 Behavior
- An entry is passivated/overflowed to disk and is discovered to have expired.
- The expiration maintenance thread discovers that an entry it has found is expired.
4.5. Configure Expiration
Procedure 4.1. Configure Expiration in Library Mode
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.<expiration lifespan="1000" maxIdle="1000" />
Set the Background Reaper Thread
Enable or disable the background reaper thread to test entries for expiration. Regardless of whether a reaper is used, entries are tested for expiration lazily when they are touched. The default value istrue
.<expiration lifespan="1000" maxIdle="1000" reaperEnabled="true" />
Set the Expiration Interval
Set the interval (in milliseconds) between subsequent runs to purge expired entries from memory and any associated cache stores. To disable the periodic eviction process set the interval to-1
. The default value is1000
.<expiration lifespan="1000" maxIdle="1000" reaperEnabled="true" wakeUpInterval="5000" />
Procedure 4.2. Configuration Expiration in Remote Client-Server Mode
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.<expiration lifespan="1000" max-idle="1000" />
Set the Expiration Interval
Set the interval (in milliseconds) between subsequent runs to purge expired entries from memory and any associated cache stores. To disable the periodic eviction process set the interval to-1
. The default value is5000
.<expiration lifespan="1000" max-idle="1000" interval="10000" />
Reaper Thread in Remote Client-Server Mode
In Remote Client-Server Mode the background reaper thread is only enabled ifinterval
is greater than0
. Asinterval
defaults to5000
the background reaper thread is automatically enabled if expiration is configured.
4.6. 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:
- An entry is passivated/overflowed to disk and is discovered to have expired.
- The expiration maintenance thread discovers that an entry it has found is expired.
get()
or containsKey()
for the expired entry causes JBoss Data Grid to return a null value. The expired entry is later removed by the expiration 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. Logging Sample Configuration Location
standalone.xml
or clustered.xml
.
5.5.2. 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.4"> <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.4"> <root-logger> <level name="INFO"/> <handlers> <handler name="CONSOLE"/> <handler name="FILE"/> </handlers> </root-logger> </subsystem>
5.5.3. Sample XML Configuration for a Log Category
Procedure 5.2. Configure a Log Category
<subsystem xmlns="urn:jboss:domain:logging:1.4"> <logger category="com.company.accounts.rec" use-parent-handlers="true"> <level name="WARN"/> <handlers> <handler name="accounts-rec"/> </handlers> </logger> </subsystem>
- Use the
category
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. - Use the
level
property to set the maximum level of log message that the log category records. - The
handlers
element contains a list of log handlers.
5.5.4. Sample XML Configuration for a Console Log Handler
Procedure 5.3. Configure the Console Log Handler
<subsystem xmlns="urn:jboss:domain:logging:1.4"> <console-handler name="CONSOLE" autoflush="true"> <level name="INFO"/> <encoding value="UTF-8"/> <target value="System.out"/> <filter-spec value="not(match("JBAS.*"))"/> <formatter> <pattern-formatter pattern="%K{level}%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/> </formatter> </console-handler> </subsystem>
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.Set the
level
PropertyThelevel
property sets the maximum level of log messages recorded.Set the
encoding
OutputUseencoding
to set the character encoding scheme to be used for the output.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.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.*"))
.Specify the
formatter
Useformatter
to list the log formatter used by the log handler.
5.5.5. Sample XML Configuration for a File Log Handler
Procedure 5.4. Configure the File Log Handler
<file-handler name="accounts-rec-trail" autoflush="true"> <level name="INFO"/> <encoding value="UTF-8"/> <file relative-to="jboss.server.log.dir" path="accounts-rec-trail.log"/> <formatter> <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/> </formatter> <append value="true"/> </file-handler>
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.Set the
level
PropertyThelevel
property sets the maximum level of log message that the root logger records.Set the
encoding
OutputUseencoding
to set the character encoding scheme to be used for the output.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.Specify the
formatter
Useformatter
to list the log formatter used by the log handler.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.
5.5.6. Sample XML Configuration for a Periodic Log Handler
Procedure 5.5. Configure the Periodic Log Handler
<periodic-rotating-file-handler name="FILE" autoflush="true"> <level name="INFO"/> <encoding value="UTF-8"/> <formatter> <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/> </formatter> <file relative-to="jboss.server.log.dir" path="server.log"/> <suffix value=".yyyy-MM-dd"/> <append value="true"/> </periodic-rotating-file-handler>
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.Set the
level
PropertyThelevel
property sets the maximum level of log message that the root logger records.Set the
encoding
OutputUseencoding
to set the character encoding scheme to be used for the output.Specify the
formatter
Useformatter
to list the log formatter used by the log handler.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.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.htmlSet 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.
5.5.7. Sample XML Configuration for a Size Log Handler
Procedure 5.6. Configure the Size Log Handler
<size-rotating-file-handler name="accounts_debug" autoflush="false"> <level name="DEBUG"/> <encoding value="UTF-8"/> <file relative-to="jboss.server.log.dir" path="accounts-debug.log"/> <rotate-size value="500k"/> <max-backup-index value="5"/> <formatter> <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/> </formatter> <append value="true"/> </size-rotating-file-handler>
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.Set the
level
PropertyThelevel
property sets the maximum level of log message that the root logger records.Set the
encoding
OutputUseencoding
to set the character encoding scheme to be used for the output.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.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.Set the
max-backup-index
NumberThe maximum number of rotated logs that are kept. When this number is reached, the oldest log is reused.Specify the
formatter
Useformatter
to list the log formatter used by the log handler.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.
5.5.8. Sample XML Configuration for a Async Log Handler
Procedure 5.7. Configure the Async Log Handler
<async-handler name="Async_NFS_handlers"> <level name="INFO"/> <queue-length value="512"/> <overflow-action value="block"/> <subhandlers> <handler name="FILE"/> <handler name="accounts-record"/> </subhandlers> </async-handler>
- The
name
property sets the unique identifier for this log handler. - The
level
property sets the maximum level of log message that the root logger records. - The
queue-length
defines the maximum number of log messages that will be held by this handler while waiting for sub-handlers to respond. - The
overflow-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. - The
subhandlers
list is the list of log handlers to which this async handler passes its log messages.
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
<subsystem xmlns="urn:infinispan:server:core:6.2" default-cache-container="local"> <cache-container name="local" default-cache="default" statistics="true" listener-executor="infinispan-listener" start="EAGER"> <local-cache name="default" start="EAGER" statistics="false"> <!-- Additional configuration information here --> </local-cache> </cache-container> </subsystem>
Configure the Cache Container
Thecache-container
element specifies information about the cache container using the following parameters:- The
name
parameter defines the name of the cache container. - The
default-cache
parameter defines the name of the default cache used with the cache container. - The
statistics
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. - The
listener-executor
defines the executor used for asynchronous cache listener notifications. - The
start
parameter indicates when the cache container starts, i.e. whether it will start lazily when requested or "eagerly" when the server starts up. Valid values for this parameter areEAGER
andLAZY
.
Configure 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
.
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
<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>
local-cache
element specifies information about the local cache used with the cache container using the following parameters:
- The
name
parameter specifies the name of the local cache to use. - The
start
parameter indicates when the cache container starts, i.e. whether it will start lazily when requested or "eagerly" when the server starts up. Valid values for this parameter areEAGER
andLAZY
. - The
batching
parameter specifies whether batching is enabled for the local cache. - If
statistics
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
. - The
index
attribute of theindexing
parameter specifies the type of indexing used for the local cache. Valid values for this attribute areNONE
,LOCAL
andALL
.
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="ASYNC" batching="false" statistics="true"> <!-- Additional configuration information here --> </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.
ClusterLoader
must be configured, otherwise a node will become the owner or backup owner of a key without the data being loaded into its cache. In addition, if State Transfer is disabled in distributed mode then a key will occasionally have less than numOwners
owners.
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.
- Allows a
GET
operation to successfully retrieve a key from another node without returning a null value during a progressive state transfer.
- 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
<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" owners="2" statistics="true"> <!-- Additional configuration information here --> </distributed-cache> </cache-container>
distributed-cache
element configures settings for the distributed cache using the following parameters:
- The
name
parameter provides a unique identifier for the cache. - The
mode
parameter sets the clustered cache mode. Valid values areSYNC
(synchronous) andASYNC
(asynchronous). - 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
. - The
start
parameter specifies whether the cache starts when the server starts up or when it is requested or deployed. - The
owners
parameter indicates the number of nodes that will contain the hash segment. - If
statistics
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
.
Important
cache-container
, locking
, and transaction
elements, see the appropriate chapter.
7.6. Configure Distribution Mode (Library Mode)
Procedure 7.2. Distributed Cache Configuration
Configure the Clustering Element
<clustering mode="distribution"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" timeout="${TIME}" />
- The
clustering
element'smode
parameter's value determines the clustering mode selected for the cache. - The
sync
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. - The
stateTransfer
element specifies how state is transferred when a node leaves or joins the cluster. It uses the following parameters:- The
chunkSize
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. - The
fetchInMemoryState
parameter when set totrue
, requests state information from neighboring caches on start up. This impacts the start up time for the cache. Set the default totrue
if there is no shared cache store behind to avoid cache inconsistency. - The
awaitInitialTransfer
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. - The
timeout
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 thetimeout
period, the start up process aborts and an exception is thrown. As a result of the failed state transfer, the cache is not available on that instance.
Specify Transport Configuration
<global> <transport clusterName="${NAME}" distributedSyncTimeout="${TIME}" transportClass="${CLASS}" /> </global>
Thetransport
element defines the transport configuration for the cache container as follows:- The
clusterName
parameter specifies the name of the cluster. Nodes can only connect to clusters that share the same name. - The
distributedSyncTimeout
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. - The
transportClass
parameter specifies a class that represents a network transport for the cache container.
7.7. Synchronous and Asynchronous Distribution
Example 7.1. Communication Mode example
A
, B
and C
, and a key K
that maps nodes A
and B
. Perform an operation on node C
that requires a return value, for example Cache.remove(K)
. To execute successfully, the operation must first synchronously forward the call to both node A
and B
, and then wait for a result returned from either node 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
<cache-container name="clustered" default-cache="default" statistics="true"> <transport executor="infinispan-transport" lock-timeout="60000"/> <replicated-cache name="default" mode="SYNC" start="EAGER" statistics="true"> <transaction mode="NONE" /> </replicated-cache> </cache-container>
Important
replicated-cache
element configures settings for the distributed cache using the following parameters:
- The
name
parameter provides a unique identifier for the cache. - The
mode
parameter sets the clustered cache mode. Valid values areSYNC
(synchronous) andASYNC
(asynchronous). - The
start
parameter specifies whether the cache starts when the server starts up or when it is requested or deployed. - If
statistics
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
. - The
transaction
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
and locking
, see the appropriate chapter.
8.4. Configure Replication Mode (Library Mode)
Procedure 8.2. Replication Mode Configuration
Configure the Clustering Element
<clustering mode="replication"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" timeout="${TIME}" />
- The
clustering
element'smode
parameter's value determines the clustering mode selected for the cache. - The
sync
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. - The
stateTransfer
element specifies how state is transferred when a node leaves or joins the cluster. It uses the following parameters:- The
chunkSize
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. - The
fetchInMemoryState
parameter when set totrue
, requests state information from neighboring caches on start up. This impacts the startup time for the cache. Set the default totrue
if there is no shared cache store behind to avoid cache inconsistency. - The
awaitInitialTransfer
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. - The
timeout
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 thetimeout
period, the start up process aborts and an exception is thrown. As a result of the failed state transfer, the cache is not available on that instance.
Specify Transport Configuration
<global> <transport clusterName="${NAME}" distributedSyncTimeout="${TIME}" transportClass="${CLASS}" /> </global>
Thetransport
element defines the transport configuration for the cache container as follows:- The
clusterName
parameter specifies the name of the cluster. Nodes can only connect to clusters that share the same name. - The
distributedSyncTimeout
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. - The
transportClass
parameter specifies a class that represents a network transport for the cache container.
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
orclustered.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"> <!-- Additional configuration information here --> </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
<cache-container name="local" default-cache="default" statistics="true"> <invalidation-cache name="default" mode="ASYNC" start="EAGER" statistics="true"> <!-- Additional configuration information here --> </invalidation-cache> </cache-container>
invalidation-cache
element configures settings for the distributed cache using the following parameters:
- The
name
parameter provides a unique identifier for the cache. - The
mode
parameter sets the clustered cache mode. Valid values areSYNC
(synchronous) andASYNC
(asynchronous). - The
start
parameter specifies whether the cache starts when the server starts up or when it is requested or deployed. - If
statistics
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
.
Important
cache-container
, locking
, and transaction
elements, see the appropriate chapter.
9.3. Configure Invalidation Mode (Library Mode)
Procedure 9.2. Invalidation Mode Configuration
Configure the Clustering Element
<clustering mode="invalidation"> <sync replTimeout="${TIME}" /> <stateTransfer chunkSize="${SIZE}" fetchInMemoryState="{true/false}" awaitInitialTransfer="{true/false}" timeout="${TIME}" />
- The
clustering
element'smode
parameter's value determines the clustering mode selected for the cache. - The
sync
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. - The
stateTransfer
element specifies how state is transferred when a node leaves or joins the cluster. It uses the following parameters:- The
chunkSize
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. - The
fetchInMemoryState
parameter when set totrue
, requests state information from neighboring caches on start up. This impacts the start up time for the cache. - The
awaitInitialTransfer
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. - The
timeout
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 thetimeout
period, the start up process aborts and an exception is thrown.
Specify Transport Configuration
<global> <transport clusterName="${NAME}" distributedSyncTimeout="${TIME}" transportClass="${CLASS}" /> </global>
Thetransport
element defines the transport configuration for the cache container as follows:- The
clusterName
parameter specifies the name of the cluster. Nodes can only connect to clusters that share the same name. - The
distributedSyncTimeout
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. - The
transportClass
parameter specifies a class that represents a network transport for the cache container.
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
Important
security-domain
and auth-method
parameters from the connector.
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('/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/default/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/default/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
<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
<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>
rest-connector
element specifies the configuration information for the REST connector.
- The
virtual-server
parameter specifies the virtual server used by the REST connector. The default value for this parameter isdefault-host
. This is an optional parameter. - The
cache-container
parameter names the cache container used by the REST connector. This is a mandatory parameter. - The
context-path
parameter specifies the context path for the REST connector. The default value for this parameter is an empty string (""
). This is an optional parameter. - The
security-domain
parameter specifies that the specified domain, declared in the security subsystem, should be used to authenticate access to the REST endpoint. This is an optional parameter. If this parameter is omitted, no authentication is performed. - The
auth-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. - The
security-mode
parameter specifies whether authentication is required only for write operations (such as PUT, POST and DELETE) or for read operations (such as GET and HEAD) as well. Valid values for this parameter areWRITE
for authenticating write operations only, orREAD_WRITE
to authenticate read and write operations. The default value for this parameter isREAD_WRITE
.
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 group, 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
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.
<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>
- The
socket-binding
parameter specifies the socket binding port used by the memcached connector. This is a mandatory parameter. - The
cache-container
parameter names the cache container used by the memcached connector. This is a mandatory parameter. - The
worker-threads
parameter specifies the number of worker threads available for the memcached connector. The default value for this parameter is 160. This is an optional parameter. - The
idle-timeout
parameter specifies the time (in milliseconds) the connector can remain idle before the connection times out. The default value for this parameter is-1
, which means that no timeout period is set. This is an optional parameter. - The
tcp-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. - The
send-buffer-size
parameter indicates the size of the send buffer for the memcached connector. The default value for this parameter is the size of the TCP stack buffer. This is an optional parameter. - The
receive-buffer-size
parameter indicates the size of the receive buffer for the memcached connector. The default value for this parameter is the size of the TCP stack buffer. This is an optional parameter.
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.
Warning
cacheManager.getCache
method.
13.3. Hot Rod Hash Functions
13.4. The Hot Rod Interface Connector
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
<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>
- The
hotrod-connector
element defines the configuration elements for use with Hot Rod.- The
socket-binding
parameter specifies the socket binding port used by the Hot Rod connector. This is a mandatory parameter. - The
cache-container
parameter names the cache container used by the Hot Rod connector. This is a mandatory parameter. - The
worker-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. - The
idle-timeout
parameter specifies the time (in milliseconds) the connector can remain idle before the connection times out. The default value for this parameter is-1
, which means that no timeout period is set. This is an optional parameter. - The
tcp-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. - The
send-buffer-size
parameter indicates the size of the send buffer for the Hot Rod connector. The default value for this parameter is the size of the TCP stack buffer. This is an optional parameter. - The
receive-buffer-size
parameter indicates the size of the receive buffer for the Hot Rod connector. The default value for this parameter is the size of the TCP stack buffer. This is an optional parameter.
- The
topology-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
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. - The
replication-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. - The
external-host
parameter specifies the hostname sent by the Hot Rod server to clients listed in the topology information. The default value for this parameter is the host address. This is an optional parameter. - The
external-port
parameter specifies the port sent by the Hot Rod server to clients listed in the topology information. The default value for this parameter is the configured port. This is an optional parameter. - The
lazy-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. - The
await-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
.
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
.
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
.
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
.
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 thebutton near the top of the page.
- In the Product Downloads page, click .
- 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 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 BasicCacheContainer cacheContainer = new RemoteCacheManager(); //obtain a handle to the remote default cache BasicCache<String, String> cache = cacheContainer.getCache(); //now add something to the cache and ensure 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 BasicCacheContainer
.
DefaultCacheManager
and RemoteCacheManager
, which is simplified by the common BasicCacheContainer
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> remoteCache = 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.removeWithVersion("car", valueBinary.getVersion()); assert !remoteCache.containsKey("car");
Example 13.5. Using Replace
remoteCache.put("car", "ferrari"); VersionedValue valueBinary = remoteCache.getVersioned("car"); assert remoteCache.replaceWithVersion("car", "lamborghini", valueBinary.getVersion());
13.10. Hot Rod C++ Client
- Red Hat Enterprise Linux 5, 64-bit
- Red Hat Enterprise Linux 6, 64-bit
- Red Hat Enterprise Linux 7, 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
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.
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 .
Figure 13.2. Hot Rod C# Client End-User License Agreement
- To change the default directory, clickor click to install in the default directory.
Figure 13.3. Hot Rod C# Client Destination Folder
- Clickto 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.11.4. String Marshaller for Interoperability
[...] RemoteCacheManager cacheManager = new RemoteCacheManager(new CompatibilitySerializer()); [...] cache.Put("key", "value"); String value = cache.Get("key"); [...]
Note
HotRodClientException
being thrown.
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; }
13.13. Compatibility Between Server and Hot Rod Client Versions
Note
The following will be the impact on the client side:
- client will not have advantage of the latest protocol improvements.
- client might run into known issues which are fixed for the server-side version.
- client can only use the functionalities available in its current version and the previous versions.
In this case, when a Hot Rod client connects to a JBoss Data Grid server, the connection will be rejected with an exception error. The client can be downgraded to a known protocol version by setting the client side property - org.infinispan.client.hotrod.configuration.ConfigurationBuilder.protocolVersion
to a specific version, such as Hot Rod 1.3, as a String. In this case the client is able to connect to the server, but will be restricted to the functionality of that version. Any command which is not supported by this protocol version will not work and throw an exception. Also, the topology information might be inefficient in this case.
Note
Table 13.47. Hot Rod client and server compatibility
JBoss Data Grid Server Version | Hot Rod Protocol Version |
---|---|
JBoss Data Grid 6.6.1 | Hot Rod 2.3 |
JBoss Data Grid 6.6.0 | Hot Rod 2.3 |
JBoss Data Grid 6.5.1 | Hot Rod 2.2 |
JBoss Data Grid 6.5.0 | Hot Rod 2.2 |
JBoss Data Grid 6.4.1 | Hot Rod 2.0 |
JBoss Data Grid 6.4.0 | Hot Rod 2.0 |
JBoss Data Grid 6.3.2 | Hot Rod 2.0 |
JBoss Data Grid 6.3.1 | Hot Rod 2.0 |
JBoss Data Grid 6.3.0 | Hot Rod 2.0 |
JBoss Data Grid 6.2.1 | Hot Rod 1.3 |
JBoss Data Grid 6.2.0 | Hot Rod 1.3 |
JBoss Data Grid 6.1.0 | Hot Rod 1.2 |
JBoss Data Grid 6.0.1 | Hot Rod 1.1 |
JBoss Data Grid 6.0.0 | Hot Rod 1.1 |
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)
<distributed-cache> <locking acquire-timeout="30000" concurrency-level="1000" striping="false" /> <!-- Additional configuration here --> </distributed-cache>
- The
acquire-timeout
parameter specifies the number of milliseconds after which lock acquisition will time out. - The
concurrency-level
parameter defines the number of lock stripes used by the LockManager. - The
striping
parameter specifies whether lock striping will be used for the local cache.
14.2. Configure Locking (Library Mode)
locking
element and its parameters are set 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)
<infinispan> <!-- Other configuration elements here --> <default> <locking concurrencyLevel="${VALUE}" isolationLevel="${LEVEL}" lockAcquisitionTimeout="${TIME}" useLockStriping="${TRUE/FALSE}" writeSkewCheck="${TRUE/FALSE}" />
- The
concurrencyLevel
parameter specifies the concurrency level for the lock container. Set this value according to the number of concurrent threads interacting with the data grid. - The
isolationLevel
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” - The
lockAcquisitionTimeout
parameter specifies time (in milliseconds) after which a lock acquisition attempt times out. - The
useLockStriping
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” - The
writeSkewCheck
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. ThewriteSkewCheck
parameter can be only used withOPTIMISTIC
transactions and it requires entry versioning to be enabled, withSIMPLE
versioning scheme.
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
tx.begin() cache.lock(K) cache.put(K,V5) tx.commit()
- When the line
cache.lock(K)
executes, a cluster-wide lock is acquired onK
. - When the line
cache.put(K,V5)
executes, it guarantees success. - When the line
tx.commit()
executes, the locks held for this process are released.
14.3.5. Implicit Pessimistic Locking Example
Procedure 14.4. Transaction with Implicit Pessimistic locking
tx.begin() cache.put(K,V) cache.put(K2,V2) cache.put(K,V5) tx.commit()
- When the line
cache.put(K,V)
executes, a cluster-wide lock is acquired onK
. - When the line
cache.put(K2,V2)
executes, a cluster-wide lock is acquired onK2
. - 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. - When the line
tx.commit()
executes, all locks held for this transaction are released.
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. There are two types of LockContainers
JBoss Data Grid uses internally and their choice is dependent on the useLockStriping
setting. 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 is10000
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 is32
. - 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)
<infinispan> <!-- Additional configuration elements here --> <default> <locking concurrencyLevel="${VALUE}" isolationLevel="${LEVEL}" lockAcquisitionTimeout="${TIME}" useLockStriping="${TRUE/FALSE}" writeSkewCheck="${TRUE/FALSE}" /> <!-- Additional configuration elements here --> </default> </infinispan>
- The
concurrencyLevel
is used to specify the size of the shared lock collection use when lock striping is enabled. - The
isolationLevel
parameter specifies the cache's isolation level. Valid isolation levels areREAD_COMMITTED
andREPEATABLE_READ
. - The
lockAcquisitionTimeout
parameter specifies time (in milliseconds) after which a lock acquisition attempt times out. - The
useLockStriping
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. - The
writeSkewCheck
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. ThewriteSkewCheck
parameter can be only used withOPTIMISTIC
transactions and it requires entry versioning to be enabled, withSIMPLE
versioning scheme.
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 in different transactions 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 operation 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 in a single transaction will always match, even if a write operation occurs in a different transaction between the two reads.
Part VII. Set Up and Configure a Cache Store
Chapter 17. Cache Stores
Note
shared
is set to false
), on node join, stale entries which might have been removed from the cluster might still be present in the stores and can reappear.
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, and CacheWriter
is used to enforce entry passivation and activation on eviction in a cache.
AdvancedCacheLoader
and AdvancedCacheWriter
provide operations to manipulate the underlying storage in bulk: parallel iteration and purging of expired entries, clear and size.
org.infinispan.persistence.file.SingleFileStore
is a good starting point to write your own store implementation.
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);
Note
location
are specific to the single-file cache store and are not used for other types of cache stores.
Procedure 17.1. Configure the Cache store Programatically
- Use the
ConfigurationBuilder
to create a new configuration object. - The
passivation
elements affects the way Red Hat JBoss Data Grid interacts with stores. Passivation removes an object from an in-memory cache and writes it to a secondary data store, such as a system or database. If no secondary data store exists, then the object will only be removed from the in-memory cache. Passivation isfalse
by default. - The
addSingleFileStore()
elements 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. - 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. - The
preload
element 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. - The
fetchPersistentState
element 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
element 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
purgeOnStartup
element controls whether cache store is purged when it starts up and isfalse
by default. - The
location
element configuration element sets a location on disk where the store can write. - These attributes configure aspects specific to each cache store. For example, the
location
attribute points to where the SingleFileStore will keep files containing data. Other stores may require more complex configuration. - 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. 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. - The
pushStateWhenCoordinator
element 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.2.5. About the SKIP_CACHE_STORE Flag
SKIP_CACHE_STORE
Flag is used then the cache store will not be considered for the specified cache operations. This flag can be useful to place an entry in the cache without having it included in the configured cache store, along with determining if an entry is found within a cache without retrieving it from the associated cache store.
17.2.6. About the SKIP_SHARED_CACHE_STORE Flag
SKIP_SHARED_CACHE_STORE
Flag is enabled then any shared cache store will not be considered for the specified cache operations. This flag can be useful to place an entry in the cache without having it included in the shared cache store, along with determining if an entry is found within a cache without retrieving it from the shared cache store.
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.
- PooledConnectionFactory.
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
.
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
Note
shared
is set to false
), on node join, stale entries which might have been removed from the cluster might still be present in the stores and can reappear.
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. When an object is evicted from in-memory cache, passivation writes it to a secondary data store, such as a system or a 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 modification methods are applied to the specific cache store. This allows write operations to be applied 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, restricting the size of the index 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 is1
. - 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 maximum amount of time that can be taken 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 provides an estimation of the key size. 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 default value is 60,000 ms, or one minute. - 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
relative-to
parameter specifies the base directory to store the cache state. This value defaults tojboss.server.data.dir
. - The
path
parameter defines where, within the directory specified in therelative-to
parameter, 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. Upgrade JBoss Data Grid Cache Stores
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>
Note
Directories will be automatically created if they do not exist.
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 using
LevelDBCacheStoreConfigurationBuilder
class 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 xmlns="urn:infinispan:config:store:leveldb:6.0 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 higher 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 theoption.
- In the submenu, click.
- 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.
- Clickto 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.
- Clickto 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 thetab.
- In the Operation drop-down box, select the Restart operation.
- Select the radio button for the Now entry.
- Clickto 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:→ → → → → → →
- 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. JDBC Datasource Configuration
- connectionPool
- dataSource
- simpleConnection
A connectionPool
uses a JDBC driver to establish a connection, along with creating a pool of threads which may be used for any requests. This configuration is typically used in stand-alone environments that require ready access to a database without having the overhead of creating the database connection on each invocation.
A dataSource
is a connection factory that understands how to reference a JNDI tree and delegate connections to the datasource. This configuration is typically used in environments where a datasource has already been configured outside of JBoss Data Grid.
The simpleConnection
is similar to connectionPool
in that it uses a JDBC driver to establish each connection; however, instead of creating a pool of threads that are available a new connection is created on each invocation. This configuration is typically used in test environments, or where only a single connection is required.
<connectionPool />
, <dataSource />
, or <simpleConnection />
elements. Alternatively, these may be configured programmatically with the connectionPool()
, dataSource()
, or simpleConnection()
methods on the JdbcBinaryStoreConfigurationBuilde
, JdbcMixedStoreConfigurationBuilder
, or JdbcBinaryStoreConfigurationBuilder
classes.
18.6.2. 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.2.1. JdbcBinaryStore Configuration (Remote Client-Server Mode)
JdbcBinaryStore
using Red Hat JBoss Data Grid's Remote Client-Server mode with Passivation enabled:
<local-cache name="customCache"> <!-- Additional configuration elements here --> <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.2.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"> <!-- Additional configuration elements here --> <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.2.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)
- Use the
ConfigurationBuilder
to create a new configuration object. - Add the
JdbcBinaryStore
configuration builder to build a specific configuration related to this store. - The
fetchPersistentState
element 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. - The
ignoreModifications
element 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. - The
purgeOnStartup
element specifies whether the cache is purged when initially started. - 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 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.3. 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.3.1. JdbcStringBasedStore Configuration (Remote Client-Server Mode)
JdbcStringBasedStore
for Red Hat JBoss Data Grid's Remote Client-Server mode:
<local-cache name="customCache"> <!-- Additional configuration elements here --> <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.3.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"> <!-- Additional configuration elements here --> <persistence> <stringKeyedJdbcStore xmlns="urn:infinispan:config:jdbc:6.0" fetchPersistentState="false" ignoreModifications="false" purgeOnStartup="false" key2StringMapper="org.infinispan.loaders.keymappers.DefaultTwoWayKey2StringMapper"> <dataSource jndiUrl="java:jboss/datasources/JdbcDS"/> <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.3.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 <!-- Additional configuration information here --> > <!-- Additional configuration elements here --> <replicated-cache> <!-- Additional configuration elements here --> <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.3.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") .dataSource() .jndiUrl("java:jboss/datasources/JdbcDS");
Procedure 18.5. Configure the JdbcStringBasedStore Programmatically
- Use the
ConfigurationBuilder
to create a new configuration object. - Add the
JdbcStringBasedStore
configuration builder to build a specific configuration related to this store. - 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 loader has this property set totrue
. ThefetchPersistentState
property isfalse
by default. - The
ignoreModifications
parameter 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. - The
purgeOnStartup
parameter 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.- 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
dataSource
element specifies a data source using the following parameters:- The
jndiUrl
specifies the JNDI URL to the existing JDBC.
Note
18.6.4. JdbcMixedStores
JdbcMixedStore
is a hybrid implementation that delegates keys based on their type to either the JdbcBinaryStore
or JdbcStringBasedStore
.
18.6.4.1. JdbcMixedStore Configuration (Remote Client-Server Mode)
JdbcMixedStore
for Red Hat JBoss Data Grid's Remote Client-Server mode:
<local-cache name="customCache"> <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.4.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"> <!-- Additional configuration elements here --> <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.4.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
- Use the
ConfigurationBuilder
to create a new configuration object. - Add the
JdbcMixedStore
configuration builder to build a specific configuration related to this store. - 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 loader has this property set totrue
. ThefetchPersistentState
property isfalse
by default. - The
ignoreModifications
parameter 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. - The
purgeOnStartup
parameter specifies whether the cache is purged when initially started. - 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 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.5. Cache Store Troubleshooting
18.6.5.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> <!-- Additional configuration elements here --> <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}"> <!-- Additional configuration elements here --> <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)
infinispan.xml
file:
<namedCache name="users"> <!-- Insert additional configuration elements here --> <persistence passivation="false"> <jpaStore xmlns="urn:infinispan:config:jpa:6.0" shared="true" preload="true" persistenceUnitName="MyPersistenceUnit" entityClassName="org.infinispan.loaders.jpa.entity.User" /> </persistence> </namedCache>
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
<dependency> <groupId>org.infinispan</groupId> <artifactId>infinispan-cachestore-jpa</artifactId> <version>6.4.0.Final-redhat-4</version> </dependency>
Procedure 18.8. Deploy JPA Cache Stores in JBoss EAP 6.3.x and earlier
- 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.6 services, org.infinispan.persistence.jpa:jdg-6.6 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.persistence.jpa" slot="jdg-6.6" services="export"/> <module name="org.infinispan" slot="jdg-6.6" services="export"/> </dependencies> </deployment> </jboss-deployment-structure>
Procedure 18.9. Deploy JPA Cache Stores in JBoss EAP 6.4 and later
- Add the following property in
persistence.xml
:<persistence-unit> [...] <properties> <property name="jboss.as.jpa.providerModule" value="application" /> </properties> </persistence-unit>
- Add the following dependencies to the
jboss-deployment-structure.xml
:<jboss-deployment-structure> <deployment> <dependencies> <module name="org.infinispan" slot="jdg-6.6"/> <module name="org.jgroups" slot="jdg-6.6"/> <module name="org.infinispan.persistence.jpa" slot="jdg-6.6" services="export"/> <module name="org.hibernate"/> </dependencies> </deployment> </jboss-deployment-structure>
- Add any additional dependencies, such as additional JDG modules, are in use add these to the
dependencies
section injboss-deployment-structure.xml
.
Important
18.9. Custom Cache Stores
CacheLoader
CacheWriter
AdvancedCacheLoader
AdvancedCacheWriter
ExternalStore
AdvancedLoadWriteStore
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.10. Download JBoss Data Grid Source Code
- To access the Red Hat Customer Portal, navigate to https://access.redhat.com/home in a browser.
- Click.
- In the section labeled JBoss Development and Management, click .
- Enter the relevant credentials in the Red Hat Login and Password fields and click .
- From the list of downloadable files, locate Red Hat JBoss Data Grid ${VERSION} Source Code and click . Save and unpack it in a desired location.
- Locate the
SingleFileStore
source code by navigating throughjboss-datagrid-6.6.1-sources/infinispan-6.4.1.Final-redhat-1-src/core/src/main/java/org/infinispan/persistence/file/SingleFileStore.java
.
18.9.1. Custom Cache Store Maven Archetype
Procedure 18.11. Generate a Maven Archetype
- Ensure the JBoss Data Grid Maven repository has been installed by following the instructions in the Red Hat JBoss Data Grid Getting Started Guide.
- Open a command prompt and execute the following command to generate an archetype in the current directory:
mvn -Dmaven.repo.local="path/to/unzipped/jboss-datagrid-6.6.0-maven-repository/" archetype:generate -DarchetypeGroupId=org.infinispan -DarchetypeArtifactId=custom-cache-store-archetype -DarchetypeVersion=6.4.1.Final-redhat-1
Note
The above command has been broken into multiple lines for readability; however, when executed this command and all arguments must be on a single line.
18.9.2. Custom Cache Store Configuration (Remote Client-Server Mode)
Example 18.2. Custom Cache Store Configuration
<distributed-cache name="cacheStore" mode="SYNC" segments="20" owners="2" remote-timeout="30000"> <store class="my.package.CustomCacheStore"> <property name="customStoreProperty">10</property> </store> </distributed-cache>
18.9.2.1. Option 1: Add Custom Cache Store using deployments (Remote Client-Server Mode)
Procedure 18.12. Deploy Custom Cache Store .jar file to JDG server using deployments
- Add the following Java service loader file
META-INF/services/org.infinispan.persistence.spi.AdvancedLoadWriteStore
to the module and add a reference to the Custom Cache Store Class, such as seen below:my.package.CustomCacheStore
- Copy the jar to the
$JDG_HOME/standalone/deployments/
directory. - If the .jar file is available the server the following message will be displayed in the logs:
JBAS010287: Registering Deployed Cache Store service for store 'my.package.CustomCacheStore'
- In the
infinispan-core
subsystem add an entry for the cache inside acache-container
, specifying the class that overrides one of the interfaces from Section 18.9, “Custom Cache Stores”:<subsystem xmlns="urn:infinispan:server:core:6.2"> [...] <distributed-cache name="cacheStore" mode="SYNC" segments="20" owners="2" remote-timeout="30000""> <store class="my.package.CustomCacheStore"> <!-- If custom properties are included these may be specified as below --> <property name="customStoreProperty">10</property> </store> </distributed-cache> [...] </subsystem>
18.9.2.2. Option 2: Add Custom Cache Store using the CLI (Remote Client-Server Mode)
Procedure 18.13. Deploying Custom Cache Store .jar file to JDG server using the CLI
- Connect to the JDG server by running the below command:
[$JDG_HOME] $ bin/cli.sh --connect=$IP:$PORT
- Deploy the .jar file by executing the following command:
deploy /path/to/artifact.jar
18.9.2.3. Option 3: Add Custom Cache Store using JON (Remote Client-Server Mode)
Procedure 18.14. Deploying Custom Cache Store .jar file to JDG server using JBoss Operation Network
- Log into JON.
- Navigate to
Bundles
along the upper bar. - Click the
New
button and choose theRecipe
radio button. - Insert a deployment bundle file content that references the store, similar to the following example:
<?xml version="1.0"?> <project name="cc-bundle" default="main" xmlns:rhq="antlib:org.rhq.bundle"> <rhq:bundle name="Mongo DB Custom Cache Store" version="1.0" description="Custom Cache Store"> <rhq:deployment-unit name="JDG" compliance="full"> <rhq:file name="custom-store.jar"/> </rhq:deployment-unit> </rhq:bundle> <target name="main" /> </project>
- Proceed with
Next
button toBundle Groups
configuration wizard page and proceed withNext
button once again. - Locate custom cache store
.jar
file using file uploader andUpload
the file. - Proceed with
Next
button toSummary
configuration wizard page. Proceed withFinish
button in order to finish bundle configuration. - Navigate back to the
Bundles
tab along the upper bar. - Select the newly created bundle and click
Deploy
button. - Enter
Destination Name
and choose the proper Resource Group; this group should only consist of JDG servers. - Choose
Install Directory
fromBase Location
's radio box group. - Enter
/standalone/deployments
inDeployment Directory
text field below. - Proceed with the wizard using the default options.
- Validate the deployment using the following command on the server's host:
find $JDG_HOME -name "custom-store.jar"
- Confirm the bundle has been installed in
$JDG_HOME/standalone/deployments
.
18.9.3. 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>
Note
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 name="customCache"/> <!-- Additional configuration elements here --> <file-store passivation="true" <!-- Additional configuration elements here --> /> <!-- Additional configuration elements here --> </local-cache>
passivation
parameter to the persistence
element to toggle passivation:
Example 19.2. Toggle Passivation in Library Mode
<persistence passivation="true"> <!-- Additional configuration elements here --> </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 and Disadvantages
The primary advantage of the Write-Through mode is that the cache and cache store are updated simultaneously, which ensures that the cache store remains consistent with the cache contents.
Due to the cache store being updated simultaneously with the cache entry, there is a possibility of reduced performance for cache operations that occur concurrently with the cache store accesses and updates.
20.1.2. Write-Through Caching Configuration (Library Mode)
Procedure 20.1. Configure a Write-Through Local File Cache Store
<?xml version="1.0" encoding="UTF-8"?> <infinispan xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:infinispan:config:6.2"> <global /> <default /> <namedCache name="persistentCache"> <persistence> <singleFile fetchPersistentState="true" ignoreModifications="false" purgeOnStartup="false" shared="false" location="${java.io.tmpdir}"/> </persistence> </namedCache> </infinispan>
- The
name
parameter specifies the name of thenamedCache
to use. - The
fetchPersistentState
parameter determines whether the persistent state is fetched when joining a cluster. Set this totrue
if using a replication and invalidation in a clustered environment. Additionally, if multiple cache stores are chained, only one cache store can have this property enabled. If a shared cache store is used, the cache does not allow a persistent state transfer despite this property being set totrue
. ThefetchPersistentState
parameter isfalse
by default. - The
ignoreModifications
parameter determines whether operations that modify the cache (e.g. put, remove, clear, store, etc.) do not affect the cache store. As a result, the cache store can become out of sync with the cache. - The
purgeOnStartup
parameter specifies whether the cache is purged when initially started. - The
shared
parameter is used when multiple cache instances share a cache store and is now defined at the cache store level. This parameter can be set to prevent multiple cache instances writing the same modification multiple times. Valid values for this parameter aretrue
andfalse
.
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
<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>
write-behind
element uses the following configuration parameters:
- The
modification-queue-size
parameter sets the modification queue size for the asynchronous store. If updates occur faster than the cache store can process the queue, the asynchronous store behaves like a synchronous store. The store behavior remains synchronous and blocks elements until the queue is able to accept them, after which the store behavior becomes asynchronous again. - The
shutdown-timeout
parameter specifies the time in milliseconds after which the cache store is shut down. When the store is stopped some modifications may still need to be applied. Setting a large timeout value will reduce the chance of data loss. The default value for this parameter is25000
. - The
flush-lock-timeout
parameter specifies the time (in milliseconds) to acquire the lock that guards the state to be periodically flushed. The default value for this parameter is15000
. - The
thread-pool-size
parameter specifies the size of the thread pool. The threads in this thread pool apply modifications to the cache store. The default value for this parameter is5
.
20.2.3. Unscheduled Write-Behind Strategy Configuration (Library Mode)
async
element to the store configuration as follows:
Procedure 20.3. The async
Element
<persistence> <singleFile location="${LOCATION}"> <async enabled="true" modificationQueueSize="1024" shutdownTimeout="25000" flushLockTimeout="15000" threadPoolSize="5"/> </singleFile> </persistence>
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. - 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
. - 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
. - The
threadPoolSize
parameter specifies the number of threads that concurrently apply modifications to the store. The default value for this parameter is5
.
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 = new ConfigurationBuilder().jmxStatistics().enable().build();
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 = new GlobalConfigurationBuilder()..globalJmxStatistics().enable().build();
21.6. Disabling the CacheStore via JMX When Using Rolling Upgrades
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 = new GlobalConfigurationBuilder().globalJmxStatistics().enable(). cacheManagerName("Hibernate2LC").build();
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
MBeans
are available under two JMX domains:
- jboss.as - these
MBeans
are created by the server subsystem. - jboss.infinispan - these
MBeans
are symmetric to those created by embedded mode.
MBeans
under jboss.infinispan should be used for Red Hat JBoss Data Grid, as the ones under jboss.as are for Red Hat JBoss Enterprise Application Platform.
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 = new GlobalConfigurationBuilder().globalJmxStatistics().enable(). mBeanServerLookup("com.acme.MyMBeanServerLookup").build();
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.
- In the section labeled JBoss Development and Management, click .
- Enter the relevant credentials in the Red Hat Login and Password fields and click .
- Select the appropriate version in the Version drop down menu list.
- Click thebutton 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.
- Clickin the menu across the top of the page.
- Clickin the list under
JBoss Development and Management
. - 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 Data Grid
from either the Product drop-down box, or the menu on the left.- Click the
Red Hat JBoss Operations Network VERSION Base Distribution
button. - Repeat the steps to download the
Data Grid Management 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 31, 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.6.4. Create a New Cache Using JBoss Operations Network (JON)
Procedure 22.3. Creating a new cache in Remote Client-Server mode
- Log into the JBoss Operations Network Console.
- From from the JBoss Operations Network console, click.
- Selectfrom the list on the left of the console.
- Select the specific Red Hat JBoss Data Grid server from the servers list.
- Below the server name, clickand then .
- Select the desired cache container that will be parent for the newly created cache.
- Right-click the selected cache container. For example,.
- In the context menu, navigate toand select .
- Create a new cache in the resource create wizard.
- Enter the new cache name and click.
- Set the cache attributes in the Deployment Options and click.
Note
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.4. Install JBoss Operations Network Library Mode Plug-in
Open the JBoss Operations Network Console
- From the JBoss Operations Network console, select.
- Selectfrom the options on the left side of the console.
Figure 22.1. JBoss Operations Network Console for JBoss Data Grid
Upload the Library Mode Plug-in
- Click, locate the
InfinispanPlugin
on your local file system. - Clickto add the plug-in to the JBoss Operations Network Server.
Figure 22.2. Upload the
InfinispanPlugin
.Scan for Updates
- Once the file has successfully uploaded, clickat the bottom of the screen.
- The
InfinispanPlugin
will now appear in the list of installed plug-ins.
Figure 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
Procedure 22.5. Add JBoss Data Grid Instances in Library Mode
Import the Platform
- Navigate to theand select from the list on the left of the console.
- Select the platform on which the application is running and clickat the bottom of the screen.
Figure 22.4. Import the Platform from the
.Access the Servers on the Platform
- The
jdg
Platform now appears in the Platforms list. - Click on the Platform to access the servers that are running on it.
Figure 22.5. Open the
jdg
Platform to view the list of servers.Import the JMX Server
- From thetab, select .
- Click thebutton at the bottom of the screen and select the option from the list.
Figure 22.6. Import the JMX Server
Enable JDK Connection Settings
- In thewindow, specify from the list of options.
Figure 22.7. Select the JDK 5 Template.
Modify the Connector Address
- In themenu, modify the supplied with the hostname and JMX port of the process containing the Infinispan Library.
- 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 theand information if required.
- Click.
Figure 22.8. Modify the values in the Deployment Options screen.
View Cache Statistics and Operations
- Clickto refresh the list of servers.
- Thetree in the panel on the left side of the screen contains the node, which contains the available cache managers. The available cache managers contain the available caches.
- Select a cache from the available caches to view metrics.
- Select thetab.
- Theview shows statistics and metrics.
- Thetab provides access to the various operations that can be performed on the services.
Figure 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.6. 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.7. 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
22.9. Other Management Tools and Operations
22.9.1. Accessing Data via URLs
put()
and post()
methods place data in the cache, and the URL used determines the cache name and key(s) used. The data is the value placed into the cache, and is placed in the body of the request.
GET
and HEAD
methods are used for data retrieval while other headers control cache settings and behavior.
Note
22.9.2. Limitations of Map Methods
size()
, values()
, keySet()
and entrySet()
, can be used with certain limitations with Red Hat JBoss Data Grid as they are unreliable. These methods do not acquire locks (global or local) and concurrent modification, additions and removals are excluded from consideration in these calls.
From Red Hat JBoss Data Grid 6.3 onwards, the map methods size()
, values()
, keySet()
, and entrySet()
include entries in the cache loader by default whereas previously these methods only included the local data container. The underlying cache loader directly affects the performance of these commands. As an example, when using a database, these methods run a complete scan of the table where data is stored which can result in slower processing. Use Cache.getAdvancedCache().withFlags(Flag.SKIP_CACHE_LOAD).values()
to maintain the old behavior and not loading from the cache loader which would avoid the slower performance.
In JBoss Data Grid 6.3 the Cache#size()
method returned only the number of entries on the local node, ignoring other nodes for clustered caches and including any expired entries. While the default behavior was not changed in JBoss Data Grid 6.4 or later, accurate results can be enabled for bulk operations, including size()
, by setting the infinispan.accurate.bulk.ops
system property to true. In this mode of operation, the result returned by the size()
method is affected by the flags org.infinispan.context.Flag#CACHE_MODE_LOCAL
, to force it to return the number of entries present on the local node, and org.infinispan.context.Flag#SKIP_CACHE_LOAD
, to ignore any passivated entries.
In JBoss Data Grid 6.3, the Hot Rod size()
method obtained the size of a cache by invoking the STATS
operation and using the returned numberOfEntries
statistic. This statistic is not an accurate measurement of the number of entries in a cache because it does not take into account expired and passivated entries and it is only local to the node that responded to the operation. As an additional result, when security was enabled, the client would need the ADMIN
permission instead of the more appropriate BULK_READ
.
SIZE
operation, and the clients have been updated to use this operation for the size()
method. The JBoss Data Grid server will need to be started with the infinispan.accurate.bulk.ops
system property set to true
so that size can be computed accurately.
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
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.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 displays the 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="dist"> <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}"> <!-- Additional configuration information here --> </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)
<namedCache <!-- Additional configuration information here -->> <transaction <!-- Additional configuration information here --> > <locking <!-- Additional configuration information here --> > <versioning enabled="{true,false}" versioningScheme="{NONE|SIMPLE}"/> <!-- Additional configuration information here --> </namedCache>
- Set the
versioning
parameter'senabled
parameter totrue
. - Set the
versioningScheme
parameter to eitherNONE
orSIMPLE
to set the versioning scheme used.
Procedure 25.2. Configure Transactions in Library Mode (Programmatic Configuration)
Configuration config = new ConfigurationBuilder()/* ... */.transaction() .transactionMode(TransactionMode.TRANSACTIONAL) .transactionManagerLookup(new GenericTransactionManagerLookup()) .lockingMode(LockingMode.OPTIMISTIC) .useSynchronization(true) .recovery() .recoveryInfoCacheName("anotherRecoveryCacheName").build();
- Set the transaction mode.
- Select and set a lookup class. See the table below this procedure for a list of available lookup classes.
- The
lockingMode
value determines whether optimistic or pessimistic locking is used. If the cache is non-transactional, the locking mode is ignored. The default value isOPTIMISTIC
. - The
useSynchronization
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). - The
recovery
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
.
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> <!-- Additional configuration elements here --> <transaction mode="NONE" /> <!-- Additional configuration elements here --> </cache>
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 nece