Class: event
Asynchronous event registration and handling
Fields for class: event
| Field | Type | Qualifier | Description |
|---|---|---|---|
class |
string |
RO/constructor | The name of the class of the object that changed |
id |
int |
RO/constructor | An ID, monotonically increasing, and local to the current session |
obj_uuid |
string |
RO/constructor | Deprecated. The uuid of the object that changed |
operation |
event_operation |
RO/constructor | The operation that was performed |
ref |
string |
RO/constructor | A reference to the object that changed |
timestamp |
datetime |
RO/constructor | Deprecated. The time at which the event occurred |
| snapshot | object record | RO/runtime | The record of the database object that was added, changed or deleted |
RPCs associated with class: event
RPC name: from
Overview:
Blocking call which returns a new token and a (possibly empty) batch of events. The returned token can be used in subsequent calls to this function. It eliminates redundant events (for example, same field updated multiple times).
Signature:
event batch from (session ref session_ref, string set classes, string token, float timeout)
<!--NeedCopy-->
Arguments:
| Type | Name | Description |
|---|---|---|
session ref |
session_ref |
Reference to a valid session |
string set |
classes |
register for events for the indicated classes |
string |
token |
A token representing the point from which to generate database events. The empty string represents the beginning. |
float |
timeout |
Return after this many seconds if no events match |
Minimum Role: read-only
Return Type: event batch
a structure consisting of a token (‘token’), a map of valid references per object type (‘valid_ref_counts’), and a set of event records (‘events’).
Possible Error Codes: EVENT_FROM_TOKEN_PARSE_FAILURE, EVENT_SUBSCRIPTION_PARSE_FAILURE
RPC name: get_current_id
Overview:
Return the ID of the next event to be generated by the system
Signature:
int get_current_id (session ref session_ref)
<!--NeedCopy-->
Arguments:
| Type | Name | Description |
|---|---|---|
session ref |
session_ref |
Reference to a valid session |
Minimum Role: read-only
Return Type: int
the event ID
RPC name: inject
Overview:
Injects an artificial event on the given object and returns the corresponding ID in the form of a token, which can be used as a point of reference for database events. For example, to check whether an object has reached the right state before attempting an operation, one can inject an artificial event on the object and wait until the token returned by consecutive event.from calls is lexicographically greater than the one returned by event.inject.
Signature:
string inject (session ref session_ref, string class, string ref)
<!--NeedCopy-->
Arguments:
| Type | Name | Description |
|---|---|---|
session ref |
session_ref |
Reference to a valid session |
string |
class |
class of the object |
string |
ref |
A reference to the object that will be changed. |
Minimum Role: read-only
Return Type: string
the event ID in the form of a token
RPC name: next
This message is deprecated.
Overview:
Blocking call which returns a (possibly empty) batch of events. This method is only recommended for legacy use.It stores events in a buffer of limited size, raising EVENTS_LOST if too many events got generated. New development should use event.from which supersedes this method.
Signature:
event record set next (session ref session_ref)
<!--NeedCopy-->
Arguments:
| Type | Name | Description |
|---|---|---|
session ref |
session_ref |
Reference to a valid session |
Minimum Role: read-only
Return Type: event record set
A set of events
Possible Error Codes: SESSION_NOT_REGISTERED, EVENTS_LOST, EVENT_SUBSCRIPTION_PARSE_FAILURE
RPC name: register
This message is deprecated.
Overview:
Registers this session with the event system for a set of given classes. This method is only recommended for legacy use in conjunction with event.next.
Signature:
void register (session ref session_ref, string set classes)
<!--NeedCopy-->
Arguments:
| Type | Name | Description |
|---|---|---|
session ref |
session_ref |
Reference to a valid session |
string set |
classes |
the classes for which the session will register with the event system; specifying * as the desired class will register for all classes |
Minimum Role: read-only
Return Type: void
RPC name: unregister
This message is deprecated.
Overview:
Removes this session’s registration with the event system for a set of given classes. This method is only recommended for legacy use in conjunction with event.next.
Signature:
void unregister (session ref session_ref, string set classes)
<!--NeedCopy-->
Arguments:
| Type | Name | Description |
|---|---|---|
session ref |
session_ref |
Reference to a valid session |
string set |
classes |
the classes for which the session’s registration with the event system will be removed |
Minimum Role: read-only
Return Type: void