com.mysql.cj.jdbc.ha.plugins.failover

Interface ITopologyService

All Known Implementing Classes:

AuroraTopologyService

public interface ITopologyService

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 its own instance of topology service.

Method Summary

Modifier and Type	Method and Description
void	addToDownHostList(HostInfo downHost) Mark host as down.
void	clear() Clear topology service for the current cluster.
void	clearAll() Clear topology service for all clusters.
java.util.List<HostInfo>	getCachedTopology() Get cached topology.
java.lang.String	getClusterId() Returns the unique cluster identifier for topology service instance
java.util.Set<java.lang.String>	getDownHosts() Get a set of instance names that were marked down.
HostInfo	getHostByName(JdbcConnection conn) Return the HostInfo object that is associated with a provided connection from the topology host list.
HostInfo	getLastUsedReaderHost() Get details about the most recent reader that the driver has successfully connected to.
java.util.List<HostInfo>	getTopology(JdbcConnection conn, boolean forceUpdate) Get cluster topology.
boolean	isMultiWriterCluster() Check if topology belongs to multi-writer cluster.
void	removeFromDownHostList(HostInfo host) Unmark host as down.
void	setClusterId(java.lang.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(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(java.lang.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.

getClusterId

java.lang.String getClusterId()

Returns the unique cluster identifier for topology service instance

Returns:

cluster Id

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

java.util.List<HostInfo> getTopology(JdbcConnection conn,
                                     boolean forceUpdate)
                              throws java.sql.SQLException

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

Throws:

java.sql.SQLException

getCachedTopology

java.util.List<HostInfo> getCachedTopology()

Get cached topology.

Returns:

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

getLastUsedReaderHost

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(HostInfo reader)

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

Parameters:

reader - A reader host.

getHostByName

HostInfo getHostByName(JdbcConnection conn)

Return the HostInfo object that is associated with a provided connection from the topology host list.

Parameters:

conn - A connection to database.

Returns:

The HostInfo object from the topology host list. Returns null if the connection host is not found in the latest topology.

getDownHosts

java.util.Set<java.lang.String> getDownHosts()

Get a set of instance names that were marked down.

Returns:

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

addToDownHostList

void addToDownHostList(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

isMultiWriterCluster

boolean isMultiWriterCluster()

Check if topology belongs to multi-writer cluster.

Returns:

True, if it's multi-writer cluster.

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.