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
@Nullable java.util.List<HostSpec>	forceRefresh() Force a host list provider to update its topology information.
@Nullable java.util.List<HostSpec>	forceRefresh(boolean verifyTopology, long timeoutMs) Force a host list provider to update its topology information.
java.lang.String	getClusterId()
@Nullable java.util.List<HostSpec>	getCurrentTopology(java.sql.Connection conn, HostSpec initialHostSpec) Get current topology information for the connected database.
java.util.List<HostSpec>	refresh()
void	stopMonitor()

Method Detail

getCurrentTopology

@Nullable 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

@Nullable 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

@Nullable 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

getClusterId

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

Throws:

java.lang.UnsupportedOperationException

java.sql.SQLException

stopMonitor

void stopMonitor()