org.jooq.Query Maven / Gradle / Ivy
/*
* 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
* Apache-2.0 license 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.PreparedStatement;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.Executor;
import org.jooq.conf.StatementType;
import org.jooq.exception.DataAccessException;
import org.jooq.exception.DataTypeException;
import org.jooq.impl.DSL;
import org.jetbrains.annotations.Blocking;
import org.jetbrains.annotations.NotNull;
/**
* Any query.
*
* Instances can be created using {@link DSL#query(String)} and overloads,
* or by creating a subtype.
*
* @author Lukas Eder
*/
public interface Query extends Statement, AttachableQueryPart {
/**
* Execute the query, if it has been created with a proper configuration.
*
* @return A result value, depending on the concrete implementation of
* {@link Query}:
*
* - {@link Delete} : the number of deleted records
* - {@link Insert} : the number of inserted records
* - {@link Merge} : the result may have no meaning
* - {@link Select} : the number of resulting records
* - {@link Truncate} : the result may have no meaning
* - {@link Update} : the number of updated records
*
* @throws DataAccessException If anything goes wrong in the database
*/
@Blocking
int execute() throws DataAccessException;
/**
* Execute the query in a new {@link CompletionStage}.
*
* The result is asynchronously completed by a task running in an
* {@link Executor} provided by the underlying
* {@link Configuration#executorProvider()}.
*
* @return A result value, depending on the concrete implementation of
* {@link Query}:
*
* - {@link Delete} : the number of deleted records
* - {@link Insert} : the number of inserted records
* - {@link Merge} : the result may have no meaning
* - {@link Select} : the number of resulting records
* - {@link Truncate} : the result may have no meaning
* - {@link Update} : the number of updated records
*
*/
@NotNull
CompletionStage executeAsync();
/**
* Execute the query in a new {@link CompletionStage} that is asynchronously
* completed by a task running in the given executor.
*
* @return A result value, depending on the concrete implementation of
* {@link Query}:
*
* - {@link Delete} : the number of deleted records
* - {@link Insert} : the number of inserted records
* - {@link Merge} : the result may have no meaning
* - {@link Select} : the number of resulting records
* - {@link Truncate} : the result may have no meaning
* - {@link Update} : the number of updated records
*
*/
@NotNull
CompletionStage executeAsync(Executor executor);
/**
* Whether this query is executable in its current state.
*
* DML queries may be incomplete in structure and thus not executable.
* Calling {@link #execute()} on such queries has no effect, but beware that
* {@link #getSQL()} may not render valid SQL!
*/
boolean isExecutable();
/**
* Bind a new value to a named parameter.
*
* [#1886] If the bind value with name param is inlined (
* {@link Param#isInline()}) or if this query was created with
* {@link StatementType#STATIC_STATEMENT} and there is an underlying
* PreparedStatement kept open because of
* {@link #keepStatement(boolean)}, the underlying
* PreparedStatement will be closed automatically in order for
* new bind values to have an effect.
*
* @param param The named parameter name. If this is a number, then this is
* the same as calling {@link #bind(int, Object)}
* @param value The new bind value.
* @throws IllegalArgumentException if there is no parameter by the given
* parameter name or index.
* @throws DataTypeException if value cannot be converted into
* the parameter's data type
*/
@NotNull
Query bind(String param, Object value) throws IllegalArgumentException, DataTypeException;
/**
* Bind a new value to an indexed parameter.
*
Bind index order
The 1-based parameter index describes a
* parameter in rendering order, not in input order. For example,
* if a query contains a {@link DSL#log(Field, Field)} call, where the first
* argument is the value and the second argument is the
* base, this may produce different dialect specific
* renderings:
*
* - Db2:
ln(value) / ln(base)
* - Oracle:
log(base, value)
* - SQL Server:
log(value, base)
*
*
* Some bind values may even be repeated by a dialect specific emulation,
* leading to duplication and index-shifting.
*
* As such, it is usually better to supply bind values directly with the
* input of an expression, e.g.:
*
* - Directly with the {@link DSL} method, such as
* {@link DSL#log(Field, Field)}, for example.
* - With the plain SQL template constructor, e.g.
* {@link DSL#field(String, Object...)}
* - With the parser method, e.g.
* {@link Parser#parseField(String, Object...)}
*
* Inlined values
*
* [#1886] If the bind value at index is inlined (
* {@link Param#isInline()}) or if this query was created with
* {@link StatementType#STATIC_STATEMENT} and there is an underlying
* PreparedStatement kept open because of
* {@link #keepStatement(boolean)}, the underlying
* PreparedStatement will be closed automatically in order for
* new bind values to have an effect.
*
* @param index The parameter index in rendering order, starting with 1
* @param value The new bind value.
* @throws IllegalArgumentException if there is no parameter by the given
* parameter index.
* @throws DataTypeException if value cannot be converted into
* the parameter's data type
*/
@NotNull
Query bind(int index, Object value) throws IllegalArgumentException, DataTypeException;
// ------------------------------------------------------------------------
// JDBC methods
// ------------------------------------------------------------------------
/**
* Specify whether any JDBC {@link java.sql.Statement} created by this query
* should be {@link java.sql.Statement#setPoolable(boolean)}.
*
* If this method is not called on jOOQ types, then jOOQ will not specify
* the flag on JDBC either, resulting in JDBC's default behaviour.
*
* @see java.sql.Statement#setPoolable(boolean)
*/
@NotNull
Query poolable(boolean poolable);
/**
* Specify the query timeout in number of seconds for the underlying JDBC
* {@link Statement}.
*
* @see java.sql.Statement#setQueryTimeout(int)
*/
@NotNull
Query queryTimeout(int seconds);
/**
* Keep the query's underlying statement open after execution.
*
* This indicates to jOOQ that the query's underlying {@link Statement} or
* {@link PreparedStatement} should be kept open after execution. If it is
* kept open, client code is responsible for properly closing it using
* {@link CloseableQuery#close()}, e.g. via a
* try-with-resources statement.
*
* @param keepStatement Whether to keep the underlying statement open
*/
@NotNull
CloseableQuery keepStatement(boolean keepStatement);
/**
* Cancel the underlying statement.
*
* This cancels the query's underlying {@link Statement} or
* {@link PreparedStatement}. If there is no underlying open and running
* statement, this call is simply ignored.
*
* @throws DataAccessException If something went wrong cancelling the
* statement
* @see java.sql.Statement#cancel()
*/
void cancel() throws DataAccessException;
}