Interface Validator

public interface Validator
Interface to be implemented by custom validator classes. An implementation configured through PoolConfiguration.setValidatorClassName(String) is instantiated reflectively and therefore must have a public no-arg constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    validate(Connection connection, int validateAction)
    Validate a connection and return a boolean to indicate if it's valid.

  • Method Details

    • validate

      boolean validate(Connection connection, int validateAction)
      Validate a connection and return a boolean to indicate if it's valid.

      The pool calls this method with the underlying JDBC connection, outside any interceptor chain, and treats any runtime exception or non-fatal Error thrown by an implementation as a validation failure. A StackOverflowError is swallowed like a non-fatal error; the other VirtualMachineError types are re-thrown. Implementations that invoke JDBC APIs must catch SQLException and return false themselves, since this method does not declare a checked exception. A false result (or a thrown runtime exception or error) causes the pool to discard the connection; on a borrow that discard happens within the same getConnection() call, as the pool immediately re-establishes the session and validates the replacement, reporting it as PooledConnection.VALIDATE_INIT when new connections are initialized.

      The pool performs no transaction management as part of validating. The built-in, query-based check ends any transaction open on the session when it completes - its own, or one a previous borrower left behind - but a validator replaces that check and owns the session state it observes: an implementation that executes statements on a session whose auto-commit mode is off must commit or roll back the transaction those statements open, itself.

      The pool may skip validation entirely for a given action - it validates when the corresponding testOnBorrow, testOnReturn, testWhileIdle or testOnConnect flag is set (the idle action additionally requires a running pool sweeper, see PoolConfiguration.setTimeBetweenEvictionRunsMillis(int)), and for PooledConnection.VALIDATE_INIT also when a non-blank initSQL is configured - and it may short-circuit repeated validations, see PoolConfiguration.setValidationInterval(long). The validator replaces the query-based validation entirely: while it is set, neither the validation query nor a configured init SQL is executed. This method is therefore not guaranteed to run for every borrow, and it must not be relied on for per-borrow session state. Implementations are invoked concurrently from any application, management or pool-internal thread - including a sweeper timer thread shared by every pool in the JVM - and must be thread-safe.

      Parameters:
      connection - the underlying Connection to test - not the pool's proxied handle, though the object itself may be a driver or third-party wrapper
      validateAction - the action used. One of PooledConnection.VALIDATE_BORROW, PooledConnection.VALIDATE_IDLE, PooledConnection.VALIDATE_INIT or PooledConnection.VALIDATE_RETURN
      Returns:
      true if the connection is valid