Table Listener
A table listener is used to monitor events corresponding to changes in a table. A table listener is created from a specific table.
When you use a table listener, you can either monitor the contents of a specified table or a subset of rows in a specific table. For example, by using a filter, your application can track a table containing customer data and more specifically, can track the activity in a particular region to know when new customers are added or deleted, or when customers move to another region.
Events
An event indicates that the data in a table has changed.
- PUT: Indicates that new data has been added to the table.
PUT events have a current value, which is a copy of the row that was added to the table. If the PUT operation replaces an existing row, the event additionally has a previous value, which is a copy of the row before the PUT operation.
- DELETE: Indicates that a row has been deleted from the table. DELETE events have a previous value, which is a copy of the row before the DELETE operation.
- ERROR: Indicates that something has happened in the system that indicates that the flow of events are disrupted. ERROR events have an error code and an error description. The application must destroy the table listener. Depending on the error code, it might or might not make sense for the application to re-create the table listener. The ActiveSpaces API documentation provides more details on the specific error codes that are possible.
- EXPIRED: Indicates that a row has expired. When rows are removed from a table due to expiration, table listeners on the table receive EXPIRED events when the expired rows match the table listeners’ filters.
When creating a table listener, you must specify the table that is the source of the events of interest and a callback function that is invoked when events are delivered to the application. The callback function executes in a thread that is internal to the ActiveSpaces client library and is expected to complete in a timely fashion. The client library retains ownership of the events and the rows they contain so any data that is required outside of the callback must be copied and managed by the application itself.