Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface RemoteServers

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:

const remoteServers = session.remoteServers;
since

6.5

Hierarchy

  • RemoteServers

Index

Methods

checkRemoteServer

  • 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: string

      the name of the remote server

    Returns Result<RemoteServerStatus>

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

    If the task fails, the Result will resolve with an error. Common reasons for failure include:

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

createRemoteServer

  • 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

    Parameters

    Returns Promise<RemoteServer>

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

    If the task fails, the Result will resolve with an error. Common reasons for failure include:

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

  • 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.

    deprecated

    since 6.7

    Use {@link RemoteServers.createRemoteServer(RemoteServer)} in preference. This method will be removed in a future release.

    Parameters

    • name: string

      the name of the remote server

    • url: string

      the URL to use to connect to the primary server

    • principal: string

      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: Credentials

      to use for connecting to the primary server

    • Optional connectionOptions: Partial<ConnectionOptions>

      (optional) a map of connection option settings. Any options not supplied will take their default values

    Returns Result<RemoteServer>

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

    If the task fails, the Result will resolve with an error. Common reasons for failure include:

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

listRemoteServers

  • List all the remote servers that have been created.

    Returns Result<RemoteServer[]>

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

    If the task fails, the Result will resolve with an Error. Common reasons for failure include:

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

removeRemoteServer

  • removeRemoteServer(name: string): Result<void>
  • Remove a named remote server if it exists.

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

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

    Parameters

    • name: string

      the name of the remote server

    Returns Result<void>

    a Result that resolves when a response is received from the server.

    If the task fails, the Result will resolve with an Error. Common reasons for failure include:

    • the cluster was repartitioning;
    • the calling session does not have CONTROL_SERVER permission;
    • the session is closed.