MultiHostConnectionProxy
Date: 2018-05-01

com.mysql.jdbc

## Class MultiHostConnectionProxy

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

- All Implemented Interfaces:
    java.lang.reflect.InvocationHandler
  Direct Known Subclasses:
    FailoverConnectionProxy, LoadBalancedConnectionProxy, ReplicationConnectionProxy

      public abstract class MultiHostConnectionProxy
      extends java.lang.Object
      implements java.lang.reflect.InvocationHandler

  An abstract class that processes generic multi-host configurations. This class has to be sub-classed by specific multi-host implementations, such as load-balancing and failover.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `(package private) class` | `MultiHostConnectionProxy.JdbcInterfaceProxy` Proxy class to intercept and deal with errors that may occur in any object bound to the current connection.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) boolean` | `autoReconnect`
    `(package private) boolean` | `closedExplicitly`
    `(package private) java.lang.String` | `closedReason`
    `(package private) MySQLConnection` | `currentConnection`
    `(package private) java.util.List<java.lang.String>` | `hostList`
    `(package private) boolean` | `isClosed`
    `protected java.lang.Throwable` | `lastExceptionDealtWith`
    `(package private) java.util.Properties` | `localProps`
    `(package private) MySQLConnection` | `proxyConnection`
    `(package private) MySQLConnection` | `thisAsConnection`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MultiHostConnectionProxy()` Initializes a connection wrapper for this MultiHostConnectionProxy instance.
    `MultiHostConnectionProxy(java.util.List<java.lang.String> hosts, java.util.Properties props)` Constructs a MultiHostConnectionProxy instance for the given list of hosts and connection properties.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected boolean` | `allowedOnClosedConnection(java.lang.reflect.Method method)` Checks if the given method is allowed on closed connections.
    `(package private) ConnectionImpl` | `createConnectionForHost(java.lang.String hostPortSpec)` Creates a new physical connection for the given host:port.
    `(package private) void` | `dealWithInvocationException(java.lang.reflect.InvocationTargetException e)` Deals with InvocationException from proxied objects.
    `(package private) abstract void` | `doAbort(java.util.concurrent.Executor executor)` Executes a abort() invocation;
    `(package private) abstract void` | `doAbortInternal()` Executes a abortInternal() invocation;
    `(package private) abstract void` | `doClose()` Executes a close() invocation;
    `(package private) java.lang.reflect.InvocationHandler` | `getNewJdbcInterfaceProxy(java.lang.Object toProxy)` Instantiates a new JdbcInterfaceProxy for the given object.
    `(package private) MySQLConnection` | `getNewWrapperForThisAsConnection()` Wraps this object with a new multi-host Connection instance.
    `protected MySQLConnection` | `getProxy()` Get this connection's proxy.
    `(package private) int` | `initializeHostsSpecs(java.util.List<java.lang.String> hosts, java.util.Properties props)` Initializes the hosts lists and makes a "clean" local copy of the given connection properties so that it can be later used to create standard connections.
    `(package private) void` | `invalidateConnection(MySQLConnection conn)` Invalidates the specified connection by closing it.
    `(package private) void` | `invalidateCurrentConnection()` Invalidates the current connection.
    `java.lang.Object` | `invoke(java.lang.Object proxy, java.lang.reflect.Method method, java.lang.Object[] args)` Proxies method invocation on the java.sql.Connection interface, trapping multi-host specific methods and generic methods.
    `(package private) abstract java.lang.Object` | `invokeMore(java.lang.Object proxy, java.lang.reflect.Method method, java.lang.Object[] args)` Continuation of the method invocation process, to be implemented within each subclass.
    `(package private) abstract boolean` | `isMasterConnection()` Checks if current connection is to a master host.
    `(package private) abstract void` | `pickNewConnection()` Picks the "best" connection to use from now on.
    `protected void` | `propagateProxyDown(MySQLConnection proxyConn)` Propagates the connection proxy down through the multi-host connections chain.
    `(package private) java.lang.Object` | `proxyIfReturnTypeIsJdbcInterface(java.lang.Class<?> returnType, java.lang.Object toProxy)` If the given return type is or implements a JDBC interface, proxies the given object so that we can catch SQL errors and fire a connection switch.
    `protected void` | `setProxy(MySQLConnection proxyConn)` Sets this connection's proxy.
    `(package private) abstract boolean` | `shouldExceptionTriggerConnectionSwitch(java.lang.Throwable t)` Checks if the given throwable should trigger a connection switch.
    `(package private) static void` | `syncSessionState(Connection source, Connection target)` Synchronizes session state between two connections.
    `(package private) static void` | `syncSessionState(Connection source, Connection target, boolean readOnly)` Synchronizes session state between two connections, allowing to override the read-only status.

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

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

- - ### Field Detail

    - #### hostList

          java.util.List<java.lang.String> hostList

    - #### localProps

          java.util.Properties localProps

    - #### autoReconnect

          boolean autoReconnect

    - #### thisAsConnection

          MySQLConnection thisAsConnection

    - #### proxyConnection

          MySQLConnection proxyConnection

    - #### currentConnection

          MySQLConnection currentConnection

    - #### isClosed

          boolean isClosed

    - #### closedExplicitly

          boolean closedExplicitly

    - #### closedReason

          java.lang.String closedReason

    - #### lastExceptionDealtWith

          protected java.lang.Throwable lastExceptionDealtWith

  - ### Constructor Detail

    - #### MultiHostConnectionProxy

          MultiHostConnectionProxy()
                             throws java.sql.SQLException

      Initializes a connection wrapper for this MultiHostConnectionProxy instance.
      Parameters:
        `props` - The properties to be used in new internal connections.
      Throws:
        `java.sql.SQLException`

    - #### MultiHostConnectionProxy

          MultiHostConnectionProxy(java.util.List<java.lang.String> hosts,
                                  java.util.Properties props)
                             throws java.sql.SQLException

      Constructs a MultiHostConnectionProxy instance for the given list of hosts and connection properties.
      Parameters:
        `hosts` - The lists of hosts available to switch on.
        `props` - The properties to be used in new internal connections.
      Throws:
        `java.sql.SQLException`

  - ### Method Detail

    - #### initializeHostsSpecs

          int initializeHostsSpecs(java.util.List<java.lang.String> hosts,
                                 java.util.Properties props)

      Initializes the hosts lists and makes a "clean" local copy of the given connection properties so that it can be later used to create standard connections.
      Parameters:
        `hosts` - The list of hosts for this multi-host connection.
        `props` - Connection properties from where to get initial settings and to be used in new connections.
      Returns:
        The number of hosts found in the hosts list.

    - #### getNewWrapperForThisAsConnection

          MySQLConnection getNewWrapperForThisAsConnection()
                                                     throws java.sql.SQLException

      Wraps this object with a new multi-host Connection instance.
      Returns:
        The connection object instance that wraps 'this'.
      Throws:
        `java.sql.SQLException`

    - #### getProxy

          protected MySQLConnection getProxy()

      Get this connection's proxy. A multi-host connection may not be at top level in the multi-host connections chain. In such case the first connection in the chain is available as a proxy.
      Returns:
        Returns this connection's proxy if there is one or itself if this is the first one.

    - #### setProxy

          protected final void setProxy(MySQLConnection proxyConn)

      Sets this connection's proxy. This proxy should be the first connection in the multi-host connections chain. After setting the connection proxy locally, propagates it through the dependant connections.
      Parameters:
        `proxyConn` - The top level connection in the multi-host connections chain.

    - #### propagateProxyDown

          protected void propagateProxyDown(MySQLConnection proxyConn)

      Propagates the connection proxy down through the multi-host connections chain. This method is intended to be overridden in subclasses that manage more than one active connection at same time.
      Parameters:
        `proxyConn` - The top level connection in the multi-host connections chain.

    - #### proxyIfReturnTypeIsJdbcInterface

          java.lang.Object proxyIfReturnTypeIsJdbcInterface(java.lang.Class<?> returnType,
                                                          java.lang.Object toProxy)

      If the given return type is or implements a JDBC interface, proxies the given object so that we can catch SQL errors and fire a connection switch.
      Parameters:
        `returnType` - The type the object instance to proxy is supposed to be.
        `toProxy` - The object instance to proxy.
      Returns:
        The proxied object or the original one if it does not implement a JDBC interface.

    - #### getNewJdbcInterfaceProxy

          java.lang.reflect.InvocationHandler getNewJdbcInterfaceProxy(java.lang.Object toProxy)

      Instantiates a new JdbcInterfaceProxy for the given object. Subclasses can override this to return instances of JdbcInterfaceProxy subclasses.
      Parameters:
        `toProxy` - The object instance to be proxied.
      Returns:
        The new InvocationHandler instance.

    - #### dealWithInvocationException

          void dealWithInvocationException(java.lang.reflect.InvocationTargetException e)
                                     throws java.sql.SQLException,
                                            java.lang.Throwable,
                                            java.lang.reflect.InvocationTargetException

      Deals with InvocationException from proxied objects.
      Parameters:
        `e` - The Exception instance to check.
      Throws:
        `java.sql.SQLException`
        `java.lang.Throwable`
        `java.lang.reflect.InvocationTargetException`

    - #### shouldExceptionTriggerConnectionSwitch

          abstract boolean shouldExceptionTriggerConnectionSwitch(java.lang.Throwable t)

      Checks if the given throwable should trigger a connection switch.
      Parameters:
        `t` - The Throwable instance to analyze.

    - #### isMasterConnection

          abstract boolean isMasterConnection()

      Checks if current connection is to a master host.

    - #### invalidateCurrentConnection

          void invalidateCurrentConnection()
                                     throws java.sql.SQLException

      Invalidates the current connection.
      Throws:
        `java.sql.SQLException`

    - #### invalidateConnection

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

      Invalidates the specified connection by closing it.
      Parameters:
        `conn` - The connection instance to invalidate.
      Throws:
        `java.sql.SQLException`

    - #### pickNewConnection

          abstract void pickNewConnection()
                                   throws java.sql.SQLException

      Picks the "best" connection to use from now on. Each subclass needs to implement its connection switch strategy on it.
      Throws:
        `java.sql.SQLException`

    - #### createConnectionForHost

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

      Creates a new physical connection for the given host:port.
      Parameters:
        `hostPortSpec` - The host:port specification.
      Returns:
        The new Connection instance.
      Throws:
        `java.sql.SQLException`

    - #### syncSessionState

          static void syncSessionState(Connection source,
                              Connection target)
                                throws java.sql.SQLException

      Synchronizes session state between two connections.
      Parameters:
        `source` - The connection where to get state from.
        `target` - The connection where to set state.
      Throws:
        `java.sql.SQLException`

    - #### syncSessionState

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

      Synchronizes session state between two connections, allowing to override the read-only status.
      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`

    - #### doClose

          abstract void doClose()
                         throws java.sql.SQLException

      Executes a close() invocation;
      Throws:
        `java.sql.SQLException`

    - #### doAbortInternal

          abstract void doAbortInternal()
                                 throws java.sql.SQLException

      Executes a abortInternal() invocation;
      Throws:
        `java.sql.SQLException`

    - #### doAbort

          abstract void doAbort(java.util.concurrent.Executor executor)
                         throws java.sql.SQLException

      Executes a abort() invocation;
      Throws:
        `java.sql.SQLException`

    - #### invoke

          public java.lang.Object invoke(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 multi-host specific methods and generic methods. Subclasses have to override this to complete the method invocation process, deal with exceptions and decide when to switch connection. To avoid unnecessary additional exception handling overriders should consult #canDealWith(Method) before chaining here.
      Specified by:
        `invoke` in interface `java.lang.reflect.InvocationHandler`
      Throws:
        `java.lang.Throwable`

    - #### invokeMore

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

      Continuation of the method invocation process, to be implemented within each subclass.
      Throws:
        `java.lang.Throwable`

    - #### allowedOnClosedConnection

          protected boolean allowedOnClosedConnection(java.lang.reflect.Method method)

      Checks if the given method is allowed on closed connections.