com.mysql.cj.jdbc.ha

Class LoadBalancedConnectionProxy

java.lang.Object

com.mysql.cj.jdbc.ha.MultiHostConnectionProxy

com.mysql.cj.jdbc.ha.LoadBalancedConnectionProxy

All Implemented Interfaces:

PingTarget, java.lang.reflect.InvocationHandler

public class LoadBalancedConnectionProxy
extends MultiHostConnectionProxy
implements PingTarget

A proxy for a dynamic com.mysql.cj.jdbc.JdbcConnection implementation that load balances requests across a series of MySQL JDBC connections, where the balancing takes place at transaction commit. Therefore, for this to work (at all), you must use transactions, even if only reading data. This implementation will invalidate connections that it detects have had communication errors when processing a request. Problematic hosts will be added to a global blocklist for loadBalanceBlocklistTimeout ms, after which they will be removed from the blocklist and made eligible once again to be selected for new connections. This implementation is thread-safe, but it's questionable whether sharing a connection instance amongst threads is a good idea, given that transactions are scoped to connections in JDBC.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	LoadBalancedConnectionProxy.NullLoadBalancedConnectionProxy A LoadBalancedConnection proxy that provides null-functionality.

Nested classes/interfaces inherited from class com.mysql.cj.jdbc.ha.MultiHostConnectionProxy

MultiHostConnectionProxy.JdbcInterfaceProxy

Field Summary

Fields

Modifier and Type	Field and Description
private BalanceStrategy	balancer
private ConnectionGroup	connectionGroup
private long	connectionGroupProxyID
private java.util.Map<ConnectionImpl,java.lang.String>	connectionsToHostsMap
private LoadBalanceExceptionChecker	exceptionChecker
private static java.util.Map<java.lang.String,java.lang.Long>	globalBlocklist
private int	globalBlocklistTimeout
private int	hostRemovalGracePeriod
private java.util.Map<java.lang.String,java.lang.Integer>	hostsToListIndexMap
private java.util.Set<java.lang.String>	hostsToRemove
private static java.lang.Class<?>[]	INTERFACES_TO_PROXY
private boolean	inTransaction
protected java.util.Map<java.lang.String,ConnectionImpl>	liveConnections
private static LoadBalancedConnection	nullLBConnectionInstance
private long[]	responseTimes
private int	retriesAllDown
private long	totalPhysicalConnections
private long	transactionCount
private long	transactionStartTime

Fields inherited from class com.mysql.cj.jdbc.ha.MultiHostConnectionProxy

autoReconnect, closedExplicitly, closedReason, connectionUrl, currentConnection, hostsList, isClosed, lastExceptionDealtWith, parentProxyConnection, thisAsConnection, topProxyConnection

Constructor Summary

Constructors

Constructor and Description
LoadBalancedConnectionProxy(ConnectionUrl connectionUrl) Creates a proxy for java.sql.Connection that routes requests between the hosts in the connection URL.

Method Summary

Modifier and Type	Method and Description
boolean	addHost(java.lang.String hostPortPair) Adds a host to the hosts list.
void	addToGlobalBlacklist(java.lang.String host) Deprecated.
void	addToGlobalBlacklist(java.lang.String host, long timeout) Deprecated.
void	addToGlobalBlocklist(java.lang.String host) Adds a host to the blocklist.
void	addToGlobalBlocklist(java.lang.String host, long timeout) Adds a host to the blocklist with the given timeout.
private void	closeAllConnections() Closes all live connections.
ConnectionImpl	createConnectionForHost(HostInfo hostInfo) Creates a new physical connection for the given HostInfo and updates required internal mappings and statistics for that connection.
ConnectionImpl	createConnectionForHost(java.lang.String hostPortPair) Creates a new physical connection for the given host:port info.
static LoadBalancedConnection	createProxyInstance(ConnectionUrl connectionUrl) Static factory to create LoadBalancedConnection instances.
(package private) void	doAbort(java.util.concurrent.Executor executor) Aborts all live connections, using the provided Executor.
(package private) void	doAbortInternal() Aborts all live connections
(package private) void	doClose() Closes all live connections.
void	doPing() Pings live connections.
long	getActivePhysicalConnectionCount()
long	getConnectionGroupProxyID()
java.lang.String	getCurrentActiveHost()
long	getCurrentTransactionDuration()
java.util.Map<java.lang.String,java.lang.Long>	getGlobalBlacklist() Deprecated.
java.util.Map<java.lang.String,java.lang.Long>	getGlobalBlocklist() Returns a local hosts blocklist, while cleaning up expired records from the global blocklist, or a blocklist with the hosts to be removed.
(package private) JdbcConnection	getNewWrapperForThisAsConnection() Wraps this object with a new load balanced Connection instance.
(package private) static LoadBalancedConnection	getNullLoadBalancedConnectionInstance()
long	getTotalPhysicalConnectionCount()
long	getTransactionCount()
boolean	inTransaction()
(package private) void	invalidateConnection(JdbcConnection conn) Closes specified connection and removes it from required mappings.
(package private) java.lang.Object	invokeMore(java.lang.Object proxy, java.lang.reflect.Method method, java.lang.Object[] args) Proxies method invocation on the java.sql.Connection interface, trapping "close", "isClosed" and "commit/rollback" to switch connections for load balancing.
boolean	isGlobalBlacklistEnabled() Deprecated.
boolean	isGlobalBlocklistEnabled() Checks if host blocklist management was enabled.
(package private) boolean	isSourceConnection() Always returns 'true' as there are no "sources" and "replicas" in this type of connection.
void	pickNewConnection() Picks the "best" connection to use for the next transaction based on the BalanceStrategy in use.
protected void	propagateProxyDown(JdbcConnection proxyConn) Propagates the connection proxy down through all live connections.
void	removeFromGlobalBlacklist(java.lang.String host) Deprecated.
void	removeFromGlobalBlocklist(java.lang.String host) Removes a host from the blocklist.
void	removeHost(java.lang.String hostPortPair) Removes a host from the host list.
void	removeHostWhenNotInUse(java.lang.String hostPortPair) Removes a host from the host list, allowing it some time to be released gracefully if needed.
(package private) boolean	shouldExceptionTriggerConnectionSwitch(java.lang.Throwable t) Consults the registered LoadBalanceExceptionChecker if the given exception should trigger a connection fail-over.
boolean	shouldExceptionTriggerFailover(java.lang.Throwable t) Deprecated.
(package private) void	syncSessionState(JdbcConnection source, JdbcConnection target, boolean readOnly) Synchronizes session state between two connections, allowing to override the read-only status.

Methods inherited from class com.mysql.cj.jdbc.ha.MultiHostConnectionProxy

allowedOnClosedConnection, dealWithInvocationException, getNewJdbcInterfaceProxy, getParentProxy, getProxy, initializeHostsSpecs, invalidateCurrentConnection, invoke, isMasterConnection, proxyIfReturnTypeIsJdbcInterface, setProxy, syncSessionState

Methods inherited from class java.lang.Object

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

Field Detail

connectionGroup

private ConnectionGroup connectionGroup

connectionGroupProxyID

private long connectionGroupProxyID

liveConnections

protected java.util.Map<java.lang.String,ConnectionImpl> liveConnections

hostsToListIndexMap

private java.util.Map<java.lang.String,java.lang.Integer> hostsToListIndexMap

connectionsToHostsMap

private java.util.Map<ConnectionImpl,java.lang.String> connectionsToHostsMap

totalPhysicalConnections

private long totalPhysicalConnections

responseTimes

private long[] responseTimes

retriesAllDown

private int retriesAllDown

balancer

private BalanceStrategy balancer

globalBlocklistTimeout

private int globalBlocklistTimeout

globalBlocklist

private static java.util.Map<java.lang.String,java.lang.Long> globalBlocklist

hostRemovalGracePeriod

private int hostRemovalGracePeriod

hostsToRemove

private java.util.Set<java.lang.String> hostsToRemove

inTransaction

private boolean inTransaction

transactionStartTime

private long transactionStartTime

transactionCount

private long transactionCount

exceptionChecker

private LoadBalanceExceptionChecker exceptionChecker

INTERFACES_TO_PROXY

private static java.lang.Class<?>[] INTERFACES_TO_PROXY

nullLBConnectionInstance

private static LoadBalancedConnection nullLBConnectionInstance

Constructor Detail

LoadBalancedConnectionProxy

public LoadBalancedConnectionProxy(ConnectionUrl connectionUrl)
                            throws java.sql.SQLException

Creates a proxy for java.sql.Connection that routes requests between the hosts in the connection URL.

Parameters:

connectionUrl - The connection URL containing the hosts to load balance.

Throws:

java.sql.SQLException - if an error occurs

Method Detail

createProxyInstance

public static LoadBalancedConnection createProxyInstance(ConnectionUrl connectionUrl)
                                                  throws java.sql.SQLException

Static factory to create LoadBalancedConnection instances.

Parameters:

connectionUrl - The connection URL containing the hosts in a load-balance setup.

Returns:

A LoadBalancedConnection proxy.

Throws:

java.sql.SQLException - if an error occurs

getNewWrapperForThisAsConnection

JdbcConnection getNewWrapperForThisAsConnection()
                                         throws java.sql.SQLException

Wraps this object with a new load balanced Connection instance.

Overrides:

getNewWrapperForThisAsConnection in class MultiHostConnectionProxy

Returns:

The connection object instance that wraps 'this'.

Throws:

java.sql.SQLException - if an error occurs

propagateProxyDown

protected void propagateProxyDown(JdbcConnection proxyConn)

Propagates the connection proxy down through all live connections.

Overrides:

propagateProxyDown in class MultiHostConnectionProxy

Parameters:

proxyConn - The top level connection in the multi-host connections chain.

shouldExceptionTriggerFailover

@Deprecated
public boolean shouldExceptionTriggerFailover(java.lang.Throwable t)

Deprecated.

shouldExceptionTriggerConnectionSwitch

boolean shouldExceptionTriggerConnectionSwitch(java.lang.Throwable t)

Consults the registered LoadBalanceExceptionChecker if the given exception should trigger a connection fail-over.

Specified by:

shouldExceptionTriggerConnectionSwitch in class MultiHostConnectionProxy

Parameters:

t - The Exception instance to check.

Returns:

true if the given exception should trigger a connection fail-over

isSourceConnection

boolean isSourceConnection()

Always returns 'true' as there are no "sources" and "replicas" in this type of connection.

Specified by:

isSourceConnection in class MultiHostConnectionProxy

Returns:

true if current connection is to a source host

invalidateConnection

void invalidateConnection(JdbcConnection conn)
                   throws java.sql.SQLException

Closes specified connection and removes it from required mappings.

Overrides:

invalidateConnection in class MultiHostConnectionProxy

Parameters:

conn - connection

Throws:

java.sql.SQLException - if an error occurs

pickNewConnection

public void pickNewConnection()
                       throws java.sql.SQLException

Picks the "best" connection to use for the next transaction based on the BalanceStrategy in use.

Specified by:

pickNewConnection in class MultiHostConnectionProxy

Throws:

java.sql.SQLException - if an error occurs

createConnectionForHost

public ConnectionImpl createConnectionForHost(HostInfo hostInfo)
                                       throws java.sql.SQLException

Creates a new physical connection for the given HostInfo and updates required internal mappings and statistics for that connection.

Overrides:

createConnectionForHost in class MultiHostConnectionProxy

Parameters:

hostInfo - The host info instance.

Returns:

The new Connection instance.

Throws:

java.sql.SQLException - if an error occurs

syncSessionState

void syncSessionState(JdbcConnection source,
                      JdbcConnection target,
                      boolean readOnly)
               throws java.sql.SQLException

Description copied from class: MultiHostConnectionProxy

Synchronizes session state between two connections, allowing to override the read-only status.

Overrides:

syncSessionState in class MultiHostConnectionProxy

Parameters:

source - The connection where to get state from.

target - The connection where to set state.

readOnly - The new read-only status.

Throws:

java.sql.SQLException - if an error occurs

createConnectionForHost

public ConnectionImpl createConnectionForHost(java.lang.String hostPortPair)
                                       throws java.sql.SQLException

Creates a new physical connection for the given host:port info. If the this connection's connection URL knows about this host:port then its host info is used, otherwise a new host info based on current connection URL defaults is spawned.

Parameters:

hostPortPair - The host:port pair identifying the host to connect to.

Returns:

The new Connection instance.

Throws:

java.sql.SQLException - if an error occurs

closeAllConnections

private void closeAllConnections()

Closes all live connections.

doClose

void doClose()

Closes all live connections.

Specified by:

doClose in class MultiHostConnectionProxy

doAbortInternal

void doAbortInternal()

Aborts all live connections

Specified by:

doAbortInternal in class MultiHostConnectionProxy

doAbort

void doAbort(java.util.concurrent.Executor executor)

Aborts all live connections, using the provided Executor.

Specified by:

doAbort in class MultiHostConnectionProxy

Parameters:

executor - executor

invokeMore

java.lang.Object invokeMore(java.lang.Object proxy,
                            java.lang.reflect.Method method,
                            java.lang.Object[] args)
                     throws java.lang.Throwable

Proxies method invocation on the java.sql.Connection interface, trapping "close", "isClosed" and "commit/rollback" to switch connections for load balancing. This is the continuation of MultiHostConnectionProxy#invoke(Object, Method, Object[]).

Specified by:

invokeMore in class MultiHostConnectionProxy

Parameters:

proxy - proxy object

method - method to invoke

args - method parameters

Returns:

method result

Throws:

java.lang.Throwable - if an error occurs

doPing

public void doPing()
            throws java.sql.SQLException

Pings live connections.

Specified by:

doPing in interface PingTarget

Throws:

java.sql.SQLException - if an error occurs

addToGlobalBlocklist

public void addToGlobalBlocklist(java.lang.String host,
                                 long timeout)

Adds a host to the blocklist with the given timeout.

Parameters:

host - The host to be blocklisted.

timeout - The blocklist timeout for this entry.

removeFromGlobalBlocklist

public void removeFromGlobalBlocklist(java.lang.String host)

Removes a host from the blocklist.

Parameters:

host - The host to be removed from the blocklist.

removeFromGlobalBlacklist

@Deprecated
public void removeFromGlobalBlacklist(java.lang.String host)

Deprecated.

Use removeFromGlobalBlocklist(String) instead.

Parameters:

host - host

addToGlobalBlacklist

@Deprecated
public void addToGlobalBlacklist(java.lang.String host,
                                             long timeout)

Deprecated.

Use addToGlobalBlocklist(String, long) instead.

Parameters:

host - The host to be blocklisted.

timeout - The blocklist timeout for this entry.

addToGlobalBlocklist

public void addToGlobalBlocklist(java.lang.String host)

Adds a host to the blocklist.

Parameters:

host - The host to be blocklisted.

addToGlobalBlacklist

@Deprecated
public void addToGlobalBlacklist(java.lang.String host)

Deprecated.

Use addToGlobalBlocklist(String) instead.

Parameters:

host - The host to be blocklisted.

isGlobalBlocklistEnabled

public boolean isGlobalBlocklistEnabled()

Checks if host blocklist management was enabled.

Returns:

true if host blocklist management was enabled

isGlobalBlacklistEnabled

@Deprecated
public boolean isGlobalBlacklistEnabled()

Deprecated.

Use isGlobalBlocklistEnabled() instead.

Returns:

true if host blocklist management was enabled

getGlobalBlocklist

public java.util.Map<java.lang.String,java.lang.Long> getGlobalBlocklist()

Returns a local hosts blocklist, while cleaning up expired records from the global blocklist, or a blocklist with the hosts to be removed.

Returns:

A local hosts blocklist.

getGlobalBlacklist

@Deprecated
public java.util.Map<java.lang.String,java.lang.Long> getGlobalBlacklist()

Deprecated.

Use getGlobalBlocklist() instead.

Returns:

A local hosts blocklist.

removeHostWhenNotInUse

public void removeHostWhenNotInUse(java.lang.String hostPortPair)
                            throws java.sql.SQLException

Removes a host from the host list, allowing it some time to be released gracefully if needed.

Parameters:

hostPortPair - The host to be removed.

Throws:

java.sql.SQLException - if an error occurs

removeHost

public void removeHost(java.lang.String hostPortPair)
                throws java.sql.SQLException

Removes a host from the host list.

Parameters:

hostPortPair - The host to be removed.

Throws:

java.sql.SQLException - if an error occurs

addHost

public boolean addHost(java.lang.String hostPortPair)

Adds a host to the hosts list.

Parameters:

hostPortPair - The host to be added.

Returns:

true if host was added and false if the host list already contains it

inTransaction

public boolean inTransaction()

getTransactionCount

public long getTransactionCount()

getActivePhysicalConnectionCount

public long getActivePhysicalConnectionCount()

getTotalPhysicalConnectionCount

public long getTotalPhysicalConnectionCount()

getConnectionGroupProxyID

public long getConnectionGroupProxyID()

getCurrentActiveHost

public java.lang.String getCurrentActiveHost()

getCurrentTransactionDuration

public long getCurrentTransactionDuration()

getNullLoadBalancedConnectionInstance

static LoadBalancedConnection getNullLoadBalancedConnectionInstance()