software.amazon.jdbc.hostlistprovider

Class TopologyUtils

java.lang.Object

software.amazon.jdbc.hostlistprovider.TopologyUtils

Direct Known Subclasses:

AuroraTopologyUtils, MultiAzTopologyUtils

public abstract class TopologyUtils
extends java.lang.Object

An abstract class defining utility methods that can be used to retrieve and process a variety of database topology information. This class can be overridden to define logic specific to various database engine deployments (e.g. Aurora, Multi-AZ, Global Aurora etc.).

Field Summary

Fields

Modifier and Type	Field and Description
protected static int	DEFAULT_QUERY_TIMEOUT_MS
protected TopologyDialect	dialect
protected HostSpecBuilder	hostSpecBuilder
protected java.util.concurrent.Executor	networkTimeoutExecutor

Constructor Summary

Constructors

Constructor and Description
TopologyUtils(TopologyDialect dialect, HostSpecBuilder hostSpecBuilder)

Method Summary

Modifier and Type	Method and Description
HostSpec	createHost(@Nullable java.lang.String instanceId, @Nullable java.lang.String instanceName, boolean isWriter, long weight, @Nullable java.lang.Float cpuPercent, @Nullable java.lang.Float lag, @Nullable java.sql.Timestamp lastUpdateTime, HostSpec initialHostSpec, HostSpec instanceTemplate) Creates a HostSpec from the given topology information, including a load value.
HostSpec	createHost(@Nullable java.lang.String instanceId, @Nullable java.lang.String instanceName, boolean isWriter, long weight, @Nullable java.sql.Timestamp lastUpdateTime, HostSpec initialHostSpec, HostSpec instanceTemplate) Creates a HostSpec from the given topology information.
protected abstract @Nullable java.util.List<HostSpec>	getHosts(java.sql.Connection conn, java.sql.ResultSet rs, HostSpec initialHostSpec, HostSpec instanceTemplate)
abstract boolean	isWriterInstance(java.sql.Connection connection) Evaluate whether the given connection is to a writer instance.
@Nullable java.util.List<HostSpec>	queryForTopology(java.sql.Connection conn, HostSpec initialHostSpec, HostSpec instanceTemplate) Query the database for information for each instance in the database topology.
protected Pair<java.lang.Integer,java.lang.Boolean>	setNetworkTimeout(java.sql.Connection conn)
protected @Nullable java.util.List<HostSpec>	verifyWriter(@Nullable java.util.List<HostSpec> allHosts)

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_QUERY_TIMEOUT_MS

protected static final int DEFAULT_QUERY_TIMEOUT_MS

See Also:

Constant Field Values

networkTimeoutExecutor

protected final java.util.concurrent.Executor networkTimeoutExecutor

dialect

protected final TopologyDialect dialect

hostSpecBuilder

protected final HostSpecBuilder hostSpecBuilder

Constructor Detail

TopologyUtils

public TopologyUtils(TopologyDialect dialect,
                     HostSpecBuilder hostSpecBuilder)

Method Detail

queryForTopology

public @Nullable java.util.List<HostSpec> queryForTopology(java.sql.Connection conn,
                                                           HostSpec initialHostSpec,
                                                           HostSpec instanceTemplate)
                                                    throws java.sql.SQLException

Query the database for information for each instance in the database topology.

Parameters:

conn - the connection to use to query the database.

initialHostSpec - the HostSpec that was used to initially connect.

instanceTemplate - the template HostSpec to use when constructing new HostSpec objects from the data returned by the topology query.

Returns:

a list of HostSpec objects representing the results of the topology query.

Throws:

java.sql.SQLException - if an error occurs when executing the topology or processing the results.

setNetworkTimeout

protected Pair<java.lang.Integer,java.lang.Boolean> setNetworkTimeout(java.sql.Connection conn)

getHosts

protected abstract @Nullable java.util.List<HostSpec> getHosts(java.sql.Connection conn,
                                                               java.sql.ResultSet rs,
                                                               HostSpec initialHostSpec,
                                                               HostSpec instanceTemplate)
                                                        throws java.sql.SQLException

Throws:

java.sql.SQLException

verifyWriter

protected @Nullable java.util.List<HostSpec> verifyWriter(@Nullable java.util.List<HostSpec> allHosts)

createHost

public HostSpec createHost(@Nullable java.lang.String instanceId,
                           @Nullable java.lang.String instanceName,
                           boolean isWriter,
                           long weight,
                           @Nullable java.sql.Timestamp lastUpdateTime,
                           HostSpec initialHostSpec,
                           HostSpec instanceTemplate)

Creates a HostSpec from the given topology information.

Parameters:

instanceId - the database instance identifier, e.g. "mydb-instance-1" or "db-WQFQKBTL2LQUPIEFIFBGENS4ZQ".

instanceName - the database instance name, e.g. "mydb-instance-1.cluster-xxxxx.region.rds.amazonaws.com".

isWriter - true if this is a writer instance, false for reader.

weight - the instance weight for load balancing.

lastUpdateTime - the timestamp of the last update to this instance's information.

initialHostSpec - the original host specification used for connecting.

instanceTemplate - the template used to construct the new HostSpec.

Returns:

a HostSpec representing the given information.

createHost

public HostSpec createHost(@Nullable java.lang.String instanceId,
                           @Nullable java.lang.String instanceName,
                           boolean isWriter,
                           long weight,
                           @Nullable java.lang.Float cpuPercent,
                           @Nullable java.lang.Float lag,
                           @Nullable java.sql.Timestamp lastUpdateTime,
                           HostSpec initialHostSpec,
                           HostSpec instanceTemplate)

Creates a HostSpec from the given topology information, including a load value.

Parameters:

instanceId - the database instance identifier.

instanceName - the database instance name.

isWriter - true if this is a writer instance, false for reader.

weight - the instance weight for load balancing.

lastUpdateTime - the timestamp of the last update to this instance's information.

initialHostSpec - the original host specification used for connecting.

instanceTemplate - the template used to construct the new HostSpec.

Returns:

a HostSpec representing the given information.

isWriterInstance

public abstract boolean isWriterInstance(java.sql.Connection connection)
                                  throws java.sql.SQLException

Evaluate whether the given connection is to a writer instance.

Parameters:

connection - the connection to evaluate.

Returns:

true if the connection is to a writer instance, false otherwise.

Throws:

java.sql.SQLException - if an exception occurs when querying the database or processing the database response.