org.jgroups.blocks

## Class MessageDispatcher

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

All Implemented Interfaces:
  RequestHandler

Direct Known Subclasses:
  MuxMessageDispatcher, 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.

Author:
  Bela Ban

### Field Summary

Fields
`protected PullPushAdapter` `adapter`
`protected Channel` `channel`
`protected RequestCorrelator` `corr`
`protected org.jgroups.blocks.MessageDispatcher.PullPushHandler` `handler`
`protected boolean` `hardware_multicast_supported`
`protected java.io.Serializable` `id`
`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 org.jgroups.blocks.MessageDispatcher.TransportAdapter` `transport_adapter`

### Constructor Summary

Constructors
Constructor and Description
`MessageDispatcher()`
`MessageDispatcher(Channel channel, MessageListener l, MembershipListener l2)`
`MessageDispatcher(Channel channel, MessageListener l, MembershipListener l2, boolean deadlock_detection)` Deprecated.
`MessageDispatcher(Channel channel, MessageListener l, MembershipListener l2, boolean deadlock_detection, boolean concurrent_processing)` Deprecated.
`MessageDispatcher(Channel channel, MessageListener l, MembershipListener l2, RequestHandler req_handler)`
`MessageDispatcher(Channel channel, MessageListener l, MembershipListener l2, RequestHandler req_handler, boolean deadlock_detection)` Deprecated.
`MessageDispatcher(Channel channel, MessageListener l, MembershipListener l2, RequestHandler req_handler, boolean deadlock_detection, boolean concurrent_processing)` Deprecated.
`MessageDispatcher(PullPushAdapter adapter, java.io.Serializable id, MessageListener l, MembershipListener l2)` Deprecated.
`MessageDispatcher(PullPushAdapter adapter, java.io.Serializable id, MessageListener l, MembershipListener l2, RequestHandler req_handler)` Deprecated.
`MessageDispatcher(PullPushAdapter adapter, java.io.Serializable id, MessageListener l, MembershipListener l2, RequestHandler req_handler, boolean concurrent_processing)` Deprecated.

### Method Summary

Methods
`protected GroupRequest` `cast(java.util.Collection<Address> dests, Message msg, RequestOptions options, boolean block_for_results)`
`RspList` `castMessage(java.util.Collection<Address> dests, Message msg, RequestOptions options)` Sends a message to the members listed in dests.
`RspList` `castMessage(java.util.Vector dests, Message msg, int mode, long timeout)` Deprecated.
`RspList` `castMessage(java.util.Vector dests, Message msg, int mode, long timeout, boolean use_anycasting)` Deprecated.
`RspList` `castMessage(java.util.Vector dests, Message msg, int mode, long timeout, boolean use_anycasting, RspFilter filter)` Deprecated.
`NotifyingFuture<RspList>` `castMessageWithFuture(java.util.Collection<Address> dests, Message msg, RequestOptions options)`
`NotifyingFuture<RspList>` `castMessageWithFuture(java.util.Vector dests, Message msg, int mode, long timeout, boolean use_anycasting, RspFilter filter)` Deprecated.
`protected void` `correlatorStarted()`
`protected RequestCorrelator` `createRequestCorrelator(java.lang.Object transport, RequestHandler handler, Address local_addr)`
`void` `done(long req_id)`
`Channel` `getChannel()` Offers access to the underlying Channel.
`boolean` `getConcurrentProcessing()` Deprecated.
`boolean` `getDeadlockDetection()` Deprecated.
`protected java.util.Collection` `getMembers()` Returns a copy of members
`MessageListener` `getMessageListener()` Gives access to the currently configured MessageListener.
`UpHandler` `getProtocolAdapter()`
`java.lang.Object` `handle(Message msg)`
`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` `send(Message msg)` Deprecated.
`java.lang.Object` `sendMessage(Message msg, int mode, long timeout)` Deprecated. Use `sendMessage(org.jgroups.Message, RequestOptions)` instead
`java.lang.Object` `sendMessage(Message msg, RequestOptions opts)`
`<T> NotifyingFuture<T>` `sendMessageWithFuture(Message msg, int mode, long timeout)` Deprecated.
`<T> NotifyingFuture<T>` `sendMessageWithFuture(Message msg, RequestOptions options)`
`void` `setChannel(Channel ch)`
`void` `setConcurrentProcessing(boolean flag)` Deprecated.
`void` `setDeadlockDetection(boolean flag)` Deprecated.
`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<Address> members

#### local_addr

    protected Address local_addr

#### adapter

    protected PullPushAdapter adapter

#### handler

    protected org.jgroups.blocks.MessageDispatcher.PullPushHandler handler

#### id

    protected java.io.Serializable id

#### log

    protected final Log log

#### hardware_multicast_supported

    protected boolean hardware_multicast_supported

### Constructor Detail

#### MessageDispatcher

    public MessageDispatcher()

#### MessageDispatcher

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

#### MessageDispatcher

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

Deprecated.

#### MessageDispatcher

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

Deprecated.

#### MessageDispatcher

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

#### MessageDispatcher

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

Deprecated.

#### MessageDispatcher

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

Deprecated.

#### MessageDispatcher

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

Deprecated.

#### MessageDispatcher

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

Deprecated.

#### MessageDispatcher

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

Deprecated.

### Method Detail

#### getProtocolAdapter

    public UpHandler getProtocolAdapter()

#### getMembers

    protected java.util.Collection getMembers()

Returns a copy of members

#### getDeadlockDetection

    @Deprecated
    public boolean getDeadlockDetection()

Deprecated.

#### setDeadlockDetection

    @Deprecated
    public void setDeadlockDetection(boolean flag)

Deprecated.

#### getConcurrentProcessing

    @Deprecated
    public boolean getConcurrentProcessing()

Deprecated.

#### setConcurrentProcessing

    @Deprecated
    public void setConcurrentProcessing(boolean flag)

Deprecated.

#### start

    public void start()

#### createRequestCorrelator

    protected RequestCorrelator createRequestCorrelator(java.lang.Object 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()

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.

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

#### send

    @Deprecated
    public void send(Message msg)
              throws ChannelNotConnectedException,
                     ChannelClosedException

Deprecated.

Throws:
  `ChannelNotConnectedException`
  `ChannelClosedException`

#### castMessage

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

Deprecated.

#### castMessage

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

Deprecated.

#### castMessage

    @Deprecated
    public RspList castMessage(java.util.Vector dests,
                                 Message msg,
                                 int mode,
                                 long timeout,
                                 boolean use_anycasting,
                                 RspFilter filter)

Deprecated.

#### castMessage

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

Sends a message to the members listed in dests. If dests is null, the message is sent to all current group members.

Parameters:
  `dests` - A list of group members. The message is sent to all members of the current group if null
  `msg` - The message to be sent
  `options` - A set of options that govern the call. See `RequestOptions` for details
Returns:
Since:
  2.9

#### castMessageWithFuture

    @Deprecated
    public NotifyingFuture<RspList> castMessageWithFuture(java.util.Vector dests,
                                                            Message msg,
                                                            int mode,
                                                            long timeout,
                                                            boolean use_anycasting,
                                                            RspFilter filter)

Deprecated.

#### castMessageWithFuture

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

#### cast

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

#### done

    public void done(long req_id)

#### sendMessage

    @Deprecated
    public java.lang.Object sendMessage(Message msg,
                                          int mode,
                                          long timeout)
                                 throws TimeoutException,
                                        SuspectedException

Deprecated. Use `sendMessage(org.jgroups.Message, RequestOptions)` instead
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`

#### sendMessage

    public java.lang.Object sendMessage(Message msg,
                               RequestOptions opts)
                                 throws TimeoutException,
                                        SuspectedException

Throws:
  `TimeoutException`
  `SuspectedException`

#### sendMessageWithFuture

    @Deprecated
    public <T> NotifyingFuture<T> sendMessageWithFuture(Message msg,
                                                          int mode,
                                                          long timeout)
                                             throws TimeoutException,
                                                    SuspectedException

Deprecated.

Throws:
  `TimeoutException`
  `SuspectedException`

#### sendMessageWithFuture

    public <T> NotifyingFuture<T> sendMessageWithFuture(Message msg,
                                               RequestOptions options)
                                             throws TimeoutException,
                                                    SuspectedException

Throws:
  `TimeoutException`
  `SuspectedException`

#### handle

    public java.lang.Object handle(Message msg)

Specified by:
  `handle` in interface `RequestHandler`