Package com.pushtechnology.diffusion.client.features

Interface Messaging

All Superinterfaces:
Feature
public interface Messaging extends Feature
This feature provides a client session with request-response messaging capabilities that can be used to implement application services.

Request-response messaging allows a session to send requests to other sessions. Each receiving session provides a corresponding response, which is returned to the sending session. Each request and response carries an application provided value.

The method used to send a request determines which sessions will receive it. Each request is routed using the provided message path – an application provided string. Two addressing schemes are provided: unaddressed requests and addressed requests.

Unaddressed requests

A session can provide an application service by implementing a handler and registering it with the server. This is somewhat similar to implementing a REST service, except that interactions between the sender and receiver are asynchronous.

Unaddressed requests sent using sendRequest are routed by the server to a handler that has been pre-registered by another session, and matches the message path.

Handlers are registered with addRequestHandler(java.lang.String, java.lang.Class<? extends T>, java.lang.Class<? super R>, com.pushtechnology.diffusion.client.features.Messaging.RequestHandler<T, R>, java.lang.String...). Each session may register at most one handler for a given message path. Optionally, one or more session property names can be provided (see Session for a full description of session properties), in which case the values of the session properties for each recipient session will be returned along with its response. To add a request handler, the control client session must have REGISTER_HANDLER permission. If registering to receive session property values, the session must also have VIEW_SESSION permission.

Routing works as follows:

  1. The session sends the request, providing the message path, the request value and data type, and the expected response type.
  2. The server uses the message path to apply access control. The sender must have the SEND_TO_MESSAGE_HANDLER path permission for the message path, or the request will be rejected.
  3. The server uses the message path to select a pre-registered handler and route the request to the appropriate recipient session. The server will consider all registered handlers and select one registered for the most specific path. If multiple sessions have registered a handler registered for a path, one will be chosen arbitrarily. If there is no registered handler matching the message path, the request will be rejected.
  4. Otherwise, the server forwards the request to one of the sessions registered to handle the message path. The message path is also passed to the recipient session, providing a hierarchical context.
  5. The recipient session processes the request and returns a response to the server, which forwards the response to the sending session.

Registration works across a cluster of servers. If no matching handler is registered on the server to which the sending session is connected, the request will be routed to another server in the cluster that has one.

Addressed requests

Addressed requests provide a way to perform actions on a group of sessions, or to notify sessions of one-off events (for repeating streams of events, use a topic instead).

An addressed request can be sent to a set of sessions using sendRequestToFilter. For the details of session filters, see Session. Sending a request to a filter will match zero or more sessions. Each response received will be passed to the provided callback. As a convenience, an addressed request can be sent a specific session using the overloaded variant of sendRequest that accepts a session id.

Sending an addressed request requires SEND_TO_SESSION permission.

If the sending session is connected to a server belonging to a cluster, the recipient sessions can be connected to other servers in the cluster. The filter will be evaluated against all sessions hosted by the cluster.

To receive addressed requests, a session must set up a local request stream to handle the specific message path, using setRequestStream. When a request is received for the message path, the onRequest method on the stream is triggered. The session should respond using the provided responder. Streams receive an onClose callback when unregistered and an onError callback if the session is closed.

If a request is sent to a session that does not have a matching stream for the message path, an error will be returned to the sending session.

Accessing the feature

Obtain this feature from a session as follows: 

 
 Messaging messaging = session.feature(Messaging.class);
Since:
5.0
Author:
DiffusionData Limited

  • Method Details

    • sendRequest

      <T, R> CompletableFuture<R> sendRequest(String path, T request, Class<T> requestType, Class<R> responseType)
      Send a request. A response is returned when the CompletableFuture has been completed.
      Type Parameters:
      T - request object type
      R - response object type
      Parameters:
      path - the path to send a request to
      request - the request to send
      requestType - the request type
      responseType - the response type
      Returns:
      a CompletableFuture that completes when a response has been received by a handler.If the task completes successfully, the CompletableFuture result will be the response (to the request) of type R.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Throws:
      IllegalArgumentException - if there is no data type matching the request type parameter
      Since:
      6.0

    • setRequestStream

      <T, R> Messaging.RequestStream<?,?> setRequestStream(String path, Class<? extends T> requestType, Class<? super R> responseType, Messaging.RequestStream<T,R> requestStream)
      Set a request stream to handle requests to a specified path.
      Type Parameters:
      T - request type
      R - response type
      Parameters:
      path - path to receive requests on
      requestType - the request type.
      responseType - the response type.
      requestStream - request stream to handle requests to this path
      Returns:
      null if the request stream is the first stream to be set to the path, otherwise this method will return the previously set request stream.
      Throws:
      IllegalArgumentException - if there is no data type matching the request type parameter
      Since:
      6.0

    • removeRequestStream

      Messaging.RequestStream<?,?> removeRequestStream(String path)
      Remove the request stream at a particular path.
      Parameters:
      path - path at which to remove the request stream
      Returns:
      the request stream that was removed from the path. If the path does not have a request stream assigned (or the path does not exist), null will be returned instead
      Since:
      6.0

    • sendRequest

      <T, R> CompletableFuture<R> sendRequest(SessionId sessionId, String path, T request, Class<T> requestType, Class<R> responseType)
      Send a request to a session.
      Type Parameters:
      T - request type
      R - response type
      Parameters:
      sessionId - session to send the request to
      path - message path used by the recipient to select an appropriate handler
      request - request to send
      requestType - the request type
      responseType - the response type
      Returns:
      A CompletableFuture that completes when a response has been received by the session. If the task completes successfully, the CompletableFuture result will be a response (to the request) of type R.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.0

    • addRequestHandler

      <T, R> CompletableFuture<Registration> addRequestHandler(String path, Class<? extends T> requestType, Class<? super R> responseType, Messaging.RequestHandler<T,R> handler, String... sessionProperties)
      Register a request handler to handle requests from other client sessions for a branch of the message path hierarchy.

      Each control session may register a single handler for a branch. When the handler is no longer required, it may be closed using the Registration provided by the CompletableFuture result. To change the handler for a particular branch the previous handler must first be closed.

      Type Parameters:
      T - request type
      R - response type
      Parameters:
      path - the request message path
      requestType - the request type. If this class is not supported by the available datatypes, an IllegalArgumentException will be thrown.
      responseType - the response type. If this class is not supported by the available datatypes, an IllegalArgumentException will be thrown.
      handler - request handler to be registered at the server
      sessionProperties - a list of keys of session properties that should be supplied with each request. See Session for a full list of available fixed property keys. To request no properties supply an empty list. To request all fixed properties include Session.ALL_FIXED_PROPERTIES as a key. In this case any other fixed property keys would be ignored. To request all user properties include Session.ALL_USER_PROPERTIES as a key. In this case any other user properties are ignored.
      Returns:
      a CompletableFuture that completes when the handler has been registered, returning a Registration which can be used to unregister the handler.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.0

    • sendRequestToFilter

      <T, R> CompletableFuture<Integer> sendRequestToFilter(String filter, String path, T request, Class<T> requestType, Class<R> responseType, Messaging.FilteredRequestCallback<? super R> callback)
      Send a request to all sessions that satisfy a given session filter.
      Type Parameters:
      T - request type
      R - response type
      Parameters:
      filter - the session filter expression. See Session for a full description of filter expressions.
      path - message path used by the recipient to select an appropriate handler
      request - the request object
      requestType - the type of the request to be sent
      responseType - the type of the response to be received
      callback - the callback to receive notification of responses (or errors) from sessions
      Returns:
      a CompletableFuture that completes when the server has dispatched all the requests.

      If the server successfully evaluated the filter, the result of this contains the number of sessions the request was sent to. Failure to send a request to a particular matching session is reported to the callback.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.0