Module org.jooq
Package org.jooq

Interface DiagnosticsListener

All Known Implementing Classes:
DefaultDiagnosticsListener
public interface DiagnosticsListener
A diagnostics listener.
Author:
Lukas Eder

  • Method Details

    • tooManyRowsFetched

      default void tooManyRowsFetched(DiagnosticsContext ctx)
      The fetched JDBC ResultSet returned more rows than necessary.

      An event indicating that a JDBC ResultSet was fetched with A rows, but only B rows (B < A) were consumed.

      Typically, this problem can be remedied by applying the appropriate LIMIT clause in SQL, or SelectLimitStep.limit(Number) clause in jOOQ.

      Parameters:
      ctx - The context containing information about the diagnostic.

    • tooManyColumnsFetched

      default void tooManyColumnsFetched(DiagnosticsContext ctx)
      The fetched JDBC ResultSet returned more columns than necessary.

      An event indicating that a JDBC ResultSet was fetched with A columns, but only B (B < A) were consumed.

      Typically, this problem can be remedied by not running a SELECT * query when this isn't strictly required.

      Parameters:
      ctx - The context containing information about the diagnostic.

    • unnecessaryWasNullCall

      default void unnecessaryWasNullCall(DiagnosticsContext ctx)
      The fetched JDBC ResultSet returned a value for a column, on which ResultSet.wasNull() was called unnecessarily (more than once, or for a non-primitive type).
      Parameters:
      ctx - The context containing information about the diagnostic.

    • missingWasNullCall

      default void missingWasNullCall(DiagnosticsContext ctx)
      The fetched JDBC ResultSet returned a primitive type value for a column, which could have been null, but ResultSet.wasNull() was not called.
      Parameters:
      ctx - The context containing information about the diagnostic.

    • duplicateStatements

      default void duplicateStatements(DiagnosticsContext ctx)
      The executed JDBC statement has duplicates.

      Many databases maintain an execution plan cache, which remembers execution plans for a given SQL string. These caches often use the verbatim SQL string (or a hash thereof) as a key, meaning that "similar" but not identical statements will produce different keys. This may be desired in rare cases when querying skewed data, as a hack to force the optimiser to calculate a new plan for a given "similar" but not identical query, but mostly, this is not desirable as calculating execution plans can turn out to be expensive.

      Examples of such duplicate statements include:

      Whitespace differences

      
 SELECT * FROM  actor;
 SELECT  * FROM actor;

      Inline bind values

      
 SELECT * FROM actor WHERE id = 1;
 SELECT * FROM actor WHERE id = 2;

      Aliasing and qualification

      
 SELECT a1.* FROM actor a1 WHERE id = ?;
 SELECT * FROM actor a2 WHERE a2.id = ?;

      Examples of identical statements (which are not considered duplicate, but repeatedStatements(DiagnosticsContext), if on the same Connection) are: 

      
 SELECT * FROM actor WHERE id = ?;
 SELECT * FROM actor WHERE id = ?;

      This is a system-wide diagnostic that is not specific to individual Connection instances.

      Parameters:
      ctx - The context containing information about the diagnostic.

    • repeatedStatements

      default void repeatedStatements(DiagnosticsContext ctx)
      The executed JDBC statement is repeated consecutively on the same JDBC Connection.

      This problem goes by many names, the most famous one being the N + 1 problem, when a single (1) query for a parent entity requires many (N) subsequent queries for child entities. This could have been prevented by rewriting the parent query to use a JOIN. If such a rewrite is not possible (or not easy), the subsequent N queries could at least profit (depending on the exact query):

      • From reusing the PreparedStatement
      • From being batched
      • From being re-written as a bulk fetch or write query

      This problem can be aggravated if combined with the duplicateStatements(DiagnosticsContext) problem, in case of which the repeated statements might not be diagnosed as easily.

      Repeated statements may or may not be "identical". In the following example, there are two repeated and identical statements: 

      
 SELECT * FROM actor WHERE id = ?;
 SELECT * FROM actor WHERE id = ?;

      In this example, we have three repeated statements, only some of which are also identical: 

      
 SELECT * FROM actor WHERE id = ?;
 SELECT * FROM actor WHERE id = ?;
 SELECT * FROM actor WHERE id =  ?;

      This is a Connection-specific diagnostic that is reset every time Connection.close() is called.

      Parameters:
      ctx - The context containing information about the diagnostic.

    • trivialCondition

      @Pro default void trivialCondition(DiagnosticsContext ctx)
      A trivial condition was encountered, which can be replaced by a NULL predicate, or even by DSL.trueCondition() or DSL.falseCondition(), but it is more likely just a typo.

      A trivial condition might compare a column to itself, e.g. 

      
 SELECT *
 FROM actor a
 JOIN film_actor fa
 ON a.actor_id = a.actor_id

      The above JOIN predicate is effectively a.actor_id IS NOT NULL, but what the author probably meant was to write a.actor_id = fa.actor_id instead.

      This mistake can often be very subtle, especially when comparing columns of composite constraints. In many cases, it's a bug, and if it isn't there's probably a more straightforward way to declare the condition.

      Parameters:
      ctx - The context containing information about the diagnostic.

    • exception

      default void exception(DiagnosticsContext ctx)
      Something went wrong while diagnosing a SQL query.

      The actual exception will be provided by DiagnosticsContext.exception(). Likely exceptions include:

      Parameters:
      ctx - The context containing information about the diagnostic.