11.4. Hot Rod Remote Events
Clients may register Remote Event Listeners, allowing them to receive updates on events happening in the server. As soon as a client listener has been added events are generated and sent, allowing the client to receive all events that have occurred after adding the listener.
11.4.1. Hot Rod Add Client Listener for Remote Events
Adding client listeners for remote events uses the following request format:
| Field | Data Type | Details |
|---|---|---|
| Header | variable | Request Header. |
| Listener ID | byte array | Listener identifier. |
| Include state | byte | When this byte is set to 1, cached state is sent back to remote clients when either adding a cache listener for the first time, or when the node where a remote listener is registered changes in a clustered environment. When enabled, state is sent back as cache entry created events to the clients. If set to 0, no state is sent back to the client when adding a listener, nor it gets state when the node where the listener is registered changes. |
| Key/value filter factory name | String | Optional name of the key/value filter factory to be used with this listener. The factory is used to create key/value filter instances which allow events to be filtered directly in the Hot Rod server, avoiding sending events that the client is not interested in. If no factory is to be used, the length of the string is 0. |
| Key/value filter factory parameter count | byte | The key/value filter factory, when creating a filter instance, can take an arbitrary number of parameters, enabling the factory to be used to create different filter instances dynamically. This count field indicates how many parameters will be passed to the factory. If no factory name was provided, this field is not present in the request. |
| Key/value filter factory parameter (per parameter) | byte array | Key/value filter factory parameter. |
| Converter factory name | String | Optional name of the converter factory to be used with this listener. The factory is used to transform the contents of the events sent to clients. By default, when no converter is in use, events are well defined, according to the type of event generated. However, there might be situations where users want to add extra information to the event, or they want to reduce the size of the events. In these cases, a converter can be used to transform the event contents. The given converter factory name produces converter instances to do this job. If no factory is to be used, the length of the string is 0. |
| Converter factory parameter count | byte | The converter factory, when creating a converter instance, can take an arbitrary number of parameters, enabling the factory to be used to create different converter instances dynamically. This count field indicates how many parameters will be passed to the factory. If no factory name was provided, this field is not present in the request. |
| Converter factory parameter (per parameter) | byte array | Converter factory parameter. |
| Use raw data | byte | If filter/converter parameters should be raw binary, then 1, otherwise 0. |
The format of the operation's response is as follows:
| Field | Data Type | Details |
|---|---|---|
| Header | Variable | Response Header. |
11.4.2. Hot Rod Remote Client Listener for Remote Events
Removing a previously added client listener uses the following request format:
| Field | Data Type | Details |
|---|---|---|
| Header | variable | Request Header. |
| Listener ID | byte array | Listener Identifier |
The format of the operation's response is as follows:
| Field | Data Type | Details |
|---|---|---|
| Header | Variable | Response Header. |
11.4.3. Hot Rod Event Header
Each remote event uses a header that adheres to the following format:
| Field Name | Size | Value |
|---|---|---|
| Magic | 1 byte | 0xA1 = response |
| Message ID | vLong | ID of event |
| Opcode | 1 byte | A code responding to the Event type:
0x60 = cache entry created event 0x61 = cache entry modified event 0x62 = cache entry removed event 0x50 = error |
| Status | 1 byte | Status of the response, with the following possible values:
0x00 = No error |
| Topology Change Marker | 1 byte | Since events are not associated with a particular incoming topology ID to be able to decide whether a new topology is required to be sent or not, new topologies will never be sent with events. Hence, this marker will always have 0 value for events. |
11.4.4. Hot Rod Cache Entry Created Event
The
CacheEntryCreated event includes the following:
| Field Name | Size | Value |
|---|---|---|
| Header | variable | Event header with 0x60 operation code. |
| Listener ID | byte array | Listener for which this event is directed |
| Custom Marker | byte | Custom event marker. For created events, this is 0. |
| Command Retried | byte | Marker for events that are result of retried commands. If command is retried, it returns 1, otherwise 0. |
| Key | byte array | Created key. |
| Version | long | Version of the created entry. This version information can be used to make conditional operations on this cache entry. |
11.4.5. Hot Rod Cache Entry Modified Event
The
CacheEntryModified event includes the following:
| Field Name | Size | Value |
|---|---|---|
| Header | variable | Event header with 0x61 operation code. |
| Listener ID | byte array | Listener for which this event is directed |
| Custom Marker | byte | Custom event marker. For created events, this is 0. |
| Command Retried | byte | Marker for events that are result of retried commands. If command is retried, it returns 1, otherwise 0. |
| Key | byte array | Modified key. |
| Version | long | Version of the modified entry. This version information can be used to make conditional operations on this cache entry. |
11.4.6. Hot Rod Cache Entry Removed Event
The
CacheEntryRemoved event includes the following:
| Field Name | Size | Value |
|---|---|---|
| Header | variable | Event header with 0x62 operation code. |
| Listener ID | byte array | Listener for which this event is directed |
| Custom Marker | byte | Custom event marker. For created events, this is 0. |
| Command Retried | byte | Marker for events that are result of retried commands. If command is retried, it returns 1, otherwise 0. |
| Key | byte array | Removed key. |
11.4.7. Hot Rod Custom Event
The
Custom event includes the following:
| Field Name | Size | Value |
|---|---|---|
| Header | variable | Event header with event specific operation code |
| Listener ID | byte array | Listener for which this event is directed |
| Custom Marker | byte | Custom event marker. For custom events whose event data needs to be unmarshalled before returning to user the value is 1. For custom events that need to return the event data as-is to the user, the value is 2. |
| Event Data | byte array | Custom event data. If the custom marker is 1, the bytes represent the marshalled version of the instance returned by the converter. If custom marker is 2, it represents the byte array, as returned by the converter. |
