software.amazon.jdbc

Interface PluginService

All Superinterfaces:

ExceptionHandler, StateSnapshotProvider, java.sql.Wrapper

All Known Implementing Classes:

PartialPluginService, PluginServiceImpl

public interface PluginService
extends ExceptionHandler, java.sql.Wrapper, StateSnapshotProvider

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.
java.sql.Connection	connect(HostSpec hostSpec, java.util.Properties props, @Nullable ConnectionPlugin pluginToSkip)
java.sql.Connection	forceConnect(HostSpec hostSpec, java.util.Properties props) Establishes a connection to the given host using the given properties.
java.sql.Connection	forceConnect(HostSpec hostSpec, java.util.Properties props, @Nullable ConnectionPlugin pluginToSkip)
void	forceRefreshHostList()
boolean	forceRefreshHostList(boolean verifyTopology, long timeoutMs) Initiates a topology update.
java.util.List<HostSpec>	getAllHosts() Get host information for all hosts in the cluster.
PluginCallContext	getCallContext() Returns the per-call context that flows through the plugin pipeline for the current JDBC call.
java.sql.Connection	getCurrentConnection()
HostSpec	getCurrentHostSpec()
ConnectionProvider	getDefaultConnectionProvider()
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(@Nullable 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, @Nullable HostRole role, java.lang.String strategy) Selects a HostSpec with the requested role from available hosts using the requested strategy.
HostSpec	getInitialConnectionHostSpec()
java.lang.String	getOriginalUrl()
<T> T	getPlugin(java.lang.Class<T> pluginClazz)
java.util.Properties	getProperties()
@Nullable HostSpec	getRoutedHostSpec()
@NonNull SessionStateService	getSessionStateService()
TargetDriverDialect	getTargetDriverDialect()
java.lang.String	getTargetName()
TelemetryFactory	getTelemetryFactory()
TrackedConnectionList.Node	getTrackedConnectionNode() Returns the tracked connection list node associated with the current connection.
@Nullable HostSpec	identifyConnection(java.sql.Connection connection)
@Nullable HostSpec	identifyConnection(java.sql.Connection connection, @NonNull HostSpec connectionHostSpec)
boolean	isDialectConfirmed()
boolean	isInTransaction()
boolean	isPluginInUse(java.lang.Class<? extends ConnectionPlugin> pluginClazz)
@Nullable java.lang.Boolean	isPooledConnection() Retrieves details about the most recent connect(software.amazon.jdbc.HostSpec, java.util.Properties, software.amazon.jdbc.ConnectionPlugin) or forceConnect(software.amazon.jdbc.HostSpec, java.util.Properties) calls.
boolean	isPooledConnectionProvider(HostSpec host, java.util.Properties props) Deprecated.
void	refreshHostList()
void	setAvailability(@NonNull HostSpec hostSpec, @NonNull 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	setRoutedHostSpec(@Nullable HostSpec routedHostSpec)
void	setTrackedConnectionNode(TrackedConnectionList.Node node) Sets the tracked connection list node for the current connection.
void	updateDialect(@NonNull java.sql.Connection connection)

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

isLoginException, isLoginException, isNetworkException, isNetworkException, isReadOnlyConnectionException, isReadOnlyConnectionException

Methods inherited from interface java.sql.Wrapper

isWrapperFor, unwrap

Methods inherited from interface software.amazon.jdbc.util.StateSnapshotProvider

getSnapshotState

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 - if there's an error setting a current connection.

getRoutedHostSpec

@Nullable HostSpec getRoutedHostSpec()

setRoutedHostSpec

void setRoutedHostSpec(@Nullable HostSpec routedHostSpec)

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()

getOriginalUrl

java.lang.String getOriginalUrl()

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 - if there's an error processing this method.

getHostSpecByStrategy

HostSpec getHostSpecByStrategy(@Nullable 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,
                               @Nullable 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(@NonNull HostSpec hostSpec,
                     @NonNull HostAvailability availability)

isInTransaction

boolean isInTransaction()

isDialectConfirmed

boolean isDialectConfirmed()

getHostListProvider

HostListProvider getHostListProvider()

refreshHostList

void refreshHostList()
              throws java.sql.SQLException

Throws:

java.sql.SQLException

forceRefreshHostList

void forceRefreshHostList()
                   throws java.sql.SQLException

Throws:

java.sql.SQLException

forceRefreshHostList

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

Initiates a topology update.

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 the topology gets refreshed (if verifyWriter has a value of false) or verified (if verifyTopology has a value of true).

Returns:

true if successful, false if unsuccessful or the 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,
                            @Nullable ConnectionPlugin pluginToSkip)
                     throws java.sql.SQLException

Throws:

java.sql.SQLException

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 Driver.setCustomConnectionProvider(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 Driver.setCustomConnectionProvider(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,
                                 @Nullable ConnectionPlugin pluginToSkip)
                          throws java.sql.SQLException

Throws:

java.sql.SQLException

getDialect

Dialect getDialect()

getTargetDriverDialect

TargetDriverDialect getTargetDriverDialect()

updateDialect

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

Throws:

java.sql.SQLException

identifyConnection

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

Throws:

java.sql.SQLException

identifyConnection

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

Throws:

java.sql.SQLException

getHostSpecBuilder

HostSpecBuilder getHostSpecBuilder()

getDefaultConnectionProvider

ConnectionProvider getDefaultConnectionProvider()

isPooledConnectionProvider

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

Deprecated.

getDriverProtocol

java.lang.String getDriverProtocol()

getProperties

java.util.Properties getProperties()

getTelemetryFactory

TelemetryFactory getTelemetryFactory()

getTargetName

java.lang.String getTargetName()

getSessionStateService

@NonNull SessionStateService getSessionStateService()

getCallContext

PluginCallContext getCallContext()

Returns the per-call context that flows through the plugin pipeline for the current JDBC call. Plugins can use it to share SQL analysis results and other per-call attributes.

Returns:

the current PluginCallContext.

getPlugin

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

isPluginInUse

boolean isPluginInUse(java.lang.Class<? extends ConnectionPlugin> pluginClazz)

getTrackedConnectionNode

TrackedConnectionList.Node getTrackedConnectionNode()

Returns the tracked connection list node associated with the current connection.

Returns:

the node, or null if the current connection is not tracked

setTrackedConnectionNode

void setTrackedConnectionNode(TrackedConnectionList.Node node)

Sets the tracked connection list node for the current connection.

Parameters:

node - the node returned by OpenedConnectionTracker.populateOpenedConnectionQueue(software.amazon.jdbc.HostSpec, java.sql.Connection)

isPooledConnection

@Nullable java.lang.Boolean isPooledConnection()

Retrieves details about the most recent connect(software.amazon.jdbc.HostSpec, java.util.Properties, software.amazon.jdbc.ConnectionPlugin) or forceConnect(software.amazon.jdbc.HostSpec, java.util.Properties) calls. Specifically indicates whether the returned connection was obtained from a connection pool or newly created.

Note: The ConnectionPlugin must process or store this information during the current JDBC call, as these details will be reset before the next JDBC call is processed, or another connect(software.amazon.jdbc.HostSpec, java.util.Properties, software.amazon.jdbc.ConnectionPlugin) or forceConnect(software.amazon.jdbc.HostSpec, java.util.Properties) is made.

Returns:

true if the most recent connection was obtained from a connection pool, false if it was newly created, null if the information is not available