11.2. Hot Rod Operations

The following are valid operations when using Hot Rod protocol 1.3 to interact with Red Hat JBoss Data Grid:
  • Authenticate
  • AuthMechList
  • BulkGet
  • BulkKeysGet
  • Clear
  • ContainsKey
  • Exec
  • Get
  • GetAll
  • GetWithMetadata
  • GetWithVersion
  • IterationEnd
  • IterationNext
  • IterationStart
  • Ping
  • Put
  • PutAll
  • PutIfAbsent
  • Query
  • Remove
  • RemoveIfUnmodified
  • Replace
  • ReplaceIfUnmodified
  • Stats
  • Size

Important

When using the RemoteCache API to call the Hot Rod client's 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.

11.2.1. Hot Rod Authenticate Operation

The purpose of this operation is to authenticate a client against a server using SASL. The authentication process, depending on the chosen mech, might be a multi-step operation. Once complete the connection becomes authenticated.
The Authenticate operation request format includes the following:

Table 11.7. Authenticate Operation Request Format

Field Data Type Details
Header variable Request header.
Mech String String containing the name of the mech chosen by the client for authentication. Empty on the successive invocations.
Response length vInt Length of the SASL client response.
Response data byte array The SASL client response.
The response header for this operation contains the following:

Table 11.8. Authenticate Operation Response Format

Field Data Type Details
Header variable Response header.
Completed byte 0 if further processing is needed, or 1 if authentication is complete.
Challenge length vInt Length of the SASL server challenge.
Challenge data byte array The SASL server challenge.

11.2.2. Hot Rod AuthMechList Operation

The purpose of this operation is to obtain the list of valid SASL authentication mechs supported by the server. The client will then need to issue an Authenticate request with the preferred mech.
The AuthMechList operation request format includes the following:

Table 11.9. AuthMechList Operation Request Format

Field Data Type Details
Header Variable Request header
The response header for this operation contains the following:

Table 11.10. AuthMechList Operation Response Format

Field Data Type Details
Header Variable Response header
Mech count vInt The number of mechs.
Mech String String containing the name of the SASL mech in its IANA-registered form (e.g. GSSAPI, CRAM-MD5, etc)
The Mech value recurs for each supported mech.

11.2.3. Hot Rod BulkGet Operation

A Hot Rod BulkGet operation uses the following request format:

Table 11.11. BulkGet Operation Request Format

Field Data Type Details
Header variable Request 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.
The response header for this operation contains one of the following response statuses:

Table 11.12. BulkGet Operation Response Format

Field Data Type Details
Header variable Response 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 Length vInt Contains the length of the key.
Key byte array Contains the key value.
Value Length vInt Contains the length of the value.
Value byte array Contains the value.
For each entry that was requested, a More, Key Size, Key, Value Size and Value entry is appended to the response.

11.2.4. Hot Rod BulkKeysGet Operation

A Hot Rod BulkKeysGet operation uses the following request format:

Table 11.13. BulkKeysGet Operation Request Format

Field Data Type Details
Header variable Request header.
Scope vInt
  • 0 = Default Scope - This scope is used by RemoteCache.keySet() method. If the remote cache is a distributed cache, the server launches a map/reduce operation to retrieve all keys from all of the nodes (A topology-aware Hot Rod Client could be load balancing the request to any one node in the cluster). Otherwise, it will get keys from the cache instance local to the server receiving the request, as the keys must be the same across all nodes in a replicated cache.
  • 1 = Global Scope - This scope behaves the same to Default Scope.
  • 2 = Local Scope - In situations where the remote cache is a distributed cache, the server will not launch a map/reduce operation to retrieve keys from all nodes. Instead, it will only get keys local from the cache instance local to the server receiving the request.
The response header for this operation contains one of the following response statuses:

Table 11.14. 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 Length vInt Length of key
Key byte array Retrieved key.
More 1 byte One byte representing whether more entries need to be read from the stream. So, when it’s set to 1, it means that an entry follows, whereas when it’s set to 0, it’s the end of stream and no more entries are left to read.
The values Key Length and Key recur for each key.

11.2.5. Hot Rod Clear Operation

The clear operation format includes only a header.
Valid response statuses for this operation are as follows:

Table 11.15. Clear Operation Response

Response Status Details
0x00 Red Hat JBoss Data Grid was successfully cleared.

11.2.6. Hot Rod ContainsKey Operation

A Hot Rod ContainsKey operation uses the following request format:

Table 11.16. 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.
The response header for this operation contains one of the following response statuses:

Table 11.17. ContainsKey Operation Response Format

Response Status Details
0x00 Successful operation.
0x02 The key does not exist.
The response for this operation is empty.

11.2.7. Hot Rod Exec Operation

The Exec operation request format includes the following:

Table 11.18. Exec Operation Request Format

Field Data Type Details
Header variable Request header.
Script String Name of the script to execute.
Parameter Count vInt The number of parameters.
Parameter Name (per parameter) String The name of the parameter.
Parameter Length (per parameter) vInt The length of the parameter.
Parameter Value (per parameter) byte array The value of the parameter.
The response header for this operation contains the following:

Table 11.19. Exec Operation Response Format

Field Data Type Details
Header variable Response header.
Response status 1 byte 0x00 if the execution completed successfully. 0x85 if the server resulted in an error.
Value Length vInt If success, length of return value.
Value byte array If success, the result of the execution.

11.2.8. Hot Rod Get Operation

A Hot Rod Get operation uses the following request format:

Table 11.20. Get Operation Request Format

Field Data Type Details
Header Variable Request 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.
The response header for this operation contains one of the following response statuses:

Table 11.21. Get Operation Response Format

Response Status Details
0x00 Successful operation.
0x02 The key does not exist.
The format of the get operation's response when the key is found is as follows:

Table 11.22. Get Operation Response Format

Field Data Type Details
Header Variable Response Header
Value Length vInt Contains the length of the value.
Value Byte array Contains the requested value.

11.2.9. Hot Rod GetAll Operation

Bulk operation to get all entries that map to a given set of keys.
A Hot Rod GetAll operation uses the following request format:

Table 11.23. GetAll Operation Request Format

Field Data Type Details
Header variable Request header
Key Count vInt How many keys to find entities for.
Key Length vInt Length of key.
Key byte array Retrieved key.
The Key Length and Key values recur for each key.
The response header for this operation contains the following:

Table 11.24. GetAll Operation Response Format

Field Data Type Details
Header variable Response header
Entry count vInt How many entries are being returned.
Key Length vInt Length of key.
Key byte array Retrieved key.
Value Length vInt Length of value.
Value byte array Retrieved value.
The Key Length, Key, Value Length, and Value entries recur per key and value.

11.2.10. Hot Rod GetWithMetadata Operation

A Hot Rod GetWithMetadata operation uses the following request format:

Table 11.25. 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.
The response header for this operation contains one of the following response statuses:

Table 11.26. 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.

11.2.11. Hot Rod GetWithVersion Operation

A Hot Rod GetWithVersion operation uses the following request format:

Table 11.27. GetWithVersion Operation Request Format

Field Data Type Details
Header Variable Request 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.
The response header for this operation contains one of the following response statuses:

Table 11.28. GetWithVersion Operation Response Format

Response Status Details
0x00 Successful operation.
0x02 The key does not exist.
The format of the GetWithVersion operation's response when the key is found is as follows:

Table 11.29. GetWithVersion Operation Response Format

Field Data Type Details
Header variable Response header
Entry Version 8 bytes Unique value of an existing entry’s modification. The protocol does not mandate that entry_version values are sequential. They just need to be unique per update at the key level.
Value Length vInt Contains the length of the value.
Value Byte array Contains the requested value.

11.2.12. Hot Rod IterationEnd Operation

The IterationEnd operation request format includes the following:

Table 11.30. IterationEnd Operation Request Format

Field Data Type Details
iterationId String The unique id of the iteration.
The following are the valid response values returned from this operation:

Table 11.31. IterationEnd Operation Response Format

Response Status Details
0x00 Successful operation.
0x05 Error for non existent iterationId.

11.2.13. Hot Rod IterationNext Operation

The IterationNext operation request format includes the following:

Table 11.32. IterationNext Operation Request Format

Field Data Type Details
IterationId String The unique id of the iteration.
The response header for this operation contains the following:

Table 11.33. IterationNext Operation Response Format

Field Data Type Details
Finished segments size vInt Size of the bitset representing segments that were finished iterating.
Finished segments byte array Bitset encoding of the segments that were finished iterating.
Entry count vInt How many entries are being returned.
Number of value projections vInt Number of projections for the values.
Metadata 1 byte If set, entry has metadata associated.
Expiration 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). Only present if the metadata flag above is set.
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’s modification. Only present if Metadata flag is set.
Key Length vInt Length of key.
Key byte array Retrieved key.
Value Length vInt Length of value.
Value byte array Retrieved value.
For each entry the Metadata, Expiration, Created, Lifespan, LastUsed, MaxIdle, Entry Version, Key Length, Key, Value Length, and Value fields recur.

11.2.14. Hot Rod IterationStart Operation

The IterationStart operation request format includes the following:

Table 11.34. IterationStart Operation Request Format

Field Data Type Details
Segments size signed vInt Size of the bitset encoding of the segments ids to iterate on. The size is the maximum segment id rounded to nearest multiple of 8. A value -1 indicates no segment filtering is to be done
Segments byte array (Optional) Contains the segments ids bitset encoded, where each bit with value 1 represents a segment in the set. Byte order is little-endian. Example: segments [1,3,12,13] would result in the following encoding:
00001010 00110000
size: 16 bits
first byte: represents segments from 0 to 7, from which 1 and 3 are set
second byte: represents segments from 8 to 15, from which 12 and 13 are set
More details in the java.util.BitSet implementation. Segments will be sent if the previous field is not negative
FilterConverter size signed vInt The size of the String representing a KeyValueFilterConverter factory name deployed on the server, or -1 if no filter will be used.
FilterConverter UTF-8 byte array (Optional) KeyValueFilterConverter factory name deployed on the server. Present if previous field is not negative.
Parameters size byte The number of parameters of the filter. Only present when FilterConverter is provided.
Parameters byte[][] An array of parameters. Each parameter is a byte array. Only present if Parameters size is greater than 0.
BatchSize vInt Number of entries to transfers from the server at one go.
Metadata 1 byte 1 if metadata is to be returned for each entry, 0 otherwise.
The response header for this operation contains the following:

Table 11.35. IterationEnd Operation Response Format

Field Data Type Details
IterationId String The unique id of the iteration.

11.2.15. Hot Rod Ping Operation

The ping is an application level request to check for server availability.
Valid response statuses for this operation are as follows:

Table 11.36. Ping Operation Response

Response Status Details
0x00 Successful ping without any errors.

11.2.16. Hot Rod Put Operation

The put operation request format includes the following:

Table 11.37. 

Field Data Type Details
Header variable Request header.
Key Length - Contains the length of the key.
Key Byte array Contains the key value.
TimeUnits Byte Time units of lifespan (first 4 bits) and maxIdle (last 4 bits). Special units DEFAULT and INFINITE can be used for default server expiration and no expiration respectively. Possible values:
0x00 = SECONDS
0x01 = MILLISECONDS
0x02 = NANOSECONDS
0x03 = MICROSECONDS
0x04 = MINUTES
0x05 = HOURS
0x06 = DAYS
0x07 = DEFAULT
0x08 = INFINITE
Lifespan vInt Duration which the entry is allowed to life. Only sent when time unit is not DEFAULT or INFINITE
Max Idle vInt Duration that each entry can be idle before it’s evicted from the cache. Only sent when time unit is not DEFAULT or INFINITE.
Value Length vInt Contains the length of the value.
Value Byte array The requested value.
The following are the valid response values returned from this operation:

Table 11.38. 

Response Status Details
0x00 The value was successfully stored.
0x03 The value was successfully stored, and the previous value follows.
An empty response is the default response for this operation. However, if 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.

11.2.17. Hot Rod PutAll Operation

Bulk operation to put all key value entries into the cache at the same time.
The PutAll operation request format includes the following:

Table 11.39. PutAll Operation Request Format

Field Data Type Details
Header variable Request header.
TimeUnits Byte Time units of lifespan (first 4 bits) and maxIdle (last 4 bits). Special units DEFAULT and INFINITE can be used for default server expiration and no expiration respectively. Possible values:
0x00 = SECONDS
0x01 = MILLISECONDS
0x02 = NANOSECONDS
0x03 = MICROSECONDS
0x04 = MINUTES
0x05 = HOURS
0x06 = DAYS
0x07 = DEFAULT
0x08 = INFINITE
Lifespan vInt Duration which the entry is allowed to life. Only sent when time unit is not DEFAULT or INFINITE
Max Idle vInt Duration that each entry can be idle before it’s evicted from the cache. Only sent when time unit is not DEFAULT or INFINITE.
Entry count vInt How many entries are being inserted.
Key Length vInt Length of key.
Key byte array Retrieved key.
Value Length vInt Length of value.
Value byte array Retrieved value.
The Key Length, Key, Value Length, and Value fields repeat for each entry that will be placed.
The response header for this operation contains one of the following response statuses:

Table 11.40. PutAll Operation Response Format

Response Status Details
0x00 Successful operation, indicating all keys were successfully put.

11.2.18. Hot Rod PutIfAbsent Operation

The putIfAbsent operation request format includes the following:

Table 11.41. PutIfAbsent Operation Request Fields

Field Data Type Details
Header variable Request header.
Key Length vInt Contains the length of the key.
Key Byte array Contains the key value.
TimeUnits Byte Time units of lifespan (first 4 bits) and maxIdle (last 4 bits). Special units DEFAULT and INFINITE can be used for default server expiration and no expiration respectively. Possible values:
0x00 = SECONDS
0x01 = MILLISECONDS
0x02 = NANOSECONDS
0x03 = MICROSECONDS
0x04 = MINUTES
0x05 = HOURS
0x06 = DAYS
0x07 = DEFAULT
0x08 = INFINITE
Lifespan vInt Duration which the entry is allowed to life. Only sent when time unit is not DEFAULT or INFINITE
Max Idle vInt Duration that each entry can be idle before it’s evicted from the cache. Only sent when time unit is not DEFAULT or INFINITE.
Value Length vInt Contains the length of the value.
Value Byte array Contains the requested value.
The following are the valid response values returned from this operation:

Table 11.42. 

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.
0x04 The operation failed because the key was present and its value follows in the response.
An empty response is the default response for this operation. However, if 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.

11.2.19. Hot Rod Query Operation

The Query operation request format includes the following:

Table 11.43. 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.
The following are the valid response values returned from this operation:

Table 11.44. 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.

11.2.20. Hot Rod Remove Operation

A Hot Rod Remove operation uses the following request format:

Table 11.45. Remove Operation Request Format

Field Data Type Details
Header variable Request 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.
The response header for this operation contains one of the following response statuses:

Table 11.46. Remove Operation Response Format

Response Status Details
0x00 Successful operation.
0x02 The key does not exist.
0x03 The key was removed, and the previous or removed value follows in the response.
Normally, the response header for this operation is empty. However, if ForceReturnPreviousValue is passed, the response header contains either:
  • The value and length of the previous key.
  • The value length 0 and the response status 0x02 to indicate that the key does not exist.
The remove operation's response header contains the previous value and the length of the previous value for the provided key if ForceReturnPreviousValue is passed. If the key does not exist or the previous value was null, the value length is 0.

11.2.21. Hot Rod RemoveIfUnmodified Operation

The RemoveIfUnmodified operation request format includes the following:

Table 11.47. RemoveIfUnmodified Operation Request Fields

Field Data Type Details
Header variable Request 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.
The following are the valid response values returned from this operation:

Table 11.48. RemoveIfUnmodified Operation Response

Response Status Details
0x00 The entry was replaced or removed.
0x01 The entry replace or remove was unsuccessful because the key was modified.
0x02 The key does not exist.
0x03 The key was removed, and the previous or replaced value follows in the response.
0x04 The entry remove was unsuccessful because the key was modified, and the modified value follows in the response.
An empty response is the default response for this operation. However, if 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.

11.2.22. Hot Rod Replace Operation

The replace operation request format includes the following:

Table 11.49. Replace Operation Request Fields

Field Data Type Details
Header variable Request header.
Key Length vInt Contains the length of the key.
Key Byte array Contains the key value.
TimeUnits Byte Time units of lifespan (first 4 bits) and maxIdle (last 4 bits). Special units DEFAULT and INFINITE can be used for default server expiration and no expiration respectively. Possible values:
0x00 = SECONDS
0x01 = MILLISECONDS
0x02 = NANOSECONDS
0x03 = MICROSECONDS
0x04 = MINUTES
0x05 = HOURS
0x06 = DAYS
0x07 = DEFAULT
0x08 = INFINITE
Lifespan vInt Duration which the entry is allowed to life. Only sent when time unit is not DEFAULT or INFINITE
Max Idle vInt Duration that each entry can be idle before it’s evicted from the cache. Only sent when time unit is not DEFAULT or INFINITE.
Value Length vInt Contains the length of the value.
Value Byte array Contains the requested value.
The following are the valid response values returned from this operation:

Table 11.50. Replace Operation Response

Response Status Details
0x00 The value was successfully stored.
0x01 The value was not stored because the key does not exist.
0x03 The value was successfully replaced, and the previous or replaced value follows in the response.
An empty response is the default response for this operation. However, if 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.

11.2.23. Hot Rod ReplaceIfUnmodified Operation

The ReplaceIfUnmodified operation request format includes the following:

Table 11.51. ReplaceIfUnmodified 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 5 bytes which in theory can produce bigger numbers than Integer.MAX_VALUE. However, Java cannot create a single array that’s bigger than Integer.MAX_VALUE, hence the protocol is limiting vint array lengths to Integer.MAX_VALUE.
Key byte array Byte array containing the key whose value is being requested.
TimeUnits Byte Time units of lifespan (first 4 bits) and maxIdle (last 4 bits). Special units DEFAULT and INFINITE can be used for default server expiration and no expiration respectively. Possible values:
0x00 = SECONDS
0x01 = MILLISECONDS
0x02 = NANOSECONDS
0x03 = MICROSECONDS
0x04 = MINUTES
0x05 = HOURS
0x06 = DAYS
0x07 = DEFAULT
0x08 = INFINITE
Lifespan vInt Duration which the entry is allowed to life. Only sent when time unit is not DEFAULT or INFINITE
Max Idle vInt Duration that each entry can be idle before it’s evicted from the cache. Only sent when time unit is not DEFAULT or INFINITE.
Entry Version 8 bytes Use the value returned by GetWithVersion operation.
Value Length vInt Length of value.
Value byte array Value to be stored.
The response header for this operation contains one of the following response statuses:

Table 11.52. ReplaceIfUnmodified Operation Response Status

Response Status Details
0x00 The value was successfully stored.
0x01 Replace did not happen because key had been modified.
0x02 Replace did not happen because key does not exist.
0x03 The key was replaced, and the previous or replaced value follows in the response.
0x04 The entry replace was unsuccessful because the key was modified, and the modified value follows in the response.
The following are the valid response values returned from this operation:

Table 11.53. ReplaceIfUnmodified Operation Response Format

Field Data Type Details
Header variable Response header.
Previous value length vInt If force return previous value flag was sent in the request, the length of the previous value will be returned. If the key does not exist, value length would be 0. If no flag was sent, no value length would be present.
Previous value byte array If force return previous value flag was sent in the request and the key was replaced, previous value.

11.2.24. Hot Rod ReplaceWithVersion Operation

The ReplaceWithVersion operation request format includes the following:

Note

In the RemoteCache API, the Hot Rod ReplaceWithVersion operation uses the ReplaceIfUnmodified operation. As a result, these two operations are exactly the same in JBoss Data Grid.

Table 11.54. 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.
The following are the valid response values returned from this operation:

Table 11.55. 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.
An empty response is the default response for this operation. However, if 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.

11.2.25. Hot Rod Stats Operation

This operation returns a summary of all available statistics. For each returned statistic, a name and value is returned in both string and UTF-8 formats.
The following are supported statistics for this operation:

Table 11.56. 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.
globalCurrentNumberOfEntries Number of entries currently across the Hot Rod cluster.
globalStores Total number of put operations across the Hot Rod cluster.
globalRetrievals Total number of get operations across the Hot Rod cluster.
globalHits Total number of get hits across the Hot Rod cluster.
globalMisses Total number of get misses across the Hot Rod cluster.
globalRemoveHits Total number of removal hits across the Hot Rod cluster.
globalRemoveMisses Total number of removal misses across the Hot Rod cluster.

Note

Any of the statistics beginning with global are not available if Hot Rod is running in local mode.
The response header for this operation contains the following:

Table 11.57. Stats Operation Response

Name Data Type Details
Header variable Response 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.
The values Name Length, Name, Value Length and Value recur for each statistic requested.

11.2.26. Hot Rod Size Operation

The Size operation request format includes the following:

Table 11.58. Size Operation Request Format

Field Data Type Details
Header variable Request header
The response header for this operation contains the following:

Table 11.59. Size Operation Response Format

Field Data Type Details
Header variable Response header.
Size vInt Size of the remote cache, which is calculated globally in the clustered set ups, and if present, takes cache store contents into account as well.