org.jgroups.blocks

Class MessageDispatcher

java.lang.Object

org.jgroups.blocks.MessageDispatcher

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, AsyncRequestHandler, RequestHandler, ChannelListener

Direct Known Subclasses:

MuxMessageDispatcher, RpcDispatcher

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

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

Fields

Modifier and Type	Field and Description
protected boolean	async_dispatching
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 org.jgroups.blocks.MessageDispatcher.ProtocolAdapter	prot_adapter
protected RequestHandler	req_handler
protected RpcStats	rpc_stats
protected boolean	wrap_exceptions

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
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<RspList<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<RspList<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
void	close()
RequestCorrelator	correlator()
<T extends MessageDispatcher> T	correlator(RequestCorrelator c)
protected void	correlatorStarted()
protected RequestCorrelator	createRequestCorrelator(Protocol transport, RequestHandler handler, Address local_addr)
void	done(long req_id)
boolean	extendedStats()
MessageDispatcher	extendedStats(boolean fl)
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)
RpcStats	rpcStats()
<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()
boolean	wrapExceptions()
MessageDispatcher	wrapExceptions(boolean flag)

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

wrap_exceptions

protected boolean wrap_exceptions

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

channel_listeners

protected final java.util.Set<ChannelListener> channel_listeners

rpc_stats

protected final RpcStats rpc_stats

Constructor Detail

MessageDispatcher

public MessageDispatcher()

MessageDispatcher

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

MessageDispatcher

public MessageDispatcher(Channel channel,
                         RequestHandler req_handler)

MessageDispatcher

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

Method Detail

rpcStats

public RpcStats rpcStats()

extendedStats

public MessageDispatcher extendedStats(boolean fl)

extendedStats

public boolean extendedStats()

asyncDispatching

public boolean asyncDispatching()

asyncDispatching

public MessageDispatcher asyncDispatching(boolean flag)

wrapExceptions

public boolean wrapExceptions()

wrapExceptions

public MessageDispatcher wrapExceptions(boolean flag)

getProtocolAdapter

public UpHandler getProtocolAdapter()

correlator

public RequestCorrelator correlator()

correlator

public <T extends MessageDispatcher> T correlator(RequestCorrelator c)

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()

close

public void close()
           throws java.io.IOException

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.IOException

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<RspList<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<RspList<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