Listeners

ActiveSpaces can proactively notify applications of changes to the tuples stored in a space. Users can invoke the metaspace or space’s listen method to obtain a listener on spaces for receiving event notifications.

There are five types of listeners.

PutListener

 The PutListener’s onPut method is invoked whenever a SpaceEntry is inserted, updated, or overwritten in the space.

TakeListener

 The PutListener’s onTake method is invoked whenever a SpaceEntry is removed from the space.

ExpireListener

 The PutListener’s onExpire method is invoked whenever a SpaceEntry in the space has reached its time to live (TTL) and has expired.

SeedListener

 The PutListener’s onSeed method is invoked whenever there is redistribution after an existing seeder leaves the space and now the local node is seeding additional entries. This is only applicable if the listener distribution scope is SEEDED.

UnseedListener

 The PutListener’s onUnseed method is invoked whenever there is redistribution after a new seeder joins the space and now the local node stops seeding some of the entries. Only applicable if the listener distribution scope is SEEDED.

In the ActiveSpaces Java API, listeners must implement at least one of the listener interfaces shown. Listeners are activated using the listen method of the Metaspace or Space class.

• The PutListener interface requires an onPut(PutEvent event) method.
• The TakeListener interface requires an onTake(TakeEvent event) method.
• The ExpireListener interface requires anonExpire(ExpireEvent event) method.
• The SeedListener interface requires an onSeed(SeedEvent event) method.
• The UnseedListener interface requires an onUnseed(UnseedEvent event) method.

In the C API, you must call the tibasListener_Create function and specify a single callback function that is invoked for all event types. The new tibasListener object created by tibasListenerCreate is then activated using the tibasMetaspace_Listen or tibasSpace_Listen functions. The callback function is passed a tibasSpaceEvent object whose type can be determined by invoking the tibasSpaceEvent_GetType function.

ActiveSpaces generates space events of the following type:

• TIBAS_EVENT_PUT when a tuple is inserted, overwritten, or updated.
• TIBAS_EVENT_TAKE when a tuple is taken or removed.
• TIBAS_EVENT_EXPIRE when a tuple reaches the end of its time to live and expires from the space.
• TIBAS_EVENT_SEED when there is redistribution after a seeder joins or leaves, and the local node is seeding or unseeding. This is only applicable if the listener distribution scope is SEEDED.
• TIBAS_EVENT_UNSEED when there is redistribution after a seeder joins or leaves, and the local node is seeding or unseeding. This is only applicable if the listener’s distribution scope is SEEDED.

You can also specify that a current snapshot of the entries stored in the space (sometimes referred to as initial values) is prepended to the stream of events. In this case, the initial values of all the tuples contained in the space at the listener’s creation time are seen as space events of type PUT preceding the current stream of events.