software.amazon.jdbc

Interface ConnectionPlugin

All Known Implementing Classes:

AbstractConnectionPlugin, AuroraConnectionTrackerPlugin, AuroraInitialConnectionStrategyPlugin, AuroraStaleDnsPlugin, AwsSecretsManagerConnectionPlugin, BlueGreenConnectionPlugin, ConnectTimeConnectionPlugin, CustomEndpointPlugin, DataCacheConnectionPlugin, DefaultConnectionPlugin, DeveloperConnectionPlugin, DriverMetaDataConnectionPlugin, ExecutionTimeConnectionPlugin, FailoverConnectionPlugin, FailoverConnectionPlugin, FastestResponseStrategyPlugin, FederatedAuthPlugin, HostMonitoringConnectionPlugin, HostMonitoringConnectionPlugin, IamAuthConnectionPlugin, LimitlessConnectionPlugin, LogQueryConnectionPlugin, OktaAuthPlugin, ReadWriteSplittingPlugin

public interface ConnectionPlugin

Interface for connection plugins. This class implements ways to execute a JDBC method and to clean up resources used before closing the plugin.

Method Summary

Modifier and Type	Method and Description
boolean	acceptsStrategy(HostRole role, java.lang.String strategy) Returns a boolean indicating if this ConnectionPlugin implements the specified host selection strategy for the given role in getHostSpecByStrategy(software.amazon.jdbc.HostRole, java.lang.String).
java.sql.Connection	connect(java.lang.String driverProtocol, HostSpec hostSpec, java.util.Properties props, boolean isInitialConnection, JdbcCallable<java.sql.Connection,java.sql.SQLException> connectFunc) Establishes a connection to the given host using the given driver protocol and properties.
<T,E extends java.lang.Exception> T	execute(java.lang.Class<T> resultClass, java.lang.Class<E> exceptionClass, java.lang.Object methodInvokeOn, java.lang.String methodName, JdbcCallable<T,E> jdbcMethodFunc, java.lang.Object[] jdbcMethodArgs)
java.sql.Connection	forceConnect(java.lang.String driverProtocol, HostSpec hostSpec, java.util.Properties props, boolean isInitialConnection, JdbcCallable<java.sql.Connection,java.sql.SQLException> forceConnectFunc) Establishes a connection to the given host using the given driver protocol and properties.
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)
java.util.Set<java.lang.String>	getSubscribedMethods()
void	initHostProvider(java.lang.String driverProtocol, java.lang.String initialUrl, java.util.Properties props, HostListProviderService hostListProviderService, JdbcCallable<java.lang.Void,java.sql.SQLException> initHostProviderFunc)
OldConnectionSuggestedAction	notifyConnectionChanged(java.util.EnumSet<NodeChangeOptions> changes)
void	notifyNodeListChanged(java.util.Map<java.lang.String,java.util.EnumSet<NodeChangeOptions>> changes)

Method Detail

getSubscribedMethods

java.util.Set<java.lang.String> getSubscribedMethods()

execute

<T,E extends java.lang.Exception> T execute(java.lang.Class<T> resultClass,
                                            java.lang.Class<E> exceptionClass,
                                            java.lang.Object methodInvokeOn,
                                            java.lang.String methodName,
                                            JdbcCallable<T,E> jdbcMethodFunc,
                                            java.lang.Object[] jdbcMethodArgs)
                                     throws E extends java.lang.Exception

Throws:

E extends java.lang.Exception

connect

java.sql.Connection connect(java.lang.String driverProtocol,
                            HostSpec hostSpec,
                            java.util.Properties props,
                            boolean isInitialConnection,
                            JdbcCallable<java.sql.Connection,java.sql.SQLException> connectFunc)
                     throws java.sql.SQLException

Establishes a connection to the given host using the given driver protocol and properties. If a non-default ConnectionProvider has been set with Driver.setCustomConnectionProvider(ConnectionProvider) and ConnectionProvider.acceptsUrl(String, HostSpec, Properties) returns true for the given 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:

driverProtocol - the driver protocol that should be used to establish the connection

hostSpec - the host details for the desired connection

props - the connection properties

isInitialConnection - a boolean indicating whether the current Connection is establishing an initial physical connection to the database or has already established a physical connection in the past

connectFunc - the function to call to continue the connect request down the connect pipeline

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(java.lang.String driverProtocol,
                                 HostSpec hostSpec,
                                 java.util.Properties props,
                                 boolean isInitialConnection,
                                 JdbcCallable<java.sql.Connection,java.sql.SQLException> forceConnectFunc)
                          throws java.sql.SQLException

Establishes a connection to the given host using the given driver protocol and properties. This call differs from 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 Driver.setCustomConnectionProvider(ConnectionProvider). The default ConnectionProvider will be DriverConnectionProvider for connections requested via the DriverManager and DataSourceConnectionProvider for connections requested via an AwsWrapperDataSource.

Parameters:

driverProtocol - the driver protocol that should be used to establish the connection

hostSpec - the host details for the desired connection

props - the connection properties

isInitialConnection - a boolean indicating whether the current Connection is establishing an initial physical connection to the database or has already established a physical connection in the past

forceConnectFunc - the function to call to continue the forceConnect request down the forceConnect pipeline

Returns:

a Connection to the requested host

Throws:

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

acceptsStrategy

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

Returns a boolean indicating if this ConnectionPlugin implements the specified host selection strategy for the given role in 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 this ConnectionPlugin supports the selection of a host with the requested role and strategy via getHostSpecByStrategy(software.amazon.jdbc.HostRole, java.lang.String). Otherwise, return false.

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 this ConnectionPlugin supports 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 hosts do not contain any hosts matching the requested role or an error occurs while selecting a host

java.lang.UnsupportedOperationException - if this ConnectionPlugin does 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

Throws:

java.sql.SQLException

java.lang.UnsupportedOperationException

initHostProvider

void initHostProvider(java.lang.String driverProtocol,
                      java.lang.String initialUrl,
                      java.util.Properties props,
                      HostListProviderService hostListProviderService,
                      JdbcCallable<java.lang.Void,java.sql.SQLException> initHostProviderFunc)
               throws java.sql.SQLException

Throws:

java.sql.SQLException

notifyConnectionChanged

OldConnectionSuggestedAction notifyConnectionChanged(java.util.EnumSet<NodeChangeOptions> changes)

notifyNodeListChanged

void notifyNodeListChanged(java.util.Map<java.lang.String,java.util.EnumSet<NodeChangeOptions>> changes)