jDBI 2.0 Documentation

Statements and Queries

Query and statement processing goes through a number of stages. When a statement is first created it is effectively a builder object which you use to configure what you want it to do. You can add customizers, result mappers, define properties on its statement context, bind arguments, and so on. It stays pretty much the same, modulo what you set, until the statement is executed. When the statement is executed the fun starts.

The first thing the statement does is lookup the actual SQL to use from the StatementLocator. This class receives the string used to create the statement and returns another String, possibly the same. The default implementation returns the same string if it lokos like SQL, otherwise looks for it on the classpath, you can see the javadocs for ClasspathStatementLocator for the exact details. You can plug your own in on the DBI if you want different lookup rules. The StringTemplateStatementLocator is another bundled statement locator which supports some dynamic sql generation, for example.

After the bas SQL string has been located it is passed to a StatementRewriter. The rewriter is used to do final manipulation. The default one, for instance, converts :foo tokens into ? to support named parameters. See ColonPrefixNamedParamStatementRewriter for more information.

Next, the rewritten SQL is passed to a StatementBuilder which converts the sql to a JDBC PreparedStatement. The default implementation creates a new prepared statement every time, but there is also an incuded implementation which will cache prepared statements on a given handle.

The last step before execution is to invoke any statement customizers which have been applied to the statement. This includes things like the OracleReturning functionality, as well as custom ones.

Post execution, query customizers are run again (post-execution callback).

After customizers run, a query has its result set passed through the specified mapper, either eagerly in the case of list() or lazily in the case of iterate(), whereas a DML statement just returns the rows modfied.