Package org.jgroups.blocks

Class MessageDispatcher

java.lang.Object
org.jgroups.blocks.MessageDispatcher
All Implemented Interfaces:
Closeable, AutoCloseable, RequestHandler, ChannelListener
Direct Known Subclasses:
RpcDispatcher
public class MessageDispatcher extends Object implements RequestHandler, Closeable, 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.

  • Field Details

    • channel

      protected JChannel channel

    • corr

      protected RequestCorrelator corr

    • receiver

      protected Receiver receiver

    • req_handler

      protected RequestHandler req_handler

    • async_dispatching

      protected boolean async_dispatching

    • async_rsp_handling

      protected boolean async_rsp_handling
      When enabled, responses are handled by the common ForkJoinPool (https://issues.redhat.com/browse/JGRP-2644)

    • wrap_exceptions

      protected boolean wrap_exceptions

    • prot_adapter

      protected MessageDispatcher.ProtocolAdapter prot_adapter

    • members

      protected volatile Collection<Address> members

    • local_addr

      protected Address local_addr

    • log

      protected final Log log

    • empty_rsplist

      protected static final RspList empty_rsplist

    • empty_group_request

      protected static final GroupRequest empty_group_request

  • Constructor Details

    • MessageDispatcher

      public MessageDispatcher()

    • MessageDispatcher

      public MessageDispatcher(JChannel channel)

    • MessageDispatcher

      public MessageDispatcher(JChannel channel, RequestHandler req_handler)

  • Method Details

    • getChannel

      public JChannel getChannel()

    • getCorrelator

      public RequestCorrelator getCorrelator()

    • correlator

      public RequestCorrelator correlator()

    • getAsyncDispatching

      public boolean getAsyncDispatching()

    • asyncDispatching

      public boolean asyncDispatching()

    • asyncRspHandling

      public boolean asyncRspHandling()

    • asyncRspHandling

      public MessageDispatcher asyncRspHandling(boolean f)

    • getWrapExceptions

      public boolean getWrapExceptions()

    • wrapExceptions

      public boolean wrapExceptions()

    • getProtocolAdapter

      public UpHandler getProtocolAdapter()

    • protocolAdapter

      public UpHandler protocolAdapter()

    • rpcStats

      public RpcStats rpcStats()

    • setChannel

      public <X extends MessageDispatcher> X setChannel(JChannel ch)

    • setCorrelator

      public <X extends MessageDispatcher> X setCorrelator(RequestCorrelator c)

    • correlator

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

    • setReceiver

      public <X extends MessageDispatcher> X setReceiver(Receiver r)

    • setRequestHandler

      public <X extends MessageDispatcher> X setRequestHandler(RequestHandler rh)

    • setAsynDispatching

      public <X extends MessageDispatcher> X setAsynDispatching(boolean flag)

    • asyncDispatching

      public <X extends MessageDispatcher> X asyncDispatching(boolean flag)

    • setWrapExceptions

      public <X extends MessageDispatcher> X setWrapExceptions(boolean flag)

    • wrapExceptions

      public <X extends MessageDispatcher> X wrapExceptions(boolean flag)

    • setMembers

      protected <X extends MessageDispatcher> X setMembers(List<Address> new_mbrs)

    • start

      public <X extends MessageDispatcher> X start()

    • createRequestCorrelator

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

    • close

      public void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException

    • stop

      public <X extends MessageDispatcher> X stop()

    • installUpHandler

      protected <X extends MessageDispatcher> X installUpHandler(UpHandler handler, boolean canReplace)
      Sets the given UpHandler as the UpHandler for the channel. 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 can be replaced; false if this method shouldn't install

    • castMessage

      public <T> RspList<T> castMessage(Collection<Address> dests, Message msg, RequestOptions opts) throws 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
      opts - A set of options that govern the call. See RequestOptions for details
      Returns:
      RspList A list of Rsp elements, or null if the RPC is asynchronous
      Throws:
      Exception - If the request cannot be sent
      Since:
      2.9

    • castMessageWithFuture

      public <T> CompletableFuture<RspList<T>> castMessageWithFuture(Collection<Address> dests, Message msg, RequestOptions opts) throws 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
      opts - A set of options that govern the call. See RequestOptions for details
      Returns:
      CompletableFuture A future from which the results (RspList) can be retrieved, or null if the request was sent asynchronously
      Throws:
      Exception - If the request cannot be sent

    • cast

      protected <T> GroupRequest<T> cast(Collection<Address> dests, Message msg, RequestOptions options, boolean block_for_results) throws Exception
      Throws:
      Exception

    • sendMessage

      public <T> T sendMessage(Message msg, RequestOptions opts) throws Exception
      Sends a unicast message and - depending on the options - returns a result
      Parameters:
      msg - the payload to send
      opts - the options to be used
      Returns:
      T the result. Null if the call is asynchronous (non-blocking) or if the response is null
      Throws:
      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> CompletableFuture<T> sendMessageWithFuture(Message msg, RequestOptions opts) throws Exception
      Sends a unicast message to the target defined by msg.getDest() and returns a future
      Parameters:
      msg - the payload to send
      opts - the options
      Returns:
      CompletableFuture A future from which the result can be fetched, or null if the call was asynchronous
      Throws:
      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

    • handle

      public Object handle(Message msg) throws Exception
      Description copied from interface: RequestHandler
      Processes a request synchronously, ie. on the thread invoking this handler
      Specified by:
      handle in interface RequestHandler
      Parameters:
      msg - the message containing the request
      Returns:
      the object, rceeived as result, or null (void method)
      Throws:
      Exception

    • handle

      public void handle(Message request, Response response) throws Exception
      Description copied from interface: RequestHandler
      Processes a request asynchronously. This could be done (for example) 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 RequestHandler
      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:
      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

    • _sendMessage

      protected <T> UnicastRequest<T> _sendMessage(Message msg, RequestOptions opts) throws Exception
      Throws:
      Exception

    • handleUpEvent

      protected Object handleUpEvent(Event evt) throws Exception
      Throws:
      Exception

    • getState

      protected boolean getState(OutputStream out) throws Exception
      Throws:
      Exception

    • setState

      protected boolean setState(InputStream in) throws Exception
      Throws:
      Exception

    • channelDisconnected

      public void channelDisconnected(JChannel 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(JChannel channel)
      Description copied from interface: ChannelListener
      Channel has been closed notification callback
      Specified by:
      channelClosed in interface ChannelListener
      Parameters:
      channel - the closed channel