MultiHostConnectionProxy
Date: 2016-03-08

com.mysql.jdbc

## Class MultiHostConnectionProxy

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

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

      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`
    `(package private) java.util.Properties` | `localProps`
    `(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
    --- | ---
    `(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.
    `(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)`
    `(package private) abstract java.lang.Object` | `invokeMore(java.lang.Object proxy, java.lang.reflect.Method method, java.lang.Object[] args)`
    `(package private) abstract void` | `pickNewConnection()` Picks the "best" connection to use from now on.
    `(package private) java.lang.Object` | `proxyIfIsJdbcInterface(java.lang.Object toProxy)` If the given object implements a JDBC interface, proxies it so that we can catch SQL errors and fire a connection switch.
    `(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

    - #### currentConnection

          MySQLConnection currentConnection

    - #### isClosed

          boolean isClosed

    - #### closedExplicitly

          boolean closedExplicitly

    - #### closedReason

          java.lang.String closedReason

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

    - #### proxyIfIsJdbcInterface

          java.lang.Object proxyIfIsJdbcInterface(java.lang.Object toProxy)

      If the given object implements a JDBC interface, proxies it so that we can catch SQL errors and fire a connection switch.
      Parameters:
        `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.

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

      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

      Throws:
        `java.lang.Throwable`