Package org.jgroups.blocks

Class MessageDispatcher

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

    Author:
    Bela Ban

    • Field Detail

      • 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

      • members

        protected volatile java.util.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 Detail

      • MessageDispatcher

        public MessageDispatcher()

      • MessageDispatcher

        public MessageDispatcher​(JChannel channel)

    • Method Detail

      • getChannel

        public JChannel getChannel()

      • getAsyncDispatching

        public boolean getAsyncDispatching()

      • asyncDispatching

        public boolean asyncDispatching()

      • asyncRspHandling

        public boolean asyncRspHandling()

      • getWrapExceptions

        public boolean getWrapExceptions()

      • wrapExceptions

        public boolean wrapExceptions()

      • getProtocolAdapter

        public UpHandler getProtocolAdapter()

      • protocolAdapter

        public UpHandler protocolAdapter()

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

      • close

        public void close()
           throws java.io.IOException
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Throws:
        java.io.IOException

      • 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​(java.util.Collection<Address> dests,
                                  Message msg,
                                  RequestOptions opts)
                           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
        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:
        java.lang.Exception - If the request cannot be sent
        Since:
        2.9

      • castMessageWithFuture

        public <T> java.util.concurrent.CompletableFuture<RspList<T>> castMessageWithFuture​(java.util.Collection<Address> dests,
                                                                                    Message msg,
                                                                                    RequestOptions opts)
                                                                             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
        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:
        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)
                            throws java.lang.Exception
        Throws:
        java.lang.Exception

      • 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 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:
        java.lang.Exception - If there was problem sending the request, processing it at the receiver, or processing it at the sender.
        java.util.concurrent.TimeoutException - If the call didn't succeed within the timeout defined in options (if set)

      • sendMessageWithFuture

        public <T> java.util.concurrent.CompletableFuture<T> sendMessageWithFuture​(Message msg,
                                                                           RequestOptions opts)
                                                                    throws java.lang.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:
        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

      • handle

        public java.lang.Object handle​(Message msg)
                        throws java.lang.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:
        java.lang.Exception

      • handle

        public void handle​(Message request,
                   Response response)
            throws java.lang.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:
        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

      • handleUpEvent

        protected java.lang.Object handleUpEvent​(Event evt)
                                  throws java.lang.Exception
        Throws:
        java.lang.Exception

      • getState

        protected boolean getState​(java.io.OutputStream out)
                    throws java.lang.Exception
        Throws:
        java.lang.Exception

      • setState

        protected boolean setState​(java.io.InputStream in)
                    throws java.lang.Exception
        Throws:
        java.lang.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