LoadBalancedConnectionProxy
Date: 2018-05-06

com.mysql.jdbc

## Class LoadBalancedConnectionProxy

- java.lang.Object
- - com.mysql.jdbc.MultiHostConnectionProxy
  - - com.mysql.jdbc.LoadBalancedConnectionProxy

- All Implemented Interfaces:
    PingTarget, java.lang.reflect.InvocationHandler

      public class LoadBalancedConnectionProxy
      extends MultiHostConnectionProxy
      implements PingTarget

  A proxy for a dynamic com.mysql.jdbc.Connection 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 blacklist for loadBalanceBlacklistTimeout ms, after which they will be removed from the blacklist 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/interfaces inherited from class com.mysql.jdbc.MultiHostConnectionProxy

      `MultiHostConnectionProxy.JdbcInterfaceProxy`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `BLACKLIST_TIMEOUT_PROPERTY_KEY`
    `protected java.util.Map<java.lang.String,ConnectionImpl>` | `liveConnections`

    - ### Fields inherited from class com.mysql.jdbc.MultiHostConnectionProxy

      `autoReconnect, closedExplicitly, closedReason, currentConnection, hostList, isClosed, lastExceptionDealtWith, localProps, proxyConnection, thisAsConnection`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `addHost(java.lang.String host)` Adds a host to the hosts list.
    `void` | `addToGlobalBlacklist(java.lang.String host)` Adds a host to the blacklist.
    `void` | `addToGlobalBlacklist(java.lang.String host, long timeout)` Adds a host to the blacklist with the given timeout.
    `ConnectionImpl` | `createConnectionForHost(java.lang.String hostPortSpec)` Creates a new physical connection for the given host:port and updates required internal mappings and statistics for that connection.
    `static LoadBalancedConnection` | `createProxyInstance(java.util.List<java.lang.String> hosts, java.util.Properties props)`
    `(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()` Returns a local hosts blacklist, or a blacklist with a single host to be removed, while cleaning up expired records from the global blacklist.
    `(package private) MySQLConnection` | `getNewWrapperForThisAsConnection()` Wraps this object with a new load balanced Connection instance.
    `long` | `getTotalPhysicalConnectionCount()`
    `long` | `getTransactionCount()`
    `boolean` | `inTransaction()`
    `(package private) void` | `invalidateConnection(MySQLConnection conn)` Closes specified connection and removes it from required mappings.
    `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()` Checks if host blacklist management was enabled.
    `(package private) boolean` | `isMasterConnection()` Always returns 'true' as there are no "masters" and "slaves" in this type of connection.
    `(package private) void` | `pickNewConnection()` Picks the "best" connection to use for the next transaction based on the BalanceStrategy in use.
    `protected void` | `propagateProxyDown(MySQLConnection proxyConn)` Propagates the connection proxy down through all live connections.
    `void` | `removeHost(java.lang.String host)` Removes a host from the host list.
    `void` | `removeHostWhenNotInUse(java.lang.String host)` 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.

    - ### Methods inherited from class com.mysql.jdbc.MultiHostConnectionProxy

      `allowedOnClosedConnection, dealWithInvocationException, getNewJdbcInterfaceProxy, getProxy, initializeHostsSpecs, invalidateCurrentConnection, invoke, proxyIfReturnTypeIsJdbcInterface, setProxy, syncSessionState, syncSessionState`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### liveConnections

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

    - #### BLACKLIST_TIMEOUT_PROPERTY_KEY

          public static final java.lang.String BLACKLIST_TIMEOUT_PROPERTY_KEY

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### createProxyInstance

          public static LoadBalancedConnection createProxyInstance(java.util.List<java.lang.String> hosts,
                                                   java.util.Properties props)
                                                            throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### getNewWrapperForThisAsConnection

          MySQLConnection 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`

    - #### propagateProxyDown

          protected void propagateProxyDown(MySQLConnection 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.

    - #### 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:
        `ex` - The Exception instance to check.

    - #### isMasterConnection

          boolean isMasterConnection()

      Always returns 'true' as there are no "masters" and "slaves" in this type of connection.
      Specified by:
        `isMasterConnection` in class `MultiHostConnectionProxy`

    - #### invalidateConnection

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

      Closes specified connection and removes it from required mappings.
      Overrides:
        `invalidateConnection` in class `MultiHostConnectionProxy`
      Parameters:
        `conn` -
      Throws:
        `java.sql.SQLException`

    - #### pickNewConnection

          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`

    - #### createConnectionForHost

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

      Creates a new physical connection for the given host:port and updates required internal mappings and statistics for that connection.
      Overrides:
        `createConnectionForHost` in class `MultiHostConnectionProxy`
      Parameters:
        `hostPortSpec` - The host:port specification.
      Returns:
        The new Connection instance.
      Throws:
        `java.sql.SQLException`

    - #### 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`

    - #### invokeMore

          public 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`
      Throws:
        `java.lang.Throwable`

    - #### doPing

          public void doPing()
                      throws java.sql.SQLException

      Pings live connections.
      Specified by:
        `doPing` in interface `PingTarget`
      Throws:
        `java.sql.SQLException`

    - #### addToGlobalBlacklist

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

      Adds a host to the blacklist with the given timeout.
      Parameters:
        `host` - The host to be blacklisted.
        `timeout` - The blacklist timeout for this entry.

    - #### addToGlobalBlacklist

          public void addToGlobalBlacklist(java.lang.String host)

      Adds a host to the blacklist.
      Parameters:
        `host` - The host to be blacklisted.

    - #### isGlobalBlacklistEnabled

          public boolean isGlobalBlacklistEnabled()

      Checks if host blacklist management was enabled.

    - #### getGlobalBlacklist

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

      Returns a local hosts blacklist, or a blacklist with a single host to be removed, while cleaning up expired records from the global blacklist.
      Returns:
        A local hosts blacklist.

    - #### removeHostWhenNotInUse

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

      Removes a host from the host list, allowing it some time to be released gracefully if needed.
      Parameters:
        `host` - The host to be removed.
      Throws:
        `java.sql.SQLException`

    - #### removeHost

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

      Removes a host from the host list.
      Parameters:
        `host` - The host to be removed.
      Throws:
        `java.sql.SQLException`

    - #### addHost

          public boolean addHost(java.lang.String host)

      Adds a host to the hosts list.
      Parameters:
        `host` - The host to be added.

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