Listeners

Listeners are used to monitor events corresponding to changes in a table.

Using listeners you can either monitor the contents of a specific table or a subset of rows in a specific table.

For example, your application could track the table containing customer data. Specifically, track the activity in a particular geographic region; to know when new customers are added or deleted, or when customers move to another region.

An event indicates that the data in a table has changed.

An event is of type:
  • PUT: Indicates new data has been added to the table.

    PUT events have a current value which is a copy of the row that was PUT into the table. If the PUT operation replaces an existing row, the event additionally has a previous value, which is a copy of the row prior to 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 prior to the DELETE operation.
  • ERROR: Indicates that something has happened in the system that means the flow of events are disrupted. ERROR events have an error code and an error description. The application should destroy the table listener. Depending on the error code, it might or might not make sense for the application to recreate 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, if the expired rows match the 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.