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.