software.amazon.jdbc

Interface PluginService

All Superinterfaces:

ExceptionHandler

All Known Implementing Classes:

PluginServiceImpl

public interface PluginService
extends ExceptionHandler

Interface for retrieving the current active Connection and its HostSpec.

Method Summary

Modifier and Type	Method and Description
boolean	acceptsStrategy(HostRole role, java.lang.String strategy) Returns a boolean indicating if the available ConnectionProvider or ConnectionPlugin instances support the selection of a host with the requested role and strategy via getHostSpecByStrategy(software.amazon.jdbc.HostRole, java.lang.String).
java.sql.Connection	connect(HostSpec hostSpec, java.util.Properties props) Establishes a connection to the given host using the given properties.
void	fillAliases(java.sql.Connection connection, HostSpec hostSpec)
java.sql.Connection	forceConnect(HostSpec hostSpec, java.util.Properties props) Establishes a connection to the given host using the given properties.
void	forceRefreshHostList()
boolean	forceRefreshHostList(boolean shouldVerifyWriter, long timeoutMs) Initiates a topology update.
void	forceRefreshHostList(java.sql.Connection connection)
java.util.List<HostSpec>	getAllHosts() Get host information for all hosts in the cluster.
ConnectionProvider	getConnectionProvider() Deprecated.
java.sql.Connection	getCurrentConnection()
HostSpec	getCurrentHostSpec()
Dialect	getDialect()
java.lang.String	getDriverProtocol()
HostListProvider	getHostListProvider()
HostRole	getHostRole(java.sql.Connection conn) Evaluates the host role of the given connection - either a writer or a reader.
java.util.List<HostSpec>	getHosts() Get host information for allowed hosts in the cluster.
HostSpecBuilder	getHostSpecBuilder()
HostSpec	getHostSpecByStrategy(HostRole role, java.lang.String strategy) Selects a HostSpec with the requested role from available hosts using the requested strategy.
HostSpec	getHostSpecByStrategy(java.util.List<HostSpec> hosts, HostRole role, java.lang.String strategy) Selects a HostSpec with the requested role from available hosts using the requested strategy.
HostSpec	getInitialConnectionHostSpec()
<T> T	getPlugin(java.lang.Class<T> pluginClazz)
java.util.Properties	getProperties()
@NonNull SessionStateService	getSessionStateService()
TargetDriverDialect	getTargetDriverDialect()
java.lang.String	getTargetName()
TelemetryFactory	getTelemetryFactory()
HostSpec	identifyConnection(java.sql.Connection connection)
boolean	isInTransaction()
boolean	isPooledConnectionProvider(HostSpec host, java.util.Properties props)
void	refreshHostList()
void	refreshHostList(java.sql.Connection connection)
void	setAllowedAndBlockedHosts(AllowedAndBlockedHosts allowedAndBlockedHosts) Set the collection of hosts that should be allowed and/or blocked for connections.
void	setAvailability(java.util.Set<java.lang.String> hostAliases, HostAvailability availability)
void	setCurrentConnection(@NonNull java.sql.Connection connection, @NonNull HostSpec hostSpec)
java.util.EnumSet<NodeChangeOptions>	setCurrentConnection(@NonNull java.sql.Connection connection, @NonNull HostSpec hostSpec, @Nullable ConnectionPlugin skipNotificationForThisPlugin) Set a new internal connection.
void	updateDialect(@NonNull java.sql.Connection connection)

Methods inherited from interface software.amazon.jdbc.exceptions.ExceptionHandler

isLoginException, isLoginException, isNetworkException, isNetworkException

Method Detail

getCurrentConnection

java.sql.Connection getCurrentConnection()

getCurrentHostSpec

HostSpec getCurrentHostSpec()

setCurrentConnection

void setCurrentConnection(@NonNull java.sql.Connection connection,
                          @NonNull HostSpec hostSpec)
                   throws java.sql.SQLException

Throws:

java.sql.SQLException

setCurrentConnection

java.util.EnumSet<NodeChangeOptions> setCurrentConnection(@NonNull java.sql.Connection connection,
                                                          @NonNull HostSpec hostSpec,
                                                          @Nullable ConnectionPlugin skipNotificationForThisPlugin)
                                                   throws java.sql.SQLException

Set a new internal connection. While setting a new connection, a notification may be sent to all plugins. See ConnectionPlugin.notifyConnectionChanged(EnumSet) for more details. A plugin mentioned in parameter skipNotificationForThisPlugin won't be receiving such notification.

Parameters:

connection - the new internal connection.

hostSpec - the host details for a new internal connection.

skipNotificationForThisPlugin - A reference to a plugin that doesn't need to receive notification about connection change. Usually, a plugin that initiates connection change doesn't need to receive such notification and uses a pointer to itself as a call parameter.

Returns:

a set of notification options about this connection switch.

Throws:

java.sql.SQLException

getAllHosts

java.util.List<HostSpec> getAllHosts()

Get host information for all hosts in the cluster.

Returns:

host information for all hosts in the cluster.

getHosts

java.util.List<HostSpec> getHosts()

Get host information for allowed hosts in the cluster. Certain hosts in the cluster may be disallowed, and these hosts will not be returned by this function. For example, if a custom endpoint is being used, hosts outside the custom endpoint will not be returned.

Returns:

host information for allowed hosts in the cluster.

getInitialConnectionHostSpec

HostSpec getInitialConnectionHostSpec()

setAllowedAndBlockedHosts

void setAllowedAndBlockedHosts(AllowedAndBlockedHosts allowedAndBlockedHosts)

Set the collection of hosts that should be allowed and/or blocked for connections.

Parameters:

allowedAndBlockedHosts - An object defining the allowed and blocked sets of hosts.

acceptsStrategy

boolean acceptsStrategy(HostRole role,
                        java.lang.String strategy)
                 throws java.sql.SQLException

Returns a boolean indicating if the available ConnectionProvider or ConnectionPlugin instances support the selection of a host with the requested role and strategy via getHostSpecByStrategy(software.amazon.jdbc.HostRole, java.lang.String).

Parameters:

role - the desired host role

strategy - the strategy that should be used to pick a host (eg "random")

Returns:

true if the available ConnectionProvider or ConnectionPlugin instances support the selection of a host with the requested role and strategy via getHostSpecByStrategy(software.amazon.jdbc.HostRole, java.lang.String). Otherwise, return false.

Throws:

java.sql.SQLException

getHostSpecByStrategy

HostSpec getHostSpecByStrategy(HostRole role,
                               java.lang.String strategy)
                        throws java.sql.SQLException,
                               java.lang.UnsupportedOperationException

Selects a HostSpec with the requested role from available hosts using the requested strategy. acceptsStrategy(software.amazon.jdbc.HostRole, java.lang.String) should be called first to evaluate if the available ConnectionProvider or ConnectionPlugin instances support the selection of a host with the requested role and strategy.

Parameters:

role - the desired role of the host - either a writer or a reader

strategy - the strategy that should be used to select a HostSpec from the available hosts (eg "random")

Returns:

a HostSpec with the requested role

Throws:

java.sql.SQLException - if the available ConnectionProvider or ConnectionPlugin instances do not cannot find a host matching the requested role or an error occurs while selecting a host

java.lang.UnsupportedOperationException - if the available ConnectionProvider or ConnectionPlugin instances do not support the requested strategy

getHostSpecByStrategy

HostSpec getHostSpecByStrategy(java.util.List<HostSpec> hosts,
                               HostRole role,
                               java.lang.String strategy)
                        throws java.sql.SQLException,
                               java.lang.UnsupportedOperationException

Selects a HostSpec with the requested role from available hosts using the requested strategy. acceptsStrategy(software.amazon.jdbc.HostRole, java.lang.String) should be called first to evaluate if the available ConnectionProvider or ConnectionPlugin instances support the selection of a host with the requested role and strategy.

Parameters:

hosts - the list of HostSpec from which a HostSpec will be selected from

role - the desired role of the host - either a writer or a reader

strategy - the strategy that should be used to select a HostSpec from the available hosts (eg "random")

Returns:

a HostSpec with the requested role

Throws:

java.sql.SQLException - if the available ConnectionProvider or ConnectionPlugin instances do not cannot find a host matching the requested role or an error occurs while selecting a host

java.lang.UnsupportedOperationException - if the available ConnectionProvider or ConnectionPlugin instances do not support the requested strategy

getHostRole

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

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

Parameters:

conn - 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

setAvailability

void setAvailability(java.util.Set<java.lang.String> hostAliases,
                     HostAvailability availability)

isInTransaction

boolean isInTransaction()

getHostListProvider

HostListProvider getHostListProvider()

refreshHostList

void refreshHostList()
              throws java.sql.SQLException

Throws:

java.sql.SQLException

refreshHostList

void refreshHostList(java.sql.Connection connection)
              throws java.sql.SQLException

Throws:

java.sql.SQLException

forceRefreshHostList

void forceRefreshHostList()
                   throws java.sql.SQLException

Throws:

java.sql.SQLException

forceRefreshHostList

void forceRefreshHostList(java.sql.Connection connection)
                   throws java.sql.SQLException

Throws:

java.sql.SQLException

forceRefreshHostList

boolean forceRefreshHostList(boolean shouldVerifyWriter,
                             long timeoutMs)
                      throws java.sql.SQLException

Initiates a topology update.

Parameters:

shouldVerifyWriter - true, if a caller expects to get topology with the latest confirmed writer

timeoutMs - timeout in msec to wait until topology gets refreshed and a new (or existing) writer is confirmed (if shouldVerifyWriter has a value of true).

Returns:

true, if successful. False, if operation is unsuccessful or timeout is reached

Throws:

java.sql.SQLException - if there was an error establishing a connection or fetching a topology

connect

java.sql.Connection connect(HostSpec hostSpec,
                            java.util.Properties props)
                     throws java.sql.SQLException

Establishes a connection to the given host using the given properties. If a non-default ConnectionProvider has been set with ConnectionProviderManager.setConnectionProvider(software.amazon.jdbc.ConnectionProvider) and ConnectionProvider.acceptsUrl(String, HostSpec, Properties) returns true for the desired protocol, host, and properties, the connection will be created by the non-default ConnectionProvider. Otherwise, the connection will be created by the default ConnectionProvider. The default ConnectionProvider will be DriverConnectionProvider for connections requested via the DriverManager and DataSourceConnectionProvider for connections requested via an AwsWrapperDataSource.

Parameters:

hostSpec - the host details for the desired connection

props - the connection properties

Returns:

a Connection to the requested host

Throws:

java.sql.SQLException - if there was an error establishing a Connection to the requested host

forceConnect

java.sql.Connection forceConnect(HostSpec hostSpec,
                                 java.util.Properties props)
                          throws java.sql.SQLException

Establishes a connection to the given host using the given properties. This call differs from ConnectionPlugin.connect(java.lang.String, software.amazon.jdbc.HostSpec, java.util.Properties, boolean, software.amazon.jdbc.JdbcCallable<java.sql.Connection, java.sql.SQLException>) in that the default ConnectionProvider will be used to establish the connection even if a non-default ConnectionProvider has been set via ConnectionProviderManager.setConnectionProvider(software.amazon.jdbc.ConnectionProvider). The default ConnectionProvider will be DriverConnectionProvider for connections requested via the DriverManager and DataSourceConnectionProvider for connections requested via an AwsWrapperDataSource.

Parameters:

hostSpec - the host details for the desired connection

props - the connection properties

Returns:

a Connection to the requested host

Throws:

java.sql.SQLException - if there was an error establishing a Connection to the requested host

getDialect

Dialect getDialect()

getTargetDriverDialect

TargetDriverDialect getTargetDriverDialect()

updateDialect

void updateDialect(@NonNull java.sql.Connection connection)
            throws java.sql.SQLException

Throws:

java.sql.SQLException

identifyConnection

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

Throws:

java.sql.SQLException

fillAliases

void fillAliases(java.sql.Connection connection,
                 HostSpec hostSpec)
          throws java.sql.SQLException

Throws:

java.sql.SQLException

getHostSpecBuilder

HostSpecBuilder getHostSpecBuilder()

getConnectionProvider

@Deprecated
ConnectionProvider getConnectionProvider()

Deprecated.

isPooledConnectionProvider

boolean isPooledConnectionProvider(HostSpec host,
                                   java.util.Properties props)

getDriverProtocol

java.lang.String getDriverProtocol()

getProperties

java.util.Properties getProperties()

getTelemetryFactory

TelemetryFactory getTelemetryFactory()

getTargetName

java.lang.String getTargetName()

getSessionStateService

@NonNull SessionStateService getSessionStateService()

getPlugin

<T> T getPlugin(java.lang.Class<T> pluginClazz)