software.amazon.jdbc.hostlistprovider

Interface HostListProvider

All Known Subinterfaces:

DynamicHostListProvider, StaticHostListProvider

All Known Implementing Classes:

ConnectionStringHostListProvider, GlobalAuroraHostListProvider, RdsHostListProvider

public interface HostListProvider

Method Summary

Modifier and Type	Method and Description
java.util.List<HostSpec>	forceRefresh() Force a host list provider to update its topology information.
java.util.List<HostSpec>	forceRefresh(boolean verifyTopology, long timeoutMs) Force a host list provider to update its topology information.
java.lang.String	getClusterId()
java.util.List<HostSpec>	getCurrentTopology(java.sql.Connection conn, HostSpec initialHostSpec) Get current topology information for the connected database.
HostRole	getHostRole(java.sql.Connection connection) Evaluates the host role of the given connection - either a writer or a reader.
@Nullable HostSpec	identifyConnection(java.sql.Connection connection)
java.util.List<HostSpec>	refresh()
void	stopMonitor()

Method Detail

getCurrentTopology

java.util.List<HostSpec> getCurrentTopology(java.sql.Connection conn,
                                            HostSpec initialHostSpec)
                                     throws java.sql.SQLException

Get current topology information for the connected database. The returned topology should be the static host list if `this` is a StaticHostListProvider. The returned topology should be fresh info returned from a topology query if `this` is a DynamicHostListProvider,

Parameters:

conn - the connection to use to query the database for topology information, if needed.

initialHostSpec - the host details of the initial connection.

Returns:

the topology information for the connected database.

Throws:

java.sql.SQLException - if an error occurs while attempting to acquire the database topology information.

refresh

java.util.List<HostSpec> refresh()
                          throws java.sql.SQLException

Throws:

java.sql.SQLException

forceRefresh

java.util.List<HostSpec> forceRefresh()
                               throws java.sql.SQLException,
                                      java.util.concurrent.TimeoutException

Force a host list provider to update its topology information. Results will be returned when the topology is updated or the writer is verified, unless the default timeout is hit. It the caller needs topology from a verified writer or with a different timeout value, they should call forceRefresh(boolean, long) instead.

Returns:

a list of host details representing a cluster topology

Throws:

java.sql.SQLException - if there's errors updating topology

java.util.concurrent.TimeoutException - if topology update takes longer time than expected

forceRefresh

java.util.List<HostSpec> forceRefresh(boolean verifyTopology,
                                      long timeoutMs)
                               throws java.sql.SQLException,
                                      java.util.concurrent.TimeoutException

Force a host list provider to update its topology information. Results will be returned when the topology is updated or the writer is verified, unless the timeout is hit.

Parameters:

verifyTopology - defines whether extra measures should be taken to verify the topology. If false, the method will return as soon as topology is successfully retrieved from any instance. If true, extra steps are taken to verify the topology is accurate.

timeoutMs - timeout in msec to wait until topology is updated or the writer is verified. If a timeout of 0 is provided, a topology update will be initiated but cached topology will be returned. If a non-zero timeout is provided and the timeout is hit, a TimeoutException will be thrown.

Returns:

a list of host details representing the cluster topology

Throws:

java.sql.SQLException - if there's errors updating topology

java.util.concurrent.TimeoutException - if the timeout is hit

getHostRole

HostRole getHostRole(java.sql.Connection connection)
              throws java.sql.SQLException

Evaluates the host role of the given connection - either a writer or a reader.

Parameters:

connection - a connection to the database instance whose role should be determined

Returns:

the role of the given connection - either a writer or a reader

Throws:

java.sql.SQLException - if there is a problem executing or processing the SQL query used to determine the host role

identifyConnection

@Nullable HostSpec identifyConnection(java.sql.Connection connection)
                               throws java.sql.SQLException

Throws:

java.sql.SQLException

getClusterId

java.lang.String getClusterId()
                       throws java.lang.UnsupportedOperationException,
                              java.sql.SQLException

Throws:

java.lang.UnsupportedOperationException

java.sql.SQLException

stopMonitor

void stopMonitor()