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:

Table 11.66. Add Client Listener Operation 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:

Table 11.67. Add Client Listener Response Format

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:

Table 11.68. Remove Client Listener Operation 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:

Table 11.69. Add Client Listener Response Format

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:

Table 11.70. Remote Event Header

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:

Table 11.71. Cache Entry Created Event

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:

Table 11.72. Cache Entry Modified Event

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:

Table 11.73. Cache Entry Removed Event

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:

Table 11.74. Custom Event

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.