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

Introduction

This feature allows a client session to manage remote servers.

A remote server provides the configuration to connect to a Diffusion server belonging to a different cluster. Each server in the local cluster will establish a session with each remote server.

Higher level components, such as remote topic views, can specify the use of such remote servers by name. The connecting and disconnecting is handled automatically by the server (or servers in the same cluster) where the remote servers are defined.

A component can specify a remote server by name even if it does not exist (has not yet been created) and when the remote server is created the connection will take place automatically.

If a remote server is removed and there are components that depend upon it, those components will be disabled.

An example of the use of remote servers is within remote topic views (those that indicate that their source topics are to be taken from a different server) where the name of such a server can be specified.

Remote Server persistence and replication

Remote server configurations created through this feature are replicated across a cluster and persisted to disk.

Access control

The following access control restrictions are applied:

Accessing the feature

This feature may be obtained from a session as follows:

PTDiffusionRemoteServersFeature *remoteServers = session.remoteServersFeature;
Since
6.5
Inheritance diagram for PTDiffusionRemoteServersFeature:
PTDiffusionFeature

Instance Methods

(void) - createRemoteServer:withURL:principal:credentials:completionHandler:
 Create a new remote server instance with default connection options. More...
 
(void) - createRemoteServer:withURL:principal:credentials:connectionOptions:completionHandler:
 Create a new remote server instance. More...
 
(void) - checkRemoteServer:completionHandler:
 Check the current state of a named remote server. More...
 
(void) - listRemoteServers:
 List all the remote servers that have been created. More...
 
(void) - removeRemoteServer:completionHandler:
 Remove a named remote server if it exists. More...
 

Additional Inherited Members

- Properties inherited from PTDiffusionFeature
PTDiffusionSessionsession
 

Method Documentation

- (void) checkRemoteServer: (NSString *const)  name
completionHandler: (PTDiffusionCheckRemoteServerResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler 

Check the current state of a named remote server.

This will report back the current state of the remote server, but also can be used to forcibly retry a failed remote server connection.

Parameters
namethe name of the remote server
completionHandlera completion handler that returns when a response is received from the server, return the details of the remote server state.

If the state is nil, this could mean an error has occurred. These may include:

  • SessionSecurity - if the calling session does not have PTDiffusionGlobalPermission.ControlServer permission
  • SessionClosed - if the session is closed
Since
6.5
- (void) createRemoteServer: (NSString *const)  name
withURL: (NSString *const)  url
principal: (NSString *const)  principal
credentials: (PTDiffusionCredentials *const)  credentials
completionHandler: (PTDiffusionCreateRemoteServerResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler 

Create a new remote server instance with default connection options.

If a remote server with the same name already exists an error will be returned.

Parameters
namethe name of the remote server
urlthe URL used to connect to the primary server
principalthe name of a principal used by the remote server to connect to the primary server. A zero length string may be supplied to indicate an anonymous connection
credentialsused for connecting to the primary server
completionHandlera completion handler that returns when a response is received from the server, returning a full definition of the remote server created by the operation

If the remote server definition is nil, this could mean an error has occured. These may include:

  • RemoteServerAlreadyExists - if a remote server with the given name already exists
  • ClusterRouting or ClusterRepartition - if a transient cluster error occurred
  • SessionSecurity - if the calling session does not have PTDiffusionGlobalPermission.ControlServer permission
  • SessionClosed - if the session is closed
Since
6.5
- (void) createRemoteServer: (NSString *const)  name
withURL: (NSString *const)  url
principal: (NSString *const)  principal
credentials: (PTDiffusionCredentials *const)  credentials
connectionOptions: (NSDictionary< PTDiffusionRemoteServerConnectionOption *, NSString * > const *)  connectionOptions
completionHandler: (PTDiffusionCreateRemoteServerResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler 

Create a new remote server instance.

If a remote server with the same name already exists an error will be returned.

Parameters
namethe name of the remote server
urlthe URL used to connect to the primary server
principalthe name of a principal used by the remote server to connect to the primary server. A zero length string may be supplied to indicate an anonymous connection
credentialsused for connecting to the primary server
connectionOptionsmap of connection option settings. Any options not supplied will take their default values
completionHandlera completion handler that returns when a response is received from the server, returning a full definition of the remote server created by the operation

If the remote server definition is nil, this could mean an error has occurred. These may include:

  • RemoteServerAlreadyExists - if a remote server with the given name already exists
  • ClusterRouting or ClusterRepartition - if a transient cluster error occurred
  • SessionSecurity - if the calling session does not have PTDiffusionGlobalPermission.ControlServer permission
  • SessionClosed - if the session is closed
Since
6.5
- (void) listRemoteServers: (NSArray< PTDiffusionRemoteServer * > *_Nullable)  result
(NSError *_Nullable error)  completionHandler 

List all the remote servers that have been created.

Parameters
completionHandlera completion handler that returns when a response is received from the server, returning a list of remote servers.

If the list is nil, this could mean an error has occurred. These may include:

  • SessionSecurity - if the calling session does not have PTDiffusionGlobalPermission.ViewServer permission
  • SessionClosed - if the session is closed
Since
6.5
- (void) removeRemoteServer: (NSString *const)  name
completionHandler: (NSError *_Nullable error)  completionHandler 

Remove a named remote server if it exists.

If the named remote server does not exist the completionHandler will return without an error

When a named remote server is removed, any components that specify it would be disabled.

Parameters
namethe name of the remote server
completionHandlera completion handler that returns when a response is received from the server.

If the error is not nil, this means an error has occured. These may include:

  • ClusterRouting or ClusterRepartition - if a transient cluster error occurred
  • SessionSecurity - if the calling session does not have PTDiffusionGlobalPermission.ControlServer permission
  • SessionClosed - if the session is closed
Since
6.5