Apache Geode CHANGELOG

How Events Work

Members in your Geode cluster receive cache updates from other members through cache events. The other members can be peers to the member, clients or servers or other clusters.

Events Features

These are the primary features of Geode events:

  • Content-based events
  • Asynchronous event notifications with conflation
  • Synchronous event notifications for low latency
  • High availability through redundant messaging queues
  • Event ordering and once and only-once delivery
  • Distributed event notifications
  • Durable subscriptions
  • Continuous querying

Types of Events

There are two categories of events and event handlers.

  • Cache events in the caching API are used by applications with a cache. Cache events provide detail-level notification for changes to your data. Continuous query events are in this category.
  • Administrative events in the administration API are used by administrative applications without caches.

Both kinds of events can be generated by a single member operation.

Note: You can handle one of these categories of events in a single system member. You cannot handle both cache and administrative events in a single member.

Because Geode maintains the order of administrative events and the order of cache events separately, using cache events and administrative events in a single process can cause unexpected results.

Event Cycle

The following steps describe the event cycle:

  1. An operation begins, such as data put or a cache close.

  2. The operation execution generates these objects:

    • An object of type Operation that describes the method that triggered the event.
    • An event object that describes the event, such as the member and region where the operation originated.

  3. The event handlers that can handle the event are called and passed the event objects. Different event types require different handler types in different locations. If there is no matching event handler, that does not change the effect of the operation, which happens as usual.

  4. When the handler receives the event, it triggers the handler’s callback method for this event. The callback method can hand off the event object as input to another method. Depending on the type of event handler, the callbacks can be triggered before or after the operation. The timing depends on the event handler, not on the event itself. Note: For transactions, after-operation listeners receive the events after the transaction has committed.

  5. If the operation is distributed, so that it causes follow-on operations in other members, those operations generate their own events, which can be handled by their listeners in the same way.

Event Objects

Event objects come in several types, depending on the operation. Some operations generate multiple objects of different types. All event objects contain data describing the event, and each event type carries slightly different kinds of data appropriate to its matching operation. An event object is stable. For example, its content does not change if you pass it off to a method on another thread.

For cache events, the event object describes the operation performed in the local cache. If the event originated remotely, it describes the local application of the remote entry operation, not the remote operation itself. The only exception is when the local region has an empty data policy; then the event carries the information for the remote (originating) cache operation.

Event Distribution

After a member processes an event in its local cache, it distributes it to remote caches according to the member’s configuration and the configurations of the remote caches. For example, if a client updates its cache, the update is forwarded to the client’s server. The server distributes the update to its peers and forwards it to any other clients according to their interest in the data entry. If the server system is part of a multi-site deployment and the data region is configured to use a gateway sender, then the gateway sender also forwards the update to a remote site, where the update is further distributed and propagated.

Event Handlers and Region Data Storage

You can configure a region for no local data storage and still send and receive events for the region. Conversely, if you store data in the region, the cache is updated with data from the event regardless of whether you have any event handlers installed.

Multiple Listeners

When multiple listeners are installed, as can be done with cache listeners, the listeners are invoked sequentially in the order they were added to the region or cache. Listeners are executed one at a time. So, unless you program a listener to pass off processing to another thread, you can use one listener’s work in later listeners.

Event Ordering

During a cache operation, event handlers are called at various stages of the operation. Some event handlers are called before a region update and some are called after the region update operation. Depending on the type of event handler being called, the event handler can receive the events in-order or out-of-order in which they are applied on Region.

  • CacheWriter and AsyncEventListener always receive events in the order in which they are applied on region.
  • CacheListener and CqListener can receive events in a different order than the order in which they were applied on the region.

Note: An EntryEvent contains both the old value and the new value of the entry, which helps to indicate the value that was replaced by the cache operation on a particular key.