Interface ISession

A client session to a server or cluster of servers.

Namespace: PushTechnology.ClientInterface.Client.Session

Assembly: Diffusion.Client.dll

Syntax

public interface ISession

Remarks

A new session can be created by connecting to a server using Open(String), specifying the server URL. The session factory can be configured to control the behavior the session.

The session provides a variety of operations to the application. These are grouped into feature interfaces, such as ITopics and IMessaging, exposed to the application through various properties.

Session lifecycle

Each session is managed by a server. The server assigns the session a unique identity (ISessionId), and manages the session's topic subscriptions, security details, and session properties.

A session can be terminated using Close(). A session may also be terminated by the server because of an error or a time out, or by other privileged sessions using the IClientControl feature.

A client can become disconnected from the server, and reconnect to the server without loss of the session. Reconnection can be configured using the ISessionFactory. The server must be configured to allow reconnection.

If a session is connected to a server that belongs to a cluster with session replication enabled, and then becomes disconnected, it will attempt to reconnect to the original server. A properly configured load balancer can detect that the original server is unavailable and re-route the reconnection request to a second server in the cluster. The second server can recover session data and continue the session. This process is known as "fail over". Unlike reconnection, in-flight messages can be lost during failover, and the application will be unsubscribed and re-subscribed to topics.

The current state of the session can be retrieved with State. A listener can be registered with the StateChanged event which will be notified when the session state changes.

Session Properties

For each session, the server stores a set of session properties that describe various attributes of the session.

There are two types of session property. Fixed properties are assigned by the server. User-defined properties are assigned by the application.

Many operations use session filter expressions that use session properties to select sessions.

A privileged client can monitor other sessions, including changes to their session properties, using a ISessionPropertiesListener. When registering to receive session properties, special key values of ALL_FIXED_PROPERTIES and ALL_USER_PROPERTIES can be used.

Each property is identified by a key. Most properties have a single string value. The exception is the ROLES fixed property which has a set of string values.

Fixed properties are identified by keys with a $ prefix. The available fixed session properties are:

Key	Description
`$ClientIP`	The Internet address of the client in string format.
`$ClientType`	The client type of the session. One of `ANDROID`, `C`, `DOTNET`, `IOS`, `JAVA`, `JAVASCRIPT_BROWSER`, or `OTHER`.
`$Connector`	The configuration name of the server connector that the client connected to.
`$Country`	The country code for the country where the client's Internet address was allocated (for example, `NZ` for New Zealand). If the country code could not be determined, this will be a zero length string.
`$Language`	The language code for the official language of the country where the client's Internet address was allocated (for example, `en` for English). If the language could not be determined or is not applicable, this will be a zero length `string`.
`$Latitude`	The client's latitude, if available. This will be the `string` representation of a floating point number and will be `NaN` if not available.
`$Longitude`	The client's longitude, if available. This will be the string representation of a floating point number and will be `NaN` if not available.
`$Principal`	The security principal associated with the client session.
`$Roles`	Authorisation roles assigned to the session. This is a set of roles represented as quoted strings (for example, `"role1","role2"`). The utility method StringToRoles(String) can be used to parse the `string` value into a set of roles.
`$ServerName`	The name of the server to which the session is connected.
`$SessionId`	The session identifier. Equivalent to ISessionId's `ToString()` output.
`$StartTime`	The session's start time in milliseconds since the epoch.
`$Transport`	The session transport type. One of `WEBSOCKET`, `HTTP_LONG_POLL`, or `OTHER`.

All listed property keys constants can be found in SessionProperty.

All user-defined property keys are non-empty strings and are case-sensitive. The characters ' ', '\t', '\r', '\n', '"', ''', '(', ')' are not allowed.

Session properties are initially associated with a session as follows:

When a client starts a new session, it can optionally propose user-defined session properties (see Property(String, String) and Properties(IDictionary<String, String>)). Session properties proposed in this way must be accepted by the authenticator. This safeguard prevents abuse by a rogue, unprivileged client.
The server allocates all fixed property values.
The new session is authenticated by registered authenticators. An authenticator that accepts a session can veto or change the user-defined session properties and add new user-defined session properties. The authenticator can also change certain fixed properties.

Once a session is established, its user-defined session properties can be modified by clients with VIEW_SESSION and MODIFY_SESSION permissions using . A privileged client can also modify its own session properties.

If a session re-authenticates (see ChangePrincipalAsync(String, ICredentials)), the authenticator that allows the re-authentication can modify the user-defined session properties and a subset of the fixed properties as mentioned above.

Session Filters

Session filters are query expressions for session properties. They can be used to address a set of sessions based on their session properties. For example, it is possible to send a message to all sessions that satisfy a specified filter. Session filters are parsed and evaluated at the server.

A session filter expression consists of either a single clause, or multiple clauses connected by the binary operators and and or. The and operator takes precedence over or but parentheses can be used to override the precedence. For example:

Department is "Accounts"
hasRoles[ "operator" "trading desk" ]
Department is "Payroll" and Status is "Closed"
(Department is "Accounts" or Department is "Payroll") and Status is "Closed"

The unary not operator can be used to negate the following clause or an expression within parentheses:

not Department is "Payroll"
not (Department is "Payroll" or Department is "Accounts")

An equality clause has the form key operator value where key is the name of a session property and value is the property value. The supported operators are is or eq, both of which mean "equals", and ne which means "does not equal". Values are strings enclosed within single or double quotes. Special characters (", ', or \) can be included within the value by preceding with the escape character \. The utility method EscapeString(String) can be used to insert escape characters into a value.

hasRoles is a special operator for querying the $Roles session property. A hasRoles clause has the form hasRoles[ "role1" "role2"... "roleN" ]. The clause will match sessions that have all the specified authorisation roles. Each role is a string enclosed within either single or double quotes. Roles can be space or comma separated.

The all operator matches all sessions.

The $Roles session property can also be queried with an equality clause, for example, $Roles eq '"admin","client"', but the hasRoleshasRoles clause is usually more convenient. An equality clause will match sessions that have exactly the listed roles. In contrast, a hasRoles clause will match any sessions with the listed roles, regardless of whether they have other roles. The equality clause requires the value to be in the canonical form produced by the utility method.

All operators are case insensitive.

Examples

The following are further examples of valid session filter expressions:

$Principal is "Alice"
Department is "Accounts" and $Country ne "US"
$Language EQ "en" and $Country NE "US"
not (Department is "Accounts" or Department is "Payroll") and $Country is "FR"
Text is "xyz\"\\"
hasRoles ["operator"]
$Transport is "wss" and hasRoles ["accountancy" "administrator"]
hasRoles ["operator"] and not hasRoles ["administrator"]

Session locks

The actions of multiple sessions can be coordinated using session locks. See ISessionLock.

Properties

Attributes

Returns the session attributes.

Declaration

ISessionAttributes Attributes { get; }

Property Value

Type	Description
ISessionAttributes

AuthenticationControl

Gets the 'Authentication Control' feature.

Declaration

IAuthenticationControl AuthenticationControl { get; }

Property Value

Type	Description
IAuthenticationControl	The authentication control feature.

Remarks

This may be used to get the feature and it will automatically instantiate the feature the first time it is called.

ClientControl

Gets the 'Client Control' feature.

Declaration

IClientControl ClientControl { get; }

Property Value

Type	Description
IClientControl	The client control feature.

Remarks

This may be used to get the feature and it will automatically instantiate the feature the first time it is called.

Messaging

Gets the 'Messaging' feature.

Declaration

IMessaging Messaging { get; }

Property Value

Type	Description
IMessaging	The messaging feature.

Remarks

This may be used to get the feature and it will automatically instantiate the feature the first time it is called.

MessagingControl

Gets the 'Messaging Control' feature.

Declaration

IMessagingControl MessagingControl { get; }

Property Value

Type	Description
IMessagingControl	The messaging control feature.

Remarks

This may be used to get the feature and it will automatically instantiate the feature the first time it is called.

Ping

Gets the 'Ping' feature.

Declaration

IPings Ping { get; }

Property Value

Type	Description
IPings	The ping feature.

Remarks

This may be used to get the feature and it will automatically instantiate the feature the first time it is called.

Principal

Returns the name of the security principal associated with the session.

Declaration

string Principal { get; }

Property Value

Type	Description
String

Security

Gets the 'Security' feature.

Declaration

ISecurity Security { get; }

Property Value

Type	Description
ISecurity	The security feature.

Remarks

This may be used to get the feature and it will automatically instantiate the feature the first time it is called.

SecurityControl

Gets the 'Security Control' feature.

Declaration

ISecurityControl SecurityControl { get; }

Property Value

Type	Description
ISecurityControl	The security control feature.

Remarks

This may be used to get the feature and it will automatically instantiate the feature the first time it is called.

SessionId

Returns the unique identifier for the session as assigned by the (first) server it connects to.

Declaration

ISessionId SessionId { get; }

Property Value

Type	Description
ISessionId

State

Returns the current state of the session.

Declaration

SessionState State { get; }

Property Value

Type	Description
SessionState

SubscriptionControl

Gets the 'Subscription Control' feature.

Declaration

ISubscriptionControl SubscriptionControl { get; }

Property Value

Type	Description
ISubscriptionControl	The subscription control feature.

Remarks

This may be used to get the feature and it will automatically instantiate the feature the first time it is called.

SystemAuthenticationControl

Gets the 'System Authentication Control' feature.

Declaration

ISystemAuthenticationControl SystemAuthenticationControl { get; }

Property Value

Type	Description
ISystemAuthenticationControl	The system authentication control feature.

Remarks

This may be used to get the feature and it will automatically instantiate the feature the first time it is called.

TimeSeries

Gets the 'Time Series' feature.

Declaration

ITimeSeries TimeSeries { get; }

Property Value

Type	Description
ITimeSeries	The time series feature.

Remarks

This may be used to get the feature and it will automatically instantiate the feature the first time it is called.

Added in version 6.1.

TopicControl

Gets the 'Topic Control' feature.

Declaration

ITopicControl TopicControl { get; }

Property Value

Type	Description
ITopicControl	The topic control feature.

Remarks

This may be used to get the feature and it will automatically instantiate the feature the first time it is called.

TopicNotifications

Gets the 'Topic Notifications' feature.

Declaration

ITopicNotifications TopicNotifications { get; }

Property Value

Type	Description
ITopicNotifications	The topic notifications feature.

Remarks

Added in version 6.1.

Topics

Gets the 'Topics' feature.

Declaration

ITopics Topics { get; }

Property Value

Type	Description
ITopics	The topics feature.

Remarks

This may be used to get the feature and it will automatically instantiate the feature the first time it is called.

TopicUpdate

Gets the 'TopicUpdate' feature.

Declaration

ITopicUpdate TopicUpdate { get; }

Property Value

Type	Description
ITopicUpdate	The topics update feature.

Remarks

This may be used to get the feature and it will automatically instantiate the feature the first time it is called.

TopicUpdateControl

Gets the 'Topic Update Control' feature.

Declaration

ITopicUpdateControl TopicUpdateControl { get; }

Property Value

Type	Description
ITopicUpdateControl	The topic update control feature.

Remarks

Deprecated: The ITopicUpdateControl feature has been replaced by the ITopicUpdate feature and will be removed in a future release. The ITopicUpdate feature provides equivalent and additional functionality, such as conditional updates.

This may be used to get the feature and it will automatically instantiate the feature the first time it is called.

TopicViews

Gets the 'TopicViews' feature.

Declaration

ITopicViews TopicViews { get; }

Property Value

Type	Description
ITopicViews	The topic views feature.

Remarks

This may be used to get the feature and it will automatically instantiate the feature the first time it is called.

Methods

Close()

Close the session.

Has no effect if the session is already closed.

Declaration

void Close()

LockAsync(String)

Attempts to acquire a ISessionLock.

Declaration

Task<ISessionLock> LockAsync(string lockName)

Parameters

Type	Name	Description
String	lockName	The name of the session lock.

Returns

Type	Description
Task<ISessionLock>	The `Task` representing the current operation.

Remarks

If the operation completes successfully, the Task result will be the requested ISessionLock assigned to the calling session by the server. The session owns the returned lock and is responsible for unlocking it.

Acquiring the lock can take an arbitrarily long time if other sessions are competing for the lock. The server will retain the session's request for the lock until it is assigned to the session, the session is closed.

A session can call this method multiple times. If the lock is acquired, all calls will complete successfully with equal ISessionLock.

A session that acquires a lock will remain its owner until it is unlocked (via UnlockAsync()) or the session closes. The LockAsync(String, SessionLockScope) variant of this method takes a scope argument that provides the further option of releasing the lock when the session loses its connection to the server.

Access control

To allow fine-grained access control, lock names are interpreted as path names, controlled with the ACQUIRE_LOCK topic permission. This allows permission to be granted to a session to acquire the lock update-topic/a while preventing the session from acquiring the lock update-topic/b, for example.

This method is the same as calling LockAsync(String, CancellationToken) with .

Exceptions

Type	Condition
SessionSecurityException	The calling session does not have ACQUIRE_LOCK permission for `lockName`. Thrown by the returned `Task`.
SessionClosedException	The calling session is closed. Thrown by the returned `Task`.

LockAsync(String, CancellationToken)

Attempts to acquire a ISessionLock.

Declaration

Task<ISessionLock> LockAsync(string lockName, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	lockName	The name of the session lock.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<ISessionLock>	The `Task` representing the current operation.

Remarks

A session can call this method multiple times. If the lock is acquired, all calls will complete successfully with equal ISessionLock.

Canceling the returned Task has no effect on other pending lock calls made by the session.

A session that acquires a lock will remain its owner until it is unlocked (via UnlockAsync(CancellationToken)) or the session closes. The LockAsync(String, SessionLockScope, CancellationToken) variant of this method takes a scope argument that provides the further option of releasing the lock when the session loses its connection to the server.

Access control

Exceptions

Type	Condition
SessionSecurityException	The calling session does not have ACQUIRE_LOCK permission for `lockName`. Thrown by the returned `Task`.
SessionClosedException	The calling session is closed. Thrown by the returned `Task`.

LockAsync(String, SessionLockScope)

Attempts to acquire a ISessionLock with a given scope.

Declaration

Task<ISessionLock> LockAsync(string lockName, SessionLockScope scope)

Parameters

Type	Name	Description
String	lockName	The name of the session lock.
SessionLockScope	scope	The scope of the session lock.

Returns

Type	Description
Task<ISessionLock>	The `Task` representing the current operation.

Remarks

A session can call this method multiple times. If the lock is acquired, all calls will complete successfully with equal ISessionLock.

A session that acquires a lock will remain its owner until it is unlocked (via UnlockAsync()) or the session closes.

If called with a scope of UNLOCK_ON_SESSION_LOSS, this method behaves exactly like LockAsync(String).

If called with a scope of UNLOCK_ON_CONNECTION_LOSS, any lock that are returned will be unlocked if the session loses its connection to the server. This is useful to allow another session to take ownership of the lock while this session is reconnecting.

If a session makes multiple requests for a lock using different scopes, and the server assigns the lock to the session fulfilling the requests, the lock will be given the weakest scope (UNLOCK_ON_CONNECTION_LOSS).

Access control

This method is the same as calling LockAsync(String, SessionLockScope, CancellationToken) with .

Exceptions

Type	Condition
SessionSecurityException	The calling session does not have ACQUIRE_LOCK permission for `lockName`. Thrown by the returned `Task`.
SessionClosedException	The calling session is closed. Thrown by the returned `Task`.

LockAsync(String, SessionLockScope, CancellationToken)

Attempts to acquire a ISessionLock with a given scope.

Declaration

Task<ISessionLock> LockAsync(string lockName, SessionLockScope scope, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	lockName	The name of the session lock.
SessionLockScope	scope	The scope of the session lock.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<ISessionLock>	The `Task` representing the current operation.

Remarks

A session can call this method multiple times. If the lock is acquired, all calls will complete successfully with equal ISessionLock.

Canceling the returned Task has no effect on other pending lock calls made by the session.

A session that acquires a lock will remain its owner until it is unlocked (via UnlockAsync(CancellationToken)) or the session closes.

If called with a scope of UNLOCK_ON_SESSION_LOSS, this method behaves exactly like LockAsync(String).

Access control

Exceptions

Type	Condition
SessionSecurityException	The calling session does not have ACQUIRE_LOCK permission for `lockName`. Thrown by the returned `Task`.
SessionClosedException	The calling session is closed. Thrown by the returned `Task`.

Events

ErrorNotified

Notifies when an error occurs.

Declaration

event EventHandler<SessionErrorHandlerEventArgs> ErrorNotified

Event Type

Type	Description
EventHandler<SessionErrorHandlerEventArgs>

StateChanged

Notifies when the session state changes.

Declaration

event EventHandler<SessionListenerEventArgs> StateChanged

Event Type

Type	Description
EventHandler<SessionListenerEventArgs>