org.apache.ignite

## Interface IgniteMessaging

- All Superinterfaces:
    IgniteAsyncSupport

      public interface IgniteMessaging
      extends IgniteAsyncSupport

  Provides functionality for topic-based message exchange among nodes defined by `clusterGroup()`. Users can send ordered and unordered messages to various topics. Note that same topic name cannot be reused between ordered and unordered messages.

  Instance of `IgniteMessaging` is obtained from `Ignite` as follows:

       Ignite ignite = Ignition.ignite();

       // Messaging instance spanning all cluster nodes.
       IgniteMessaging m = ignite.message();

  You can also obtain an instance of messaging facade over a specific cluster group:

       // 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);

  There are `2` ways to subscribe to message listening, `local` and `remote`.

  Local subscription, defined by `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.

  Remote subscription, defined by `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.

  # Ordered vs Unordered

  Ignite allows for sending ordered messages (see `sendOrdered(Object, Object, long)`), i.e. messages will be received in the same order they were sent. Ordered messages have a `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.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `ClusterGroup` | `clusterGroup()` Gets the cluster group to which this `GridMessaging` instance belongs.
    `void` | `localListen(@Nullable Object topic, IgniteBiPredicate<UUID,?> p)` Adds local listener for given topic on local node only.
    `UUID` | `remoteListen(@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).
    `IgniteFuture<UUID>` | `remoteListenAsync(@Nullable Object topic, IgniteBiPredicate<UUID,?> p)` 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).
    `void` | `send(@Nullable Object topic, Collection<?> msgs)` Sends given messages with the specified topic to the nodes in the underlying cluster group.
    `void` | `send(@Nullable Object topic, Object msg)` Sends given message with specified topic to the nodes in the underlying cluster group.
    `void` | `sendOrdered(@Nullable Object topic, Object msg, long timeout)` Sends given message with specified topic to the nodes in the underlying cluster group.
    `void` | `stopLocalListen(@Nullable Object topic, IgniteBiPredicate<UUID,?> p)` Unregisters local listener for given topic on local node only.
    `void` | `stopRemoteListen(UUID opId)` Unregisters all listeners identified with provided operation ID on all nodes in the cluster group.
    `IgniteFuture<Void>` | `stopRemoteListenAsync(UUID opId)` Asynchronously unregisters all listeners identified with provided operation ID on all nodes in the cluster group.
    `IgniteMessaging` | `withAsync()` Deprecated.

    - ### Methods inherited from interface org.apache.ignite.lang.IgniteAsyncSupport

      `future, isAsync`

- - ### Method Detail

    - #### clusterGroup

          ClusterGroup clusterGroup()

      Gets the cluster group to which this `GridMessaging` instance belongs.
      Returns:
        Cluster group to which this `GridMessaging` instance belongs.

    - #### send

          void send(@Nullable
                    @Nullable Object topic,
                    Object msg)
             throws IgniteException

      Sends given message with specified topic to the nodes in the underlying cluster group.

      By default all local listeners will be executed in the calling thread, or if you use `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).

      Parameters:
        `topic` - Topic to send to, `null` for default topic.
        `msg` - Message to send.
      Throws:
        `IgniteException` - If failed to send a message to any of the nodes.
        `ClusterGroupEmptyException` - Thrown in case when cluster group is empty.

    - #### send

          void send(@Nullable
                    @Nullable Object topic,
                    Collection<?> msgs)
             throws IgniteException

      Sends given messages with the specified topic to the nodes in the underlying cluster group.

      By default all local listeners will be executed in the calling thread, or if you use `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).

      Parameters:
        `topic` - Topic to send to, `null` for default topic.
        `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.
        `ClusterGroupEmptyException` - Thrown in case when cluster group is empty.

    - #### sendOrdered

          void sendOrdered(@Nullable
                           @Nullable Object topic,
                           Object msg,
                           long timeout)
                    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 `withAsync()` mode is used.

      The `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.

      Parameters:
        `topic` - Topic to send to, `null` for default topic.
        `msg` - Message to send.
        `timeout` - Message timeout in milliseconds, `0` for default which is `IgniteConfiguration.getNetworkTimeout()`.
      Throws:
        `IgniteException` - If failed to send a message to any of the nodes.
        `ClusterGroupEmptyException` - Thrown in case when cluster group is empty.

    - #### localListen

          void localListen(@Nullable
                           @Nullable Object topic,
                           IgniteBiPredicate<UUID,?> p)

      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.
      Parameters:
        `topic` - Topic to subscribe to.
        `p` - Predicate that is called on each received message. If predicate returns `false`, then it will be unsubscribed from any further notifications.

    - #### stopLocalListen

          void stopLocalListen(@Nullable
                               @Nullable Object topic,
                               IgniteBiPredicate<UUID,?> p)

      Unregisters local listener for given topic on local node only.
      Parameters:
        `topic` - Topic to unsubscribe from.
        `p` - Listener predicate.

    - #### remoteListen

          @IgniteAsyncSupported
          UUID remoteListen(@Nullable
                                                  @Nullable Object topic,
                                                  IgniteBiPredicate<UUID,?> p)
                                           throws IgniteException

      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.
      Parameters:
        `topic` - Topic to subscribe to, `null` means default topic.
        `p` - Predicate that is called on each node for each received message. If predicate returns `false`, then it will be unsubscribed from any further notifications.
      Returns:
        `Operation ID` that can be passed to `stopRemoteListen(UUID)` method to stop listening.
      Throws:
        `IgniteException` - If failed to add listener.

    - #### remoteListenAsync

          IgniteFuture<UUID> remoteListenAsync(@Nullable
                                               @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.
      Parameters:
        `topic` - Topic to subscribe to, `null` means default topic.
        `p` - Predicate that is called on each node for each received message. If predicate returns `false`, then it will be unsubscribed from any further notifications.
      Returns:
        a Future representing pending completion of the operation. The completed future contains `Operation ID` that can be passed to `stopRemoteListen(UUID)` method to stop listening.
      Throws:
        `IgniteException` - If failed to add listener.

    - #### stopRemoteListen

          @IgniteAsyncSupported
          void stopRemoteListen(UUID opId)
                                               throws IgniteException

      Unregisters all listeners identified with provided operation ID on all nodes in the cluster group.

      Supports asynchronous execution (see `IgniteAsyncSupport`).

      Parameters:
        `opId` - Listen ID that was returned from `remoteListen(Object, IgniteBiPredicate)` method.
      Throws:
        `IgniteException` - If failed to unregister listeners.

    - #### stopRemoteListenAsync

          IgniteFuture<Void> stopRemoteListenAsync(UUID opId)
                                            throws IgniteException

      Asynchronously unregisters all listeners identified with provided operation ID on all nodes in the cluster group.
      Parameters:
        `opId` - Listen ID that was returned from `remoteListen(Object, IgniteBiPredicate)` method.
      Returns:
        a Future representing pending completion of the operation.
      Throws:
        `IgniteException` - If failed to unregister listeners.

    - #### withAsync

          @Deprecated
          IgniteMessaging withAsync()

      Deprecated.
      Gets instance of this component with asynchronous mode enabled.
      Specified by:
        `withAsync` in interface `IgniteAsyncSupport`
      Returns:
        Instance of this component with asynchronous mode enabled.

${current.year} Copyright © Apache Software Foundation
| Follow @ApacheIgnite
Ignite Database and Caching Platform | : ver. 2.16.0
Release Date | : December 15 2023