Interface IRemoteServers

This feature allows a client session to manage remote servers.

Inherited Members

IFeature.Session

Namespace: PushTechnology.ClientInterface.Client.Features.Control.Clients

Assembly: Diffusion.Client.dll

Syntax

public interface IRemoteServers : IFeature

Remarks

This feature provides the ability to configure the various modes of operation for the use of remote topic views. This is the ability for a topic view specification to indicate that the source topics for the view are to come from another server in a different Diffusion cluster. The server where the topic views are configured is referred to as the 'secondary server' and the server where the actual topics are is referred to as the 'primary server'.

Outbound Connection from the Secondary Server

The typical configuration for a remote server is that there is only configuration at the secondary server (the configuration is automatically distributed to all members of the secondary cluster). In this case, each secondary server connects to a server in the primary cluster (typically via a load-balancer).

Remote topic views can specify the use of such remote servers by name. The connection and disconnection 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 topic views that depend upon it, those topic views will be disabled.

This form of connection is provided by a IRemoteServer of type SECONDARY_INITIATOR and represented by the sub-type ISecondaryInitiator.

Such a remote server can be built using a ISecondaryInitiatorBuilder created using NewRemoteServerBuilder(RemoteServerType). It may then be added to the server (cluster) using CreateRemoteServerAsync(IRemoteServer).

In this mode a connection from secondary to primary server is only maintained when there is a topic view that depends upon it. There will be no connections if there are no topic views that specify the remote server.

Outbound Connection from the Primary Server

In some cases it may be preferred that the connection is initiated by the primary server, connecting to the secondary server cluster. In this case a single primary server will connect to all members of the secondary cluster.

This form of connection is provided by a IRemoteServer of type PRIMARY_INITIATOR and represented by the sub-type IPrimaryInitiator. This can be built using a IPrimaryInitiatorBuilder created using NewRemoteServerBuilder(RemoteServerType). It may then be added to the primary server (cluster) using CreateRemoteServerAsync(IRemoteServer). Secondly a IRemoteServer of type SECONDARY_ACCEPTOR and represented by the sub-type ISecondaryAcceptor should be created in the secondary server (cluster) with the same name as the primary initiator. Such a remote server can be built using a ISecondaryAcceptorBuilder created using NewRemoteServerBuilder(RemoteServerType). It may then be added to the secondary server (cluster) using CreateRemoteServerAsync(IRemoteServer).

Unlike the secondary initiator mode, this mode of connection will establish connections even if there are no topic views in the secondary server (cluster) that name the remote server. If the connection is lost any topic views that depend upon it will be disabled and the primary initiator will attempt to re-establish the connection(s). Topic views depending upon the remote server will only be enabled when the connection is re-established.

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:

• To create a remote server (see CreateRemoteServerAsync(String, String, String, ICredentials)), remove a remote server (see RemoveRemoteServerAsync(String)) or check a remote server (see CheckRemoteServerAsync(String)), a session needs the CONTROL_SERVER global permission.
• To list remote servers (see ListRemoteServersAsync()), a session needs the VIEW_SERVER global permission.

Accessing the feature

This feature may be obtained from an ISession as follows:

var remoteServers = session.RemoteServers;

Added in version 6.5.

Methods

CheckRemoteServerAsync(String)

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 secondary initiator connection.

Currently this only reports the state of the remote server at the server the session is connected to. In a cluster the state of the remote server on other cluster members is not reported.

Declaration

Task<ICheckRemoteServerResult> CheckRemoteServerAsync(string name)

Parameters

Type	Name	Description
String	name	The name of the remote server.

Returns

Type	Description
Task<ICheckRemoteServerResult>	A Task that completes when a response is received from the server, returning details of the remote server state.

Remarks

If the task fails, the Task will complete exceptionally. Common reasons for failure, listed by the exception reported as the cause, include:

• SessionSecurityExceptionif the calling session does not have CONTROL_SERVER permission;
• SessionClosedExceptionif the session is closed.

CheckRemoteServerAsync(String, CancellationToken)

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 secondary initiator connection.

Currently this only reports the state of the remote server at the server the session is connected to. In a cluster the state of the remote server on other cluster members is not reported.

Declaration

Task<ICheckRemoteServerResult> CheckRemoteServerAsync(string name, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	name	The name of the remote server.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<ICheckRemoteServerResult>	A Task that completes when a response is received from the server, returning details of the remote server state.

Remarks

If the task fails, the Task will complete exceptionally. Common reasons for failure, listed by the exception reported as the cause, include:

• SessionSecurityExceptionif the calling session does not have CONTROL_SERVER permission;
• SessionClosedExceptionif the session is closed.

CreateRemoteServerAsync(IRemoteServer)

Create a new remote server instance at the server.

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

Declaration

Task<IRemoteServer> CreateRemoteServerAsync(IRemoteServer remoteServer)

Parameters

Type	Name	Description
IRemoteServer	remoteServer	A remote server definition created using the appropriate sub-type of IRemoteServerBuilder remote server builder.

Returns

Type	Description
Task<IRemoteServer>	A Task that completes when a response is received from the server, returning a full definition of the remote server created by the operation. The returned object may need to be cast to the appropriate sub-type in order to obtain its full details.

Remarks

If the task fails, the Task will complete exceptionally. Common reasons for failure, listed by the exception reported as the cause, include:

• RemoteServerExistsExceptionif a remote server with the given name already exists;
• RemoteServerOptionsExceptionif one or more connection options are invalid;
• ClusterRoutingExceptionif the operation failed due to a transient cluster error;
• SessionSecurityExceptionif the calling session does not have CONTROL_SERVER permission;
• SessionClosedExceptionif the session is closed.

CreateRemoteServerAsync(IRemoteServer, CancellationToken)

Create a new remote server instance at the server.

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

Declaration

Task<IRemoteServer> CreateRemoteServerAsync(IRemoteServer remoteServer, CancellationToken cancellationToken)

Parameters

Type	Name	Description
IRemoteServer	remoteServer	A remote server definition created using the appropriate sub-type of IRemoteServerBuilder remote server builder.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<IRemoteServer>	A Task that completes when a response is received from the server, returning a full definition of the remote server created by the operation. The returned object may need to be cast to the appropriate sub-type in order to obtain its full details.

Remarks

If the task fails, the Task will complete exceptionally. Common reasons for failure, listed by the exception reported as the cause, include:

• RemoteServerExistsExceptionif a remote server with the given name already exists;
• RemoteServerOptionsExceptionif one or more connection options are invalid;
• ClusterRoutingExceptionif the operation failed due to a transient cluster error;
• SessionSecurityExceptionif the calling session does not have CONTROL_SERVER permission;
• SessionClosedExceptionif the session is closed.

CreateRemoteServerAsync(String, String, String, ICredentials)

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.

Declaration

Task<IRemoteServer> CreateRemoteServerAsync(string name, string url, string principal, ICredentials credentials)

Parameters

Type	Name	Description
String	name	The name of the remote server.
String	url	The URL to use to connect to the primary server.
String	principal	The 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.
ICredentials	credentials	To use for connecting to the primary server.

Returns

Type	Description
Task<IRemoteServer>	A Task that completes when a response is received from the server, returning a full definition of the remote server created by the operation.

Remarks

Caution

Deprecated since 6.7. Use CreateRemoteServerAsync(IRemoteServer) in preference. This method will be removed in a future release.

If the task fails, the Task will complete exceptionally. Common reasons for failure, listed by the exception reported as the cause, include:

• RemoteServerExistsExceptionif a remote server with the given name already exists;
• ClusterRoutingExceptionif the operation failed due to a transient cluster error;
• SessionSecurityExceptionif the calling session does not have CONTROL_SERVER permission;
• SessionClosedExceptionif the session is closed.

CreateRemoteServerAsync(String, String, String, ICredentials, CancellationToken)

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.

Declaration

Task<IRemoteServer> CreateRemoteServerAsync(string name, string url, string principal, ICredentials credentials, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	name	The name of the remote server.
String	url	The URL to use to connect to the primary server.
String	principal	The 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.
ICredentials	credentials	To use for connecting to the primary server.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<IRemoteServer>	A Task that completes when a response is received from the server, returning a full definition of the remote server created by the operation.

Remarks

Caution

Deprecated since 6.7. Use CreateRemoteServerAsync(IRemoteServer) in preference. This method will be removed in a future release.

If the task fails, the Task will complete exceptionally. Common reasons for failure, listed by the exception reported as the cause, include:

• RemoteServerExistsExceptionif a remote server with the given name already exists;
• ClusterRoutingExceptionif the operation failed due to a transient cluster error;
• SessionSecurityExceptionif the calling session does not have CONTROL_SERVER permission;
• SessionClosedExceptionif the session is closed.

CreateRemoteServerAsync(String, String, String, ICredentials, Dictionary<RemoteServerConnectionOption, String>)

Create a new remote server instance.

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

Declaration

Task<IRemoteServer> CreateRemoteServerAsync(string name, string url, string principal, ICredentials credentials, Dictionary<RemoteServerConnectionOption, string> connectionOptions)

Parameters

Type	Name	Description
String	name	The name of the remote server.
String	url	The URL to use to connect to the primary server.
String	principal	The 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.
ICredentials	credentials	To use for connecting to the primary server.
Dictionary<RemoteServerConnectionOption, String>	connectionOptions	A dictionary of connection option settings. Any options not supplied will take their default values.

Returns

Type	Description
Task<IRemoteServer>	A Task that completes when a response is received from the server, returning a full definition of the remote server created by the operation.

Remarks

Caution

Deprecated since 6.7. Use CreateRemoteServerAsync(IRemoteServer) in preference. This method will be removed in a future release.

If the task fails, the Task will complete exceptionally. Common reasons for failure, listed by the exception reported as the cause, include:

• RemoteServerExistsExceptionif a remote server with the given name already exists;
• RemoteServerOptionsExceptionif one or more connection options are invalid;
• ClusterRoutingExceptionif the operation failed due to a transient cluster error;
• SessionSecurityExceptionif the calling session does not have CONTROL_SERVER permission;
• SessionClosedExceptionif the session is closed.

CreateRemoteServerAsync(String, String, String, ICredentials, Dictionary<RemoteServerConnectionOption, String>, CancellationToken)

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.

Declaration

Task<IRemoteServer> CreateRemoteServerAsync(string name, string url, string principal, ICredentials credentials, Dictionary<RemoteServerConnectionOption, string> connectionOptions, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	name	The name of the remote server.
String	url	The URL to use to connect to the primary server.
String	principal	The 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.
ICredentials	credentials	To use for connecting to the primary server.
Dictionary<RemoteServerConnectionOption, String>	connectionOptions	A dictionary of connection option settings. Any options not supplied will take their default values.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<IRemoteServer>	A Task that completes when a response is received from the server, returning a full definition of the remote server created by the operation.

Remarks

Caution

Deprecated since 6.7. Use CreateRemoteServerAsync(IRemoteServer) in preference. This method will be removed in a future release.

If the task fails, the Task will complete exceptionally. Common reasons for failure, listed by the exception reported as the cause, include:

• RemoteServerExistsExceptionif a remote server with the given name already exists;
• RemoteServerOptionsExceptionif one or more connection options are invalid;
• ClusterRoutingExceptionif the operation failed due to a transient cluster error;
• SessionSecurityExceptionif the calling session does not have CONTROL_SERVER permission;
• SessionClosedExceptionif the session is closed.

ListRemoteServersAsync()

List all the remote servers that have been created.

Declaration

Task<List<IRemoteServer>> ListRemoteServersAsync()

Returns

Type	Description
Task<List<IRemoteServer>>	A Task that completes when a response is received from the server, returning a list of remote servers. The remote server objects may need to be cast to the appropriate sub-type in order to obtain all details.

Remarks

If the task fails, the Task will complete exceptionally. Common reasons for failure, listed by the exception reported as the cause, include:

• SessionSecurityExceptionif the calling session does not have VIEW_SERVER permission;
• SessionClosedExceptionif the session is closed.

ListRemoteServersAsync(CancellationToken)

List all the remote servers that have been created.

Declaration

Task<List<IRemoteServer>> ListRemoteServersAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<List<IRemoteServer>>	A Task that completes when a response is received from the server, returning a list of remote servers. The remote server objects may need to be cast to the appropriate sub-type in order to obtain all details.

Remarks

If the task fails, the Task will complete exceptionally. Common reasons for failure, listed by the exception reported as the cause, include:

• SessionSecurityExceptionif the calling session does not have VIEW_SERVER permission;
• SessionClosedExceptionif the session is closed.

RemoveRemoteServerAsync(String)

Remove a named remote server if it exists.

If the named remote server does not exist the Task will complete successfully.

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

Declaration

Task<object> RemoveRemoteServerAsync(string name)

Parameters

Type	Name	Description
String	name	The name of the remote server.

Returns

Type	Description
Task<Object>	A Task that completes when a response is received from the server.

Remarks

If the task fails, the Task will complete exceptionally. Common reasons for failure, listed by the exception reported as the cause, include:

• ClusterRoutingExceptionif the operation failed due to a transient cluster error;
• SessionSecurityExceptionif the calling session does not have CONTROL_SERVER permission;
• SessionClosedExceptionif the session is closed.

RemoveRemoteServerAsync(String, CancellationToken)

Remove a named remote server if it exists.

If the named remote server does not exist the Task will complete successfully.

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

Declaration

Task<object> RemoveRemoteServerAsync(string name, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	name	The name of the remote server.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<Object>	A Task that completes when a response is received from the server.

Remarks

If the task fails, the Task will complete exceptionally. Common reasons for failure, listed by the exception reported as the cause, include:

• ClusterRoutingExceptionif the operation failed due to a transient cluster error;
• SessionSecurityExceptionif the calling session does not have CONTROL_SERVER permission;
• SessionClosedExceptionif the session is closed.