software.aws.rds.jdbc.postgresql.ca

Class ClusterAwareConnectionProxy

java.lang.Object

software.aws.rds.jdbc.postgresql.ca.ClusterAwareConnectionProxy

All Implemented Interfaces:

InvocationHandler

public class ClusterAwareConnectionProxy
extends Object
implements InvocationHandler

This class is a proxy of org.postgresql.core.BaseConnection that contains functionality to monitor the underlying connection status and fail over to other DB instances when the connection encounters communications exceptions or cluster topology changes.

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	closedExplicitly
protected @Nullable String	closedReason
protected @Nullable String	clusterIdSetting
protected @Nullable String	clusterInstanceHostPatternSetting
protected int	clusterTopologyRefreshRateMsSetting
protected ConnectionProvider	connectionProvider
protected @Nullable BaseConnection	currentConnection
protected @Nullable HostInfo	currentHost
protected static int	DEFAULT_CONNECT_TIMEOUT
protected static int	DEFAULT_SOCKET_TIMEOUT
protected boolean	enableFailoverSetting
protected boolean	explicitlyReadOnly
protected int	failoverClusterTopologyRefreshRateMsSetting
protected int	failoverConnectTimeout
protected int	failoverReaderConnectTimeoutMsSetting
protected int	failoverSocketTimeout
protected int	failoverTimeoutMsSetting
protected int	failoverWriterReconnectIntervalMsSetting
protected boolean	gatherPerfMetricsSetting
protected List<HostInfo>	hosts
protected Properties	initialConnectionProps
protected boolean	inTransaction
protected boolean	isClosed
protected boolean	isClusterTopologyAvailable
protected boolean	isRds
protected boolean	isRdsProxy
protected @Nullable Throwable	lastHandledException
protected ClusterAwareMetrics	metrics
protected String	originalUrl
protected RdsDnsAnalyzer	rdsDnsAnalyzer
protected ReaderFailoverHandler	readerFailoverHandler
protected TopologyService	topologyService
protected static int	WRITER_CONNECTION_INDEX
protected WriterFailoverHandler	writerFailoverHandler

Constructor Summary

Constructors

Constructor and Description
ClusterAwareConnectionProxy(HostSpec hostSpec, Properties props, String url) Constructor for ClusterAwareConnectionProxy

Method Summary

Modifier and Type	Method and Description
protected boolean	allowedOnClosedConnection(Method method) Checks whether the given method can be executed against a closed connection
protected @Nullable BaseConnection	createConnectionForHost(HostInfo hostInfo, Properties props) Creates a connection to the host specified by the given HostInfo
protected void	doAbort(Executor executor) Abort the current connection if it exists
protected void	doClose() Close the current connection if it exists
protected void	failover() Initiates the failover procedure.
protected void	failoverReader() Initiates the reader failover procedure
protected void	failoverWriter() Initiates the writer failover procedure
@Nullable Connection	getConnection() Accessor method for currentConnection
protected void	invalidateConnection(@Nullable BaseConnection conn) Close the given connection if it is not already closed
@Nullable Object	invoke(Object proxy, Method method, @Nullable Object[] args) Invoke a method on the connection underlying this proxy.
boolean	isClusterTopologyAvailable() Checks if proxy is connected to cluster that can report its topology.
protected boolean	isConnectionSwitchRequired(Throwable t) Checks whether or not the exception indicates that we should initiate failover to a new connection
boolean	isFailoverEnabled() Checks if cluster-aware failover is enabled/possible.
boolean	isRds() Checks if this proxy is connected to an RDS-hosted cluster.
boolean	isRdsProxy() Checks if this proxy is connected to a cluster using RDS proxy.
protected void	processIllegalStateException(IllegalStateException e) Analyze the given exception and initiate failover if required, then throw the exception
protected void	processInvocationException(InvocationTargetException e) Analyze the given exception and initiate failover if required, then throw the exception
protected void	switchConnection(boolean inInitialization) Picks a new connection.
protected void	syncSessionState(@Nullable BaseConnection source, @Nullable BaseConnection target, boolean readOnly) Set the target connection read-only status according to the given parameter, and the autocommit and transaction isolation status according to the source connection state.
protected void	updateTopologyAndConnectIfNeeded(boolean forceUpdate) Method that updates the topology when necessary and establishes a new connection if the proxy is not connected or the current host is not found in the new topology.
protected @Nullable Object	wrapWithProxyIfNeeded(Class<?> returnType, @Nullable Object toProxy) Checks whether the return type of an invoked method implements or is a JDBC interface, and returns a proxy of the object returned by the method if so.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_SOCKET_TIMEOUT

protected static final int DEFAULT_SOCKET_TIMEOUT

See Also:

Constant Field Values

DEFAULT_CONNECT_TIMEOUT

protected static final int DEFAULT_CONNECT_TIMEOUT

See Also:

Constant Field Values

WRITER_CONNECTION_INDEX

protected static final int WRITER_CONNECTION_INDEX

See Also:

Constant Field Values

originalUrl

protected final String originalUrl

explicitlyReadOnly

protected boolean explicitlyReadOnly

inTransaction

protected boolean inTransaction

isClusterTopologyAvailable

protected boolean isClusterTopologyAvailable

isRdsProxy

protected boolean isRdsProxy

isRds

protected boolean isRds

topologyService

protected TopologyService topologyService

hosts

protected List<HostInfo> hosts

initialConnectionProps

protected Properties initialConnectionProps

writerFailoverHandler

protected WriterFailoverHandler writerFailoverHandler

readerFailoverHandler

protected ReaderFailoverHandler readerFailoverHandler

rdsDnsAnalyzer

protected RdsDnsAnalyzer rdsDnsAnalyzer

connectionProvider

protected ConnectionProvider connectionProvider

currentConnection

protected @Nullable BaseConnection currentConnection

currentHost

protected @Nullable HostInfo currentHost

isClosed

protected boolean isClosed

closedExplicitly

protected boolean closedExplicitly

closedReason

protected @Nullable String closedReason

metrics

protected ClusterAwareMetrics metrics

enableFailoverSetting

protected boolean enableFailoverSetting

clusterTopologyRefreshRateMsSetting

protected int clusterTopologyRefreshRateMsSetting

clusterIdSetting

protected @Nullable String clusterIdSetting

clusterInstanceHostPatternSetting

protected @Nullable String clusterInstanceHostPatternSetting

gatherPerfMetricsSetting

protected boolean gatherPerfMetricsSetting

failoverTimeoutMsSetting

protected int failoverTimeoutMsSetting

failoverClusterTopologyRefreshRateMsSetting

protected int failoverClusterTopologyRefreshRateMsSetting

failoverWriterReconnectIntervalMsSetting

protected int failoverWriterReconnectIntervalMsSetting

failoverReaderConnectTimeoutMsSetting

protected int failoverReaderConnectTimeoutMsSetting

failoverConnectTimeout

protected int failoverConnectTimeout

failoverSocketTimeout

protected int failoverSocketTimeout

lastHandledException

protected @Nullable Throwable lastHandledException

Constructor Detail

ClusterAwareConnectionProxy

public ClusterAwareConnectionProxy(HostSpec hostSpec,
                                   Properties props,
                                   String url)
                            throws SQLException

Constructor for ClusterAwareConnectionProxy

Parameters:

hostSpec - The HostSpec information for the desired connection

props - The Properties specifying the connection and failover configuration

url - The URL to connect to

Throws:

SQLException - if an error occurs while creating this instance

Method Detail

isFailoverEnabled

public boolean isFailoverEnabled(@UnknownInitialization ClusterAwareConnectionProxy this)

Checks if cluster-aware failover is enabled/possible.

Returns:

true if cluster-aware failover is enabled

switchConnection

@RequiresNonNull(value={"this.initialConnectionProps","this.topologyService","this.metrics","this.readerFailoverHandler","this.writerFailoverHandler","this.connectionProvider","this.hosts"})
protected void switchConnection(@UnknownInitialization ClusterAwareConnectionProxy this,
                                                                                                                                                                                                                               boolean inInitialization)
                                                                                                                                                                                                                        throws SQLException

Picks a new connection. Conducts failover if needed.

Parameters:

inInitialization - True if driver is initializing

Throws:

SQLException - if failover fails

createConnectionForHost

@RequiresNonNull(value="this.connectionProvider")
protected @Nullable BaseConnection createConnectionForHost(@UnknownInitialization ClusterAwareConnectionProxy this,
                                                                                                             HostInfo hostInfo,
                                                                                                             Properties props)
                                                                                                      throws SQLException

Creates a connection to the host specified by the given HostInfo

Parameters:

hostInfo - the HostInfo specifying the host to connect to

props - The properties that should be passed to the new connection

Returns:

a connection to the given host

Throws:

SQLException - if an error occurs while connecting to the given host

invalidateConnection

protected void invalidateConnection(@UnknownInitialization ClusterAwareConnectionProxy this,
                                    @Nullable BaseConnection conn)

Close the given connection if it is not already closed

Parameters:

conn - the connection to close

syncSessionState

protected void syncSessionState(@UnknownInitialization ClusterAwareConnectionProxy this,
                                @Nullable BaseConnection source,
                                @Nullable BaseConnection target,
                                boolean readOnly)
                         throws SQLException

Set the target connection read-only status according to the given parameter, and the autocommit and transaction isolation status according to the source connection state.

Parameters:

source - the source connection that holds the desired state for the target connection

target - the target connection that should hold the desired state from the source connection at the end of this method call

readOnly - The new read-only status

Throws:

SQLException - if an error occurs while setting the target connection's state

failover

@RequiresNonNull(value={"this.topologyService","this.initialConnectionProps","this.readerFailoverHandler","this.writerFailoverHandler","this.metrics","this.connectionProvider","this.hosts"})
protected void failover(@UnknownInitialization ClusterAwareConnectionProxy this)
                                                                                                                                                                                                                throws SQLException

Initiates the failover procedure. This process tries to establish a new connection to an instance in the topology.

Throws:

SQLException - upon successful failover to indicate that failover has occurred and session state should be reconfigured by the user. May also throw a SQLException if failover is unsuccessful.

failoverWriter

@RequiresNonNull(value={"this.topologyService","this.initialConnectionProps","this.writerFailoverHandler","this.metrics","this.hosts"})
protected void failoverWriter(@UnknownInitialization ClusterAwareConnectionProxy this)
                                                                                                                                                               throws SQLException

Initiates the writer failover procedure

Throws:

SQLException - if failover was unsuccessful

failoverReader

@RequiresNonNull(value={"this.topologyService","this.initialConnectionProps","this.readerFailoverHandler","this.metrics","this.writerFailoverHandler","this.connectionProvider","this.hosts"})
protected void failoverReader(@UnknownInitialization ClusterAwareConnectionProxy this)
                                                                                                                                                                                                                      throws SQLException

Initiates the reader failover procedure

Throws:

SQLException - if failover was unsuccessful

updateTopologyAndConnectIfNeeded

@RequiresNonNull(value={"this.initialConnectionProps","this.topologyService","this.metrics","this.readerFailoverHandler","this.writerFailoverHandler","this.connectionProvider","this.hosts"})
protected void updateTopologyAndConnectIfNeeded(@UnknownInitialization ClusterAwareConnectionProxy this,
                                                                                                                                                                                                                                               boolean forceUpdate)
                                                                                                                                                                                                                                        throws SQLException

Method that updates the topology when necessary and establishes a new connection if the proxy is not connected or the current host is not found in the new topology.

Parameters:

forceUpdate - a boolean used to force an update instead of the default behavior of updating only when necessary

Throws:

SQLException - if an error occurs fetching the topology or while conducting failover

isRds

public boolean isRds()

Checks if this proxy is connected to an RDS-hosted cluster.

Returns:

true if this proxy is connected to an RDS-hosted cluster

isRdsProxy

public boolean isRdsProxy()

Checks if this proxy is connected to a cluster using RDS proxy.

Returns:

true if this proxy is connected to a cluster using RDS proxy

invoke

public @Nullable Object invoke(Object proxy,
                               Method method,
                               @Nullable Object[] args)
                        throws Throwable

Invoke a method on the connection underlying this proxy. Called automatically when a method is called against the proxied connection. Member variables are changed depending on the method parameter and failover is initiated if a communications problem occurs while executing the invocation.

Specified by:

invoke in interface InvocationHandler

Parameters:

proxy - The proxied connection

method - The method being called

args - The arguments to the method

Returns:

The results of the method call

Throws:

Throwable - if an error occurs while invoking the method against the proxy

allowedOnClosedConnection

protected boolean allowedOnClosedConnection(Method method)

Checks whether the given method can be executed against a closed connection

Parameters:

method - the method to check

Returns:

true if the given method can be executed against a closed connection

doClose

protected void doClose()
                throws SQLException

Close the current connection if it exists

Throws:

SQLException - if an error occurs while closing the connection

doAbort

protected void doAbort(Executor executor)
                throws SQLException

Abort the current connection if it exists

Parameters:

executor - The Executor implementation which will be used by abort

Throws:

SQLException - if an error occurs while aborting the current connection

processInvocationException

protected void processInvocationException(InvocationTargetException e)
                                   throws Throwable,
                                          InvocationTargetException

Analyze the given exception and initiate failover if required, then throw the exception

Parameters:

e - the InvocationTargetException to analyze

Throws:

Throwable - when the given exception contains a target exception, failover occurs, or another error is encountered while handling the exception

InvocationTargetException - when the given exception does not contain a target exception

processIllegalStateException

protected void processIllegalStateException(IllegalStateException e)
                                     throws Throwable

Analyze the given exception and initiate failover if required, then throw the exception

Parameters:

e - the IllegalStateException to analyze

Throws:

Throwable - this error or the cause of this error. May also throw an error if failover occurs or another error is encountered while handling the exception

isConnectionSwitchRequired

protected boolean isConnectionSwitchRequired(Throwable t)

Checks whether or not the exception indicates that we should initiate failover to a new connection

Parameters:

t - The exception to check

Returns:

True if failover should be initiated

isClusterTopologyAvailable

public boolean isClusterTopologyAvailable()

Checks if proxy is connected to cluster that can report its topology.

Returns:

true if proxy is connected to cluster that can report its topology

getConnection

public @Nullable Connection getConnection()

Accessor method for currentConnection

Returns:

the current connection object. Returns null if it doesn't exist.

wrapWithProxyIfNeeded

protected @Nullable Object wrapWithProxyIfNeeded(Class<?> returnType,
                                                 @Nullable Object toProxy)

Checks whether the return type of an invoked method implements or is a JDBC interface, and returns a proxy of the object returned by the method if so. This is done so that we can monitor the object for communications exceptions and initiate failovers when required (see JdbcInterfaceProxy).

Parameters:

returnType - the return type of the invoked method

toProxy - the object returned by the invoked method

Returns:

a proxy of the object returned by the invoked method, if it implements or is a JDBC interface. Otherwise, simply returns the object itself.