Table of Contents

Interface IMessaging

Namespace
PushTechnology.ClientInterface.Client.Features
Assembly
Diffusion.Client.dll

This feature provides a client session with request-response messaging capabilities that can be used to implement application services.

public interface IMessaging : IFeature
Inherited Members

Remarks

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 SendRequestAsync<TRequest, TResponse>(string, TRequest) 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 AddRequestHandlerAsync<TRequest, TResponse>(string, IRequestHandler<TRequest, TResponse>, params 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 ISession 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 (with SendRequestAsync<TRequest, TResponse>(string, TRequest)) 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 SendRequestToFilterAsync<TRequest, TResponse>(string, string, TRequest, IFilteredRequestCallback<TResponse>). For the details of session filters, see ISession. Sending a request to a filter will match zero or more sessions. Each response received will be passed to the provided IFilteredRequestCallback<TResponse>. As a convenience, an addressed request can be sent to a specific session using the overloaded variant of SendRequestAsync<TRequest, TResponse>(ISessionId, string, TRequest) 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<TRequest, TResponse>(string, IRequestStream<TRequest, TResponse>). When a request is received for the message path, the OnRequest(string, TRequest, IResponder<TResponse>) method on the stream is triggered. The session should respond using the provided Respond(TResponse) method call. Streams receive an OnClose() callback when unregistered and an OnError(ErrorReason)) 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 an ISession as follows: 

var messaging = session.Messaging;

Added in version 5.0.

Methods

AddRequestHandlerAsync<TRequest, TResponse>(string, IRequestHandler<TRequest, TResponse>, params string[])

Registers a request handler to handle requests from other client sessions for a branch of the message path hierarchy.

Task<IRegistration> AddRequestHandlerAsync<TRequest, TResponse>(string path, IRequestHandler<TRequest, TResponse> handler, params string[] sessionProperties)

Parameters

path string

The request message path.

handler IRequestHandler<TRequest, TResponse>

Request handler to be registered at the server.

sessionProperties string[]

A list of keys of session properties that should be supplied with each request. See ISession for a full list of available fixed property keys. To request no properties, supply an empty list. To request all fixed properties, include AllFixedProperties as a key. In this case, any other fixed property keys would be ignored. To request all user properties, include AllUserProperties as a key. In this case, any other user properties are ignored.

Returns

Task<IRegistration>

A Task that completes when the handler has been registered, returning a IRegistration which can be used to unregister the handler. Otherwise, the Task will complete with an exception.

Type Parameters

TRequest

The type of the request. If this class is not supported by the available data types, an ArgumentException will be thrown.

TResponse

The type of the response. If this class is not supported by the available data types, an ArgumentException will be thrown.

Remarks

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

Since 6.5

Exceptions

ArgumentNullException

If path or handler is null.

SessionClosedException

The session is closed. Thrown by the returned task.

HandlerConflictException

The session has already registered a handler for this message path. Thrown by the returned task.

SessionSecurityException

The session does not have REGISTER_HANDLER permission to register a request handler on the server. Thrown by the returned task.

SessionSecurityException

The session does not have VIEW_SESSION permission to access the client's session properties. Thrown by the returned task.

AddRequestHandlerAsync<TRequest, TResponse>(string, IRequestHandler<TRequest, TResponse>, CancellationToken, params string[])

Registers a IRequestHandler<TRequest, TResponse> that will handle requests from other client sessions for a branch of the message path hierarchy.

Task<IRegistration> AddRequestHandlerAsync<TRequest, TResponse>(string path, IRequestHandler<TRequest, TResponse> handler, CancellationToken cancellationToken, params string[] sessionProperties)

Parameters

path string

The request message path.

handler IRequestHandler<TRequest, TResponse>

Request handler to be registered at the server.

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

sessionProperties string[]

A list of keys of session properties that should be supplied with each request. See ISession for a full list of available fixed property keys. To request no properties, supply an empty list. To request all fixed properties, include AllFixedProperties as a key. In this case, any other fixed property keys are ignored. To request all user properties, include AllUserProperties as a key. In this case, any other user properties are ignored.

Returns

Task<IRegistration>

A Task that completes when the handler has been registered, returning a IRegistration which can be used to unregister the handler. Otherwise, the Task will complete with an exception.

Type Parameters

TRequest

The type of the request. If this class is not supported by the available data types, an ArgumentException will be thrown.

TResponse

The type of the response. If this class is not supported by the available data types, an ArgumentException will be thrown.

Remarks

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

Since 6.5

Exceptions

ArgumentNullException

If path or handler is null.

SessionClosedException

The session is closed. Thrown by the returned task.

HandlerConflictException

The session has already registered a handler for this message path. Thrown by the returned task.

SessionSecurityException

The session does not have REGISTER_HANDLER permission to register a request handler on the server. Thrown by the returned task.

SessionSecurityException

The session does not have VIEW_SESSION permission to access the client's session properties. Thrown by the returned task.

RemoveRequestStream(string)

Removes the request stream at a particular path.

IStream RemoveRequestStream(string path)

Parameters

path string

The path at which to remove the request stream.

Returns

IStream

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.

Remarks

Since 6.1

Exceptions

ArgumentNullException

If path is null.

SendRequestAsync<TRequest, TResponse>(ISessionId, string, TRequest)

Sends a request.

Task<TResponse> SendRequestAsync<TRequest, TResponse>(ISessionId sessionId, string path, TRequest request)

Parameters

sessionId ISessionId

The session identifier.

path string

The path to send a request to.

request TRequest

The request to send.

Returns

Task<TResponse>

A Task that completes when a response has been received by a handler.

Type Parameters

TRequest

The type of the request.

TResponse

The type of the response.

Remarks

If the Task completes successfully, its result will be the response (to the request) of type TResponse. Otherwise, the Task will complete with an exception.

Since 6.5

Exceptions

ArgumentNullException

If sessionId or path or request is null.

ArgumentException

There is no data type matching the TRequest type parameter.

UnhandledMessageException

There is no handler registered on the server to receive requests for this message path. Thrown by the returned task.

IncompatibleDatatypeException

The request is not compatible with the data type bound to the handler's message path. Thrown by the returned task.

ArgumentException

The response is not compatible with the specified response type. Thrown by the returned task.

RejectedRequestException

The request has been rejected by the recipient session calling Reject(string). Thrown by the returned task.

SessionClosedException

The session is closed. Thrown by the returned task.

SessionSecurityException

The session does not have SEND_TO_MESSAGE_HANDLER permission. Thrown by the returned task.

TimeoutException

The recipient session did not respond before the request timed out. Thrown by the returned task.

SendRequestAsync<TRequest, TResponse>(ISessionId, string, TRequest, CancellationToken)

Sends a request.

Task<TResponse> SendRequestAsync<TRequest, TResponse>(ISessionId sessionId, string path, TRequest request, CancellationToken cancellationToken)

Parameters

sessionId ISessionId

The session identifier.

path string

The path to send a request to.

request TRequest

The request to send.

cancellationToken CancellationToken

The cancellation token for the Task created.

Returns

Task<TResponse>

A Task that completes when a response has been received by a handler.

Type Parameters

TRequest

The type of the request.

TResponse

The type of the response.

Remarks

If the Task completes successfully, its result will be the response (to the request) of type TResponse. Otherwise, the Task will complete with an exception.

Since 6.5

Exceptions

ArgumentNullException

If sessionId or path or request is null.

ArgumentException

There is no data type matching the TRequest type parameter.

UnhandledMessageException

There is no handler registered on the server to receive requests for this message path. Thrown by the returned task.

IncompatibleDatatypeException

The request is not compatible with the data type bound to the handler's message path. Thrown by the returned task.

ArgumentException

The response is not compatible with the specified response type. Thrown by the returned task.

RejectedRequestException

The request has been rejected by the recipient session calling Reject(string). Thrown by the returned task.

SessionClosedException

The session is closed. Thrown by the returned task.

SessionSecurityException

The session does not have SEND_TO_MESSAGE_HANDLER permission. Thrown by the returned task.

TimeoutException

The recipient session did not respond before the request timed out. Thrown by the returned task.

SendRequestAsync<TRequest, TResponse>(string, TRequest)

Sends the request.

Task<TResponse> SendRequestAsync<TRequest, TResponse>(string path, TRequest request)

Parameters

path string

The path to send a request to.

request TRequest

The request to send.

Returns

Task<TResponse>

A Task that completes when a response has been received by a handler.

Type Parameters

TRequest

The type of the request.

TResponse

The type of the response.

Remarks

If the Task completes successfully, its result will contain a TResponse response. Otherwise, the Task will complete with an exception.

Since 6.1

Exceptions

ArgumentNullException

If path or request is null.

ArgumentException

There is no data type matching the request type parameter.

UnhandledMessageException

There is no handler registered on the server to receive requests for this message path. Thrown by the returned task.

IncompatibleDatatypeException

The request is not compatible with the data type bound to the handler's message path. Thrown by the returned task.

ArgumentException

The response is not compatible with the specified response type. Thrown by the returned task.

RejectedRequestException

The request has been rejected by the recipient session calling Reject(string). Thrown by the returned task.

SessionClosedException

The session is closed. Thrown by the returned task.

SessionSecurityException

The session does not have SEND_TO_MESSAGE_HANDLER permission. Thrown by the returned task.

TimeoutException

The recipient session did not respond before the request timed out. Thrown by the returned task.

SendRequestAsync<TRequest, TResponse>(string, TRequest, CancellationToken)

Sends the request.

Task<TResponse> SendRequestAsync<TRequest, TResponse>(string path, TRequest request, CancellationToken cancellationToken)

Parameters

path string

The path to send a request to.

request TRequest

The request to send.

cancellationToken CancellationToken

The cancellation token for the Task returned.

Returns

Task<TResponse>

A Task that completes when a response has been received by a handler.

Type Parameters

TRequest

The type of the request.

TResponse

The type of the response.

Remarks

If the Task completes successfully, its result will contain a TResponse response. Otherwise, the Task will complete with an exception.

Since 6.1

Exceptions

ArgumentNullException

If path or request is null.

ArgumentException

There is no data type matching the request type parameter.

UnhandledMessageException

There is no handler registered on the server to receive requests for this message path. Thrown by the returned task.

IncompatibleDatatypeException

The request is not compatible with the data type bound to the handler's message path. Thrown by the returned task.

ArgumentException

The response is not compatible with the specified response type. Thrown by the returned task.

RejectedRequestException

The request has been rejected by the recipient session calling Reject(string). Thrown by the returned task.

SessionClosedException

The session is closed. Thrown by the returned task.

SessionSecurityException

The session does not have SEND_TO_MESSAGE_HANDLER permission. Thrown by the returned task.

TimeoutException

The recipient session did not respond before the request timed out. Thrown by the returned task.

SendRequestToFilterAsync<TRequest, TResponse>(string, string, TRequest, IFilteredRequestCallback<TResponse>)

Sends a request to all sessions that satisfy a given session filter.

Task<int> SendRequestToFilterAsync<TRequest, TResponse>(string filter, string path, TRequest request, IFilteredRequestCallback<TResponse> callback)

Parameters

filter string

The session filter expression.

path string

Message path used by the recipient to select an appropriate handler.

request TRequest

The request object.

callback IFilteredRequestCallback<TResponse>

The callback to receive notification of responses (or errors) from sessions.

Returns

Task<int>

A Task that completes when the server has dispatched all the requests.

Type Parameters

TRequest

The request type.

TResponse

The response type.

Remarks

If the server has successfully evaluated the filter, the result 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 Task will complete with an exception.

Since 6.5

Exceptions

ArgumentNullException

If filter or path or request or callback is null.

InvalidFilterException

The filter parameter could not be parsed. Thrown by the returned task.

SessionSecurityException

The calling session does not have SEND_TO_SESSION permission. Thrown by the returned task.

SessionClosedException

The calling session is closed. Thrown by the returned task.

SendRequestToFilterAsync<TRequest, TResponse>(string, string, TRequest, IFilteredRequestCallback<TResponse>, CancellationToken)

Sends a request to all sessions that satisfy a given session filter.

Task<int> SendRequestToFilterAsync<TRequest, TResponse>(string filter, string path, TRequest request, IFilteredRequestCallback<TResponse> callback, CancellationToken cancellationToken)

Parameters

filter string

The session filter expression.

path string

Message path used by the recipient to select an appropriate handler.

request TRequest

The request object.

callback IFilteredRequestCallback<TResponse>

The callback to receive notification of responses (or errors) from sessions.

cancellationToken CancellationToken

The cancellation token for the Task returned.

Returns

Task<int>

A Task that completes when the server has dispatched all the requests.

Type Parameters

TRequest

The request type.

TResponse

The response type.

Remarks

If the server has successfully evaluated the filter, the result 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 Task will complete with an exception.

Since 6.5

Exceptions

ArgumentNullException

If filter or path or request or callback is null.

InvalidFilterException

The filter parameter could not be parsed. Thrown by the returned task.

SessionSecurityException

The calling session does not have SEND_TO_SESSION permission. Thrown by the returned task.

SessionClosedException

The calling session is closed. Thrown by the returned task.

SetRequestStream<TRequest, TResponse>(string, IRequestStream<TRequest, TResponse>)

Sets the requestStream to handle requests to a specified path (replacing the stream previously set for this path, if any).

IStream SetRequestStream<TRequest, TResponse>(string path, IRequestStream<TRequest, TResponse> requestStream)

Parameters

path string

Path to receive requests on.

requestStream IRequestStream<TRequest, TResponse>

Request stream to handle requests to this path.

Returns

IStream

The stream registered previously for the path (which is being replaced by the new specified request stream) or null if no stream was registered.

Type Parameters

TRequest

The type of the request.

TResponse

The type of the response.

Remarks

Since 6.1

Exceptions

ArgumentNullException

If path or requestStream is null.