Interface IMessaging

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

Inherited Members

IFeature.Session

Namespace: PushTechnology.ClientInterface.Client.Features

Assembly: Diffusion.Client.dll

Syntax

public interface IMessaging : IFeature

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>, 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>, CancellationToken, String[])

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

Declaration

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

Parameters

Type	Name	Description
String	path	The request message path.
IRequestHandler<TRequest, TResponse>	handler	Request handler to be registered at the server.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.
String[]	sessionProperties	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

Type	Description
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

Name	Description
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

Type	Condition
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>, String[])

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

Declaration

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

Parameters

Type	Name	Description
String	path	The request message path.
IRequestHandler<TRequest, TResponse>	handler	Request handler to be registered at the server.
String[]	sessionProperties	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

Type	Description
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

Name	Description
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

Type	Condition
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.

Declaration

IStream RemoveRequestStream(string path)

Parameters

Type	Name	Description
String	path	The path at which to remove the request stream.

Returns

Type	Description
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

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

Sends a request.

Declaration

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

Parameters

Type	Name	Description
ISessionId	sessionId	The session identifier.
String	path	The path to send a request to.
TRequest	request	The request to send.

Returns

Type	Description
Task<TResponse>	A Task that completes when a response has been received by a handler.

Type Parameters

Name	Description
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

Type	Condition
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.
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.

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

Sends a request.

Declaration

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

Parameters

Type	Name	Description
ISessionId	sessionId	The session identifier.
String	path	The path to send a request to.
TRequest	request	The request to send.
CancellationToken	cancellationToken	The cancellation token for the Task created.

Returns

Type	Description
Task<TResponse>	A Task that completes when a response has been received by a handler.

Type Parameters

Name	Description
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

Type	Condition
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.
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.

SendRequestAsync<TRequest, TResponse>(String, TRequest)

Sends the request.

Declaration

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

Parameters

Type	Name	Description
String	path	The path to send a request to.
TRequest	request	The request to send.

Returns

Type	Description
Task<TResponse>	A Task that completes when a response has been received by a handler.

Type Parameters

Name	Description
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

Type	Condition
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.
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.

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

Sends the request.

Declaration

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

Parameters

Type	Name	Description
String	path	The path to send a request to.
TRequest	request	The request to send.
CancellationToken	cancellationToken	The cancellation token for the Task returned.

Returns

Type	Description
Task<TResponse>	A Task that completes when a response has been received by a handler.

Type Parameters

Name	Description
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

Type	Condition
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.
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.

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

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

Declaration

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

Parameters

Type	Name	Description
String	filter	The session filter expression.
String	path	Message path used by the recipient to select an appropriate handler.
TRequest	request	The request object.
IFilteredRequestCallback<TResponse>	callback	The callback to receive notification of responses (or errors) from sessions.

Returns

Type	Description
Task<Int32>	A Task that completes when the server has dispatched all the requests.

Type Parameters

Name	Description
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

Type	Condition
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.

Declaration

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

Parameters

Type	Name	Description
String	filter	The session filter expression.
String	path	Message path used by the recipient to select an appropriate handler.
TRequest	request	The request object.
IFilteredRequestCallback<TResponse>	callback	The callback to receive notification of responses (or errors) from sessions.
CancellationToken	cancellationToken	The cancellation token for the Task returned.

Returns

Type	Description
Task<Int32>	A Task that completes when the server has dispatched all the requests.

Type Parameters

Name	Description
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

Type	Condition
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).

Declaration

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

Parameters

Type	Name	Description
String	path	Path to receive requests on.
IRequestStream<TRequest, TResponse>	requestStream	Request stream to handle requests to this path.

Returns

Type	Description
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

Name	Description
TRequest	The type of the request.
TResponse	The type of the response.

Remarks

Since 6.1