Package com.qfs.messenger

Interface IDistributedMessenger

All Superinterfaces:

IAgent, IExtendedPluginValue, IMonitoredComponent

All Known Implementing Classes:

ADistributedMessenger, AJGroupsMessenger, LocalMessenger, LogNettyMessenger, NettyMessenger

public interface IDistributedMessenger
extends IAgent, IMonitoredComponent

An object used to broadcast messages to other instances and process remote messages.

Author:

ActiveViam

Nested Class Summary

Nested classes/interfaces inherited from interface com.quartetfs.fwk.IAgent

IAgent.ITransition, IAgent.State

Field Summary

Fields

Modifier and Type	Field	Description
static String	DEFAULT_PLUGIN_KEY	The plugin key of the default IDistributedMessenger implementation.

Method Summary

Modifier and Type	Method	Description
long	awaitNewView(long viewId, long timeout, TimeUnit unit)	Waits at most the given time for the view ID to be strictly greater than the given one.
long	awaitViewNotification(long viewId, long timeout, TimeUnit unit)	It waits for the given timeout for the viewId to be applied.
<AnswerT,OutputT> OutputT	broadcast(IBroadcastMessage<AnswerT,OutputT,?> message, long timeout)	Broadcasts the given message to all instances, collects the answers and processes them to produce the global answer.
<AnswerT,OutputT> CompletionStage<OutputT>	broadcastAsynchronously(IBroadcastMessage<AnswerT,OutputT,?> message, long timeout)	Broadcasts the given message to all remote instances asynchronously, and executes it locally asynchronously as well.
IAddress	getAddress()	Returns the IAddress of the current (local) instance.
String	getAddressAsString()	Returns the address of the current (local) instance.
long	getDefaultTimeout()	Returns the default timeout in milliseconds to use for the messages sent by this messenger.
IDistributedExecutorService	getExecutorService()	Returns the ExecutorService used by the messenger.
<ContextT> ContextT	getMessageContext(Class<ContextT> contextType)	Returns the local message context of the given kind.
Set<IDistributedAgent>	getRegisteredAgents()	Returns all the registered IDistributedAgents.
IClusterView	getView()	Returns the IClusterView of the current cluster.
boolean	register(IDistributedAgent agent)	Register the given IDistributedAgent.
void	restart()	Restart the messenger.
<AnswerT,OutputT> OutputT	sendMessage(IBroadcastMessage<AnswerT,OutputT,?> message, Collection<String> addresses, long timeout)	Sends the given message to some specific instances, collects the answers and process them to produce the global answer.
<AnswerT,OutputT> CompletableFuture<OutputT>	sendMessageAsynchronously(IBroadcastMessage<AnswerT,OutputT,?> message, Collection<String> addresses, long timeout)	Sends the given message to some specific remote instances asynchronously.
<ContextT> void	setMessageContext(Class<ContextT> contextType, ContextT context)	Sets a local message context for a given type.
boolean	unregister(IDistributedAgent agent)	Unregister the given IDistributedAgent.

Methods inherited from interface com.quartetfs.fwk.IAgent

getProperties, getStatus, init, pause, resume, start, stop

Methods inherited from interface com.quartetfs.fwk.types.IExtendedPluginValue

getType

Methods inherited from interface com.quartetfs.fwk.monitoring.IMonitoredComponent

getAvailableAttributes, getAvailableOperations, getMonitoredChildren, getStatistics

Field Detail

DEFAULT_PLUGIN_KEY

static final String DEFAULT_PLUGIN_KEY

The plugin key of the default IDistributedMessenger implementation.

See Also:

Constant Field Values

Method Detail

broadcast

<AnswerT,OutputT> OutputT broadcast(IBroadcastMessage<AnswerT,OutputT,?> message,
                                          long timeout)
                                   throws Exception

Broadcasts the given message to all instances, collects the answers and processes them to produce the global answer.

The whole process is done synchronously on the current thread.

Type Parameters:

AnswerT - the result type of the message execution on a remote instance

OutputT - the result type of the message after receiving all AnswerType

Parameters:

message - The message to broadcast

timeout - The time (in ms) after which we consider that this broadcast has timed out if we did not get a reply from all the addressees.

Returns:

The global answer to this message

Throws:

Exception - if a exception is raised when broadcasting the message. answers

broadcastAsynchronously

<AnswerT,OutputT> CompletionStage<OutputT> broadcastAsynchronously(IBroadcastMessage<AnswerT,OutputT,?> message,
                                                                         long timeout)
                                                                  throws Exception

Broadcasts the given message to all remote instances asynchronously, and executes it locally asynchronously as well.

The message will then be automatically processed by invoking IBroadcastMessage.processReplies(Collection) asynchronously in another thread when the remote answers have been received.

There are no strong guarantees that the processing will ever be done, since the message may time out and never come back.

Type Parameters:

AnswerT - the result type of the message execution on a remote instance

OutputT - the result type of the message after receiving all AnswerType

Parameters:

message - The message to broadcast

timeout - The time (in ms) after which we consider that this broadcast has timed out if we did not get a reply from all the addressees.

Returns:

A stage of the asynchronous transmission of the message. It could be used to trigger actions when the message has been transmitted either normally or abnormally.

Throws:

Exception - if a exception is raised when broadcasting the message.

sendMessage

<AnswerT,OutputT> OutputT sendMessage(IBroadcastMessage<AnswerT,OutputT,?> message,
                                            Collection<String> addresses,
                                            long timeout)
                                     throws Exception

Sends the given message to some specific instances, collects the answers and process them to produce the global answer.

The whole process is done synchronously on the current thread.

Type Parameters:

AnswerT - the result type of the message execution on a remote instance

OutputT - the result type of the message after receiving all AnswerType

Parameters:

message - The message to broadcast

addresses - The addresses of the members to send the message to

timeout - The time (in ms) after which we consider that this broadcast has timed out if we did not get a reply from all the addressees.

Returns:

The global answer to this message

Throws:

Exception - if a exception is raised when sending the message.

sendMessageAsynchronously

<AnswerT,OutputT> CompletableFuture<OutputT> sendMessageAsynchronously(IBroadcastMessage<AnswerT,OutputT,?> message,
                                                                             Collection<String> addresses,
                                                                             long timeout)

Sends the given message to some specific remote instances asynchronously.

The message will then be automatically processed by invoking IBroadcastMessage.processReplies(Collection) asynchronously in another thread when the remote answers have been received.

There are no strong guarantees that the processing will ever be done, since the message may time out and never come back.

Type Parameters:

AnswerT - the result type of the message execution on a remote instance

OutputT - the result type of the message after receiving all AnswerType

Parameters:

message - The message to broadcast

addresses - The addresses of the members to send the message to

timeout - The time (in ms) after which we consider that this broadcast has timed out if we did not get a reply from all the addressees.

Returns:

A stage of the asynchronous transmission of the message. It could be used to trigger actions when the message has been transmitted either normally or abnormally.

getDefaultTimeout

long getDefaultTimeout()

Returns the default timeout in milliseconds to use for the messages sent by this messenger.

awaitNewView

long awaitNewView(long viewId,
                  long timeout,
                  TimeUnit unit)
           throws InterruptedException,
                  TimeoutException

Waits at most the given time for the view ID to be strictly greater than the given one.

Parameters:

viewId - The current view ID

timeout - A timeout

unit - The timeout's time unit

Returns:

The new view Id

Throws:

InterruptedException - if any thread interrupted the current thread before or while the current thread was waiting for a notification. The interrupted status of the current thread is cleared when this exception is thrown.

TimeoutException - if the wait timed out

awaitViewNotification

long awaitViewNotification(long viewId,
                           long timeout,
                           TimeUnit unit)
                    throws InterruptedException,
                           TimeoutException

It waits for the given timeout for the viewId to be applied.

Parameters:

viewId - The current view ID

timeout - A timeout

unit - The timeout's time unit

Returns:

The new view Id

Throws:

InterruptedException - if any thread interrupted the current thread before or while the current thread was waiting for a notification. The interrupted status of the current thread is cleared when this exception is thrown.

TimeoutException - if the wait timed out

register

boolean register(IDistributedAgent agent)
          throws AgentException

Register the given IDistributedAgent.

Parameters:

agent - An IDistributedAgent

Returns:

true if this agent is being registered for the first time

Throws:

AgentException - if the Agent cannot be registered

restart

void restart()

Restart the messenger.

unregister

boolean unregister(IDistributedAgent agent)
            throws AgentException

Unregister the given IDistributedAgent.

Parameters:

agent - An IDistributedAgent

Returns:

true if this agent has been successfully unregistered

Throws:

AgentException - if the Agent cannot be unregistered.

getRegisteredAgents

Set<IDistributedAgent> getRegisteredAgents()

Returns all the registered IDistributedAgents. The returned set is a copy of the currently registered IDistributedAgents and is therefore thread-safe.

Returns:

All the registered IDistributedAgents

getAddressAsString

String getAddressAsString()

Returns the address of the current (local) instance.

getAddress

IAddress getAddress()

Returns the IAddress of the current (local) instance.

setMessageContext

<ContextT> void setMessageContext(Class<ContextT> contextType,
                                  ContextT context)

Sets a local message context for a given type. This should never be called concurrently with another setMessageContext(Class, Object) or a getMessageContext(Class).

Type Parameters:

ContextT - the context associated to the message. It is set before the message computation on a remote instance

Parameters:

contextType - The context type

context - The actual context object

getMessageContext

<ContextT> ContextT getMessageContext(Class<ContextT> contextType)

Returns the local message context of the given kind.

Type Parameters:

ContextT - the context associated to the message. It is set before the message computation on a remote instance

Parameters:

contextType - The type of context we want

Returns:

The local context of the requested type

getExecutorService

IDistributedExecutorService getExecutorService()

Returns the ExecutorService used by the messenger.

getView

IClusterView getView()

Returns the IClusterView of the current cluster.

If the messenger is not started or paused, null is returned. Otherwise, a non-null value is returned.
Notice it returns the most recent view of the cluster each time this method is called. By consequence, two consecutive calls to this method may return a different result.