public interface RemoteServers extends Feature
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'.
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 RemoteServers.RemoteServer
of type
SECONDARY_INITIATOR
and
represented by the sub-type SecondaryInitiator
.
Such a remote server can be built using an
SecondaryInitiatorBuilder
created using
Diffusion.newRemoteServerBuilder(Class)
. It may then be added to the
server (cluster) using createRemoteServer(com.pushtechnology.diffusion.client.features.control.RemoteServers.RemoteServer)
.
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.
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 RemoteServers.RemoteServer
of type
PRIMARY_INITIATOR
and represented
by the sub-type PrimaryInitiator
. This
can be built using a
PrimaryInitiatorBuilder
created using
Diffusion.newRemoteServerBuilder(Class)
. It may then be added to the
primary server (cluster) using createRemoteServer(com.pushtechnology.diffusion.client.features.control.RemoteServers.RemoteServer)
. Secondly a
RemoteServers.RemoteServer
of type SECONDARY_ACCEPTOR
and represented by the sub-type
SecondaryAcceptor
should be created
in the secondary server (cluster) with the same name as the primary
initiator. Such a remote server can be built using an
SecondaryAcceptorBuilder
created using
Diffusion.newRemoteServerBuilder(Class)
. It may then be added to the
secondary server (cluster) using createRemoteServer(com.pushtechnology.diffusion.client.features.control.RemoteServers.RemoteServer)
.
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 configurations created through this feature are replicated across a cluster and persisted to disk.
The following access control restrictions are applied:
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.
This feature may be obtained from a session
as follows:
RemoteServers remoteServers = session.feature(RemoteServers.class);
Modifier and Type | Interface and Description |
---|---|
static interface |
RemoteServers.CheckRemoteServerResult
Result returned from a
checkRemoteServer(java.lang.String) invocation. |
static interface |
RemoteServers.PrimaryInitiator
A primary initiator.
|
static interface |
RemoteServers.RemoteServer
Base interface for a remote server definition.
|
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.
|
static interface |
RemoteServers.SecondaryAcceptor
Secondary remote server that accepts a connection from a primary server.
|
static interface |
RemoteServers.SecondaryInitiator
Secondary remote server that initiates a connection to a primary server.
|
static interface |
RemoteServers.SecondaryServer
Base interface for a secondary remote server.
|
getSession
CompletableFuture<RemoteServers.RemoteServer> createRemoteServer(RemoteServers.RemoteServer remoteServer)
If a remote server with the same name already exists an error will be returned.
remoteServer
- a remote server definition created using the
appropriate sub-type of RemoteServers.RemoteServer.RemoteServerBuilder
.
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.
@Deprecated default CompletableFuture<RemoteServers.RemoteServer> createRemoteServer(String name, String url, String principal, Credentials credentials)
Use createRemoteServer(RemoteServer)
in preference.
This method will be removed in a future release.
If a remote server with the same name already exists an error will be returned.
name
- the name of the remote serverurl
- the URL to use to connect to the primary serverprincipal
- 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 connectioncredentials
- to use for connecting to the primary 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:
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.
@Deprecated CompletableFuture<RemoteServers.RemoteServer> createRemoteServer(String name, String url, String principal, Credentials credentials, Map<RemoteServers.RemoteServer.ConnectionOption,String> connectionOptions)
Use createRemoteServer(RemoteServer)
in preference.
This method will be removed in a future release.
If a remote server with the same name already exists an error will be returned.
name
- the name of the remote serverurl
- the URL to use to connect to the primary serverprincipal
- 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 connectioncredentials
- to use for connecting to the primary serverconnectionOptions
- a map of connection option settings. Any options
not supplied will take their default values
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.
CompletableFuture<List<RemoteServers.RemoteServer>> listRemoteServers()
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.
CompletableFuture<RemoteServers.CheckRemoteServerResult> checkRemoteServer(String name)
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.
name
- the name of the remote 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:
PermissionsException
– if the calling session
does not have CONTROL_SERVER permission;
SessionClosedException
– if the session is
closed.
CompletableFuture<Void> removeRemoteServer(String name)
If the named remote server does not exist the CompletableFuture will complete successfully.
When a named remote server is removed, any topic views that specify it would be disabled.
name
- the name of the remote 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.
Copyright © 2024 DiffusionData Ltd. All Rights Reserved.