com.pushtechnology.diffusion.client.features.control

Interface RemoteServers

All Superinterfaces:

Feature

public interface RemoteServers
extends Feature

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:

• To create, remove or check a remote server, a session needs the CONTROL_SERVER global permission. To list remote servers , a session needs the VIEW_SERVER global permission.

Accessing the feature

This feature may be obtained from a session as follows:

 RemoteServers remoteServers = session.feature(RemoteServers.class);
 

Since:

6.5

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	RemoteServers.CheckRemoteServerResult Result returned from a checkRemoteServer(java.lang.String) invocation.
static interface	RemoteServers.RemoteServer Interface for a Remote Server specification.
static class	RemoteServers.RemoteServerExistsException Exception thrown when an attempt has been made to create a remote server when one with the same name is already defined.
static class	RemoteServers.RemoteServerOptionsException Exception thrown when one or more of the options specified when creating a remote server have been found to be invalid.

Method Summary

Modifier and Type	Method and Description
CompletableFuture<RemoteServers.CheckRemoteServerResult>	checkRemoteServer(String name) Check the current state of a named remote server.
CompletableFuture<RemoteServers.RemoteServer>	createRemoteServer(RemoteServers.RemoteServer remoteServer) Create a new remote server instance at the server.
default CompletableFuture<RemoteServers.RemoteServer>	createRemoteServer(String name, String url, String principal, Credentials credentials) Deprecated. since 6.7 Use createRemoteServer(RemoteServer) in preference. This method will be removed in a future release.
CompletableFuture<RemoteServers.RemoteServer>	createRemoteServer(String name, String url, String principal, Credentials credentials, Map<RemoteServers.RemoteServer.ConnectionOption,String> connectionOptions) Deprecated. since 6.7 Use createRemoteServer(RemoteServer) in preference. This method will be removed in a future release.
CompletableFuture<List<RemoteServers.RemoteServer>>	listRemoteServers() List all the remote servers that have been created.
CompletableFuture<Void>	removeRemoteServer(String name) Remove a named remote server if it exists.

Methods inherited from interface com.pushtechnology.diffusion.client.session.Feature

getSession

Method Detail

createRemoteServer

CompletableFuture<RemoteServers.RemoteServer> createRemoteServer(RemoteServers.RemoteServer remoteServer)

Create a new remote server instance at the server.

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

Parameters:

remoteServer - a remote server definition created using a remote server builder.

Returns:

a CompletableFuture that completes when a response is received from the server, returning a full definition of the remote server created by the operation.

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

• RemoteServers.RemoteServerExistsException – if a remote server with the given name already exists;
• RemoteServers.RemoteServerOptionsException – if one or more connection options are invalid;
• ClusterRoutingException – if the operation failed due to a transient cluster error;
• PermissionsException – if the calling session does not have CONTROL_SERVER permission;
• SessionClosedException – if the session is closed.

Since:

6.7

createRemoteServer

@Deprecated
default CompletableFuture<RemoteServers.RemoteServer> createRemoteServer(String name,
                                                                                     String url,
                                                                                     String principal,
                                                                                     Credentials credentials)

Deprecated. since 6.7

Use createRemoteServer(RemoteServer) in preference. This method will be removed in a future release.

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:

name - the name of the remote server

url - the URL to use to connect to the primary server

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

credentials - to use for connecting to the primary server

Returns:

a CompletableFuture that completes when a response is received from the server, returning a full definition of the remote server created by the operation.

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

• RemoteServers.RemoteServerExistsException – if a remote server with the given name already exists;
• ClusterRoutingException – if the operation failed due to a transient cluster error;
• PermissionsException – if the calling session does not have CONTROL_SERVER permission;
• SessionClosedException – if the session is closed.

createRemoteServer

@Deprecated
CompletableFuture<RemoteServers.RemoteServer> createRemoteServer(String name,
                                                                             String url,
                                                                             String principal,
                                                                             Credentials credentials,
                                                                             Map<RemoteServers.RemoteServer.ConnectionOption,String> connectionOptions)

Deprecated. since 6.7

Use createRemoteServer(RemoteServer) in preference. This method will be removed in a future release.

Create a new remote server instance.

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

Parameters:

name - the name of the remote server

url - the URL to use to connect to the primary server

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

credentials - to use for connecting to the primary server

connectionOptions - a map of connection option settings. Any options not supplied will take their default values

Returns:

a CompletableFuture that completes when a response is received from the server, returning a full definition of the remote server created by the operation.

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

• RemoteServers.RemoteServerExistsException – if a remote server with the given name already exists;
• RemoteServers.RemoteServerOptionsException – if one or more connection options are invalid;
• ClusterRoutingException – if the operation failed due to a transient cluster error;
• PermissionsException – if the calling session does not have CONTROL_SERVER permission;
• SessionClosedException – if the session is closed.

listRemoteServers

CompletableFuture<List<RemoteServers.RemoteServer>> listRemoteServers()

List all the remote servers that have been created.

Returns:

a CompletableFuture that completes when a response is received from the server, returning a list of remote servers.

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

• PermissionsException – if the calling session does not have VIEW_SERVER permission;
• SessionClosedException – if the session is closed.

checkRemoteServer

CompletableFuture<RemoteServers.CheckRemoteServerResult> checkRemoteServer(String name)

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:

name - the name of the remote server

Returns:

a CompletableFuture that completes when a response is received from the server, returning details of the remote server state.

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

• PermissionsException – if the calling session does not have CONTROL_SERVER permission;
• SessionClosedException – if the session is closed.

removeRemoteServer

CompletableFuture<Void> removeRemoteServer(String name)

Remove a named remote server if it exists.

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

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

Parameters:

name - the name of the remote server

Returns:

a CompletableFuture that completes when a response is received from the server.

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

• ClusterRoutingException – if the operation failed due to a transient cluster error;
• PermissionsException – if the calling session does not have CONTROL_SERVER permission;
• SessionClosedException – if the session is closed.