org.jgroups.blocks
Class MessageDispatcher

java.lang.Object
  extended by org.jgroups.blocks.MessageDispatcher
All Implemented Interfaces:
RequestHandler
Direct Known Subclasses:
RpcDispatcher

public class MessageDispatcher
extends java.lang.Object
implements RequestHandler

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.

Version:
$Id: MessageDispatcher.java,v 1.60.2.3 2007/03/08 10:14:45 belaban Exp $
Author:
Bela Ban

Field Summary
protected  PullPushAdapter adapter
           
protected  Channel channel
           
protected  boolean concurrent_processing
          Process items on the queue concurrently (RequestCorrelator).
protected  RequestCorrelator corr
           
protected  boolean deadlock_detection
           
protected  org.jgroups.blocks.MessageDispatcher.PullPushHandler handler
           
protected  java.io.Serializable id
           
protected  Address local_addr
           
protected  org.apache.commons.logging.Log log
           
protected  java.util.Collection members
           
protected  MembershipListener membership_listener
           
protected  MessageListener msg_listener
           
protected  org.jgroups.blocks.MessageDispatcher.ProtocolAdapter prot_adapter
           
protected  RequestHandler req_handler
           
protected  org.jgroups.blocks.MessageDispatcher.TransportAdapter transport_adapter
           
 
Constructor Summary
MessageDispatcher(Channel channel, MessageListener l, MembershipListener l2)
           
MessageDispatcher(Channel channel, MessageListener l, MembershipListener l2, boolean deadlock_detection)
           
MessageDispatcher(Channel channel, MessageListener l, MembershipListener l2, boolean deadlock_detection, boolean concurrent_processing)
           
MessageDispatcher(Channel channel, MessageListener l, MembershipListener l2, RequestHandler req_handler)
           
MessageDispatcher(Channel channel, MessageListener l, MembershipListener l2, RequestHandler req_handler, boolean deadlock_detection)
           
MessageDispatcher(Channel channel, MessageListener l, MembershipListener l2, RequestHandler req_handler, boolean deadlock_detection, boolean concurrent_processing)
           
MessageDispatcher(PullPushAdapter adapter, java.io.Serializable id, MessageListener l, MembershipListener l2)
           
MessageDispatcher(PullPushAdapter adapter, java.io.Serializable id, MessageListener l, MembershipListener l2, RequestHandler req_handler)
           
MessageDispatcher(PullPushAdapter adapter, java.io.Serializable id, MessageListener l, MembershipListener l2, RequestHandler req_handler, boolean concurrent_processing)
           
 
Method Summary
 void castMessage(java.util.Vector dests, long req_id, Message msg, RspCollector coll)
          Multicast a message request to all members in dests and receive responses via the RspCollector interface.
 RspList castMessage(java.util.Vector dests, Message msg, int mode, long timeout)
           
 RspList castMessage(java.util.Vector dests, Message msg, int mode, long timeout, boolean use_anycasting)
          Cast a message to all members, and wait for mode responses.
protected  void correlatorStarted()
           
 void done(long req_id)
           
 Channel getChannel()
          Offers access to the underlying Channel.
protected  java.util.Collection getMembers()
          Returns a copy of members
 MessageListener getMessageListener()
          Gives access to the currently configured MessageListener.
 java.lang.Object handle(Message msg)
           
 void send(Message msg)
           
 java.lang.Object sendMessage(Message msg, int mode, long timeout)
          Sends a message to a single member (destination = msg.dest) and returns the response.
 void setConcurrentProcessing(boolean flag)
           
 void setDeadlockDetection(boolean flag)
           
 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

prot_adapter

protected org.jgroups.blocks.MessageDispatcher.ProtocolAdapter prot_adapter

transport_adapter

protected org.jgroups.blocks.MessageDispatcher.TransportAdapter transport_adapter

members

protected final java.util.Collection members

local_addr

protected Address local_addr

deadlock_detection

protected boolean deadlock_detection

adapter

protected PullPushAdapter adapter

handler

protected org.jgroups.blocks.MessageDispatcher.PullPushHandler handler

id

protected java.io.Serializable id

log

protected final org.apache.commons.logging.Log log

concurrent_processing

protected boolean concurrent_processing
Process items on the queue concurrently (RequestCorrelator). The default is to wait until the processing of an item has completed before fetching the next item from the queue. Note that setting this to true may destroy the properties of a protocol stack, e.g total or causal order may not be guaranteed. Set this to true only if you know what you're doing !

Constructor Detail

MessageDispatcher

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

MessageDispatcher

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

MessageDispatcher

public MessageDispatcher(Channel channel,
                         MessageListener l,
                         MembershipListener l2,
                         boolean deadlock_detection,
                         boolean concurrent_processing)

MessageDispatcher

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

MessageDispatcher

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

MessageDispatcher

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

MessageDispatcher

public MessageDispatcher(PullPushAdapter adapter,
                         java.io.Serializable id,
                         MessageListener l,
                         MembershipListener l2)

MessageDispatcher

public MessageDispatcher(PullPushAdapter adapter,
                         java.io.Serializable id,
                         MessageListener l,
                         MembershipListener l2,
                         RequestHandler req_handler)

MessageDispatcher

public MessageDispatcher(PullPushAdapter adapter,
                         java.io.Serializable id,
                         MessageListener l,
                         MembershipListener l2,
                         RequestHandler req_handler,
                         boolean concurrent_processing)
Method Detail

getMembers

protected java.util.Collection getMembers()
Returns a copy of members


setDeadlockDetection

public void setDeadlockDetection(boolean flag)

setConcurrentProcessing

public void setConcurrentProcessing(boolean flag)

start

public final void start()

correlatorStarted

protected void correlatorStarted()

stop

public void stop()

setMessageListener

public final void setMessageListener(MessageListener l)

getMessageListener

public MessageListener getMessageListener()
Gives access to the currently configured MessageListener. Returns null if there is no configured MessageListener.


setMembershipListener

public final void setMembershipListener(MembershipListener l)

setRequestHandler

public final void setRequestHandler(RequestHandler rh)

getChannel

public Channel getChannel()
Offers access to the underlying Channel.

Returns:
a reference to the underlying Channel.

send

public void send(Message msg)
          throws ChannelNotConnectedException,
                 ChannelClosedException
Throws:
ChannelNotConnectedException
ChannelClosedException

castMessage

public RspList castMessage(java.util.Vector dests,
                           Message msg,
                           int mode,
                           long timeout)

castMessage

public RspList castMessage(java.util.Vector dests,
                           Message msg,
                           int mode,
                           long timeout,
                           boolean use_anycasting)
Cast a message to all members, and wait for mode responses. The responses are returned in a response list, where each response is associated with its sender.

Uses GroupRequest.

Parameters:
dests - The members to which the message is to be sent. If it is null, then the message is sent to all members
msg - The message to be sent to n members
mode - Defined in GroupRequest. The number of responses to wait for:
  1. GET_FIRST: return the first response received.
  2. GET_ALL: wait for all responses (minus the ones from suspected members)
  3. GET_MAJORITY: wait for a majority of all responses (relative to the grp size)
  4. GET_ABS_MAJORITY: wait for majority (absolute, computed once)
  5. GET_N: wait for n responses (may block if n > group size)
  6. GET_NONE: wait for no responses, return immediately (non-blocking)
timeout - If 0: wait forever. Otherwise, wait for mode responses or timeout time.
Returns:
RspList A list of responses. Each response is an Object and associated to its sender.

castMessage

public void castMessage(java.util.Vector dests,
                        long req_id,
                        Message msg,
                        RspCollector coll)
Multicast a message request to all members in dests and receive responses via the RspCollector interface. When done receiving the required number of responses, the caller has to call done(req_id) on the underlyinh RequestCorrelator, so that the resources allocated to that request can be freed.

Parameters:
dests - The list of members from which to receive responses. Null means all members
req_id - The ID of the request. Used by the underlying RequestCorrelator to correlate responses with requests
msg - The request to be sent
coll - The sender needs to provide this interface to collect responses. Call will return immediately if this is null

done

public void done(long req_id)

sendMessage

public java.lang.Object sendMessage(Message msg,
                                    int mode,
                                    long timeout)
                             throws TimeoutException,
                                    SuspectedException
Sends a message to a single member (destination = msg.dest) and returns the response. The message's destination must be non-zero !

Throws:
TimeoutException
SuspectedException

handle

public java.lang.Object handle(Message msg)
Specified by:
handle in interface RequestHandler


Copyright ? 1998-2006 Bela Ban. All Rights Reserved.