software.amazon.jdbc.targetdriverdialect

Interface TargetDriverDialect

All Known Implementing Classes:

GenericTargetDriverDialect, MariadbTargetDriverDialect, MysqlConnectorJTargetDriverDialect, PgTargetDriverDialect

public interface TargetDriverDialect

Method Summary

Modifier and Type	Method and Description
void	abortConnection(@NonNull java.sql.Connection connectionToAbort, @NonNull java.util.concurrent.Executor abortExecutor)
java.util.Set<java.lang.String>	getAllowedOnConnectionMethodNames()
byte[]	getEncryptedBytes(@NonNull java.sql.ResultSet rs, java.lang.Object columnRef)
java.util.Set<java.lang.String>	getNetworkBoundMethodNames(@Nullable java.util.Properties properties)
@Nullable java.lang.String	getSQLQueryString(java.sql.PreparedStatement ps)
java.lang.String	getSQLState(java.lang.Throwable throwable)
boolean	isDialect(java.sql.Driver driver)
boolean	isDialect(java.lang.String dataSourceClass)
boolean	isDriverRegistered()
boolean	ping(@NonNull java.sql.Connection connection) Attempts to communicate to a database node in order to measure network latency.
ConnectInfo	prepareConnectInfo(@NonNull java.lang.String protocol, @NonNull HostSpec hostSpec, @NonNull java.util.Properties props)
void	prepareDataSource(@NonNull javax.sql.DataSource dataSource, @NonNull java.lang.String protocol, @NonNull HostSpec hostSpec, @NonNull java.util.Properties props)
default java.lang.String	prepareTargetDataSource(@NonNull javax.sql.CommonDataSource dataSource, @NonNull java.lang.String url, @NonNull java.util.Properties props) Applies AWS Wrapper connection settings that a target data source can only receive through driver-specific bean setters (for example connect/socket timeouts, whose unit differs per driver), and returns the connection URL to apply to that data source.
void	registerDataType(@NonNull java.sql.Connection connection, @NonNull java.lang.String typeName, @NonNull java.lang.String className)
void	registerDriver()
default java.util.Set<java.lang.String>	removeHostSelectionProperties(@NonNull java.util.Properties props) Removes properties that restrict which database node the target driver is willing to accept a connection to, and returns the names of the properties that were removed.
void	setEncryptedParameter(@NonNull java.sql.PreparedStatement ps, int paramIndex, byte[] encrypted)
void	updateInternalState(@NonNull PluginService pluginService, @NonNull java.util.Properties props) Allows each target driver dialect to perform last-minute adjustments to the wrapper's internal state after the initial connection is established.

Method Detail

isDialect

boolean isDialect(java.sql.Driver driver)

isDialect

boolean isDialect(java.lang.String dataSourceClass)

prepareConnectInfo

ConnectInfo prepareConnectInfo(@NonNull java.lang.String protocol,
                               @NonNull HostSpec hostSpec,
                               @NonNull java.util.Properties props)
                        throws java.sql.SQLException

Throws:

java.sql.SQLException

prepareDataSource

void prepareDataSource(@NonNull javax.sql.DataSource dataSource,
                       @NonNull java.lang.String protocol,
                       @NonNull HostSpec hostSpec,
                       @NonNull java.util.Properties props)
                throws java.sql.SQLException

Throws:

java.sql.SQLException

prepareTargetDataSource

default java.lang.String prepareTargetDataSource(@NonNull javax.sql.CommonDataSource dataSource,
                                                 @NonNull java.lang.String url,
                                                 @NonNull java.util.Properties props)
                                          throws java.sql.SQLException

Applies AWS Wrapper connection settings that a target data source can only receive through driver-specific bean setters (for example connect/socket timeouts, whose unit differs per driver), and returns the connection URL to apply to that data source.

This is used by the XA datasource path, which configures a target driver XADataSource directly instead of going through prepareConnectInfo(String, HostSpec, Properties). Because that path hands the target only its own (non-wrapper) properties, wrapper properties such as socketTimeout would otherwise be dropped. Dialects whose target data source cannot express a setting as a bean property may instead add it to the returned URL.

The default implementation applies nothing and returns url unchanged.

Parameters:

dataSource - the target driver data source being configured.

url - the target driver URL, with AWS Wrapper parameters already removed.

props - the effective connection properties, including AWS Wrapper properties.

Returns:

the URL to apply to the target data source.

Throws:

java.sql.SQLException - if a setting cannot be applied to the target data source.

isDriverRegistered

boolean isDriverRegistered()
                    throws java.sql.SQLException

Throws:

java.sql.SQLException

registerDriver

void registerDriver()
             throws java.sql.SQLException

Throws:

java.sql.SQLException

ping

boolean ping(@NonNull java.sql.Connection connection)

Attempts to communicate to a database node in order to measure network latency. Some database protocols may not support the simplest "ping" packet. In this case, it's recommended to execute a simple connection validation, or the simplest SQL query like "SELECT 1".

Parameters:

connection - The database connection to a node to ping.

Returns:

True, if operation is succeeded. False, otherwise.

getAllowedOnConnectionMethodNames

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

getSQLState

java.lang.String getSQLState(java.lang.Throwable throwable)

getNetworkBoundMethodNames

java.util.Set<java.lang.String> getNetworkBoundMethodNames(@Nullable java.util.Properties properties)

abortConnection

void abortConnection(@NonNull java.sql.Connection connectionToAbort,
                     @NonNull java.util.concurrent.Executor abortExecutor)
              throws java.sql.SQLException

Throws:

java.sql.SQLException

getSQLQueryString

@Nullable java.lang.String getSQLQueryString(java.sql.PreparedStatement ps)

registerDataType

void registerDataType(@NonNull java.sql.Connection connection,
                      @NonNull java.lang.String typeName,
                      @NonNull java.lang.String className)
               throws java.sql.SQLException

Throws:

java.sql.SQLException

setEncryptedParameter

void setEncryptedParameter(@NonNull java.sql.PreparedStatement ps,
                           int paramIndex,
                           byte[] encrypted)
                    throws java.sql.SQLException

Throws:

java.sql.SQLException

getEncryptedBytes

byte[] getEncryptedBytes(@NonNull java.sql.ResultSet rs,
                         java.lang.Object columnRef)
                  throws java.sql.SQLException

Throws:

java.sql.SQLException

updateInternalState

void updateInternalState(@NonNull PluginService pluginService,
                         @NonNull java.util.Properties props)
                  throws java.sql.SQLException

Allows each target driver dialect to perform last-minute adjustments to the wrapper's internal state after the initial connection is established. This includes transferring driver-specific connection properties (e.g. PostgreSQL's currentSchema) into the wrapper's session state so they are preserved across connection switches (failover, read-write splitting, initial connection strategy, etc.).

Each dialect implementation should inspect the provided properties for driver-specific settings that affect session state and register them with the appropriate services (e.g. SessionStateService).

This method is called once after the initial connection is established in ConnectionWrapper.init().

Parameters:

pluginService - the plugin service providing access to session state and other services

props - the connection properties that may contain driver-specific settings

Throws:

java.sql.SQLException - if an error occurs while updating internal state

removeHostSelectionProperties

default java.util.Set<java.lang.String> removeHostSelectionProperties(@NonNull java.util.Properties props)

Removes properties that restrict which database node the target driver is willing to accept a connection to, and returns the names of the properties that were removed.

Some target drivers can be told to reject a node that does not match a role, for example PostgreSQL's targetServerType, which makes the driver verify the server is writable and fail the connection otherwise. Such a setting is meaningful for an application connection, where the driver performs its own host selection, but not for the wrapper's internal monitoring connections: those are opened against one specific node that the wrapper has already chosen, and frequently against a reader or a replica on purpose. Inheriting the restriction there makes those connections fail, silently disabling the monitor that depends on them.

Implementations must only remove properties that constrain node selection. Properties affecting authentication, encryption, timeouts, or session state must be left untouched so a monitoring connection keeps behaving like an application connection in every other respect.

The default implementation removes nothing and returns an empty set, so a target driver with no such property, and any implementation outside this library, needs no change.

Parameters:

props - the properties to adjust in place; typically a copy made for a monitoring connection.

Returns:

the names of the removed properties, empty if none applied.