com.mysql.cj.interceptors

## Interface QueryInterceptor

    public interface QueryInterceptor

Implement this interface to be placed "in between" query execution, so that you can influence it. QueryInterceptors are "chainable" when configured by the user, the results returned by the "current" interceptor will be passed on to the next on in the chain, from left-to-right order, as specified by the user in the driver configuration property "queryInterceptors".

### Method Summary

All Methods Instance Methods Abstract Methods Default Methods
`void` `destroy()` Called by the driver when this extension should release any resources it is holding and cleanup internally before the connection is closed.
`boolean` `executeTopLevelOnly()` Should the driver execute this interceptor only for the "original" top-level query, and not put it in the execution path for queries that may be executed from other interceptors? If an interceptor issues queries using the connection it was created for, and does not return `true` for this method, it must ensure that it does not cause infinite recursion.
`QueryInterceptor` `init(MysqlConnection conn, Properties props, Log log)` Called once per connection that wants to use the interceptor The properties are the same ones passed in in the URL or arguments to Driver.connect() or DriverManager.getConnection().
`default <M extends Message> M` `postProcess(M queryPacket, M originalResponsePacket)` Called after the given query packet has been sent to the server for processing.
`<T extends Resultset> T` `postProcess(Supplier<String> sql, Query interceptedQuery, T originalResultSet, ServerSession serverSession)` Called after the given query has been sent to the server for processing.
`default <M extends Message> M` `preProcess(M queryPacket)` Called before the given query packet is going to be sent to the server for processing.
`<T extends Resultset> T` `preProcess(Supplier<String> sql, Query interceptedQuery)` Called before the given query is going to be sent to the server for processing.

### Method Detail

#### init

    QueryInterceptor init(MysqlConnection conn,
                          Properties props,
                          Log log)

Called once per connection that wants to use the interceptor The properties are the same ones passed in in the URL or arguments to Driver.connect() or DriverManager.getConnection().

Parameters:
  `conn` - the connection for which this interceptor is being created
  `props` - configuration values as passed to the connection. Note that in order to support javax.sql.DataSources, configuration properties specific to an interceptor must be passed via setURL() on the DataSource. QueryInterceptor properties are not exposed via accessor/mutator methods on DataSources.
  `log` - logger
Returns:
  `QueryInterceptor`

#### preProcess

    <T extends Resultset> T preProcess(Supplier<String> sql,
                                       Query interceptedQuery)

Called before the given query is going to be sent to the server for processing. Interceptors are free to return a result set (which must implement the interface `Resultset`), and if so, the server will not execute the query, and the given result set will be returned to the application instead. This method will be called while the connection-level mutex is held, so it will only be called from one thread at a time.

Type Parameters:
  `T` - `Resultset` object
Parameters:
  `sql` - the Supplier for SQL representation of the query
  `interceptedQuery` - the actual `Query` instance being intercepted
Returns:
  a `Resultset` that should be returned to the application instead of results that are created from actual execution of the intercepted query.

#### preProcess

    default <M extends Message> M preProcess(M queryPacket)

Called before the given query packet is going to be sent to the server for processing. Interceptors are free to return a PacketPayload, and if so, the server will not execute the query, and the given PacketPayload will be returned to the application instead. This method will be called while the connection-level mutex is held, so it will only be called from one thread at a time.

Type Parameters:
  `M` - `Message` object
Parameters:
  `queryPacket` - original `Message`
Returns:
  processed `Message`

#### executeTopLevelOnly

    boolean executeTopLevelOnly()

Should the driver execute this interceptor only for the "original" top-level query, and not put it in the execution path for queries that may be executed from other interceptors? If an interceptor issues queries using the connection it was created for, and does not return `true` for this method, it must ensure that it does not cause infinite recursion.

Returns:
  true if the driver should ensure that this interceptor is only executed for the top-level "original" query.

#### destroy

    void destroy()

Called by the driver when this extension should release any resources it is holding and cleanup internally before the connection is closed.

#### postProcess

    <T extends Resultset> T postProcess(Supplier<String> sql,
                                        Query interceptedQuery,
                                        T originalResultSet,
                                        ServerSession serverSession)

Called after the given query has been sent to the server for processing. Interceptors are free to inspect the "original" result set, and if a different result set is returned by the interceptor, it is used in place of the "original" result set. This method will be called while the connection-level mutex is held, so it will only be called from one thread at a time.

Type Parameters:
  `T` - `Resultset` object
Parameters:
  `sql` - the Supplier for SQL representation of the query
  `interceptedQuery` - the actual `Query` instance being intercepted
  `originalResultSet` - a `Resultset` created from query execution
  `serverSession` - `ServerSession` object after the query execution
Returns:
  a `Resultset` that should be returned to the application instead of results that are created from actual execution of the intercepted query.

#### postProcess

    default <M extends Message> M postProcess(M queryPacket,
                                              M originalResponsePacket)

Called after the given query packet has been sent to the server for processing. Interceptors are free to return either a different PacketPayload than the originalResponsePacket or null. This method will be called while the connection-level mutex is held, so it will only be called from one thread at a time.

Type Parameters:
  `M` - `Message` object
Parameters:
  `queryPacket` - query `Message`
  `originalResponsePacket` - response `Message`
Returns:
  `Message`

Copyright © 2016, 2024, Oracle and/or its affiliates.