org.apache.tomcat.jdbc.pool
Class JdbcInterceptor

java.lang.Object
  org.apache.tomcat.jdbc.pool.JdbcInterceptor

All Implemented Interfaces:

InvocationHandler

Direct Known Subclasses:

AbstractCreateStatementInterceptor, ConnectionState, DisposableConnectionFacade, ProxyConnection, TrapException

public abstract class JdbcInterceptor
extends Object
implements InvocationHandler

Abstract class that is to be extended for implementations of interceptors. Everytime an operation is called on the Connection object the invoke(Object, Method, Object[]) method on the interceptor will be called. Interceptors are useful to change or improve behavior of the connection pool.
Interceptors can receive a set of properties. Each sub class is responsible for parsing the properties during runtime when they are needed or simply override the setProperties(Map) method. Properties arrive in a key-value pair of Strings as they were received through the configuration. This method is called once per cached connection object when the object is first configured.

Version:

1.0

Author:

Filip Hanik

Field Summary

static String	CLOSE_VAL Connection.close() method name
static String	GETCONNECTION_VAL PooledConnection.getConnection() method name
static String	ISCLOSED_VAL Connection.isClosed() method name
static String	ISVALID_VAL java.sql.Connection#isValid(boolean) method name
static String	ISWRAPPERFOR_VAL Wrapper.isWrapperFor(Class) method name
protected Map<String,PoolProperties.InterceptorProperty>	properties Properties for this interceptor.
static String	TOSTRING_VAL Object.toString() method name
static String	UNWRAP_VAL Wrapper.unwrap(Class) method name

Constructor Summary

JdbcInterceptor()
Public constructor for instantation through reflection

Method Summary

boolean	compare(String methodName, Method method) Compares a method name (String) to a method (Method) compare(String,String) Uses reference comparison unless the useEquals property is set to true
boolean	compare(String name1, String name2) Performs a string comparison, using references unless the useEquals property is set to true.
void	disconnected(ConnectionPool parent, PooledConnection con, boolean finalizing) Called when Connection.close() is called on the underlying connection.
JdbcInterceptor	getNext() Returns the next interceptor in the chain
Map<String,PoolProperties.InterceptorProperty>	getProperties() Returns the properties configured for this interceptor
Object	invoke(Object proxy, Method method, Object[] args) Gets invoked each time an operation on Connection is invoked.
boolean	isUseEquals()
void	poolClosed(ConnectionPool pool) This method is invoked by a connection pool when the pool is closed.
void	poolStarted(ConnectionPool pool) This method is invoked by a connection pool when the pool is first started up, usually when the first connection is requested.
abstract void	reset(ConnectionPool parent, PooledConnection con) Gets called each time the connection is borrowed from the pool This means that if an interceptor holds a reference to the connection the interceptor can be reused for another connection.
void	setNext(JdbcInterceptor next) configures the next interceptor in the chain
void	setProperties(Map<String,PoolProperties.InterceptorProperty> properties) Called during the creation of an interceptor The properties can be set during the configuration of an interceptor Override this method to perform type casts between string values and object properties
void	setUseEquals(boolean useEquals) Set to true if string comparisons (for the compare(String, Method) and compare(String, String) methods) should use the Object.equals(Object) method The default is false

Methods inherited from class java.lang.Object

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

Field Detail

CLOSE_VAL

public static final String CLOSE_VAL

Connection.close() method name

See Also:

Constant Field Values

TOSTRING_VAL

public static final String TOSTRING_VAL

Object.toString() method name

See Also:

Constant Field Values

ISCLOSED_VAL

public static final String ISCLOSED_VAL

Connection.isClosed() method name

See Also:

Constant Field Values

GETCONNECTION_VAL

public static final String GETCONNECTION_VAL

PooledConnection.getConnection() method name

See Also:

Constant Field Values

UNWRAP_VAL

public static final String UNWRAP_VAL

Wrapper.unwrap(Class) method name

See Also:

Constant Field Values

ISWRAPPERFOR_VAL

public static final String ISWRAPPERFOR_VAL

Wrapper.isWrapperFor(Class) method name

See Also:

Constant Field Values

ISVALID_VAL

public static final String ISVALID_VAL

java.sql.Connection#isValid(boolean) method name

See Also:

Constant Field Values

properties

protected Map<String,PoolProperties.InterceptorProperty> properties

Properties for this interceptor.

Constructor Detail

JdbcInterceptor

public JdbcInterceptor()

Public constructor for instantation through reflection

Method Detail

invoke

public Object invoke(Object proxy,
                     Method method,
                     Object[] args)
              throws Throwable

Gets invoked each time an operation on Connection is invoked.

Specified by:

invoke in interface InvocationHandler

Throws:

Throwable

getNext

public JdbcInterceptor getNext()

Returns the next interceptor in the chain

Returns:

the next interceptor in the chain

setNext

public void setNext(JdbcInterceptor next)

configures the next interceptor in the chain

Parameters:

next -

compare

public boolean compare(String name1,
                       String name2)

Performs a string comparison, using references unless the useEquals property is set to true.

Parameters:

name1 -

name2 -

Returns:

true if name1 is equal to name2 based on useEquals

compare

public boolean compare(String methodName,
                       Method method)

Compares a method name (String) to a method (Method) compare(String,String) Uses reference comparison unless the useEquals property is set to true

Parameters:

methodName -

method -

Returns:

true if the name matches

reset

public abstract void reset(ConnectionPool parent,
                           PooledConnection con)

Gets called each time the connection is borrowed from the pool This means that if an interceptor holds a reference to the connection the interceptor can be reused for another connection.
This method may be called with null as both arguments when we are closing down the connection.

Parameters:

parent - - the connection pool owning the connection

con - - the pooled connection

disconnected

public void disconnected(ConnectionPool parent,
                         PooledConnection con,
                         boolean finalizing)

Called when Connection.close() is called on the underlying connection. This is to notify the interceptors, that the physical connection has been released. Implementation of this method should be thought through with care, as no actions should trigger an exception.

Parameters:

parent - - the connection pool that this connection belongs to

con - - the pooled connection that holds this connection

finalizing - - if this connection is finalizing. True means that the pooled connection will not reconnect the underlying connection

getProperties

public Map<String,PoolProperties.InterceptorProperty> getProperties()

Returns the properties configured for this interceptor

Returns:

the configured properties for this interceptor

setProperties

public void setProperties(Map<String,PoolProperties.InterceptorProperty> properties)

Called during the creation of an interceptor The properties can be set during the configuration of an interceptor Override this method to perform type casts between string values and object properties

Parameters:

properties -

isUseEquals

public boolean isUseEquals()

Returns:

true if the compare method uses the Object.equals(Object) method false if comparison is done on a reference level

setUseEquals

public void setUseEquals(boolean useEquals)

Set to true if string comparisons (for the compare(String, Method) and compare(String, String) methods) should use the Object.equals(Object) method The default is false

Parameters:

useEquals -

poolClosed

public void poolClosed(ConnectionPool pool)

This method is invoked by a connection pool when the pool is closed. Interceptor classes can override this method if they keep static variables or other tracking means around. This method is only invoked on a single instance of the interceptor, and not on every instance created.

Parameters:

pool - - the pool that is being closed.

poolStarted

public void poolStarted(ConnectionPool pool)

This method is invoked by a connection pool when the pool is first started up, usually when the first connection is requested. Interceptor classes can override this method if they keep static variables or other tracking means around. This method is only invoked on a single instance of the interceptor, and not on every instance created.

Parameters:

pool - - the pool that is being closed.