Introduction

A client session to a server or cluster of servers.

The Quick Start guide provides basic instructions on how to connect to a Diffusion server.

Also see:

A new session can be created by connecting to a server using openWithURL:completionHandler: (PTDiffusionSession) specifying the server URL. A PTDiffusionSessionConfiguration can also be configured to control the behaviour of the session using openWithURL:configuration:completionHandler: (PTDiffusionSession)

The session provides a variety of operations to the application. These are grouped into feature interfaces, such as Topics and Messaging, exposed to the application through the following methods:

Session lifecycle

Each session is managed by a server. The server assigns the session a unique identity, 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 ClientControl feature.

A client can become disconnected from the server, and reconnect to the server without loss of the session. Reconnection can be configured using PTDiffusionSessionConfiguration.reconnectionStrategy. 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. This property is Key-Value Observable with changes being notified on the main dispatch queue when the session state changes.

Session locks

The actions of multiple sessions can be coordinated using session locks. See lockWithName:completionHandler: (PTDiffusionSession)

Since: 5.6

Inheritance diagram for PTDiffusionSession:

Class Methods
(void)	+ openWithURL:configuration:completionHandler:

(void)	+ openWithURL:completionHandler:

(NSString *)	+ anonymousPrincipal

(NSString *)	+ allFixedProperties

(NSString *)	+ allUserProperties

(NSString *)	+ rolesPropertyKey

(NSString *)	+ sessionIdPropertyKey

(NSString *)	+ principalPropertyKey

(NSString *)	+ connectorPropertyKey

(NSString *)	+ transportPropertyKey

(NSString *)	+ clientTypePropertyKey

(NSString *)	+ countryPropertyKey

(NSString *)	+ languagePropertyKey

(NSString *)	+ serverNamePropertyKey

(NSString *)	+ clientIPPropertyKey

(NSString *)	+ latitudePropertyKey

(NSString *)	+ longitudePropertyKey

(NSString *)	+ startTimePropertyKey

Properties
PTDiffusionSessionConfiguration *	configuration

PTDiffusionSessionId *	sessionId

NSString *	principal

PTDiffusionSessionState *	state

id< PTDiffusionErrorListener >	errorListener

PTDiffusionClientControlFeature *	clientControl

PTDiffusionTopicsFeature *	topics

PTDiffusionTopicControlFeature *	topicControl

PTDiffusionTopicUpdateFeature *	topicUpdate

PTDiffusionMessagingFeature *	messaging

PTDiffusionMessagingControlFeature *	messagingControl

PTDiffusionSecurityFeature *	security

PTDiffusionPingsFeature *	pings

PTDiffusionTimeSeriesFeature *	timeSeries

PTDiffusionTopicNotificationsFeature *	topicNotifications

PTDiffusionSubscriptionControlFeature *	subscriptionControl

PTDiffusionTopicViewsFeature *	topicViews

PTDiffusionRemoteServersFeature *	remoteServers

Instance Methods
(void)	- close

(PTDiffusionSessionLockAttempt *)	- lockWithName:completionHandler:

(PTDiffusionSessionLockAttempt *)	- lockWithName:scope:completionHandler:

(PTDiffusionHTTPResponse *_Nullable)	- websocketHTTPResponse

Method Documentation

+ (NSString *) allFixedProperties

This constant can be used instead of a property key in requests for session property values to indicate that all fixed session properties are required.

Returns: String representing a filter for all fixed session properties.

Since: 6.0

+ (NSString *) allUserProperties

This constant can be used instead of a property key in requests for session property values to indicate that all user defined session properties are required.

Returns: String representing a filter for all user defined session properties.

Since: 6.0

+ (NSString *) anonymousPrincipal

Value assigned to the principal property if this is an anonymous session.

Returns: String representing the principal property value for an anonymous session.

Since: 6.0

+ (NSString *) clientIPPropertyKey

Session property key for client IP address.

Returns: String representing the session property key for client IP address.

Since: 6.2

+ (NSString *) clientTypePropertyKey

Session property key for client type.

Returns: String representing the session property key for client type.

Since: 6.2

- (void) close

Close the session. Once closed a session cannot be restarted.

Since: 5.6

+ (NSString *) connectorPropertyKey

Session property key for connector name.

Returns: String representing the session property key for connector name.

Since: 6.2

+ (NSString *) countryPropertyKey

Session property key for country code.

Returns: String representing the session property key for country code.

Since: 6.2

+ (NSString *) languagePropertyKey

Session property key for language code.

Returns: String representing the session property key for language code.

Since: 6.2

+ (NSString *) latitudePropertyKey

Session property key for client latitude.

Returns: String representing the session property key for client latitude.

Since: 6.2

- (PTDiffusionSessionLockAttempt *) lockWithName:	(NSString *)	name
completionHandler:	(PTDiffusionSessionLock *_Nullable)	lock
	(NSError *_Nullable error)	completionHandler

Attempt to acquire a session lock.

The completion handler block will be called with the requested lock if the server assigns it to the session. Otherwise, the completion handler block will be called with an error indicating why the lock could not be acquired.

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, or the session cancels the CompletableFuture.

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

Calling cancel on the returned PTDiffusionCancellable has no effect on other pending calls to acquire this lock.

Upon successful acquisition, the session owns the lock and is responsible for unlocking it. When calling cancel on the returned PTDiffusionCancellable, take care that it has not already completed by checking the return value. The following Swift code releases the lock if the request could not be canceled.

let attempt = session.lock(withName: "my-lock") { (lock, error) in / / .. }

if (!attempt.cancel()) { attempt.lock?.unlock() { (wasOwned, error) in } }

A session that acquires a lock will remain its owner until it is unlocked or the session closes. The variant of this methods that takes a scope parameter 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 acquireLock (PTDiffusionPathPermission) path 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.

Parameters

name	The name of the session lock.
completionHandler	Block to be called asynchronously on success or failure. If the operation was successful, the `error` argument passed to the block will be `nil`. The completion handler will be called asynchronously on the main dispatch queue.

If this session has successfully acquired the session lock, or this session already owns the session lock, the completion handler will be called with the lock instance.

If the completion handler is called with an error to indicate failure, this session does not own the session lock. Common reasons for failure include:

The calling session does not have the acquireLock (PTDiffusionPathPermission) permission for this lock name.
The session is closed.

Returns: The handle to a session lock request.

Exceptions

NSInvalidArgumentException Raised if any supplied arguments are nil.

See Also: - lockWithName:scope:completionHandler:

Since: 6.3

- (PTDiffusionSessionLockAttempt *) lockWithName:	(NSString *)	name
scope:	(PTDiffusionSessionLockScope *)	scope
completionHandler:	(PTDiffusionSessionLock *_Nullable)	lock
	(NSError *_Nullable error)	completionHandler

Variant of lockWithName:completionHandler: that provides control over when a lock will be released.

If called with unlockOnSessionLoss (PTDiffusionSessionLockScope), this method behaves exactly like lockWithName:completionHandler:.

If called with unlockOnConnectionLoss (PTDiffusionSessionLockScope), any lock that is 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.

Parameters

name	The name of the session lock
scope	Preferred scope. The scope of a lock controls when it will be released automatically. 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 (unlockOnConnectionLoss (PTDiffusionSessionLockScope)).
completionHandler	Block to be called asynchronously on success or failure. If the operation was successful, the `error` argument passed to the block will be `nil`. The completion handler will be called asynchronously on the main dispatch queue.

Returns: The handle to a session lock request.

See Also: - lockWithName:completionHandler:

Since: 6.3

+ (NSString *) longitudePropertyKey

Session property key for client longitude.

Returns: String representing the session property key for client longitude.

Since: 6.2

+ (void) openWithURL:	(NSURL *)	url
completionHandler:	(PTDiffusionSession *_Nullable)	session
	(NSError *_Nullable error)	completionHandler

Starts asynchronously connecting to a Diffusion server using the default session configuration.

Parameters

url	The location of the server to connect to. Encapsulates host, port and protocol to use. Must be absolute.
completionHandler	The completion handler to call on connection success or failure. The completion handler will be called from the main dispatch queue and will only be called once.

Note: Your completion handler must store a strong reference to the session instance in order for it to remain open.; The completion handler block is called after the session's state property has been set to connected but before those observing through the notification center are informed.

Since: 5.6

+ (void) openWithURL:	(NSURL *)	url
configuration:	(PTDiffusionSessionConfiguration *)	configuration
completionHandler:	(PTDiffusionSession *_Nullable)	session
	(NSError *_Nullable error)	completionHandler

Starts asynchronously connecting to a Diffusion server using the given session configuration.

Parameters

url	The location of the server to connect to. Encapsulates host, port and protocol to use. Must be absolute.
configuration	The configuration options to connect with.
completionHandler	The completion handler to call on connection success or failure. The completion handler will be called from the main dispatch queue and will only be called once.

Note: Your completion handler must store a strong reference to the session instance in order for it to remain open.; The completion handler block is called after the session's state property has been set to connected but before those observing through the notification center are informed.

Since: 5.6

+ (NSString *) principalPropertyKey

Session property key for principal.

Returns: String representing the session property key for session principal.

Since: 6.2

+ (NSString *) rolesPropertyKey

Session property key for session roles.

Returns: String representing the session property key for session roles.

Since: 6.2

+ (NSString *) serverNamePropertyKey

Session property key for server name.

Returns: String representing the session property key for server name.

Since: 6.2

+ (NSString *) sessionIdPropertyKey

Session property key for session identifier.

Returns: String representing the session property key for session identifier.

See Also: PTDiffusionSessionId

Since: 6.2

+ (NSString *) startTimePropertyKey

Session property key for client start time.

Returns: String representing the session property key for client start time.

Since: 6.2

+ (NSString *) transportPropertyKey

Session property key for transport.

Returns: String representing the session property key for transport.

Since: 6.2

- (PTDiffusionHTTPResponse * _Nullable) websocketHTTPResponse

Returns the last HTTP response received from the server.

Returns: The last HTTP response received from the server.

Since: 6.3.6

Property Documentation

- (PTDiffusionClientControlFeature*) clientControl

readnonatomicassign

The Client control feature provides the capability to listen and set session properties

Since: 6.5

- (PTDiffusionSessionConfiguration*) configuration

readnonatomiccopy

The configuration used to open the session.

Since: 5.6

- (id<PTDiffusionErrorListener>) errorListener

readwritenonatomicweak

The delegate to use to report unexpected, non-fatal errors to.

Since: 6.0

- (PTDiffusionMessagingFeature*) messaging

readnonatomicassign

The Messaging feature provides messaging capabilities.

Since: 5.6

- (PTDiffusionMessagingControlFeature*) messagingControl

readnonatomicassign

Since: 6.0

Deprecated:: Since 6.5. This will be removed in a future release. Use PTDiffusionMessagingFeature instead.

See Also: PTDiffusionMessagingFeature

- (PTDiffusionPingsFeature*) pings

readnonatomicassign

The Pings feature provides a client session with the ability to test the roundtrip time associated with sending a request to the server and receiving the associated response.

Since: 5.7

- (NSString*) principal

readnonatomicassign

The name of the security principal associated with the session.

Returns: The principal name. If the session has no associated principal, it is known as an anonymous session, in which case the empty string anonymousPrincipal will be assigned to this property.

Since: 6.0

- (PTDiffusionRemoteServersFeature*) remoteServers

readnonatomicassign

The Remote Servers feature allows a client session to create, remove, list and check remote servers.

Since: 6.5

- (PTDiffusionSecurityFeature*) security

readnonatomicassign

The Security feature provides a client session with the ability to change the associated principal.

Since: 5.6

- (PTDiffusionSessionId*) sessionId

readnonatomicassign

The unique identifier for the session as assigned by the server it connects to.

This property is Key-Value Observable with changes being notified on the main dispatch queue.

- (PTDiffusionSessionState*) state

readnonatomicassign

The current state of the session.

This property is Key-Value Observable with changes being notified on the main dispatch queue. KVO notifications are sent before the invocation of any callback handler blocks.

Note: Session state can also be observed using the notification center. See PTDiffusionSessionStateChange for details.

Since: 5.7

- (PTDiffusionSubscriptionControlFeature*) subscriptionControl

readnonatomicassign

The Subscription Control feature allows a client session to subscribe or unsubscribe other sessions to topics, as well as also providing a mechanism for handling requests to subscribe to routing topics.