For detailed information and description of below handlers - please look at JavaDoc.

StatementHandler is responsible for all SQL Statement handling: setting input parameters, wrapping return, getting output parameters and cleaning up resources

StatementHandler usually is not set explicitly and LazyStatementHandler is used by default. If custom StatementHandler is needed to use:

1. In case custom StatementHandler needs to be used for whole system please use MjdbcConfig.setDefaultStatementHandler

2. In case custom StatementHandler needs to be used for new instance of QueryRunnerService please use MjdbcFactory.getQueryRunner(<DataSource/Connection>, <TypeHandler.class/null>, <StatementHandler.class>)

3. In case custom StatementHandler needs to be used for particular QueryRunnerService please cast it to QueryRunner:

LazyStatementHandler

Lazy statement is recommended default choice for majority of operations.

LazyStatementHandler is child of CallableStatementHandler and BaseStatementHandler and is responsible for handling both PreparedStatement and CallableStatement handling. On top of those classes it provides ability to execute Lazy queries (using LazyOutputHandler)

// for whole system
MjdbcConfig.setDefaultStatementHandler(LazyStatementHandler.class);

// for new QueryRunnerService instance
QueryRunnerService queryRunner = MjdbcFactory.getQueryRunner(ds, null, LazyStatementHandler.class);
			
// for this particular QueryRunner
QueryRunnerService queryRunner = MjdbcFactory.getQueryRunner(ds);
        ((QueryRunner) queryRunner).setStatementHandler(new LazyStatementHandler(
                ((QueryRunner) queryRunner).getOverrider()
        ));
		
// or a bit simpler but without Profiler
QueryRunner queryRunner = new QueryRunner(ds);
QueryRunner.setStatementHandler(new LazyStatementHandler(queryRunner.getOverrider()));

// for whole system
MjdbcConfig.setDefaultStatementHandler(CallableStatementHandler.class);

// for new QueryRunnerService instance
QueryRunnerService queryRunner = MjdbcFactory.getQueryRunner(ds, null, CallableStatementHandler.class);
			
// for this particular QueryRunner
QueryRunnerService queryRunner = MjdbcFactory.getQueryRunner(ds);
        ((QueryRunner) queryRunner).setStatementHandler(new CallableStatementHandler(
                ((QueryRunner) queryRunner).getOverrider()
        ));
		
// or a bit simpler but without Profiler
QueryRunner queryRunner = new QueryRunner(ds);
QueryRunner.setStatementHandler(new CallableStatementHandler(queryRunner.getOverrider()));

// for whole system
MjdbcConfig.setDefaultStatementHandler(BaseStatementHandler.class);

// for new QueryRunnerService instance
QueryRunnerService queryRunner = MjdbcFactory.getQueryRunner(ds, null, BaseStatementHandler.class);
			
// for this particular QueryRunner
QueryRunnerService queryRunner = MjdbcFactory.getQueryRunner(ds);
        ((QueryRunner) queryRunner).setStatementHandler(new BaseStatementHandler(
                ((QueryRunner) queryRunner).getOverrider()
        ));
		
// or a bit simpler but without Profiler
QueryRunner queryRunner = new QueryRunner(ds);
QueryRunner.setStatementHandler(new BaseStatementHandler(queryRunner.getOverrider()));

For detailed information and description of below handlers - please look at JavaDoc.

MetadataHandler is responsible for accessing DatabaseMetadata and retrieving Stored Procedure parameters.

MetadataHandler usually is not set explicitly and BaseMetadataHandler is used by default.

BaseMetadataHandler

Base implementation of MetadataHandler. Was tested to work with Derby, MySQL, MariaDB, PostgreSQL, Oracle

// for whole system
MjdbcConfig.setDefaultMetadataHandler(BaseMetadataHandler.class);
			
// for this particular QueryRunner
QueryRunnerService queryRunner = MjdbcFactory.getQueryRunner(ds);
        ((QueryRunner) queryRunner).setMetadataHandler(new BaseMetadataHandler(
                ((QueryRunner) queryRunner).getOverrider()
        ));
		
// or a bit simpler but without Profiler
QueryRunner queryRunner = new QueryRunner(ds);
QueryRunner.setMetadataHandler(new BaseMetadataHandler(queryRunner.getOverrider()));

For detailed information and description of below handlers - please look at JavaDoc.

TypeHandler performs, automatically, conversion in/from Java Classes into JDBC Classes. Few examples below:

TypeHandler allows to work with Clob just by specifying String/byte[]/InputStream and receiving String.

TypeHandler allows to work with Blob just by specifying byte[]/String/InputStream and receiving byte[].

TypeHandler Handles Cursor as well. It is returned as with List of Maps

If no TypeHandler is specified explicitly - EmptyTypeHandler is used by default and no type handling is performed.

Recommended TypeHandler choice is UniversalTypeHandler

EmptyTypeHandler

EmptyTypeHandler should be used in cases no Type handling should be performed. Is used by default if TypeHandler wasn't explicitly specified.

// for whole system
MjdbcConfig.setDefaultTypeHandler(EmptyTypeHandler.class);
			
// for this particular QueryRunner
QueryRunnerService queryRunner = MjdbcFactory.getQueryRunner(ds, EmptyTypeHandler.class);

UniversalTypeHandler

UniversalTypeHandler should be used with all major databases (MySQL/MariaDB, PostgreSQL, MsSQL) with both JDBC3 and JDBC4 drivers. It is recommended choice for majority of cases

// for whole system
MjdbcConfig.setDefaultTypeHandler(UniversalTypeHandler.class);
			
// for this particular QueryRunner
QueryRunnerService queryRunner = MjdbcFactory.getQueryRunner(ds, UniversalTypeHandler.class);

BaseTypeHandler

BaseTypeHandler can be used in cases where JDBC4(BLOB, CLOB) types should be supported. Although it is generally recommended to use UniversalTypeHandler where possible

// for whole system
MjdbcConfig.setDefaultTypeHandler(BaseTypeHandler.class);
			
// for this particular QueryRunner
QueryRunnerService queryRunner = MjdbcFactory.getQueryRunner(ds, BaseTypeHandler.class);

OracleTypeHandler

OracleTypeHandler should be used while working with Oracle DB

// for whole system
MjdbcConfig.setDefaultTypeHandler(OracleTypeHandler.class);
			
// for this particular QueryRunner
QueryRunnerService queryRunner = MjdbcFactory.getQueryRunner(ds, OracleTypeHandler.class);

For detailed information and description of below handlers - please look at JavaDoc.

TransactionHandler is responsible for Transaction handling. By default works in automatic mode, which means every transaction is committed immediately. In order to switch it to Manual mode please use setManualMode. After Manual mode was activated - commit/rollback should be invoked explicitly by invoking commit/rollback

TransactionHandler usually is not set explicitly and BaseTransactionHandler is used by default.

BaseTransactionHandler

Base TransactionHandler implementation. Perform standard Transaction handling. For more details about it please refer to Oracle Java Tutorials

// for whole system
MjdbcConfig.setDefaultTransactionHandler(BaseTransactionHandler.class);
			
// for this particular QueryRunner
QueryRunnerService queryRunner = MjdbcFactory.getQueryRunner(ds);
        ((QueryRunner) queryRunner).setTransactionHandler(new BaseTransactionHandler(
                ((QueryRunner) queryRunner).getOverrider()
        ));
		
// or a bit simpler but without Profiler
QueryRunner queryRunner = new QueryRunner(ds);
QueryRunner.setTransactionHandler(new BaseTransactionHandler(queryRunner.getOverrider()));

// change Transaction level (please look at Oracle docs for additional description)
queryRunner.setTransactionIsolationLevel();

// commit/rollback
queryRunner.commit/rollback/rollback(savepoint);

// savepoint
queryRunner.setSavepoint/setSavepoint(name)/releaseSavepoint(savepoint);

For detailed information and description of below handlers - please look at JavaDoc.

ExceptionHandler is responsible for interpreting SQLException thrown by JDBC Driver and throwing Vendor specific Exception

ExceptionHandler usually is not set explicitly and BaseExceptionHandler is used by default.

BaseExceptionHandler

Base ExceptionHandler implementation. Does not interpret SQLException into Vendor specific Exception, but rethrows original exception populated with Query parameters

// for whole system
MjdbcConfig.setDefaultExceptionHandler(new BaseExceptionHandler());
			
// it is impossible to specify ExceptionHandler per QueryRunner, as it is created to be able to process any SQLException thrown from any Vendor and any QueryRunner

SpringExceptionHandler

SpringExceptionHandler is implemented to support all existing Spring exception handlers: JDBC4, sql state prefix and database specific. This allows to catch the same exceptions as are thrown by Spring JDBC

// for whole system
MjdbcConfig.setDefaultExceptionHandler(SpringExceptionHandler.class);

// for this particular QueryRunner
QueryRunnerService queryRunner = MjdbcFactory.getQueryRunner(ds);
((QueryRunner) queryRunner).setExceptionHandler(new SpringExceptionHandler(<database name/"absent">)); 
// if "absent" is specified as database name - vendor specific exception handling is not performed, but JDBC4 and sql state prefix handling would be still available.

// database name can be received from: MetadataUtils.processDatabaseProductName(metaData.getDatabaseProductName()). metaData - is instance of DatabaseMetaData.

For detailed information and description of below classes - please look at JavaDoc.

List of available Spring SQL Exception handlers:

• BadSqlGrammarException is thrown when SQL specified is invalid.
• CannotAcquireLockException is thrown on failure to acquire a lock during an update, for example during a "select for update" statement.
• CannotSerializeTransactionException is thrown on failure to complete a transaction in serialized mode due to update conflicts.
• ConcurrencyFailureException is thrown on concurrency failure.
• DataAccessResourceFailureException is thrown when a resource fails completely: for example, if we can't connect to a database using JDBC.
• DataIntegrityViolationException is thrown when an attempt to insert or update data results in violation of an integrity constraint.
• DeadlockLoserDataAccessException is thrown when the current process was a deadlock loser, and its transaction rolled back.
• DuplicateKeyException is thrown when an attempt to insert or update data results in violation of an primary key or unique constraint.
• InvalidDataAccessApiUsageException is thrown on incorrect usage of the API, such as failing to "compile" a query object that needed compilation before execution.
• InvalidResultSetAccessException is thrown when a ResultSet has been accessed in an invalid fashion.
• PermissionDeniedDataAccessException is thrown when the underlying resource denied a permission to access a specific element, such as a specific database table.
• QueryTimeoutException is thrown on a query timeout.
• RecoverableDataAccessException is thrown when a previously failed operation might be able to succeed if the application performs some recovery steps and retries the entire transaction or in the case of a distributed transaction, the transaction branch.
• TransientDataAccessResourceException is thrown when a resource fails temporarily and the operation can be retried.

Below you can provide feedback, suggestions, questions regarding information posted on current page