com.mysql.cj.jdbc.ha.ca

Class AuroraTopologyService

java.lang.Object

com.mysql.cj.jdbc.ha.ca.AuroraTopologyService

All Implemented Interfaces:

CanCollectPerformanceMetrics, TopologyService

public class AuroraTopologyService
extends java.lang.Object
implements TopologyService, CanCollectPerformanceMetrics

An implementation of topology service for Aurora RDS. It uses information_schema.replica_host_status table to obtain cluster topology and caches it. Different instances of this service with the same 'clusterId' shares the same topology cache. Cache also includes a list of down hosts. That helps to avoid unnecessary attempts to connect them.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	clusterId
protected HostInfo	clusterInstanceTemplate
protected boolean	gatherPerfMetrics
protected Log	log The logger we're going to use.
protected static Log	NULL_LOGGER Null logger shared by all connections at startup.
protected ClusterAwareTimeMetricsHolder	queryTopologyMetrics
protected static ExpiringCache<java.lang.String,com.mysql.cj.jdbc.ha.ca.AuroraTopologyService.ClusterTopologyInfo>	topologyCache

Constructor Summary

Constructors

Constructor and Description
AuroraTopologyService(int refreshRateInMilliseconds, Log log) Initializes a service with provided topology refresh rate.
AuroraTopologyService(Log log) Initializes a service with topology default refresh rate.

Method Summary

Modifier and Type	Method and Description
void	addToDownHostList(HostInfo downHost) Mark host as down.
void	clear() Clear topology cache for the current cluster.
void	clearAll() Clear topology cache for all clusters.
java.util.List<HostInfo>	getCachedTopology() Get cached topology.
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 cached topology belongs to multi-writer cluster.
protected com.mysql.cj.jdbc.ha.ca.AuroraTopologyService.ClusterTopologyInfo	queryForTopology(JdbcConnection conn) Query the database for the cluster topology and use the results to record information about the topology.
void	removeFromDownHostList(HostInfo host) Unmark host as down.
void	reportMetrics(Log log) Report collected metrics to a provided logger.
void	setClusterId(java.lang.String clusterId) Sets cluster Id for a service instance.
void	setClusterInstanceTemplate(HostInfo clusterInstanceTemplate) Sets host details common to each instance in the cluster, including the host dns pattern.
static void	setExpireTime(int expireTimeMs) Service instances with the same cluster Id share cluster topology.
void	setLastUsedReaderHost(HostInfo reader) Set details about the most recent reader that the driver has connected to.
void	setPerformanceMetricsEnabled(boolean isEnabled) This service implementation supports metrics.
void	setRefreshRate(int refreshRate) Set new topology refresh rate.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

topologyCache

protected static final ExpiringCache<java.lang.String,com.mysql.cj.jdbc.ha.ca.AuroraTopologyService.ClusterTopologyInfo> topologyCache

clusterId

protected java.lang.String clusterId

clusterInstanceTemplate

protected HostInfo clusterInstanceTemplate

queryTopologyMetrics

protected ClusterAwareTimeMetricsHolder queryTopologyMetrics

gatherPerfMetrics

protected boolean gatherPerfMetrics

NULL_LOGGER

protected static final Log NULL_LOGGER

Null logger shared by all connections at startup.

log

protected transient Log log

The logger we're going to use.

Constructor Detail

AuroraTopologyService

public AuroraTopologyService(Log log)

Initializes a service with topology default refresh rate.

AuroraTopologyService

public AuroraTopologyService(int refreshRateInMilliseconds,
                             Log log)

Initializes a service with provided topology refresh rate.

Parameters:

refreshRateInMilliseconds - Topology refresh rate in millis

Method Detail

setExpireTime

public static void setExpireTime(int expireTimeMs)

Service instances with the same cluster Id share cluster topology. Shared topology is cached for a specified period of time. This method sets cache expiration time in millis.

Parameters:

expireTimeMs - Topology cache expiration time in millis

setClusterId

public void setClusterId(java.lang.String clusterId)

Sets cluster Id for a service instance. Different service instances with the same cluster Id share topology cache.

Specified by:

setClusterId in interface TopologyService

Parameters:

clusterId - Topology cluster Id

setClusterInstanceTemplate

public 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"

Specified by:

setClusterInstanceTemplate in interface TopologyService

Parameters:

clusterInstanceTemplate - Cluster instance details including host dns pattern.

getTopology

public java.util.List<HostInfo> getTopology(JdbcConnection conn,
                                            boolean forceUpdate)

Get cluster topology. It may require an extra call to database to fetch the latest topology. A cached copy of topology is returned if it's not yet outdated (controlled by refreshRateInMilliseconds).

Specified by:

getTopology in interface TopologyService

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

queryForTopology

protected com.mysql.cj.jdbc.ha.ca.AuroraTopologyService.ClusterTopologyInfo queryForTopology(JdbcConnection conn)

Query the database for the cluster topology and use the results to record information about the topology.

Parameters:

conn - A connection to database to fetch the latest topology.

Returns:

Cluster topology details.

getCachedTopology

public java.util.List<HostInfo> getCachedTopology()

Get cached topology.

Specified by:

getCachedTopology in interface TopologyService

Returns:

List of hosts that represents topology. If there's no topology in the cache or the cached topology is outdated, it returns null.

getLastUsedReaderHost

public HostInfo getLastUsedReaderHost()

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

Specified by:

getLastUsedReaderHost in interface TopologyService

Returns:

The host details of the most recent reader connection. Returns null if the driver has not connected to a reader within the refresh rate period.

setLastUsedReaderHost

public void setLastUsedReaderHost(HostInfo reader)

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

Specified by:

setLastUsedReaderHost in interface TopologyService

Parameters:

reader - A reader host.

getHostByName

public HostInfo getHostByName(JdbcConnection conn)

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

Specified by:

getHostByName in interface TopologyService

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

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

Get a set of instance names that were marked down.

Specified by:

getDownHosts in interface TopologyService

Returns:

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

addToDownHostList

public void addToDownHostList(HostInfo downHost)

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

Specified by:

addToDownHostList in interface TopologyService

Parameters:

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

removeFromDownHostList

public void removeFromDownHostList(HostInfo host)

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

Specified by:

removeFromDownHostList in interface TopologyService

Parameters:

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

isMultiWriterCluster

public boolean isMultiWriterCluster()

Check if cached topology belongs to multi-writer cluster.

Specified by:

isMultiWriterCluster in interface TopologyService

Returns:

True, if it's multi-writer cluster.

setRefreshRate

public void setRefreshRate(int refreshRate)

Set new topology refresh rate. Different service instances may have different topology refresh rate while sharing the same topology cache.

Specified by:

setRefreshRate in interface TopologyService

Parameters:

refreshRate - Topology refresh rate in millis.

clearAll

public void clearAll()

Clear topology cache for all clusters.

Specified by:

clearAll in interface TopologyService

clear

public void clear()

Clear topology cache for the current cluster.

Specified by:

clear in interface TopologyService

setPerformanceMetricsEnabled

public void setPerformanceMetricsEnabled(boolean isEnabled)

This service implementation supports metrics. This method enables collecting internal metrics. Metrics are disabled by default.

Specified by:

setPerformanceMetricsEnabled in interface CanCollectPerformanceMetrics

Parameters:

isEnabled - True to enable internal metrics.

reportMetrics

public void reportMetrics(Log log)

Report collected metrics to a provided logger.

Specified by:

reportMetrics in interface CanCollectPerformanceMetrics

Parameters:

log - Logger to report collected metrics to.