 |
Diffusion Apple API 6.11.5
Unified Client Library for iOS, tvOS and OS X / macOS
|
Loading...
Searching...
No Matches
|
Diffusion Apple API 6.11.5
Unified Client Library for iOS, tvOS and OS X / macOS
|
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: specifying the server URL. A PTDiffusionSessionConfiguration can also be configured to control the behaviour of the session using #openWithURL:configuration:completionHandler:
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:
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.
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 Diffusion. 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 session event listener. When registering to receive session properties, special key values of allFixedProperties and allUserProperties 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, MQTT, PYTHON, REST, OTHER. |
$Environment | The environment in which the client is running. For possible values see the user manual. |
$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). Country codes are as defined by Locale. If the country code could not be determined, this will be a zero length string. |
$GatewayType | Gateway client type. Only set for gateway client sessions. If present it indicates the type of gateway client (e.g. Kafka). |
$GatewayId | The identity of a gateway client session. Only present if the $GatewayType session property is present. |
$Language | The language code for the official language of the country where the client's Internet address was allocated (for example, en for English). Language codes are as defined by Locale. 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. |
$MQQTClientId | The MQTT client identifier. Only set for MQTT sessions. If present, the value of the $ClientType session property will be MQTT. |
$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"). |
$ServerName | The name of the server to which the session is connected. |
$SessionId | The session identifier. |
$StartTime | The session's start time in milliseconds since the epoch. |
$Transport | The session transport type. One of WEBSOCKET, HTTP_LONG_POLL, TCP, or OTHER. |
All user-defined property keys are non-empty strings. The characters ' ', \t, \r, \n, ", ', (, ) are not allowed.
Session properties are initially associated with a session as follows:
Once a session is established, its user-defined session properties can be modified by clients with VIEW_SESSION and MODIFY_SESSION permissions. A privileged client can also modify its own session properties.
If a session re-authenticates, 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 are a mechanism of addressing a set of sessions by the values of their session properties.
Session filters are specified using a Domain Specific Language (DSL). For a full and detailed description of the session filters DSL see the user manual.
The actions of multiple sessions can be coordinated using session locks. See lockWithName:completionHandler: (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 |
| (NSString *) | + gatewayTypePropertyKey |
| (NSString *) | + gatewayIdPropertyKey |
| (NSString *) | + environmentPropertyKey |
Instance Methods | |
| (void) | - close |
| (PTDiffusionSessionLockAttempt *) | - lockWithName:completionHandler: |
| (PTDiffusionSessionLockAttempt *) | - lockWithName:scope:completionHandler: |
| (PTDiffusionHTTPResponse *_Nullable) | - websocketHTTPResponse |
| + (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.
| + (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.
| + (NSString *) anonymousPrincipal |
Value assigned to the principal property if this is an anonymous session.
| + (NSString *) clientIPPropertyKey |
Session property key for client IP address.
| + (NSString *) clientTypePropertyKey |
Session property key for client type.
| - (void) close |
Close the session. Once closed a session cannot be restarted.
| + (NSString *) connectorPropertyKey |
Session property key for connector name.
| + (NSString *) countryPropertyKey |
Session property key for country code.
| + (NSString *) environmentPropertyKey |
Session property key for environment.
| + (NSString *) gatewayIdPropertyKey |
Session property key for gateway client id.
| + (NSString *) gatewayTypePropertyKey |
Session property key for gateway client type.
| + (NSString *) languagePropertyKey |
Session property key for language code.
| + (NSString *) latitudePropertyKey |
Session property key for client latitude.
| - (PTDiffusionSessionLockAttempt *) lockWithName: | (NSString *) | name | |
| completionHandler: | (void(^)(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.
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.
| 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:
acquireLock (PTDiffusionPathPermission) permission for this lock name.| NSInvalidArgumentException | Raised if any supplied arguments are `nil`. |
| - (PTDiffusionSessionLockAttempt *) lockWithName: | (NSString *) | name | |
| scope: | (PTDiffusionSessionLockScope *) | scope | |
| completionHandler: | (void(^)(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.
| 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. |
| + (NSString *) longitudePropertyKey |
Session property key for client longitude.
| + (void) openWithURL: | (NSURL *) | url | |
| completionHandler: | (void(^)(PTDiffusionSession *_Nullable session, NSError *_Nullable error)) | completionHandler | |
Starts asynchronously connecting to a Diffusion server using the default session configuration.
| 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. |
| + (void) openWithURL: | (NSURL *) | url | |
| configuration: | (PTDiffusionSessionConfiguration *) | configuration | |
| completionHandler: | (void(^)(PTDiffusionSession *_Nullable session, NSError *_Nullable error)) | completionHandler | |
Starts asynchronously connecting to a Diffusion server using the given session configuration.
| 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. |
| + (NSString *) principalPropertyKey |
Session property key for principal.
| + (NSString *) rolesPropertyKey |
Session property key for session roles.
| + (NSString *) serverNamePropertyKey |
Session property key for server name.
| + (NSString *) sessionIdPropertyKey |
| + (NSString *) startTimePropertyKey |
Session property key for client start time.
| + (NSString *) transportPropertyKey |
Session property key for transport.
| - (PTDiffusionHTTPResponse *_Nullable) websocketHTTPResponse |
Returns the last HTTP response received from the server.
|
readnonatomicassign |
The Client control feature provides the capability to listen and set session properties
|
readnonatomiccopy |
The configuration used to open the session.
|
readwritenonatomicweak |
The delegate to use to report unexpected, non-fatal errors to.
|
readnonatomicassign |
The Messaging feature provides messaging capabilities.
|
readnonatomicassign |
The Metrics feature allows a client to configure metric collectors.
|
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.
|
readnonatomicassign |
The name of the security principal associated with the session.
|
readnonatomicassign |
The Remote Servers feature allows a client session to create, remove, list and check remote servers.
|
readnonatomicassign |
The Security feature provides a client session with the ability to change the associated principal.
|
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.
|
readnonatomicassign |
The Session Trees feature allows the creation and alteration of branch mapping tables.
|
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.
|
readnonatomicassign |
The Subscription Control feature allows a client session to subscribe or unsubscribe other sessions to topics.
|
readnonatomicassign |
The Time Series feature provides a client session with the ability to update and query time series topics.
|
readnonatomicassign |
The Topic Control features provides the capability to manage topics.
|
readnonatomicassign |
The Topic Notifications feature allows a client session to receive notifications about changes to selected topics.
|
readnonatomicassign |
The Topics feature provides the capability to receive streamed topic updates and/or fetch the state of topics.
|
readnonatomicassign |
The Topic Update feature provides a client session with the ability to update topics.
|
readnonatomicassign |
The Topic Views feature allows a client session to manage topic views.
1.9.8