org.jgroups.blocks
Class MessageDispatcher

java.lang.Object
  org.jgroups.blocks.MessageDispatcher

All Implemented Interfaces:

AsyncRequestHandler, RequestHandler, ChannelListener

Direct Known Subclasses:

MuxMessageDispatcher, RpcDispatcher

public class MessageDispatcher
extends java.lang.Object
implements AsyncRequestHandler, ChannelListener

Provides synchronous and asynchronous message sending with request-response correlation; i.e., matching responses with the original request. It also offers push-style message reception (by internally using the PullPushAdapter).

Channels are simple patterns to asynchronously send a receive messages. However, a significant number of communication patterns in group communication require synchronous communication. For example, a sender would like to send a message to the group and wait for all responses. Or another application would like to send a message to the group and wait only until the majority of the receivers have sent a response, or until a timeout occurred. MessageDispatcher offers a combination of the above pattern with other patterns.

Used on top of channel to implement group requests. Client's handle() method is called when request is received. Is the equivalent of RpcProtocol on the application instead of protocol level.

Author:

Bela Ban

Field Summary

protected java.util.concurrent.atomic.AtomicInteger	async_anycasts
protected boolean	async_dispatching
protected java.util.concurrent.atomic.AtomicInteger	async_multicasts
protected java.util.concurrent.atomic.AtomicInteger	async_unicasts
protected Channel	channel
protected java.util.Set<ChannelListener>	channel_listeners
protected RequestCorrelator	corr
protected boolean	hardware_multicast_supported
protected Address	local_addr
protected Log	log
protected java.util.Collection<Address>	members
protected MembershipListener	membership_listener
protected MessageListener	msg_listener
protected DiagnosticsHandler.ProbeHandler	probe_handler
protected org.jgroups.blocks.MessageDispatcher.ProtocolAdapter	prot_adapter
protected RequestHandler	req_handler
protected java.util.concurrent.atomic.AtomicInteger	sync_anycasts
protected java.util.concurrent.atomic.AtomicInteger	sync_multicasts
protected java.util.concurrent.atomic.AtomicInteger	sync_unicasts

Constructor Summary

MessageDispatcher()

MessageDispatcher(Channel channel, MessageListener l, MembershipListener l2)

MessageDispatcher(Channel channel, MessageListener l, MembershipListener l2, RequestHandler req_handler)

Method Summary

void	addChannelListener(ChannelListener l) Adds a new channel listener to be notified on the channel's state change.
boolean	asyncDispatching()
MessageDispatcher	asyncDispatching(boolean flag)
protected <T> GroupRequest<T>	cast(java.util.Collection<Address> dests, Message msg, RequestOptions options, boolean block_for_results)
protected <T> GroupRequest<T>	cast(java.util.Collection<Address> dests, Message msg, RequestOptions options, boolean block_for_results, FutureListener<T> listener)
<T> RspList<T>	castMessage(java.util.Collection<Address> dests, Message msg, RequestOptions options) Sends a message to all members and expects responses from members in dests (if non-null).
<T> NotifyingFuture<RspList<T>>	castMessageWithFuture(java.util.Collection<Address> dests, Message msg, RequestOptions options) Sends a message to all members and expects responses from members in dests (if non-null).
<T> NotifyingFuture<RspList<T>>	castMessageWithFuture(java.util.Collection<Address> dests, Message msg, RequestOptions options, FutureListener<T> listener) Sends a message to all members and expects responses from members in dests (if non-null).
void	channelClosed(Channel channel) Channel has been closed notification callback
void	channelConnected(Channel channel) Channel has been connected notification callback
void	channelDisconnected(Channel channel) Channel has been disconnected notification callback
protected void	correlatorStarted()
protected RequestCorrelator	createRequestCorrelator(Protocol transport, RequestHandler handler, Address local_addr)
void	done(long req_id)
Channel	getChannel()
MessageListener	getMessageListener()
UpHandler	getProtocolAdapter()
java.lang.Object	handle(Message msg)
void	handle(Message request, Response response) Invokes a request.
protected java.lang.Object	handleUpEvent(Event evt)
protected void	installUpHandler(UpHandler handler, boolean canReplace) Sets the given UpHandler as the UpHandler for the channel, or, if the channel already has a Muxer installed as it's UpHandler, sets the given handler as the Muxer's default handler.
void	removeChannelListener(ChannelListener l)
<T> T	sendMessage(Message msg, RequestOptions opts) Sends a unicast message and - depending on the options - returns a result
<T> NotifyingFuture<T>	sendMessageWithFuture(Message msg, RequestOptions options) Sends a unicast message to the target defined by msg.getDest() and returns a future
<T> NotifyingFuture<T>	sendMessageWithFuture(Message msg, RequestOptions options, FutureListener<T> listener) Sends a unicast message to the target defined by msg.getDest() and returns a future
void	setChannel(Channel ch)
protected void	setMembers(java.util.List<Address> new_mbrs) If this dispatcher is using a user-provided PullPushAdapter, then need to set the members from the adapter initially since viewChange has most likely already been called in PullPushAdapter.
void	setMembershipListener(MembershipListener l)
void	setMessageListener(MessageListener l)
void	setRequestHandler(RequestHandler rh)
void	start()
void	stop()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

channel

protected Channel channel

corr

protected RequestCorrelator corr

msg_listener

protected MessageListener msg_listener

membership_listener

protected MembershipListener membership_listener

req_handler

protected RequestHandler req_handler

async_dispatching

protected boolean async_dispatching

prot_adapter

protected org.jgroups.blocks.MessageDispatcher.ProtocolAdapter prot_adapter

members

protected volatile java.util.Collection<Address> members

local_addr

protected Address local_addr

log

protected final Log log

hardware_multicast_supported

protected boolean hardware_multicast_supported

sync_unicasts

protected final java.util.concurrent.atomic.AtomicInteger sync_unicasts

async_unicasts

protected final java.util.concurrent.atomic.AtomicInteger async_unicasts

sync_multicasts

protected final java.util.concurrent.atomic.AtomicInteger sync_multicasts

async_multicasts

protected final java.util.concurrent.atomic.AtomicInteger async_multicasts

sync_anycasts

protected final java.util.concurrent.atomic.AtomicInteger sync_anycasts

async_anycasts

protected final java.util.concurrent.atomic.AtomicInteger async_anycasts

channel_listeners

protected final java.util.Set<ChannelListener> channel_listeners

probe_handler

protected final DiagnosticsHandler.ProbeHandler probe_handler

Constructor Detail

MessageDispatcher

public MessageDispatcher()

MessageDispatcher

public MessageDispatcher(Channel channel,
                         MessageListener l,
                         MembershipListener l2)

MessageDispatcher

public MessageDispatcher(Channel channel,
                         MessageListener l,
                         MembershipListener l2,
                         RequestHandler req_handler)

Method Detail

asyncDispatching

public boolean asyncDispatching()

asyncDispatching

public MessageDispatcher asyncDispatching(boolean flag)

getProtocolAdapter

public UpHandler getProtocolAdapter()

setMembers

protected void setMembers(java.util.List<Address> new_mbrs)

If this dispatcher is using a user-provided PullPushAdapter, then need to set the members from the adapter initially since viewChange has most likely already been called in PullPushAdapter.

addChannelListener

public void addChannelListener(ChannelListener l)

Adds a new channel listener to be notified on the channel's state change.

removeChannelListener

public void removeChannelListener(ChannelListener l)

start

public void start()

createRequestCorrelator

protected RequestCorrelator createRequestCorrelator(Protocol transport,
                                                    RequestHandler handler,
                                                    Address local_addr)

correlatorStarted

protected void correlatorStarted()

stop

public void stop()

setMessageListener

public final void setMessageListener(MessageListener l)

getMessageListener

public MessageListener getMessageListener()

setMembershipListener

public final void setMembershipListener(MembershipListener l)

setRequestHandler

public final void setRequestHandler(RequestHandler rh)

getChannel

public Channel getChannel()

setChannel

public void setChannel(Channel ch)

installUpHandler

protected void installUpHandler(UpHandler handler,
                                boolean canReplace)

Sets the given UpHandler as the UpHandler for the channel, or, if the channel already has a Muxer installed as it's UpHandler, sets the given handler as the Muxer's default handler. If the relevant handler is already installed, the canReplace controls whether this method replaces it (after logging a WARN) or simply leaves handler uninstalled.

Passing false as the canReplace value allows callers to use this method to install defaults without concern about inadvertently overriding

Parameters:

handler - the UpHandler to install

canReplace - true if an existing Channel upHandler or Muxer default upHandler can be replaced; false if this method shouldn't install

castMessage

public <T> RspList<T> castMessage(java.util.Collection<Address> dests,
                                  Message msg,
                                  RequestOptions options)
                       throws java.lang.Exception

Sends a message to all members and expects responses from members in dests (if non-null).

Parameters:

dests - A list of group members from which to expect responses (if the call is blocking).

msg - The message to be sent

options - A set of options that govern the call. See RequestOptions for details

Returns:

RspList A list of Rsp elements

Throws:

java.lang.Exception - If the request cannot be sent

Since:

2.9

castMessageWithFuture

public <T> NotifyingFuture<RspList<T>> castMessageWithFuture(java.util.Collection<Address> dests,
                                                             Message msg,
                                                             RequestOptions options,
                                                             FutureListener<T> listener)
                                                  throws java.lang.Exception

Sends a message to all members and expects responses from members in dests (if non-null).

Parameters:

dests - A list of group members from which to expect responses (if the call is blocking).

msg - The message to be sent

options - A set of options that govern the call. See RequestOptions for details

listener - A FutureListener which will be registered (if non null) with the future before the call is invoked

Returns:

NotifyingFuture A future from which the results (RspList) can be retrieved

Throws:

java.lang.Exception - If the request cannot be sent

castMessageWithFuture

public <T> NotifyingFuture<RspList<T>> castMessageWithFuture(java.util.Collection<Address> dests,
                                                             Message msg,
                                                             RequestOptions options)
                                                  throws java.lang.Exception

Sends a message to all members and expects responses from members in dests (if non-null).

Parameters:

dests - A list of group members from which to expect responses (if the call is blocking).

msg - The message to be sent

options - A set of options that govern the call. See RequestOptions for details

Returns:

NotifyingFuture A future from which the results (RspList) can be retrieved

Throws:

java.lang.Exception - If the request cannot be sent

cast

protected <T> GroupRequest<T> cast(java.util.Collection<Address> dests,
                                   Message msg,
                                   RequestOptions options,
                                   boolean block_for_results,
                                   FutureListener<T> listener)
                        throws java.lang.Exception

Throws:

java.lang.Exception

cast

protected <T> GroupRequest<T> cast(java.util.Collection<Address> dests,
                                   Message msg,
                                   RequestOptions options,
                                   boolean block_for_results)
                        throws java.lang.Exception

Throws:

java.lang.Exception

done

public void done(long req_id)

sendMessage

public <T> T sendMessage(Message msg,
                         RequestOptions opts)
              throws java.lang.Exception

Sends a unicast message and - depending on the options - returns a result

Parameters:

msg - the message to be sent. The destination needs to be non-null

opts - the options to be used

Returns:

T the result

Throws:

java.lang.Exception - If there was problem sending the request, processing it at the receiver, or processing it at the sender.

TimeoutException - If the call didn't succeed within the timeout defined in options (if set)

sendMessageWithFuture

public <T> NotifyingFuture<T> sendMessageWithFuture(Message msg,
                                                    RequestOptions options,
                                                    FutureListener<T> listener)
                                         throws java.lang.Exception

Sends a unicast message to the target defined by msg.getDest() and returns a future

Parameters:

msg - The unicast message to be sent. msg.getDest() must not be null

options -

listener - A FutureListener which will be registered (if non null) with the future before the call is invoked

Returns:

NotifyingFuture A future from which the result can be fetched

Throws:

java.lang.Exception - If there was problem sending the request, processing it at the receiver, or processing it at the sender. Future.get() will throw this exception

TimeoutException - If the call didn't succeed within the timeout defined in options (if set)

sendMessageWithFuture

public <T> NotifyingFuture<T> sendMessageWithFuture(Message msg,
                                                    RequestOptions options)
                                         throws java.lang.Exception

Sends a unicast message to the target defined by msg.getDest() and returns a future

Parameters:

msg - The unicast message to be sent. msg.getDest() must not be null

options -

Returns:

NotifyingFuture A future from which the result can be fetched

Throws:

java.lang.Exception - If there was problem sending the request, processing it at the receiver, or processing it at the sender. Future.get() will throw this exception

TimeoutException - If the call didn't succeed within the timeout defined in options (if set)

handle

public java.lang.Object handle(Message msg)
                        throws java.lang.Exception

Specified by:

handle in interface RequestHandler

Throws:

java.lang.Exception

handle

public void handle(Message request,
                   Response response)
            throws java.lang.Exception

Description copied from interface: AsyncRequestHandler

Invokes a request. This should be done asynchronously, e.g. by dispatching this to a thread pool. When done, if a response is needed (e.g. in case of a sync RPC), Response.send(Object,boolean) should be called.

Specified by:

handle in interface AsyncRequestHandler

Parameters:

request - The request

response - The response implementation. Contains information needed to send the reply (e.g. a request ID). If no response is required, e.g. because this is an asynchronous RPC, then response will be null.

Throws:

java.lang.Exception - If an exception is thrown (e.g. in case of an issue submitting the request to a thread pool, the exception will be taken as return value and will be sent as a response. In this case, Response.send(Object,boolean) must not be called

channelConnected

public void channelConnected(Channel channel)

Description copied from interface: ChannelListener

Channel has been connected notification callback

Specified by:

channelConnected in interface ChannelListener

Parameters:

channel - the channel that has been connected

channelDisconnected

public void channelDisconnected(Channel channel)

Description copied from interface: ChannelListener

Channel has been disconnected notification callback

Specified by:

channelDisconnected in interface ChannelListener

Parameters:

channel - the disconnected channel

channelClosed

public void channelClosed(Channel channel)

Description copied from interface: ChannelListener

Channel has been closed notification callback

Specified by:

channelClosed in interface ChannelListener

Parameters:

channel - the closed channel

handleUpEvent

protected java.lang.Object handleUpEvent(Event evt)
                                  throws java.lang.Exception

Throws:

java.lang.Exception