JdbcInterceptor (Apache Tomcat 11.0.23 API Documentation)
Description: declaration: package: org.apache.tomcat.jdbc.pool, class: JdbcInterceptor

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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `CLOSE_VAL`
  `Connection.close()` method name
  `static final String`
  `EQUALS_VAL`
  `Object.equals(Object)`
  `static final String`
  `GETCONNECTION_VAL`
  `PooledConnection.getConnection()` method name
  `static final String`
  `HASHCODE_VAL`
  `Object.hashCode()`
  `static final String`
  `ISCLOSED_VAL`
  `Connection.isClosed()` method name
  `static final String`
  `ISVALID_VAL`
  `Connection.isValid(int)` method name
  `static final String`
  `ISWRAPPERFOR_VAL`
  `Wrapper.isWrapperFor(Class)` method name
  `protected Map<String, PoolProperties.InterceptorProperty>`
  `properties`
  Properties for this interceptor.
  `static final String`
  `TOSTRING_VAL`
  `Object.toString()` method name
  `static final 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(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()`
  True if the compare method uses the Object.equals(Object) method, false if comparison is done on a reference level.
  `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 Object

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

- ## Field Details

  - ### 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
    `Connection.isValid(int)` method name
    See Also:
      - Constant Field Values

  - ### EQUALS_VAL

    public static final String EQUALS_VAL
    `Object.equals(Object)`
    See Also:
      - Constant Field Values

  - ### HASHCODE_VAL

    public static final String HASHCODE_VAL
    `Object.hashCode()`
    See Also:
      - Constant Field Values

  - ### properties

    protected Map<String, PoolProperties.InterceptorProperty> properties
    Properties for this interceptor.

- ## Constructor Details

  - ### JdbcInterceptor

    public JdbcInterceptor()
    Public constructor for instantiation through reflection

- ## Method Details

  - ### 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` - The next chain item

  - ### compare

    public boolean compare(String name1, 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(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` - 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 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` - The properties

  - ### isUseEquals

    public boolean isUseEquals()
    True if the compare method uses the Object.equals(Object) method, false if comparison is done on a reference level.
    Returns:
      true if equals is used for comparisons

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