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.