http://www.jooq.org/jooq: jOOQ effectively combines complex SQL, typesafety, source code generation, active records, stored procedures, advanced data types, and Java in a fluent, intuitive DSL. 
/*
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *  http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * Other licenses:
 * -----------------------------------------------------------------------------
 * Commercial licenses for this work are available. These replace the above
 * ASL 2.0 and offer limited warranties, support, maintenance, and commercial
 * database integrations.
 *
 * For more information, please visit: http://www.jooq.org/licenses
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */
package org.jooq;

import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.SQLWarning;
import java.sql.Statement;

import org.jooq.conf.Settings;
import org.jooq.conf.StatementType;
import org.jooq.exception.DataAccessException;

import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;


A context object for Query execution passed to registered ExecuteListener's. 
Author:Lukas Eder
See Also:
/**
 * A context object for {@link Query} execution passed to registered
 * {@link ExecuteListener}'s.
 *
 * @author Lukas Eder
 * @see ExecuteListener
 */
public interface ExecuteContext extends Scope {

    
The connection to be used in this execute context.

 This returns a proxy to the Configuration.connectionProvider() 's supplied connection. This proxy takes care of two things: 


/**
     * The connection to be used in this execute context.
     * <p>
     * This returns a proxy to the {@link Configuration#connectionProvider()}
     * 's supplied connection. This proxy takes care of two things:
     * <ul>
     * <li>It takes care of properly implementing
     * {@link Settings#getStatementType()}</li>
     * <li>It takes care of properly returning a connection to
     * {@link ConnectionProvider#release(Connection)}, once jOOQ can release the
     * connection</li>
     * </ul>
     */
    Connection connection();

    
The type of database interaction that is being executed.

See Also:
  • ExecuteType
/**
     * The type of database interaction that is being executed.
     *
     * @see ExecuteType
     */
    ExecuteType type();

    
The jOOQ Query that is being executed or null if the
query is unknown, if it is a batch query, or if there was no jOOQ
Query.

See Also:
/**
     * The jOOQ {@link Query} that is being executed or <code>null</code> if the
     * query is unknown, if it is a batch query, or if there was no jOOQ
     * <code>Query</code>.
     *
     * @see #routine()
     * @see #batchQueries()
     */
    @Nullable
    Query query();

    
The jOOQ Query objects that are being executed in batch mode, or empty if the query is unknown or if there was no jOOQ Query.


If a single Query is executed in non-batch mode, this will
return an array of length 1, containing that
Query

See Also:
Returns:The executed Query object(s). This is never
        null
/**
     * The jOOQ {@link Query} objects that are being executed in batch mode, or
     * empty if the query is unknown or if there was no jOOQ <code>Query</code>.
     * <p>
     * If a single <code>Query</code> is executed in non-batch mode, this will
     * return an array of length <code>1</code>, containing that
     * <code>Query</code>
     *
     * @see #query()
     * @see #routine()
     * @return The executed <code>Query</code> object(s). This is never
     *         <code>null</code>
     */
    @NotNull
    Query[] batchQueries();

    
The jOOQ Routine that is being executed or null if
the query is unknown or if there was no jOOQ Routine.

See Also:
/**
     * The jOOQ {@link Routine} that is being executed or <code>null</code> if
     * the query is unknown or if there was no jOOQ <code>Routine</code>.
     *
     * @see #routine()
     */
    @Nullable
    Routine<?> routine();

    
The SQL that is being executed or null if the SQL statement
is unknown or if there was no SQL statement.

/**
     * The SQL that is being executed or <code>null</code> if the SQL statement
     * is unknown or if there was no SQL statement.
     */
    @Nullable
    String sql();

    
Override the SQL statement that is being executed.


This may have no effect, if called at the wrong moment.

See Also:
/**
     * Override the SQL statement that is being executed.
     * <p>
     * This may have no effect, if called at the wrong moment.
     *
     * @see ExecuteListener#renderEnd(ExecuteContext)
     * @see ExecuteListener#prepareStart(ExecuteContext)
     */
    void sql(String sql);

    
The generated SQL statements that are being executed in batch mode, or
empty if the query is unknown or if there was no SQL statement.


If a single Query is executed in non-batch mode, this will
return an array of length 1, containing that
Query

See Also:
Returns:The generated SQL statement(s). This is never null
/**
     * The generated SQL statements that are being executed in batch mode, or
     * empty if the query is unknown or if there was no SQL statement.
     * <p>
     * If a single <code>Query</code> is executed in non-batch mode, this will
     * return an array of length <code>1</code>, containing that
     * <code>Query</code>
     *
     * @see #query()
     * @see #routine()
     * @return The generated SQL statement(s). This is never <code>null</code>
     */
    @NotNull
    String[] batchSQL();

    
Override the Connection that is being used for execution. 

This may have no effect, if called at the wrong moment.

See Also:
/**
     * Override the {@link Connection} that is being used for execution.
     * <p>
     * This may have no effect, if called at the wrong moment.
     *
     * @see ExecuteListener#start(ExecuteContext)
     */
    void connectionProvider(ConnectionProvider connectionProvider);

    
The PreparedStatement that is being executed or null
if the statement is unknown or if there was no statement.


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
    • 



/**
     * The {@link PreparedStatement} that is being executed or <code>null</code>
     * if the statement is unknown or if there was no statement.
     * <p>
     * This can be any of the following: <br/>
     * <br/>
     * <ul>
     * <li>A <code>java.sql.PreparedStatement</code> from your JDBC driver when
     * a jOOQ <code>Query</code> is being executed as
     * {@link StatementType#PREPARED_STATEMENT}</li>
     * <li>A <code>java.sql.Statement</code> from your JDBC driver wrapped in a
     * <code>java.sql.PreparedStatement</code> when your jOOQ <code>Query</code>
     * is being executed as {@link StatementType#STATIC_STATEMENT}</li>
     * <li>A <code>java.sql.CallableStatement</code> when you are executing a
     * jOOQ <code>Routine</code></li>
     * </ul>
     */
    @Nullable
    PreparedStatement statement();

    
Override the PreparedStatement that is being executed. 

This may have no effect, if called at the wrong moment.

See Also:
/**
     * Override the {@link PreparedStatement} that is being executed.
     * <p>
     * This may have no effect, if called at the wrong moment.
     *
     * @see ExecuteListener#prepareEnd(ExecuteContext)
     * @see ExecuteListener#bindStart(ExecuteContext)
     */
    void statement(PreparedStatement statement);

    
The number of times this particular statement has been executed.

 Statements that are prepared by jOOQ can be executed multiple times without being closed if Query.keepStatement(boolean) is activated. 
 This value will increment as soon as the statement is about to be executed (at the ExecuteListener.executeStart(ExecuteContext) event). 
See Also:
/**
     * The number of times this particular statement has been executed.
     * <p>
     * Statements that are prepared by jOOQ can be executed multiple times
     * without being closed if {@link Query#keepStatement(boolean)} is
     * activated.
     * <p>
     * This value will increment as soon as the statement is about to be
     * executed (at the {@link ExecuteListener#executeStart(ExecuteContext)}
     * event).
     *
     * @see ExecuteListener#executeStart(ExecuteContext)
     */
    int statementExecutionCount();

    
The ResultSet that is being fetched or null if the
result set is unknown or if no result set is being fetched.

/**
     * The {@link ResultSet} that is being fetched or <code>null</code> if the
     * result set is unknown or if no result set is being fetched.
     */
    @Nullable
    ResultSet resultSet();

    
Override the ResultSet that is being fetched. 

This may have no effect, if called at the wrong moment.

See Also:
/**
     * Override the {@link ResultSet} that is being fetched.
     * <p>
     * This may have no effect, if called at the wrong moment.
     *
     * @see ExecuteListener#executeEnd(ExecuteContext)
     * @see ExecuteListener#fetchStart(ExecuteContext)
     */
    void resultSet(ResultSet resultSet);

    
The last record that was fetched from the result set, or
null if no record has been fetched.

/**
     * The last record that was fetched from the result set, or
     * <code>null</code> if no record has been fetched.
     */
    @Nullable
    Record record();

    
Calling this has no effect. It is used by jOOQ internally.

/**
     * Calling this has no effect. It is used by jOOQ internally.
     */
    void record(Record record);

    
The number of rows that were affected by the last statement.


This returns -1:



/**
     * The number of rows that were affected by the last statement.
     * <p>
     * This returns <code>-1</code>:
     * <ul>
     * <li>if the number of affected rows is not yet available (e.g. prior to
     * the {@link ExecuteListener#executeEnd(ExecuteContext)} event).</li>
     * <li>if affected rows are not applicable for the given statement
     * (statements that do not produce a JDBC
     * {@link Statement#getUpdateCount()}.</li>
     * </ul>
     */
    int rows();

    
Calling this has no effect. It is used by jOOQ internally.

/**
     * Calling this has no effect. It is used by jOOQ internally.
     */
    void rows(int rows);

    
The number of rows that were affected by the last statement executed in
batch mode.


If a single Query is executed in non-batch mode, this will
return an array of length 1, containing rows() 

This returns -1 values if the number of affected rows is not
yet available, or if affected rows are not applicable for a given
statement.

See Also:
Returns:The affected rows. This is never null
/**
     * The number of rows that were affected by the last statement executed in
     * batch mode.
     * <p>
     * If a single <code>Query</code> is executed in non-batch mode, this will
     * return an array of length <code>1</code>, containing {@link #rows()}
     * <p>
     * This returns <code>-1</code> values if the number of affected rows is not
     * yet available, or if affected rows are not applicable for a given
     * statement.
     *
     * @see #rows()
     * @return The affected rows. This is never <code>null</code>
     */
    @NotNull
    int[] batchRows();

    
The last result that was fetched from the result set, or
null if no result has been fetched.

/**
     * The last result that was fetched from the result set, or
     * <code>null</code> if no result has been fetched.
     */
    @Nullable
    Result<?> result();

    
Calling this has no effect. It is used by jOOQ internally.

/**
     * Calling this has no effect. It is used by jOOQ internally.
     */
    void result(Result<?> result);

    
The RuntimeException being thrown. 
/**
     * The {@link RuntimeException} being thrown.
     */
    @Nullable
    RuntimeException exception();

    
Override the RuntimeException being thrown. 

This may have no effect, if called at the wrong moment.


If null is being passed, jOOQ will internally translate the "unavailable" exception to an unspecified DataAccessException. 
/**
     * Override the {@link RuntimeException} being thrown.
     * <p>
     * This may have no effect, if called at the wrong moment.
     * <p>
     * If <code>null</code> is being passed, jOOQ will internally translate the
     * "unavailable" exception to an unspecified {@link DataAccessException}.
     */
    void exception(RuntimeException e);

    
The SQLException that was thrown by the database. 
/**
     * The {@link SQLException} that was thrown by the database.
     */
    @Nullable
    SQLException sqlException();

    
Override the SQLException being thrown. 

Any SQLException will be wrapped by jOOQ using an unchecked DataAccessException. To have jOOQ throw your own custom RuntimeException, use exception(RuntimeException) instead. This may have no effect, if called at the wrong moment. 

If null is being passed, jOOQ will internally translate the "unavailable" exception to an unspecified DataAccessException. 
/**
     * Override the {@link SQLException} being thrown.
     * <p>
     * Any <code>SQLException</code> will be wrapped by jOOQ using an unchecked
     * {@link DataAccessException}. To have jOOQ throw your own custom
     * {@link RuntimeException}, use {@link #exception(RuntimeException)}
     * instead. This may have no effect, if called at the wrong moment.
     * <p>
     * If <code>null</code> is being passed, jOOQ will internally translate the
     * "unavailable" exception to an unspecified {@link DataAccessException}.
     */
    void sqlException(SQLException e);

    
The SQLWarning that was emitted by the database. 
 Note that fetching of warnings can be disabled using Settings.isFetchWarnings(), in case of which this property will be null.

/**
     * The {@link SQLWarning} that was emitted by the database.
     * <p>
     * Note that fetching of warnings can be disabled using
     * {@link Settings#isFetchWarnings()}, in case of which this property will
     * be <code>null</code>.
     */
    @Nullable
    SQLWarning sqlWarning();

    
Override the SQLWarning being emitted. 
/**
     * Override the {@link SQLWarning} being emitted.
     */
    void sqlWarning(SQLWarning e);

    
Any server output collected from this statement when
Settings.getFetchServerOutputSize() > 0.

Returns:The server output. This is never null.
/**
     * Any server output collected from this statement when
     * <code>{@link Settings#getFetchServerOutputSize()} &gt; 0</code>.
     *
     * @return The server output. This is never <code>null</code>.
     */
    @NotNull
    String[] serverOutput();

    
Any server output collected from this statement when
Settings.getFetchServerOutputSize() > 0.

/**
     * Any server output collected from this statement when
     * <code>{@link Settings#getFetchServerOutputSize()} &gt; 0</code>.
     */
    void serverOutput(String[] output);
}