software.amazon.jdbc

Interface PluginService

All Superinterfaces:

ExceptionHandler

All Known Implementing Classes:

PartialPluginService, 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.
java.sql.Connection	connect(HostSpec hostSpec, java.util.Properties props, @Nullable ConnectionPlugin pluginToSkip)
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.
java.sql.Connection	forceConnect(HostSpec hostSpec, java.util.Properties props, @Nullable ConnectionPlugin pluginToSkip)
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()
java.lang.String	getOriginalUrl()
<T> T	getPlugin(java.lang.Class<T> pluginClazz)
java.util.Properties	getProperties()
@NonNull SessionStateService	getSessionStateService()
<T> T	getStatus(@NonNull java.lang.Class<T> clazz, boolean clusterBound)
<T> T	getStatus(@NonNull java.lang.Class<T> clazz, java.lang.String key)
TargetDriverDialect	getTargetDriverDialect()
java.lang.String	getTargetName()
TelemetryFactory	getTelemetryFactory()
@Nullable HostSpec	identifyConnection(java.sql.Connection connection)
boolean	isInTransaction()
boolean	isPluginInUse(java.lang.Class<? extends ConnectionPlugin> pluginClazz)
boolean	isPooledConnectionProvider(HostSpec host, java.util.Properties props)
void	refreshHostList()
void	refreshHostList(java.sql.Connection connection)
void	setAllowedAndBlockedHosts(AllowedAndBlockedHosts allowedAndBlockedHosts) Deprecated. use StorageService#set(key, allowedAndBlockedHosts) instead.
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.
<T> void	setStatus(java.lang.Class<T> clazz, T status, boolean clusterBound)
<T> void	setStatus(java.lang.Class<T> clazz, T status, java.lang.String key)
void	updateDialect(@NonNull java.sql.Connection connection)

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

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

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

setAllowedAndBlockedHosts

@Deprecated
void setAllowedAndBlockedHosts(AllowedAndBlockedHosts allowedAndBlockedHosts)

Deprecated. use StorageService#set(key, allowedAndBlockedHosts) instead.

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

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

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)

setStatus

<T> void setStatus(java.lang.Class<T> clazz,
                   T status,
                   boolean clusterBound)

setStatus

<T> void setStatus(java.lang.Class<T> clazz,
                   T status,
                   java.lang.String key)

getStatus

<T> T getStatus(@NonNull java.lang.Class<T> clazz,
                boolean clusterBound)

getStatus

<T> T getStatus(@NonNull java.lang.Class<T> clazz,
                java.lang.String key)

isPluginInUse

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