| /* |
| * 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.UUID; |
| import org.apache.ignite.cluster.ClusterGroup; |
| import org.apache.ignite.cluster.ClusterGroupEmptyException; |
| import org.apache.ignite.configuration.IgniteConfiguration; |
| 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.jetbrains.annotations.Nullable; |
| |
| /** |
| * Provides functionality for topic-based message exchange among nodes defined by {@link #clusterGroup()}. |
| * Users can send ordered and unordered messages to various topics. Note that same topic name |
| * cannot be reused between ordered and unordered messages. |
| * <p> |
| * Instance of {@code IgniteMessaging} is obtained from {@link Ignite} as follows: |
| * <pre class="brush:java"> |
| * Ignite ignite = Ignition.ignite(); |
| * |
| * // Messaging instance spanning all cluster nodes. |
| * IgniteMessaging m = ignite.message(); |
| * </pre> |
| * You can also obtain an instance of messaging facade over a specific cluster group: |
| * <pre class="brush:java"> |
| * // Cluster group over remote nodes (excluding the local node). |
| * ClusterGroup remoteNodes = ignite.cluster().forRemotes(); |
| * |
| * // Messaging instance spanning all remote cluster nodes. |
| * IgniteMessaging m = ignite.message(remoteNodes); |
| * </pre> |
| * <p> |
| * There are {@code 2} ways to subscribe to message listening, {@code local} and {@code remote}. |
| * <p> |
| * Local subscription, defined by {@link #localListen(Object, IgniteBiPredicate)} method, will add |
| * a listener for a given topic on local node only. This listener will be notified whenever any |
| * node within the underlying cluster group will send a message for a given topic to this node. Local listen |
| * subscription will happen regardless of whether the local node belongs to this cluster group or not. |
| * <p> |
| * Remote subscription, defined by {@link #remoteListen(Object, IgniteBiPredicate)}, will add a |
| * message listener for a given topic to all nodes in the underlying cluster group (possibly including this node if |
| * it belongs to the cluster group as well). This means that any node within this cluster group can send |
| * a message for a given topic and all nodes within the cluster group will receive listener notifications. |
| * <h1 class="header">Ordered vs Unordered</h1> |
| * Ignite allows for sending ordered messages (see {@link #sendOrdered(Object, Object, long)}), i.e. |
| * messages will be received in the same order they were sent. Ordered messages have a {@code timeout} |
| * parameter associated with them which specifies how long an out-of-order message will stay in a queue, |
| * waiting for messages that are ordered ahead of it to arrive. If timeout expires, then all ordered |
| * messages for a given topic that have not arrived yet will be skipped. When (and if) expired messages |
| * actually do arrive, they will be ignored. |
| */ |
| public interface IgniteMessaging extends IgniteAsyncSupport { |
| /** |
| * Gets the cluster group to which this {@code GridMessaging} instance belongs. |
| * |
| * @return Cluster group to which this {@code GridMessaging} instance belongs. |
| */ |
| public ClusterGroup clusterGroup(); |
| |
| /** |
| * Sends given message with specified topic to the nodes in the underlying cluster group. |
| * <p> |
| * By default all local listeners will be executed in the calling thread, or if you use |
| * {@link #withAsync()}, listeners will execute in public thread pool (in this case it is user's |
| * responsibility to implement back-pressure and limit number of concurrently executed async messages). |
| * |
| * @param topic Topic to send to, {@code null} for default topic. |
| * @param msg Message to send. |
| * @throws IgniteException If failed to send a message to any of the nodes. |
| * @throws ClusterGroupEmptyException Thrown in case when cluster group is empty. |
| */ |
| public void send(@Nullable Object topic, Object msg) throws IgniteException; |
| |
| /** |
| * Sends given messages with the specified topic to the nodes in the underlying cluster group. |
| * <p> |
| * By default all local listeners will be executed in the calling thread, or if you use |
| * {@link #withAsync()}, listeners will execute in public thread pool (in this case it is user's |
| * responsibility to implement back-pressure and limit number of concurrently executed async messages). |
| * |
| * @param topic Topic to send to, {@code null} for default topic. |
| * @param msgs Messages to send. Order of the sending is undefined. If the method produces |
| * the exception none or some messages could have been sent already. |
| * @throws IgniteException If failed to send a message to any of the nodes. |
| * @throws ClusterGroupEmptyException Thrown in case when cluster group is empty. |
| */ |
| public void send(@Nullable Object topic, Collection<?> msgs) throws IgniteException; |
| |
| /** |
| * Sends given message with specified topic to the nodes in the underlying cluster group. Messages sent with |
| * this method will arrive in the same order they were sent. Note that if a topic is used |
| * for ordered messages, then it cannot be reused for non-ordered messages. Note that local listeners |
| * are always executed in public thread pool, no matter default or {@link #withAsync()} mode is used. |
| * <p> |
| * The {@code timeout} parameter specifies how long an out-of-order message will stay in a queue, |
| * waiting for messages that are ordered ahead of it to arrive. If timeout expires, then all ordered |
| * messages that have not arrived before this message will be skipped. When (and if) expired messages |
| * actually do arrive, they will be ignored. |
| * |
| * @param topic Topic to send to, {@code null} for default topic. |
| * @param msg Message to send. |
| * @param timeout Message timeout in milliseconds, {@code 0} for default |
| * which is {@link IgniteConfiguration#getNetworkTimeout()}. |
| * @throws IgniteException If failed to send a message to any of the nodes. |
| * @throws ClusterGroupEmptyException Thrown in case when cluster group is empty. |
| */ |
| public void sendOrdered(@Nullable Object topic, Object msg, long timeout) throws IgniteException; |
| |
| /** |
| * Adds local listener for given topic on local node only. This listener will be notified whenever any |
| * node within the cluster group will send a message for a given topic to this node. Local listen |
| * subscription will happen regardless of whether local node belongs to this cluster group or not. |
| * |
| * @param topic Topic to subscribe to. |
| * @param p Predicate that is called on each received message. If predicate returns {@code false}, |
| * then it will be unsubscribed from any further notifications. |
| */ |
| public void localListen(@Nullable Object topic, IgniteBiPredicate<UUID, ?> p); |
| |
| /** |
| * Unregisters local listener for given topic on local node only. |
| * |
| * @param topic Topic to unsubscribe from. |
| * @param p Listener predicate. |
| */ |
| public void stopLocalListen(@Nullable Object topic, IgniteBiPredicate<UUID, ?> p); |
| |
| /** |
| * Adds a message listener for a given topic to all nodes in the cluster group (possibly including |
| * this node if it belongs to the cluster group as well). This means that any node within this cluster |
| * group can send a message for a given topic and all nodes within the cluster group will receive |
| * listener notifications. |
| * |
| * @param topic Topic to subscribe to, {@code null} means default topic. |
| * @param p Predicate that is called on each node for each received message. If predicate returns {@code false}, |
| * then it will be unsubscribed from any further notifications. |
| * @return {@code Operation ID} that can be passed to {@link #stopRemoteListen(UUID)} method to stop listening. |
| * @throws IgniteException If failed to add listener. |
| */ |
| @IgniteAsyncSupported |
| public UUID remoteListen(@Nullable Object topic, IgniteBiPredicate<UUID, ?> p) throws IgniteException; |
| |
| /** |
| * Asynchronously adds a message listener for a given topic to all nodes in the cluster group (possibly including |
| * this node if it belongs to the cluster group as well). This means that any node within this cluster |
| * group can send a message for a given topic and all nodes within the cluster group will receive |
| * listener notifications. |
| * |
| * @param topic Topic to subscribe to, {@code null} means default topic. |
| * @param p Predicate that is called on each node for each received message. If predicate returns {@code false}, |
| * then it will be unsubscribed from any further notifications. |
| * @return a Future representing pending completion of the operation. The completed future contains |
| * {@code Operation ID} that can be passed to {@link #stopRemoteListen(UUID)} method to stop listening. |
| * @throws IgniteException If failed to add listener. |
| */ |
| public IgniteFuture<UUID> remoteListenAsync(@Nullable Object topic, IgniteBiPredicate<UUID, ?> p) |
| throws IgniteException; |
| |
| /** |
| * Unregisters all listeners identified with provided operation ID on all nodes in the cluster group. |
| * <p> |
| * Supports asynchronous execution (see {@link IgniteAsyncSupport}). |
| * |
| * @param opId Listen ID that was returned from {@link #remoteListen(Object, IgniteBiPredicate)} method. |
| * @throws IgniteException If failed to unregister listeners. |
| */ |
| @IgniteAsyncSupported |
| public void stopRemoteListen(UUID opId) throws IgniteException; |
| |
| /** |
| * Asynchronously unregisters all listeners identified with provided operation ID on all nodes in the cluster group. |
| * |
| * @param opId Listen ID that was returned from {@link #remoteListen(Object, IgniteBiPredicate)} method. |
| * @return a Future representing pending completion of the operation. |
| * @throws IgniteException If failed to unregister listeners. |
| */ |
| public IgniteFuture<Void> stopRemoteListenAsync(UUID opId) throws IgniteException; |
| |
| /** {@inheritDoc} */ |
| @Deprecated |
| @Override IgniteMessaging withAsync(); |
| } |