software.aws.rds.jdbc.postgresql.ca

Interface TopologyService

All Known Implementing Classes:

AuroraTopologyService

public interface TopologyService

It's a generic interface for all topology services. It's expected that every implementation of topology service covers different cluster types or cluster deployment.

It's expected that each instance of ClusterAwareConnectionProxy uses it's own instance of topology service.

Method Summary

Modifier and Type	Method and Description
void	addToDownHostList(@Nullable HostInfo downHost) Mark host as down.
void	clear() Clear topology service for the current cluster.
void	clearAll() Clear topology service for all clusters.
@Nullable List<HostInfo>	getCachedTopology() Get cached topology.
Set<String>	getDownHosts() Get a set of host names that were marked down.
@Nullable HostInfo	getLastUsedReaderHost() Get details about the most recent reader that the driver has successfully connected to.
List<HostInfo>	getTopology(Connection conn, boolean forceUpdate) Get cluster topology.
void	removeFromDownHostList(HostInfo host) Unmark host as down.
void	setClusterId(String clusterId) Set unique cluster identifier for topology service instance.
void	setClusterInstanceTemplate(HostInfo clusterInstanceTemplate) Sets host details common to each instance in the cluster, including the host dns pattern.
void	setLastUsedReaderHost(@Nullable HostInfo reader) Set details about the most recent reader that the driver has connected to.
void	setRefreshRate(int refreshRate) Set new topology refresh rate.

Method Detail

setClusterId

void setClusterId(String clusterId)

Set unique cluster identifier for topology service instance.

Cluster could be accessed through different connection strings like IP address, cluster dns endpoint, instance dns endpoint, custom domain alias (CNAME), etc. Cluster Id can be any string that unique identify a cluster despite the way it's been accessed.

Parameters:

clusterId - Cluster unique identifier.

setClusterInstanceTemplate

void setClusterInstanceTemplate(HostInfo clusterInstanceTemplate)

Sets host details common to each instance in the cluster, including the host dns pattern. "?" (question mark) in a host dns pattern will be replaced with a host instance name to form a fully qualified dns host endpoint.

Examples: "?.mydomain.com", "db-instance.?.mydomain.com"

Parameters:

clusterInstanceTemplate - Cluster instance details including host dns pattern.

getTopology

List<HostInfo> getTopology(Connection conn,
                           boolean forceUpdate)

Get cluster topology. A writer host is always at position 0.

Parameters:

conn - A connection to database to fetch the latest topology, if needed.

forceUpdate - If true, it forces a service to ignore cached copy of topology and to fetch a fresh one.

Returns:

A list of hosts that describes cluster topology. A writer is always at position 0. Returns an empty list if topology isn't available or is invalid (doesn't contain a writer).

getCachedTopology

@Nullable List<HostInfo> getCachedTopology()

Get cached topology.

Returns:

List of hosts that represents topology. If there's no topology in cache, it returns null.

getLastUsedReaderHost

@Nullable HostInfo getLastUsedReaderHost()

Get details about the most recent reader that the driver has successfully connected to.

Returns:

The host details of the most recent reader connection.

setLastUsedReaderHost

void setLastUsedReaderHost(@Nullable HostInfo reader)

Set details about the most recent reader that the driver has connected to.

Parameters:

reader - A reader host.

getDownHosts

Set<String> getDownHosts()

Get a set of host names that were marked down.

Returns:

A set of host dns names with port. For example: "instance-1.my-domain.com:3306".

addToDownHostList

void addToDownHostList(@Nullable HostInfo downHost)

Mark host as down. Host stays marked down until next topology refresh.

Parameters:

downHost - The HostInfo object representing the host to mark as down

removeFromDownHostList

void removeFromDownHostList(HostInfo host)

Unmark host as down. The host is removed from the list of down hosts

Parameters:

host - The HostInfo object representing the host to remove from the list of down hosts

setRefreshRate

void setRefreshRate(int refreshRate)

Set new topology refresh rate. Topology is considered valid (up to date) within provided duration of time.

Parameters:

refreshRate - Topology refresh rate in millis.

clearAll

void clearAll()

Clear topology service for all clusters.

clear

void clear()

Clear topology service for the current cluster.