Package org.apache.tomcat.jdbc.pool

Class JdbcInterceptor

java.lang.Object

org.apache.tomcat.jdbc.pool.JdbcInterceptor

All Implemented Interfaces:

java.lang.reflect.InvocationHandler

Direct Known Subclasses:

AbstractCreateStatementInterceptor, ConnectionState, DisposableConnectionFacade, ProxyConnection, TrapException

public abstract class JdbcInterceptor
extends java.lang.Object
implements java.lang.reflect.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

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	CLOSE_VAL	Connection.close() method name
static java.lang.String	EQUALS_VAL	Object.equals(Object)
static java.lang.String	GETCONNECTION_VAL	PooledConnection.getConnection() method name
static java.lang.String	HASHCODE_VAL	Object.hashCode()
static java.lang.String	ISCLOSED_VAL	Connection.isClosed() method name
static java.lang.String	ISVALID_VAL	Connection.isValid(int) method name
static java.lang.String	ISWRAPPERFOR_VAL	Wrapper.isWrapperFor(Class) method name
protected java.util.Map<java.lang.String,PoolProperties.InterceptorProperty>	properties	Properties for this interceptor.
static java.lang.String	TOSTRING_VAL	Object.toString() method name
static java.lang.String	UNWRAP_VAL	Wrapper.unwrap(Class) method name

Constructor Summary

Constructors

Constructor	Description
JdbcInterceptor()	Public constructor for instantiation through reflection

Method Summary

Modifier and Type	Method	Description
boolean	compare(java.lang.String methodName, java.lang.reflect.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(java.lang.String name1, java.lang.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
java.util.Map<java.lang.String,PoolProperties.InterceptorProperty>	getProperties()	Returns the properties configured for this interceptor
java.lang.Object	invoke(java.lang.Object proxy, java.lang.reflect.Method method, java.lang.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(java.util.Map<java.lang.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 java.lang.String CLOSE_VAL

Connection.close() method name

See Also:

Constant Field Values

TOSTRING_VAL

public static final java.lang.String TOSTRING_VAL

Object.toString() method name

See Also:

Constant Field Values

ISCLOSED_VAL

public static final java.lang.String ISCLOSED_VAL

Connection.isClosed() method name

See Also:

Constant Field Values

GETCONNECTION_VAL

public static final java.lang.String GETCONNECTION_VAL

PooledConnection.getConnection() method name

See Also:

Constant Field Values

UNWRAP_VAL

public static final java.lang.String UNWRAP_VAL

Wrapper.unwrap(Class) method name

See Also:

Constant Field Values

ISWRAPPERFOR_VAL

public static final java.lang.String ISWRAPPERFOR_VAL

Wrapper.isWrapperFor(Class) method name

See Also:

Constant Field Values

ISVALID_VAL

public static final java.lang.String ISVALID_VAL

Connection.isValid(int) method name

See Also:

Constant Field Values

EQUALS_VAL

public static final java.lang.String EQUALS_VAL

Object.equals(Object)

See Also:

Constant Field Values

HASHCODE_VAL

public static final java.lang.String HASHCODE_VAL

Object.hashCode()

See Also:

Constant Field Values

properties

protected java.util.Map<java.lang.String,PoolProperties.InterceptorProperty> properties

Properties for this interceptor.

Constructor Detail

JdbcInterceptor

public JdbcInterceptor()

Public constructor for instantiation through reflection

Method Detail

invoke

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

Gets invoked each time an operation on Connection is invoked.

Specified by:

invoke in interface java.lang.reflect.InvocationHandler

Throws:

java.lang.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 - The next chain item

compare

public boolean compare(java.lang.String name1,
                       java.lang.String name2)

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

Parameters:

name1 - The first name

name2 - The second name

Returns:

true if name1 is equal to name2 based on useEquals

compare

public boolean compare(java.lang.String methodName,
                       java.lang.reflect.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 - The method name

method - The 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 java.util.Map<java.lang.String,PoolProperties.InterceptorProperty> getProperties()

Returns the properties configured for this interceptor

Returns:

the configured properties for this interceptor

setProperties

public void setProperties(java.util.Map<java.lang.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 - The 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 - true if equals will be used for comparisons

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.