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:
| 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:
| 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:
| Field | Data Type | Details |
|---|---|---|
| Header | Variable | Request header |
The response header for this operation contains the following:
| 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:
| 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:
| 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:
| Field | Data Type | Details |
|---|---|---|
| Header | variable | Request header. |
| Scope | vInt |
|
The response header for this operation contains one of the following response statuses:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| Field | Data Type | Details |
|---|---|---|
| iterationId | String | The unique id of the iteration. |
The following are the valid response values returned from this operation:
| 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:
| Field | Data Type | Details |
|---|---|---|
| IterationId | String | The unique id of the iteration. |
The response header for this operation contains the following:
| 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:
| 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 setMore 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:
| 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:
| Response Status | Details |
|---|---|
| 0x00 | Successful ping without any errors. |
11.2.16. Hot Rod Put Operation
The
put operation request format includes the following:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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
0and the response status0x02to 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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.
| 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:
| 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:
| 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:
| 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:
| Field | Data Type | Details |
|---|---|---|
| Header | variable | Request header |
The response header for this operation contains the following:
| 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. |
