Module org.jooq

Package org.jooq

Interface VisitListener

All Superinterfaces:

EventListener

All Known Implementing Classes:

CallbackVisitListener, DefaultVisitListener

public interface VisitListener
extends EventListener

A listener for QueryPart traversal events.

Users may want to centrally inject custom behaviour when rendering their QueryPart objects or when binding values to PreparedStatement s. This service provider allows to hook in callback method implementations before or after these events:

• The visit of a Clause
• The visit of a QueryPart

The following rules apply to visiting clauses and query parts:

• Clauses may "surround" a query part. See an example below.
• Not every query part is "surrounded" by a clause

An example is given here:

SELECT 1 FROM [A CROSS JOIN B]

The above example will create the following set of events:

 Clause.SELECT
 +-Clause.SELECT_SELECT
 | +-Clause.FIELD
 |   +-val(1)
 +-Clause.SELECT_FROM
   +-Clause.TABLE_JOIN
     +-Clause.TABLE
     | +-table("A")
     +-Clause.TABLE_JOIN_CROSS
       +-Clause.TABLE
         +-table("B")
 

Whatever is not a Clause in the above example is a QueryPart.

A remark about performance

Implementors of this SPI should be wary of performance implications of their implementations. The below methods are called for every AST element of every query, which produces a lot of calls throughout an application. What would otherwise be premature optimisations may have great effect inside the VisitListener. For more details, please refer to this article: https://blog.jooq.org/top-10-easy-performance-optimisations-in- java/.

Author:

Lukas Eder

Method Summary

Modifier and Type	Method	Description
void	clauseEnd(VisitContext context)	Called after leaving a Clause.
void	clauseStart(VisitContext context)	Called before entering a Clause.
static CallbackVisitListener	onClauseEnd(Consumer<? super VisitContext> onClauseEnd)	Create a VisitListener with a onClauseEnd(Consumer) implementation.
static CallbackVisitListener	onClauseStart(Consumer<? super VisitContext> onClauseStart)	Create a VisitListener with a onClauseStart(Consumer) implementation.
static CallbackVisitListener	onVisitEnd(Consumer<? super VisitContext> onVisitEnd)	Create a VisitListener with a onClauseStart(Consumer) implementation.
static CallbackVisitListener	onVisitStart(Consumer<? super VisitContext> onVisitStart)	Create a VisitListener with a onVisitStart(Consumer) implementation.
void	visitEnd(VisitContext context)	Called after visiting a QueryPart.
void	visitStart(VisitContext context)	Called before visiting a QueryPart.

Method Details

clauseStart

void clauseStart(VisitContext context)

Called before entering a Clause.

See Also:

• Context.start(Clause)

clauseEnd

void clauseEnd(VisitContext context)

Called after leaving a Clause.

See Also:

• Context.end(Clause)

visitStart

void visitStart(VisitContext context)

Called before visiting a QueryPart.

Certain VisitListener implementations may chose to replace the QueryPart contained in the argument VisitContext through VisitContext.queryPart(QueryPart). This can be used for many use-cases, for example to add a CHECK OPTION to an Oracle INSERT statement:

 -- Original query
 INSERT INTO book (id, author_id, title)
 VALUES (10, 15, '1984')

 -- Transformed query
 INSERT INTO (
   SELECT * FROM book
   WHERE author_id IN (1, 2, 3)
   WITH CHECK OPTION
 ) (id, author_id, title)
 VALUES (10, 15, '1984')
 

The above SQL transformation allows to prevent inserting new books for authors other than those with author_id IN (1, 2, 3)

See Also:

• Context.visit(QueryPart)

visitEnd

void visitEnd(VisitContext context)

Called after visiting a QueryPart.

See Also:

• Context.visit(QueryPart)

onClauseStart

static CallbackVisitListener onClauseStart(Consumer<? super VisitContext> onClauseStart)

Create a VisitListener with a onClauseStart(Consumer) implementation.

onClauseEnd

static CallbackVisitListener onClauseEnd(Consumer<? super VisitContext> onClauseEnd)

Create a VisitListener with a onClauseEnd(Consumer) implementation.

onVisitStart

static CallbackVisitListener onVisitStart(Consumer<? super VisitContext> onVisitStart)

Create a VisitListener with a onVisitStart(Consumer) implementation.

onVisitEnd

static CallbackVisitListener onVisitEnd(Consumer<? super VisitContext> onVisitEnd)

Create a VisitListener with a onClauseStart(Consumer) implementation.