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

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Messaging.FilteredRequestCallback<R> Callback interface for requests dispatched through a filter.
static interface	Messaging.RequestHandler<T,R> Interface which specifies a request handler to receive request notifications.
static interface	Messaging.RequestStream<T,R> Interface which specifies a request stream to receive request notifications.

Method Summary

Modifier and Type	Method and Description
<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.
Messaging.RequestStream<?,?>	removeRequestStream(String path) Remove the request stream at a particular path.
<T,R> CompletableFuture<R>	sendRequest(SessionId sessionId, String path, T request, Class<T> requestType, Class<R> responseType) Send a request to a session.
<T,R> CompletableFuture<R>	sendRequest(String path, T request, Class<T> requestType, Class<R> responseType) Send a request.
<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.
<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.

Methods inherited from interface com.pushtechnology.diffusion.client.session.Feature

getSession

Method Detail

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:

• UnhandledMessageException – if there is no handler registered on the server to receive requests for this message path;
• IncompatibleDatatypeException – if the request is not compatible with the datatype bound to the handler's message path;
• IllegalArgumentException – if the response is not compatible with the specified response type;
• RejectedRequestException – if the request has been rejected by the recipient session calling Responder.reject(message);
• SessionClosedException – if the session is closed;
• PermissionsException – if the session does not have SEND_TO_MESSAGE_HANDLER permission;
• CancellationException – if the recipient session did not respond before the request timed out.

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:

• NoSuchSessionException – if the session does not exist on the server;
• UnhandledMessageException – if recipient session does not have a local request stream registered for this path;
• IncompatibleDatatypeException – if the request is not compatible with the datatype bound to the handler's message path;
• IllegalArgumentException – if the response is not compatible with the specified response type;
• RejectedRequestException – if the request has been rejected by the recipient session calling Responder.reject(message);
• SessionClosedException – if the session is closed;
• PermissionsException – if the session does not have SEND_TO_SESSION permission;

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:

• SessionClosedException – if the session is closed;
• HandlerConflictException – if the session has already registered a handler for this message path;
• PermissionsException – if the session does not have REGISTER_HANDLER permission to register a request handler on the server;
• PermissionsException – if the session does not have VIEW_SESSION permission to access the client's session properties.

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:

• InvalidFilterException – if the filter parameter could not be parsed;
• PermissionsException – if the calling session does not have SEND_TO_SESSION and VIEW_SESSION permissions;
• SessionClosedException – if the calling session is closed.

Since:

6.0