Module org.jooq

Package org.jooq

Interface ExecuteListener

All Superinterfaces:

EventListener, Serializable

All Known Implementing Classes:

CallbackExecuteListener, DefaultExecuteListener, LoggerListener, StopWatchListener

public interface ExecuteListener
extends EventListener, Serializable

An event listener for Query, Routine, or ResultSet render, prepare, bind, execute, fetch steps.

ExecuteListener is a base type for loggers, debuggers, profilers, data collectors that can be hooked into a jOOQ DSLContext using the Configuration.executeListenerProviders() property, passing Settings to DSL.using(java.sql.Connection, SQLDialect, Settings). jOOQ will use that configuration at the beginning of a query execution event to get a hold of all provided listeners via ExecuteListenerProvider.provide(). The DefaultExecuteListenerProvider will always return the same ExecuteListener instance, but user defined providers can define any custom listener lifecycle, e.g. one instance per execution to store state between the moment when a query execution starts, and the moment when a query execution finishes in the listener. Alternatively, such data can be stored in Scope.data().

Advanced ExecuteListeners can also provide custom implementations of Connection, PreparedStatement, ResultSet, SQLException or RuntimeException to jOOQ in appropriate methods.

The following table explains how every type of statement / operation invokes callback methods in the correct order for all registered ExecuteListeners. Find a legend below the table for the various use cases.

Callback method	Use case [1]	Use case [2]	Use case [3]	Use case [4]	Use case [5]	Use case [6]
start(ExecuteContext)	Yes, 1x	Yes, 1x	Yes, 1x	Yes, 1x	Yes, 1x	Yes, 1x
renderStart(ExecuteContext)	Yes, 1x	Yes, 1x	No	Yes, 1x	Yes, Nx (for every query)	Yes, 1x
renderEnd(ExecuteContext)	Yes, 1x	Yes, 1x	No	Yes, 1x	Yes, Nx (for every query)	Yes, 1x
prepareStart(ExecuteContext)	Yes, 1x	Yes, 1x	No	Yes, 1x	Yes, Nx (for every query)	Yes, 1x
prepareEnd(ExecuteContext)	Yes, 1x	Yes, 1x	No	Yes, 1x	Yes, Nx (for every query)	Yes, 1x
bindStart(ExecuteContext)	Yes, 1x	No	No	Yes, Nx (for every value set)	No	Yes, 1x
bindEnd(ExecuteContext)	Yes, 1x	No	No	Yes, Nx (for every value set)	No	Yes, 1
executeStart(ExecuteContext)	Yes, 1x	Yes, 1x	No	Yes, 1x	Yes, 1x	Yes, 1x
executeEnd(ExecuteContext)	Yes, 1x	Yes, 1x	No	Yes, 1x	Yes, 1x	Yes, 1x
outStart(ExecuteContext)	No	No	No	No	No	Yes, 1x
outEnd(ExecuteContext)	No	No	No	No	No	Yes, 1x
fetchStart(ExecuteContext)	Yes, 1x (Nx for ResultQuery.fetchMany()	Yes, 1x (Nx for ResultQuery.fetchMany()	Yes, 1x	No	No	No
resultStart(ExecuteContext)	Maybe, 1x (Nx for Cursor.fetchNext(int)	Maybe, 1x (Nx for Cursor.fetchNext(int)	Maybe, 1x	No	No	No
recordStart(ExecuteContext)	Yes, Nx	Yes, Nx	Yes, Nx	No	No	No
recordEnd(ExecuteContext)	Yes, Nx	Yes, Nx	Yes, Nx	No	No	No
resultEnd(ExecuteContext)	Maybe, 1x (Nx for Cursor.fetchNext(int)	Maybe, 1x (Nx for Cursor.fetchNext(int)	Maybe, 1x	No	No	No
fetchEnd(ExecuteContext)	Yes, 1x (Nx for ResultQuery.fetchMany()	Yes, 1x (Nx for ResultQuery.fetchMany()	Yes, 1x	No	No	No
end(ExecuteContext)	Yes, 1x	Yes, 1x	Yes, 1x	Yes, 1x	Yes, 1x	Yes, 1x
warning(ExecuteContext)	Maybe, 1x	Maybe, 1x	Maybe, 1x	Maybe, 1x	Maybe, 1x	Maybe, 1x
exception(ExecuteContext)	Maybe, 1x	Maybe, 1x	Maybe, 1x	Maybe, 1x	Maybe, 1x	Maybe, 1x

Legend:

1. Used with ResultQuery of statement type StatementType.PREPARED_STATEMENT
2. Used with ResultQuery of statement type StatementType.STATIC_STATEMENT
3. Used with DSLContext.fetch(ResultSet) or with ResultQuery.fetch()
4. Used with DSLContext.batch(Query)
5. Used with DSLContext.batch(Query[])
6. Used with DSLContext.batch(Queries)
7. Used with a Routine standalone call

If nothing is specified, the default is to use LoggerListener as the only event listener, as configured in Settings.isExecuteLogging()

Author:

Lukas Eder

Method Summary

Modifier and Type	Method	Description
default void	bindEnd(ExecuteContext ctx)	Called after bind variables to the PreparedStatement.
default void	bindStart(ExecuteContext ctx)	Called before bind variables to the PreparedStatement.
default void	end(ExecuteContext ctx)	Called at the end of the execution lifecycle.
default void	exception(ExecuteContext ctx)	Called in the event of an exception at any moment of the execution lifecycle.
default void	executeEnd(ExecuteContext ctx)	Called after executing a statement.
default void	executeStart(ExecuteContext ctx)	Called before executing a statement.
default void	fetchEnd(ExecuteContext ctx)	Called after fetching data from a ResultSet.
default void	fetchStart(ExecuteContext ctx)	Called before fetching data from a ResultSet into a Result type.
static CallbackExecuteListener	onBindEnd(ExecuteEventHandler handler)	Create an ExecuteListener with a bindEnd(ExecuteContext) implementation.
static CallbackExecuteListener	onBindStart(ExecuteEventHandler handler)	Create an ExecuteListener with a bindStart(ExecuteContext) implementation.
static CallbackExecuteListener	onEnd(ExecuteEventHandler handler)	Create an ExecuteListener with a end(ExecuteContext) implementation.
static CallbackExecuteListener	onException(ExecuteEventHandler handler)	Create an ExecuteListener with a exception(ExecuteContext) implementation.
static CallbackExecuteListener	onExecuteEnd(ExecuteEventHandler handler)	Create an ExecuteListener with a executeEnd(ExecuteContext) implementation.
static CallbackExecuteListener	onExecuteStart(ExecuteEventHandler handler)	Create an ExecuteListener with a executeStart(ExecuteContext) implementation.
static CallbackExecuteListener	onFetchEnd(ExecuteEventHandler handler)	Create an ExecuteListener with a fetchEnd(ExecuteContext) implementation.
static CallbackExecuteListener	onFetchStart(ExecuteEventHandler handler)	Create an ExecuteListener with a fetchStart(ExecuteContext) implementation.
static CallbackExecuteListener	onOutEnd(ExecuteEventHandler handler)	Create an ExecuteListener with a outEnd(ExecuteContext) implementation.
static CallbackExecuteListener	onOutStart(ExecuteEventHandler handler)	Create an ExecuteListener with a outStart(ExecuteContext) implementation.
static CallbackExecuteListener	onPrepareEnd(ExecuteEventHandler handler)	Create an ExecuteListener with a prepareEnd(ExecuteContext) implementation.
static CallbackExecuteListener	onPrepareStart(ExecuteEventHandler handler)	Create an ExecuteListener with a prepareStart(ExecuteContext) implementation.
static CallbackExecuteListener	onRecordEnd(ExecuteEventHandler handler)	Create an ExecuteListener with a recordEnd(ExecuteContext) implementation.
static CallbackExecuteListener	onRecordStart(ExecuteEventHandler handler)	Create an ExecuteListener with a recordStart(ExecuteContext) implementation.
static CallbackExecuteListener	onRenderEnd(ExecuteEventHandler handler)	Create an ExecuteListener with a renderEnd(ExecuteContext) implementation.
static CallbackExecuteListener	onRenderStart(ExecuteEventHandler handler)	Create an ExecuteListener with a renderStart(ExecuteContext) implementation.
static CallbackExecuteListener	onResultEnd(ExecuteEventHandler handler)	Create an ExecuteListener with a resultEnd(ExecuteContext) implementation.
static CallbackExecuteListener	onResultStart(ExecuteEventHandler handler)	Create an ExecuteListener with a resultStart(ExecuteContext) implementation.
static CallbackExecuteListener	onStart(ExecuteEventHandler handler)	Create an ExecuteListener with a start(ExecuteContext) implementation.
static CallbackExecuteListener	onWarning(ExecuteEventHandler handler)	Create an ExecuteListener with a warning(ExecuteContext) implementation.
default void	outEnd(ExecuteContext ctx)	Called after fetching out parameter values from a CallableStatement.
default void	outStart(ExecuteContext ctx)	Called before fetching out parameter values from a CallableStatement.
default void	prepareEnd(ExecuteContext ctx)	Called after preparing / creating the SQL statement.
default void	prepareStart(ExecuteContext ctx)	Called before preparing / creating the SQL statement.
default void	recordEnd(ExecuteContext ctx)	Called after fetching a record from a ResultSet.
default void	recordStart(ExecuteContext ctx)	Called before fetching a record from a ResultSet.
default void	renderEnd(ExecuteContext ctx)	Called after rendering SQL from a QueryPart.
default void	renderStart(ExecuteContext ctx)	Called before rendering SQL from a QueryPart.
default void	resultEnd(ExecuteContext ctx)	Called after fetching a set of records from a ResultSet.
default void	resultStart(ExecuteContext ctx)	Called before fetching a set of records from a ResultSet.
default void	start(ExecuteContext ctx)	Called to initialise an ExecuteListener.
default void	warning(ExecuteContext ctx)	Called in the event of a warning at any moment of the execution lifecycle.

Method Details

start

default void start(ExecuteContext ctx)

Called to initialise an ExecuteListener.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise

Overridable attributes in ExecuteContext:

• ExecuteContext.connectionProvider(ConnectionProvider): The connection provider used for execution. This may be particularly interesting if a Query was de-serialised and is thus lacking the underlying connection

Parameters:

ctx - The context containing information about the execution.

renderStart

default void renderStart(ExecuteContext ctx)

Called before rendering SQL from a QueryPart.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise

Parameters:

ctx - The context containing information about the execution.

renderEnd

default void renderEnd(ExecuteContext ctx)

Called after rendering SQL from a QueryPart.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..

Overridable attributes in ExecuteContext:

• ExecuteContext.sql(String): The rendered SQL statement that is about to be executed. You can modify this statement freely.

Parameters:

ctx - The context containing information about the execution.

prepareStart

default void prepareStart(ExecuteContext ctx)

Called before preparing / creating the SQL statement.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..

Overridable attributes in ExecuteContext:

• ExecuteContext.sql(String): The rendered SQL statement that is about to be executed. You can modify this statement freely.
• ExecuteContext.statement(): The PreparedStatement about to be executed. At this stage, no such statement is available yet, but if provided, the execution lifecycle will skip preparing a statement. This can be used e.g. to implement a transaction-bound prepared statement cache.

  A custom PreparedStatement needs to take into account Settings.getStatementType(), and adefault void bind variable markers for StatementType.STATIC_STATEMENT.

  Flags such as Query.queryTimeout(int), Query.poolable(boolean), ResultQuery.maxRows(int), which correspond to mutable flags on a PreparedStatement, are set by jOOQ even if a listener provides the statement.

  Flags such as ResultQuery.resultSetConcurrency(int), ResultQuery.resultSetHoldability(int), ResultQuery.resultSetType(int), which correspond to immutable flags that are set on the statement at statement creation are not set on a statement provided by a listener.

Parameters:

ctx - The context containing information about the execution.

prepareEnd

default void prepareEnd(ExecuteContext ctx)

Called after preparing / creating the SQL statement.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..
• ExecuteContext.statement(): The PreparedStatement that is about to be executed, or null if no statement is known to jOOQ. This can be any of the following:
  
  
  • A java.sql.PreparedStatement from your JDBC driver when a jOOQ Query is being executed as StatementType.PREPARED_STATEMENT
  • A java.sql.Statement from your JDBC driver wrapped in a java.sql.PreparedStatement when your jOOQ Query is being executed as StatementType.STATIC_STATEMENT
  • A java.sql.CallableStatement when you are executing a jOOQ Routine

Overridable attributes in ExecuteContext:

• ExecuteContext.statement(PreparedStatement): The Statement, PreparedStatement, or CallableStatement that is about to be executed. You can modify this statement freely, or wrap ExecuteContext.statement() with your enriched statement wrapper

Parameters:

ctx - The context containing information about the execution.

bindStart

default void bindStart(ExecuteContext ctx)

Called before bind variables to the PreparedStatement.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..
• ExecuteContext.statement(): The PreparedStatement that is about to be executed, or null if no statement is known to jOOQ. This can be any of the following:
  
  
  • A java.sql.PreparedStatement from your JDBC driver when a jOOQ Query is being executed as StatementType.PREPARED_STATEMENT
  • A java.sql.CallableStatement when you are executing a jOOQ Routine

Overridable attributes in ExecuteContext:

• ExecuteContext.statement(PreparedStatement): The PreparedStatement, or CallableStatement that is about to be executed. You can modify this statement freely, or wrap ExecuteContext.statement() with your enriched statement wrapper

Note that this method is not called when executing queries of type StatementType.STATIC_STATEMENT

Parameters:

ctx - The context containing information about the execution.

bindEnd

default void bindEnd(ExecuteContext ctx)

Called after bind variables to the PreparedStatement.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..
• ExecuteContext.statement(): The PreparedStatement that is about to be executed, or null if no statement is known to jOOQ. This can be any of the following:
  
  
  • A java.sql.PreparedStatement from your JDBC driver when a jOOQ Query is being executed as StatementType.PREPARED_STATEMENT
  • A java.sql.CallableStatement when you are executing a jOOQ Routine

Overridable attributes in ExecuteContext:

• ExecuteContext.statement(PreparedStatement): The Statement, PreparedStatement, or CallableStatement that is about to be executed. You can modify this statement freely, or wrap ExecuteContext.statement() with your enriched statement wrapper

Note that this method is not called when executing queries of type StatementType.STATIC_STATEMENT

Parameters:

ctx - The context containing information about the execution.

executeStart

default void executeStart(ExecuteContext ctx)

Called before executing a statement.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..
• ExecuteContext.statement(): The PreparedStatement that is about to be executed, or null if no statement is known to jOOQ. This can be any of the following:
  
  
  • A java.sql.PreparedStatement from your JDBC driver when a jOOQ Query is being executed as StatementType.PREPARED_STATEMENT
  • A java.sql.Statement from your JDBC driver wrapped in a java.sql.PreparedStatement when your jOOQ Query is being executed as StatementType.STATIC_STATEMENT
  • A java.sql.CallableStatement when you are executing a jOOQ Routine

Overridable attributes in ExecuteContext:

• ExecuteContext.statement(PreparedStatement): The Statement, PreparedStatement, or CallableStatement that is about to be executed. You can modify this statement freely, or wrap ExecuteContext.statement() with your enriched statement wrapper

Other attributes in ExecuteContext, affected by this lifecycle phase:

• ExecuteContext.statementExecutionCount() is incremented.

Parameters:

ctx - The context containing information about the execution.

executeEnd

default void executeEnd(ExecuteContext ctx)

Called after executing a statement.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..
• ExecuteContext.statement(): The PreparedStatement that is about to be executed, or null if no statement is known to jOOQ. This can be any of the following:
  
  
  • A java.sql.PreparedStatement from your JDBC driver when a jOOQ Query is being executed as StatementType.PREPARED_STATEMENT
  • A java.sql.Statement from your JDBC driver wrapped in a java.sql.PreparedStatement when your jOOQ Query is being executed as StatementType.STATIC_STATEMENT
  • A java.sql.CallableStatement when you are executing a jOOQ Routine
• ExecuteContext.resultSet(): The ResultSet that is about to be fetched or null, if the Query returns no result set, or if a Routine is being executed.
• ExecuteContext.rows(): The number of affected rows if applicable. In case a ResultSet is fetched, this number is only available at the fetchEnd(ExecuteContext) event.
• ExecuteContext.serverOutput(): The server output if available. This may be fetched when Settings.getFetchServerOutputSize() > 0

Overridable attributes in ExecuteContext:

• ExecuteContext.resultSet(ResultSet): The ResultSet that is about to be fetched. You can modify this result set freely, or wrap ExecuteContext.resultSet() with your enriched result set wrapper

Parameters:

ctx - The context containing information about the execution.

outStart

default void outStart(ExecuteContext ctx)

Called before fetching out parameter values from a CallableStatement.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..
• ExecuteContext.statement(): The PreparedStatement that is about to be executed, or null if no statement is known to jOOQ. This can be any of the following:
  
  
  • A java.sql.CallableStatement when you are executing a jOOQ Routine
• ExecuteContext.sqlWarning(): The SQLWarning that was emitted by the database or null if no warning was emitted.

Note that this method is called only when executing standalone routine calls.

Parameters:

ctx - The context containing information about the execution.

outEnd

default void outEnd(ExecuteContext ctx)

Called after fetching out parameter values from a CallableStatement.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..
• ExecuteContext.statement(): The PreparedStatement that is about to be executed, or null if no statement is known to jOOQ. This can be any of the following:
  
  
  • A java.sql.CallableStatement when you are executing a jOOQ Routine
• ExecuteContext.sqlWarning(): The SQLWarning that was emitted by the database or null if no warning was emitted.

Note that this method is called only when executing standalone routine calls.

Parameters:

ctx - The context containing information about the execution.

fetchStart

default void fetchStart(ExecuteContext ctx)

Called before fetching data from a ResultSet into a Result type.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..
• ExecuteContext.statement(): The PreparedStatement that is about to be executed, or null if no statement is known to jOOQ. This can be any of the following:
  
  
  • A java.sql.PreparedStatement from your JDBC driver when a jOOQ Query is being executed as StatementType.PREPARED_STATEMENT
  • A java.sql.Statement from your JDBC driver wrapped in a java.sql.PreparedStatement when your jOOQ Query is being executed as StatementType.STATIC_STATEMENT
  • A java.sql.CallableStatement when you are executing a jOOQ Routine
• ExecuteContext.resultSet(): The ResultSet that is about to be fetched.
• ExecuteContext.sqlWarning(): The SQLWarning that was emitted by the database or null if no warning was emitted.

Overridable attributes in ExecuteContext:

• ExecuteContext.resultSet(ResultSet): The ResultSet that is about to be fetched. You can modify this result set freely, or wrap ExecuteContext.resultSet() with your enriched result set wrapper

In case of multiple ResultSets with ResultQuery.fetchMany(), this is called several times, once per ResultSet

Note that this method is not called when executing queries that do not return a result, or when executing routines.

Parameters:

ctx - The context containing information about the execution.

resultStart

default void resultStart(ExecuteContext ctx)

Called before fetching a set of records from a ResultSet.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..
• ExecuteContext.statement(): The PreparedStatement that is about to be executed, or null if no statement is known to jOOQ. This can be any of the following:
  
  
  • A java.sql.PreparedStatement from your JDBC driver when a jOOQ Query is being executed as StatementType.PREPARED_STATEMENT
  • A java.sql.Statement from your JDBC driver wrapped in a java.sql.PreparedStatement when your jOOQ Query is being executed as StatementType.STATIC_STATEMENT
  • A java.sql.CallableStatement when you are executing a jOOQ Routine
• ExecuteContext.resultSet(): The ResultSet that is about to be fetched.
• ExecuteContext.result(): The set of records that are about to be fetched.
• ExecuteContext.resultLevel(): The result nesting level, in case the upcoming ExecuteContext.result() is a DSL#multiset(Select) or other type of nested result.
• ExecuteContext.sqlWarning(): The SQLWarning that was emitted by the database or null if no warning was emitted.

Executions without Result

Not all types of execution produce results of type Result. For example, these do not:

• ResultQuery.iterator()
• ResultQuery.stream()
• ResultQuery.collect(Collector) (including all Collector based fetches, such as e.g. a ResultQuery.fetchMap(Field, Field), ResultQuery.fetchGroups(Field, Field), ResultQuery.fetchSet(Field), and all the overloads)
• Publisher.subscribe(Subscriber)

In any of these cases, no resultStart(ExecuteContext) event is fired.

Note that this method is also not called when executing queries that do not return a result, or when executing routines. This is also not called when fetching single records, with Cursor.fetchNext() for instance.

Parameters:

ctx - The context containing information about the execution.

recordStart

default void recordStart(ExecuteContext ctx)

Called before fetching a record from a ResultSet.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..
• ExecuteContext.statement(): The PreparedStatement that is about to be executed, or null if no statement is known to jOOQ. This can be any of the following:
  
  
  • A java.sql.PreparedStatement from your JDBC driver when a jOOQ Query is being executed as StatementType.PREPARED_STATEMENT
  • A java.sql.Statement from your JDBC driver wrapped in a java.sql.PreparedStatement when your jOOQ Query is being executed as StatementType.STATIC_STATEMENT
  • A java.sql.CallableStatement when you are executing a jOOQ Routine
• ExecuteContext.resultSet(): The ResultSet that is about to be fetched.
• ExecuteContext.record(): The Record that is about to be fetched.
• ExecuteContext.recordLevel(): The record nesting level, in case the upcoming ExecuteContext.record() is a Row or other type of nested record. The level is also increased if a record is contained in a nested ExecuteContext.result().
• ExecuteContext.sqlWarning(): The SQLWarning that was emitted by the database or null if no warning was emitted.

Note that this method is not called when executing queries that do not return a result, or when executing routines.

Parameters:

ctx - The context containing information about the execution.

recordEnd

default void recordEnd(ExecuteContext ctx)

Called after fetching a record from a ResultSet.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..
• ExecuteContext.statement(): The PreparedStatement that is about to be executed, or null if no statement is known to jOOQ. This can be any of the following:
  
  
  • A java.sql.PreparedStatement from your JDBC driver when a jOOQ Query is being executed as StatementType.PREPARED_STATEMENT
  • A java.sql.Statement from your JDBC driver wrapped in a java.sql.PreparedStatement when your jOOQ Query is being executed as StatementType.STATIC_STATEMENT
  • A java.sql.CallableStatement when you are executing a jOOQ Routine
• ExecuteContext.resultSet(): The ResultSet that is about to be fetched.
• ExecuteContext.record(): The last Record that was fetched.
• ExecuteContext.recordLevel(): The record nesting level, in case the upcoming ExecuteContext.record() is a Row or other type of nested record. The level is also increased if a record is contained in a nested ExecuteContext.result().
• ExecuteContext.sqlWarning(): The SQLWarning that was emitted by the database or null if no warning was emitted.

Note that this method is not called when executing queries that do not return a result, or when executing routines.

Parameters:

ctx - The context containing information about the execution.

resultEnd

default void resultEnd(ExecuteContext ctx)

Called after fetching a set of records from a ResultSet.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..
• ExecuteContext.statement(): The PreparedStatement that is about to be executed, or null if no statement is known to jOOQ. This can be any of the following:
  
  
  • A java.sql.PreparedStatement from your JDBC driver when a jOOQ Query is being executed as StatementType.PREPARED_STATEMENT
  • A java.sql.Statement from your JDBC driver wrapped in a java.sql.PreparedStatement when your jOOQ Query is being executed as StatementType.STATIC_STATEMENT
  • A java.sql.CallableStatement when you are executing a jOOQ Routine
• ExecuteContext.resultSet(): The ResultSet that is about to be fetched.
• ExecuteContext.record(): The last Record that was fetched.
• ExecuteContext.result(): The set of records that were fetched.
• ExecuteContext.resultLevel(): The result nesting level, in case the upcoming ExecuteContext.result() is a DSL#multiset(Select) or other type of nested result.
• ExecuteContext.sqlWarning(): The SQLWarning that was emitted by the database or null if no warning was emitted.

Executions without Result

Not all types of execution produce results of type Result. For example, these do not:

• ResultQuery.iterator()
• ResultQuery.stream()
• ResultQuery.collect(Collector) (including all Collector based fetches, such as e.g. a ResultQuery.fetchMap(Field, Field), ResultQuery.fetchGroups(Field, Field), ResultQuery.fetchSet(Field), and all the overloads)
• Publisher.subscribe(Subscriber)

In any of these cases, no resultEnd(ExecuteContext) event is fired.

Note that this method is also not called when executing queries that do not return a result, or when executing routines. This is also not called when fetching single records, with Cursor.fetchNext() for instance.

Parameters:

ctx - The context containing information about the execution.

fetchEnd

default void fetchEnd(ExecuteContext ctx)

Called after fetching data from a ResultSet.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..
• ExecuteContext.statement(): The PreparedStatement that is about to be executed, or null if no statement is known to jOOQ. This can be any of the following:
  
  
  • A java.sql.PreparedStatement from your JDBC driver when a jOOQ Query is being executed as StatementType.PREPARED_STATEMENT
  • A java.sql.Statement from your JDBC driver wrapped in a java.sql.PreparedStatement when your jOOQ Query is being executed as StatementType.STATIC_STATEMENT
  • A java.sql.CallableStatement when you are executing a jOOQ Routine
  Note that the Statement is already closed!
• ExecuteContext.resultSet(): The ResultSet that was fetched. Note that the ResultSet is already closed!
• ExecuteContext.rows(): The number of affected rows if applicable.
• ExecuteContext.serverOutput(): The server output if available. This may be fetched when Settings.getFetchServerOutputSize() > 0
• ExecuteContext.record(): The last Record that was fetched.
• ExecuteContext.result(): The last set of records that were fetched.
• ExecuteContext.sqlWarning(): The SQLWarning that was emitted by the database or null if no warning was emitted.

In case of multiple ResultSets with ResultQuery.fetchMany(), this is called several times, once per ResultSet

Note that this method is not called when executing queries that do not return a result, or when executing routines.

Parameters:

ctx - The context containing information about the execution.

end

default void end(ExecuteContext ctx)

Called at the end of the execution lifecycle.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..
• ExecuteContext.statement(): The PreparedStatement that is about to be executed, or null if no statement is known to jOOQ. This can be any of the following:
  
  
  • A java.sql.PreparedStatement from your JDBC driver when a jOOQ Query is being executed as StatementType.PREPARED_STATEMENT
  • A java.sql.Statement from your JDBC driver wrapped in a java.sql.PreparedStatement when your jOOQ Query is being executed as StatementType.STATIC_STATEMENT
  • A java.sql.CallableStatement when you are executing a jOOQ Routine
  Note that the Statement is already closed!
• ExecuteContext.resultSet(): The ResultSet that was fetched or null, if no result set was fetched. Note that the ResultSet may already be closed!
• ExecuteContext.rows(): The number of affected rows if applicable.
• ExecuteContext.serverOutput(): The server output if available. This may be fetched when Settings.getFetchServerOutputSize() > 0
• ExecuteContext.record(): The last Record that was fetched or null if no records were fetched.
• ExecuteContext.result(): The last set of records that were fetched or null if no records were fetched.
• ExecuteContext.sqlWarning(): The SQLWarning that was emitted by the database or null if no warning was emitted.

Parameters:

ctx - The context containing information about the execution.

exception

default void exception(ExecuteContext ctx)

Called in the event of an exception at any moment of the execution lifecycle.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..
• ExecuteContext.statement(): The PreparedStatement that is about to be executed, or null if no statement is known to jOOQ. This can be any of the following:
  
  
  • A java.sql.PreparedStatement from your JDBC driver when a jOOQ Query is being executed as StatementType.PREPARED_STATEMENT
  • A java.sql.Statement from your JDBC driver wrapped in a java.sql.PreparedStatement when your jOOQ Query is being executed as StatementType.STATIC_STATEMENT
  • A java.sql.CallableStatement when you are executing a jOOQ Routine
  Note that the Statement may be closed!
• ExecuteContext.resultSet(): The ResultSet that was fetched or null, if no result set was fetched. Note that the ResultSet may already be closed!
• ExecuteContext.rows(): The number of affected rows if applicable.
• ExecuteContext.serverOutput(): The server output if available. This may be fetched when Settings.getFetchServerOutputSize() > 0
• ExecuteContext.record(): The last Record that was fetched or null if no records were fetched.
• ExecuteContext.result(): The last set of records that were fetched or null if no records were fetched.
• ExecuteContext.exception(): The RuntimeException that is about to be thrown
• ExecuteContext.sqlException(): The SQLException that was thrown by the database

Parameters:

ctx - The context containing information about the execution.

warning

default void warning(ExecuteContext ctx)

Called in the event of a warning at any moment of the execution lifecycle.

Available attributes from ExecuteContext:

• ExecuteContext.connection(): The connection used for execution
• Scope.configuration(): The execution configuration
• ExecuteContext.query(): The Query object, if a jOOQ query is being executed or null otherwise
• ExecuteContext.routine(): The Routine object, if a jOOQ routine is being executed or null otherwise
• ExecuteContext.sql(): The rendered SQL statement that is about to be executed, or null if the SQL statement is unknown..
• ExecuteContext.statement(): The PreparedStatement that is about to be executed, or null if no statement is known to jOOQ. This can be any of the following:
  
  
  • A java.sql.PreparedStatement from your JDBC driver when a jOOQ Query is being executed as StatementType.PREPARED_STATEMENT
  • A java.sql.Statement from your JDBC driver wrapped in a java.sql.PreparedStatement when your jOOQ Query is being executed as StatementType.STATIC_STATEMENT
  • A java.sql.CallableStatement when you are executing a jOOQ Routine
  Note that the Statement may be closed!
• ExecuteContext.resultSet(): The ResultSet that was fetched or null, if no result set was fetched. Note that the ResultSet may already be closed!
• ExecuteContext.rows(): The number of affected rows if applicable.
• ExecuteContext.serverOutput(): The server output if available. This may be fetched when Settings.getFetchServerOutputSize() > 0
• ExecuteContext.record(): The last Record that was fetched or null if no records were fetched.
• ExecuteContext.result(): The last set of records that were fetched or null if no records were fetched.
• ExecuteContext.sqlWarning(): The SQLWarning that was emitted by the database
• ExecuteContext.exception(): The RuntimeException that is about to be thrown or null, if no exception is being thrown.
• ExecuteContext.sqlException(): The SQLException that was thrown by the database or null, if no exception is being thrown.

This method is only invoked if a warning appears. Note that fetching of warnings can be disabled using Settings.isFetchWarnings()

Parameters:

ctx - The context containing information about the execution.

onStart

static CallbackExecuteListener onStart(ExecuteEventHandler handler)

Create an ExecuteListener with a start(ExecuteContext) implementation.

onEnd

static CallbackExecuteListener onEnd(ExecuteEventHandler handler)

Create an ExecuteListener with a end(ExecuteContext) implementation.

onRenderStart

static CallbackExecuteListener onRenderStart(ExecuteEventHandler handler)

Create an ExecuteListener with a renderStart(ExecuteContext) implementation.

onRenderEnd

static CallbackExecuteListener onRenderEnd(ExecuteEventHandler handler)

Create an ExecuteListener with a renderEnd(ExecuteContext) implementation.

onPrepareStart

static CallbackExecuteListener onPrepareStart(ExecuteEventHandler handler)

Create an ExecuteListener with a prepareStart(ExecuteContext) implementation.

onPrepareEnd

static CallbackExecuteListener onPrepareEnd(ExecuteEventHandler handler)

Create an ExecuteListener with a prepareEnd(ExecuteContext) implementation.

onBindStart

static CallbackExecuteListener onBindStart(ExecuteEventHandler handler)

Create an ExecuteListener with a bindStart(ExecuteContext) implementation.

onBindEnd

static CallbackExecuteListener onBindEnd(ExecuteEventHandler handler)

Create an ExecuteListener with a bindEnd(ExecuteContext) implementation.

onExecuteStart

static CallbackExecuteListener onExecuteStart(ExecuteEventHandler handler)

Create an ExecuteListener with a executeStart(ExecuteContext) implementation.

onExecuteEnd

static CallbackExecuteListener onExecuteEnd(ExecuteEventHandler handler)

Create an ExecuteListener with a executeEnd(ExecuteContext) implementation.

onOutStart

static CallbackExecuteListener onOutStart(ExecuteEventHandler handler)

Create an ExecuteListener with a outStart(ExecuteContext) implementation.

onOutEnd

static CallbackExecuteListener onOutEnd(ExecuteEventHandler handler)

Create an ExecuteListener with a outEnd(ExecuteContext) implementation.

onFetchStart

static CallbackExecuteListener onFetchStart(ExecuteEventHandler handler)

Create an ExecuteListener with a fetchStart(ExecuteContext) implementation.

onFetchEnd

static CallbackExecuteListener onFetchEnd(ExecuteEventHandler handler)

Create an ExecuteListener with a fetchEnd(ExecuteContext) implementation.

onResultStart

static CallbackExecuteListener onResultStart(ExecuteEventHandler handler)

Create an ExecuteListener with a resultStart(ExecuteContext) implementation.

onResultEnd

static CallbackExecuteListener onResultEnd(ExecuteEventHandler handler)

Create an ExecuteListener with a resultEnd(ExecuteContext) implementation.

onRecordStart

static CallbackExecuteListener onRecordStart(ExecuteEventHandler handler)

Create an ExecuteListener with a recordStart(ExecuteContext) implementation.

onRecordEnd

static CallbackExecuteListener onRecordEnd(ExecuteEventHandler handler)

Create an ExecuteListener with a recordEnd(ExecuteContext) implementation.

onException

static CallbackExecuteListener onException(ExecuteEventHandler handler)

Create an ExecuteListener with a exception(ExecuteContext) implementation.

onWarning

static CallbackExecuteListener onWarning(ExecuteEventHandler handler)

Create an ExecuteListener with a warning(ExecuteContext) implementation.