Local and Remote Events

❗️

This is a legacy Apache Ignite documentation

The new documentation is hosted here: https://ignite.apache.org/docs/latest/

Overview

Ignite distributed events functionality allows applications to receive notifications when a variety of events occur in the distributed grid environment. You can automatically get notified for task executions, read, write or query operations occurring on local or remote nodes within the cluster.

IgniteEvents API

Distributed events functionality is provided via IgniteEvents interface. You can get an instance of IgniteEvents from Ignite as follows:

Ignite ignite = Ignition.ignite();

IgniteEvents evts = ignite.events();

Subscribe to Events

Listen methods can be used to receive notification for specified events happening in the cluster. These methods register a listener on local or remotes nodes for the specified events. Whenever an event occurs on a node, the listeners are notified.
##Local Events
If you want to listen to events on the local node, set local event listeners via the method setLocalEventListeners(...) of IgniteConfiguration. You can also use the localListen(...) method of IgniteEvents, but note that you will miss events occurring before the call to localListen(...).
##Remote Events
remoteListen(...) method registers event listeners with specified events on all nodes within the cluster or cluster group. Following is an example of each method:

Ignite ignite = Ignition.ignite();

// Local listener that listenes to local events.
IgnitePredicate<CacheEvent> locLsnr = evt -> {
  System.out.println("Received event [evt=" + evt.name() + ", key=" + evt.key() + 
    ", oldVal=" + evt.oldValue() + ", newVal=" + evt.newValue());

  return true; // Continue listening.
};

// Subscribe to specified cache events occuring on local node.
ignite.events().localListen(locLsnr,
  EventType.EVT_CACHE_OBJECT_PUT,
  EventType.EVT_CACHE_OBJECT_READ,
  EventType.EVT_CACHE_OBJECT_REMOVED);

// Get an instance of named cache.
final IgniteCache<Integer, String> cache = ignite.cache("cacheName");

// Generate cache events.
for (int i = 0; i < 20; i++)
  cache.put(i, Integer.toString(i));

Ignite ignite = Ignition.ignite();

// Get an instance of named cache.
final IgniteCache<Integer, String> cache = ignite.cache("cacheName");

// Sample remote filter which only accepts events for keys
// that are greater than or equal to 10.
IgnitePredicate<CacheEvent> rmtLsnr = evt -> evt.<Integer>key() >= 10;

// Subscribe to specified cache events on all nodes that have cache running.
ignite.events(ignite.cluster().forCacheNodes("cacheName")).remoteListen(null, rmtLsnr,                                                                 EventType.EVT_CACHE_OBJECT_PUT,
  EventType.EVT_CACHE_OBJECT_READ,
  EventType.EVT_CACHE_OBJECT_REMOVED);

// Generate cache events.
for (int i = 0; i < 20; i++)
  cache.put(i, Integer.toString(i));

In the above example EVT_CACHE_OBJECT_PUT,EVT_CACHE_OBJECT_READ, and EVT_CACHE_OBJECT_REMOVED are pre-defined event type constants defined in EventType interface.

📘

EventType interface defines various event type constants that can be used with listen methods. Refer to javadoc for complete list of these event types.

🚧

Event types passed in as parameter in localListen(...) and remoteListen(...) methods must also be configured in IgniteConfiguration. See configuration example below.

Query for Events

All events generated in the system are kept locally on the local node. IgniteEvents API provides methods to query for these events.
##Local Query
localQuery(...) method queries for events on the local node using the passed in predicate filter. If all predicates are satisfied, a collection of events happening on the local node is returned.
##Remote Query
remoteQuery(...) method asynchronously queries for events on remote nodes in this projection using the passed in predicate filter. This operation is distributed and hence can fail on communication layer and generally can take much longer than local event notifications. Note that this method will not block and will return immediately with future.

Configuration

To get notified of any tasks or cache events occurring within the cluster, includeEventTypes property of IgniteConfiguration must be enabled.

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
 		... 
    <!-- Enable cache events. -->
    <property name="includeEventTypes">
        <util:constant static-field="org.apache.ignite.events.EventType.EVTS_CACHE"/>
    </property>
  	...
</bean>

IgniteConfiguration cfg = new IgniteConfiguration();

// Enable cache events.
cfg.setIncludeEventTypes(EVTS_CACHE);

// Start Ignite node.
Ignition.start(cfg);

By default, event notifications are turned off for performance reasons.

👍

Since thousands of events per second are generated, it creates an additional load on the system. This can lead to significant performance degradation. Therefore, it is highly recommended to enable only those events that your application logic requires.