/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.ignite;
import java.util.Collection;
import java.util.List;
import java.util.UUID;
import org.apache.ignite.cluster.ClusterGroup;
import org.apache.ignite.events.Event;
import org.apache.ignite.lang.IgniteAsyncSupport;
import org.apache.ignite.lang.IgniteAsyncSupported;
import org.apache.ignite.lang.IgniteBiPredicate;
import org.apache.ignite.lang.IgniteFuture;
import org.apache.ignite.lang.IgnitePredicate;
import org.jetbrains.annotations.Nullable;
/**
* Provides functionality for local and remote event notifications on nodes defined by {@link #clusterGroup()}.
* There are {@code 2} ways to subscribe to event listening, {@code local} and {@code remote}.
* <p>
* Instance of {@code IgniteEvents} is obtained from {@link Ignite} as follows:
* <pre class="brush:java">
* Ignite ignite = Ignition.ignite();
*
* IgniteEvents evts = ignite.events();
* </pre>
* You can also obtain an instance of the events facade over a specific cluster group:
* <pre class="brush:java">
* // Cluster group over remote nodes (excluding the local node).
* ClusterGroup remoteNodes = ignite.cluster().forRemotes();
*
* // Events instance spanning all remote cluster nodes.
* IgniteEvents evts = ignite.events(remoteNodes);
* </pre>
* <p>
* Local subscription, defined by {@link #localListen(IgnitePredicate, int...)} method, will add
* a listener for specified events on local node only. This listener will be notified whenever any
* of subscribed events happen on local node regardless of whether local node belongs to underlying
* cluster group or not.
* <p>
* Remote subscription, defined by {@link #remoteListen(IgniteBiPredicate, IgnitePredicate, int...)}, will add an
* event listener for specified events on all nodes in the cluster group (possibly including local node if
* it belongs to the cluster group as well). All cluster group nodes will then be notified of the subscribed events.
* If the events pass the remote event filter, the events will be sent to local node for local listener notification.
* <p>
* Note that by default, all events in Ignite are disabled for performance reasons. You must only enable
* events that you need within your logic. You can enable/disable events either by calling {@link #enableLocal(int...)}
* or {@link #disableLocal(int...)} methods, or from XML configuration.
* For example, you can enable all cache events as follows:
* <pre name="code" class="xml">
* <property name="includeEventTypes">
* <util:constant static-field="org.apache.ignite.events.IgniteEventType.EVTS_CACHE"/>
* </property>
* </pre>
*/
public interface IgniteEvents extends IgniteAsyncSupport {
/**
* Gets cluster group to which this {@code IgniteEvents} instance belongs.
*
* @return Cluster group to which this {@code IgniteEvents} instance belongs.
*/
public ClusterGroup clusterGroup();
/**
* Queries nodes in this cluster group for events using passed in predicate filter for event
* selection.
*
* @param p Predicate filter used to query events on remote nodes.
* @param timeout Maximum time to wait for result, {@code 0} to wait forever.
* @param types Event types to be queried.
* @return Collection of grid events returned from specified nodes.
* @throws IgniteException If query failed.
*/
@IgniteAsyncSupported
public <T extends Event> List<T> remoteQuery(IgnitePredicate<T> p, long timeout, @Nullable int... types)
throws IgniteException;
/**
* Asynchronously queries nodes in this cluster group for events using passed in predicate filter for event
* selection.
*
* @param p Predicate filter used to query events on remote nodes.
* @param timeout Maximum time to wait for result, {@code 0} to wait forever.
* @param types Event types to be queried.
* @return a Future representing pending completion of the query. The completed future contains
* collection of grid events returned from specified nodes.
* @throws IgniteException If query failed.
*/
public <T extends Event> IgniteFuture<List<T>> remoteQueryAsync(IgnitePredicate<T> p, long timeout,
@Nullable int... types) throws IgniteException;
/**
* Adds event listener for specified events to all nodes in the cluster group (possibly including
* local node if it belongs to the cluster group as well). This means that all events occurring on
* any node within this cluster group that pass remote filter will be sent to local node for
* local listener notifications.
* <p>
* The listener can be unsubscribed automatically if local node stops, if {@code locLsnr} callback
* returns {@code false} or if {@link #stopRemoteListen(UUID)} or {@link #stopRemoteListenAsync(UUID)} are called.
*
* @param locLsnr Listener callback that is called on local node. If {@code null}, this events will be handled
* on remote nodes by passed in {@code rmtFilter}.
* @param rmtFilter Filter callback that is called on remote node. Only events that pass the remote filter
* will be sent to local node. If {@code null}, all events of specified types will
* be sent to local node. This remote filter can be used to pre-handle events remotely,
* before they are passed in to local callback. It will be auto-unsubsribed on the node
* where event occurred in case if it returns {@code false}.
* @param types Types of events to listen for. If not provided, all events that pass the
* provided remote filter will be sent to local node.
* @param <T> Type of the event.
* @return {@code Operation ID} that can be passed to {@link #stopRemoteListen(UUID)} or
* {@link #stopRemoteListenAsync(UUID)} methods to stop listening.
* @throws IgniteException If failed to add listener.
*/
@IgniteAsyncSupported
public <T extends Event> UUID remoteListen(@Nullable IgniteBiPredicate<UUID, T> locLsnr,
@Nullable IgnitePredicate<T> rmtFilter,
@Nullable int... types)
throws IgniteException;
/**
* Asynchronously adds event listener for specified events to all nodes in the cluster group (possibly including
* local node if it belongs to the cluster group as well). This means that all events occurring on
* any node within this cluster group that pass remote filter will be sent to local node for
* local listener notifications.
* <p>
* The listener can be unsubscribed automatically if local node stops, if {@code locLsnr} callback
* returns {@code false} or if {@link #stopRemoteListen(UUID)} or {@link #stopRemoteListenAsync(UUID)} are called.
*
* @param <T> Type of the event.
* @param locLsnr Listener callback that is called on local node. If {@code null}, this events will be handled
* on remote nodes by passed in {@code rmtFilter}.
* @param rmtFilter Filter callback that is called on remote node. Only events that pass the remote filter
* will be sent to local node. If {@code null}, all events of specified types will
* be sent to local node. This remote filter can be used to pre-handle events remotely,
* before they are passed in to local callback. It will be auto-unsubsribed on the node
* where event occurred in case if it returns {@code false}.
* @param types Types of events to listen for. If not provided, all events that pass the
* provided remote filter will be sent to local node.
* @return a Future representing pending completion of the operation. The completed future contains
* {@code Operation ID} that can be passed to {@link #stopRemoteListen(UUID)} or
* {@link #stopRemoteListenAsync(UUID)} methods to stop listening.
* @throws IgniteException If failed to add listener.
*/
public <T extends Event> IgniteFuture<UUID> remoteListenAsync(@Nullable IgniteBiPredicate<UUID, T> locLsnr,
@Nullable IgnitePredicate<T> rmtFilter,
@Nullable int... types)
throws IgniteException;
/**
* Adds event listener for specified events to all nodes in the cluster group (possibly including
* local node if it belongs to the cluster group as well). This means that all events occurring on
* any node within this cluster group that pass remote filter will be sent to local node for
* local listener notification.
* <p>
* Supports asynchronous execution (see {@link IgniteAsyncSupport}).
*
* @param bufSize Remote events buffer size. Events from remote nodes won't be sent until buffer
* is full or time interval is exceeded.
* @param interval Maximum time interval after which events from remote node will be sent. Events
* from remote nodes won't be sent until buffer is full or time interval is exceeded.
* @param autoUnsubscribe Flag indicating that event listeners on remote nodes should be
* automatically unregistered if master node (node that initiated event listening) leaves
* topology. If this flag is {@code false}, listeners will be unregistered only when
* {@link #stopRemoteListen(UUID)} method is called, or the {@code 'callback (locLsnr)'}
* passed in returns {@code false}.
* @param locLsnr Callback that is called on local node. If this predicate returns {@code true},
* the implementation will continue listening to events. Otherwise, events
* listening will be stopped and listeners will be unregistered on all nodes
* in the cluster group. If {@code null}, this events will be handled on remote nodes by
* passed in {@code rmtFilter} until local node stops (if {@code 'autoUnsubscribe'} is {@code true})
* or until {@link #stopRemoteListen(UUID)} is called.
* @param rmtFilter Filter callback that is called on remote node. Only events that pass the remote filter
* will be sent to local node. If {@code null}, all events of specified types will
* be sent to local node. This remote filter can be used to pre-handle events remotely,
* before they are passed in to local callback. It will be auto-unsubsribed on the node
* where event occurred in case if it returns {@code false}.
* @param types Types of events to listen for. If not provided, all events that pass the
* provided remote filter will be sent to local node.
* @param <T> Type of the event.
* @return {@code Operation ID} that can be passed to {@link #stopRemoteListen(UUID)} or
* {@link #stopRemoteListen(UUID)} methods to stop listening.
* @throws IgniteException If failed to add listener.
* @see #stopRemoteListen(UUID)
* @see #stopRemoteListenAsync(UUID)
*/
@IgniteAsyncSupported
public <T extends Event> UUID remoteListen(int bufSize,
long interval,
boolean autoUnsubscribe,
@Nullable IgniteBiPredicate<UUID, T> locLsnr,
@Nullable IgnitePredicate<T> rmtFilter,
@Nullable int... types)
throws IgniteException;
/**
* Asynchronously adds event listener for specified events to all nodes in the cluster group (possibly including
* local node if it belongs to the cluster group as well). This means that all events occurring on
* any node within this cluster group that pass remote filter will be sent to local node for
* local listener notification.
*
* @param <T> Type of the event.
* @param bufSize Remote events buffer size. Events from remote nodes won't be sent until buffer
* is full or time interval is exceeded.
* @param interval Maximum time interval after which events from remote node will be sent. Events
* from remote nodes won't be sent until buffer is full or time interval is exceeded.
* @param autoUnsubscribe Flag indicating that event listeners on remote nodes should be
* automatically unregistered if master node (node that initiated event listening) leaves
* topology. If this flag is {@code false}, listeners will be unregistered only when
* {@link #stopRemoteListen(UUID)} method is called, or the {@code 'callback (locLsnr)'}
* passed in returns {@code false}.
* @param locLsnr Callback that is called on local node. If this predicate returns {@code true},
* the implementation will continue listening to events. Otherwise, events
* listening will be stopped and listeners will be unregistered on all nodes
* in the cluster group. If {@code null}, this events will be handled on remote nodes by
* passed in {@code rmtFilter} until local node stops (if {@code 'autoUnsubscribe'} is {@code true})
* or until {@link #stopRemoteListen(UUID)} is called.
* @param rmtFilter Filter callback that is called on remote node. Only events that pass the remote filter
* will be sent to local node. If {@code null}, all events of specified types will
* be sent to local node. This remote filter can be used to pre-handle events remotely,
* before they are passed in to local callback. It will be auto-unsubsribed on the node
* where event occurred in case if it returns {@code false}.
* @param types Types of events to listen for. If not provided, all events that pass the
* provided remote filter will be sent to local node.
* @return a Future representing pending completion of the operation. The completed future contains
* {@code Operation ID} that can be passed to {@link #stopRemoteListen(UUID)}
* or {@link #stopRemoteListen(UUID)} methods to stop listening.
* @throws IgniteException If failed to add listener.
* @see #stopRemoteListen(UUID)
* @see #stopRemoteListenAsync(UUID)
*/
public <T extends Event> IgniteFuture<UUID> remoteListenAsync(int bufSize,
long interval,
boolean autoUnsubscribe,
@Nullable IgniteBiPredicate<UUID, T> locLsnr,
@Nullable IgnitePredicate<T> rmtFilter,
@Nullable int... types)
throws IgniteException;
/**
* Stops listening to remote events. This will unregister all listeners identified with provided
* operation ID on all nodes defined by {@link #clusterGroup()}.
* <p>
* Supports asynchronous execution (see {@link IgniteAsyncSupport}).
*
* @param opId Operation ID that was returned from
* {@link #remoteListen(IgniteBiPredicate, IgnitePredicate, int...)} method.
* @throws IgniteException If failed to stop listeners.
* @see #remoteListen(IgniteBiPredicate, IgnitePredicate, int...)
* @see #remoteListenAsync(int, long, boolean, IgniteBiPredicate, IgnitePredicate, int...)
*/
@IgniteAsyncSupported
public void stopRemoteListen(UUID opId) throws IgniteException;
/**
* Asynchronously stops listening to remote events. This will unregister all listeners identified with provided
* operation ID on all nodes defined by {@link #clusterGroup()}.
*
* @param opId Operation ID that was returned from
* {@link #remoteListen(IgniteBiPredicate, IgnitePredicate, int...)} method.
* @return a Future representing pending completion of the operation.
* @throws IgniteException If failed to stop listeners.
* @see #remoteListen(IgniteBiPredicate, IgnitePredicate, int...)
* @see #remoteListenAsync(int, long, boolean, IgniteBiPredicate, IgnitePredicate, int...)
*/
public IgniteFuture<Void> stopRemoteListenAsync(UUID opId) throws IgniteException;
/**
* Waits for the specified events.
* <p>
* Supports asynchronous execution (see {@link IgniteAsyncSupport}).
*
* @param filter Optional filtering predicate. Only if predicates evaluates to {@code true} will the event
* end the wait.
* @param types Types of the events to wait for. If not provided, all events will be passed to the filter.
* @return Grid event.
* @throws IgniteException If wait was interrupted.
*/
@IgniteAsyncSupported
public <T extends Event> T waitForLocal(@Nullable IgnitePredicate<T> filter, @Nullable int... types)
throws IgniteException;
/**
* Create future to wait for the specified events.
*
* @param filter Optional filtering predicate. Only if predicates evaluates to {@code true} will the event
* end the wait.
* @param types Types of the events to wait for. If not provided, all events will be passed to the filter.
* @return a Future representing pending completion of the operation. The completed future contains grid event.
* @throws IgniteException If wait was interrupted.
*/
public <T extends Event> IgniteFuture<T> waitForLocalAsync(@Nullable IgnitePredicate<T> filter,
@Nullable int... types) throws IgniteException;
/**
* Queries local node for events using passed-in predicate filter for event selection.
*
* @param p Predicate to filter events. All predicates must be satisfied for the
* event to be returned.
* @param types Event types to be queried.
* @return Collection of grid events found on local node.
*/
public <T extends Event> Collection<T> localQuery(IgnitePredicate<T> p, @Nullable int... types);
/**
* Records customer user generated event. All registered local listeners will be notified.
* <p>
* NOTE: all types in range <b>from 1 to 1000 are reserved</b> for
* internal Ignite events and should not be used by user-defined events.
* Attempt to record internal event with this method will cause {@code IllegalArgumentException}
* to be thrown.
*
* @param evt Locally generated event.
* @throws IllegalArgumentException If event type is within Ignite reserved range between {@code 1} and
* {@code 1000}.
*/
public void recordLocal(Event evt);
/**
* Adds an event listener for local events. Note that listener will be added regardless of whether
* local node is in this cluster group or not.
*
* @param lsnr Predicate that is called on each received event. If predicate returns {@code false},
* it will be unregistered and will stop receiving events.
* @param types Event types for which this listener will be notified.
* @throws IllegalArgumentException Thrown in case when passed in array of event types is empty.
*/
public void localListen(IgnitePredicate<? extends Event> lsnr, int... types);
/**
* Removes local event listener.
*
* @param lsnr Local event listener to remove.
* @param types Types of events for which to remove listener. If not specified,
* then listener will be removed for all types it was registered for.
* @return {@code true} if listener was removed, {@code false} otherwise.
*/
public boolean stopLocalListen(IgnitePredicate<? extends Event> lsnr, @Nullable int... types);
/**
* Enables provided events. Allows to start recording events that
* were disabled before. Note that specified events will be enabled
* regardless of whether local node is in this cluster group or not.
*
* @param types Events to enable.
*/
public void enableLocal(int... types);
/**
* Disables provided events. Allows to stop recording events that
* were enabled before. Note that specified events will be disabled
* regardless of whether local node is in this cluster group or not.
*
* @param types Events to disable.
*/
public void disableLocal(int... types);
/**
* Gets types of enabled events.
*
* @return Types of enabled events.
*/
public int[] enabledEvents();
/**
* Check if event is enabled.
*
* @param type Event type.
* @return {@code True} if event of passed in type is enabled.
*/
public boolean isEnabled(int type);
/** {@inheritDoc} */
@Deprecated
@Override public IgniteEvents withAsync();
}