org.gridgain.grid.messaging

Interface GridMessaging

All Known Implementing Classes:

GridMessagingImpl

public interface GridMessaging

Provides functionality for topic-based message exchange among nodes defined by projection(). 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 GridMessaging is obtained from grid projection as follows:

 GridMessaging m = GridGain.grid().message();
 

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

Local subscription, defined by localListen(Object, GridBiPredicate) method, will add a listener for a given topic on local node only. This listener will be notified whenever any node within grid projection will send a message for a given topic to this node. Local listen subscription will happen regardless of whether local node belongs to this grid projection or not.

Remote subscription, defined by remoteListen(Object, GridBiPredicate), will add a message listener for a given topic to all nodes in the projection (possibly including this node if it belongs to the projection as well). This means that any node within this grid projection can send a message for a given topic and all nodes within projection will receive listener notification.

Ordered vs Unordered

GridGain 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

Methods

Modifier and Type	Method and Description
void	localListen(Object topic, GridBiPredicate<UUID,?> p) Adds local listener for given topic on local node only.
GridProjection	projection() Gets grid projection to which this GridMessaging instance belongs.
GridFuture<UUID>	remoteListen(Object topic, GridBiPredicate<UUID,?> p) Adds a message listener for a given topic to all nodes in the projection (possibly including this node if it belongs to the projection as well).
void	send(Object topic, Collection<?> msgs) Sends given messages with specified topic to the nodes in this projection.
void	send(Object topic, Object msg) Sends given message with specified topic to the nodes in this projection.
void	sendOrdered(Object topic, Object msg, long timeout) Sends given message with specified topic to the nodes in this projection.
void	stopLocalListen(Object topic, GridBiPredicate<UUID,?> p) Unregisters local listener for given topic on local node only.
GridFuture<?>	stopRemoteListen(UUID opId) Unregisters all listeners identified with provided operation ID on all nodes in this projection.

Method Detail

projection

GridProjection projection()

Gets grid projection to which this GridMessaging instance belongs.

Returns:

Grid projection to which this GridMessaging instance belongs.

send

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

Sends given message with specified topic to the nodes in this projection.

Parameters:

topic - Topic to send to, null for default topic.

msg - Message to send.

Throws:

GridException - If failed to send a message to any of the nodes.

GridEmptyProjectionException - Thrown in case when this projection is empty.

send

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

Sends given messages with specified topic to the nodes in this projection.

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:

GridException - If failed to send a message to any of the nodes.

GridEmptyProjectionException - Thrown in case when this projection is empty.

sendOrdered

void sendOrdered(@Nullable
               Object topic,
               Object msg,
               long timeout)
                 throws GridException

Sends given message with specified topic to the nodes in this projection. 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.

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 GridConfiguration.getNetworkTimeout().

Throws:

GridException - If failed to send a message to any of the nodes.

GridEmptyProjectionException - Thrown in case when this projection is empty.

localListen

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

Adds local listener for given topic on local node only. This listener will be notified whenever any node within grid projection will send a message for a given topic to this node. Local listen subscription will happen regardless of whether local node belongs to this grid projection 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
                   Object topic,
                   GridBiPredicate<UUID,?> p)

Unregisters local listener for given topic on local node only.

Parameters:

topic - Topic to unsubscribe from.

p - Listener predicate.

remoteListen

GridFuture<UUID> remoteListen(@Nullable
                            Object topic,
                            GridBiPredicate<UUID,?> p)

Adds a message listener for a given topic to all nodes in the projection (possibly including this node if it belongs to the projection as well). This means that any node within this grid projection can send a message for a given topic and all nodes within projection will receive listener notification.

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:

Future that finishes when all listeners are registered. It returns operation ID that can be passed to stopRemoteListen(UUID) method to stop listening.

stopRemoteListen

GridFuture<?> stopRemoteListen(UUID opId)

Unregisters all listeners identified with provided operation ID on all nodes in this projection.

Parameters:

opId - Listen ID that was returned from remoteListen(Object, GridBiPredicate) method.

Returns:

Future that finishes when all listeners are unregistered.