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
    Modifier and Type | Field and Description
    --- | ---
    `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
    Modifier and Type | Method and Description
    --- | ---
    `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`

Copyright © 1998-2009 Bela Ban / Red Hat. All Rights Reserved.