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.

For convenience, consider extending DefaultExecuteListener instead of implementing this interface. This will prevent compilation errors in future versions of jOOQ, when this interface might get new 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