Diffusion Apple API  6.5.1
Unified Client Library for iOS, tvOS and OS X / macOS
 All Classes Files Functions Variables Enumerations Enumerator Properties Pages
Class Methods | Properties | Instance Methods | List of all members
PTDiffusionSession Class Reference

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

PTDiffusionSessionConfigurationconfiguration
 
PTDiffusionSessionIdsessionId
 
NSString * principal
 
PTDiffusionSessionStatestate
 
id< PTDiffusionErrorListenererrorListener
 
PTDiffusionClientControlFeatureclientControl
 
PTDiffusionTopicsFeaturetopics
 
PTDiffusionTopicControlFeaturetopicControl
 
PTDiffusionTopicUpdateFeaturetopicUpdate
 
PTDiffusionMessagingFeaturemessaging
 
PTDiffusionMessagingControlFeaturemessagingControl
 
PTDiffusionSecurityFeaturesecurity
 
PTDiffusionPingsFeaturepings
 
PTDiffusionTimeSeriesFeaturetimeSeries
 
PTDiffusionTopicNotificationsFeaturetopicNotifications
 
PTDiffusionSubscriptionControlFeaturesubscriptionControl
 
PTDiffusionTopicViewsFeaturetopicViews
 
PTDiffusionRemoteServersFeatureremoteServers
 

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
nameThe name of the session lock.
completionHandlerBlock 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:

Returns
The handle to a session lock request.
Exceptions
NSInvalidArgumentExceptionRaised 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
nameThe name of the session lock
scopePreferred 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)).
completionHandlerBlock 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
urlThe location of the server to connect to. Encapsulates host, port and protocol to use. Must be absolute.
completionHandlerThe 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
urlThe location of the server to connect to. Encapsulates host, port and protocol to use. Must be absolute.
configurationThe configuration options to connect with.
completionHandlerThe 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.

Since
6.1
- (PTDiffusionTimeSeriesFeature*) timeSeries
readnonatomicassign

The Time Series feature provides a client session with the ability to update and query time series topics.

Since
6.0
- (PTDiffusionTopicControlFeature*) topicControl
readnonatomicassign

The Topic Control features provides the capability to manage topics.

Since
5.7
- (PTDiffusionTopicNotificationsFeature*) topicNotifications
readnonatomicassign

The Topic Notifications feature allows a client session to receive notifications about changes to selected topics.

Since
6.1
- (PTDiffusionTopicsFeature*) topics
readnonatomicassign

The Topics feature provides the capability to receive streamed topic updates and/or fetch the state of topics.

Since
5.6
- (PTDiffusionTopicUpdateFeature*) topicUpdate
readnonatomicassign

The Topic Update feature provides a client session with the ability to update topics.

Since
6.3
- (PTDiffusionTopicViewsFeature*) topicViews
readnonatomicassign

The Topic Views feature allows a client session to manage topic views.

Since
6.3