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.

An event can be of the following types:

  • PUT: Indicates that new data has been added to the table. PUT is also used to indicate that existing data in the table has been updated.

    PUT events have a current value, which is a copy of the row that was added to or updated in the table. If the PUT operation replaces an existing row, or the UPDATE operation modifies an existing row, the event additionally has a previous value. The previous value is a copy of the row before the PUT or UPDATE 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 is 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 runs 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 that they contain, so any data that is required outside of the callback must be copied and managed by the application itself.