• Home
• org.jooq
• jooq
• 3.19.9
• source code
• DSLContext.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

org.jooq.DSLContext 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
 *
 *  https://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: https://www.jooq.org/legal/licensing
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */
package org.jooq;

// ...
// ...
// ...
// ...
// ...
// ...
// ...
// ...
// ...
import static org.jooq.SQLDialect.CUBRID;
// ...
import static org.jooq.SQLDialect.DERBY;
import static org.jooq.SQLDialect.DUCKDB;
// ...
import static org.jooq.SQLDialect.FIREBIRD;
// ...
import static org.jooq.SQLDialect.H2;
// ...
import static org.jooq.SQLDialect.HSQLDB;
import static org.jooq.SQLDialect.IGNITE;
// ...
// ...
import static org.jooq.SQLDialect.MARIADB;
// ...
// ...
import static org.jooq.SQLDialect.MYSQL;
// ...
// ...
// ...
import static org.jooq.SQLDialect.POSTGRES;
// ...
// ...
// ...
// ...
// ...
import static org.jooq.SQLDialect.SQLITE;
// ...
// ...
// ...
// ...
// ...
import static org.jooq.SQLDialect.TRINO;
// ...
import static org.jooq.SQLDialect.YUGABYTEDB;

import java.math.BigInteger;
import java.sql.Connection;
import java.sql.DatabaseMetaData;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.Executor;
import java.util.function.BiFunction;
import java.util.function.Function;
import java.util.stream.Stream;

import javax.sql.DataSource;

import org.jooq.conf.ParamType;
import org.jooq.conf.Settings;
import org.jooq.conf.StatementType;
import org.jooq.exception.ConfigurationException;
import org.jooq.exception.DataAccessException;
import org.jooq.exception.DataDefinitionException;
import org.jooq.exception.InvalidResultException;
import org.jooq.exception.MappingException;
import org.jooq.exception.NoDataFoundException;
import org.jooq.exception.TooManyRowsException;
import org.jooq.impl.CacheType;
import org.jooq.impl.DSL;
import org.jooq.impl.ParserException;
import org.jooq.impl.ThreadLocalTransactionProvider;
import org.jooq.tools.jdbc.BatchedConnection;
import org.jooq.tools.jdbc.MockCallable;
import org.jooq.tools.jdbc.MockDataProvider;
import org.jooq.tools.jdbc.MockRunnable;
import org.jooq.util.xml.jaxb.InformationSchema;

import org.jetbrains.annotations.ApiStatus.Experimental;
import org.jetbrains.annotations.ApiStatus.Internal;
import org.jetbrains.annotations.Blocking;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import io.r2dbc.spi.ConnectionFactory;

/**
 * A contextual DSL providing "attached" implementations to the
 * org.jooq interfaces.
 * 

 * Apart from the {@link DSL}, this contextual DSL is the main entry point for
 * client code, to access jOOQ classes and functionality that are related to
 * {@link Query} execution. Unlike objects created through the DSL
 * type, objects created from a DSLContext will be "attached" to
 * the DSLContext's {@link #configuration()}, such that they can be
 * executed immediately in a fluent style. An example is given here:
 * 

 * 

 * DSLContext create = DSL.using(connection, dialect);
 *
 * // Immediately fetch results after constructing a query
 * create.selectFrom(MY_TABLE).where(MY_TABLE.ID.eq(1)).fetch();
 *
 * // The above is equivalent to this "non-fluent" style
 * create.fetch(DSL.selectFrom(MY_TABLE).where(MY_TABLE.ID.eq(1)));
 * 
 * 

 * The DSL provides convenient constructors to create a
 * {@link Configuration}, which will be shared among all Query
 * objects thus created. Optionally, you can pass a reusable
 * Configuration to the {@link DSL#using(Configuration)}
 * constructor. Please consider thread-safety concerns documented in
 * {@link Configuration}, should you want to reuse the same
 * Configuration instance in various threads and / or transactions.
 * 

 * {@link DSLContext} is a {@link Scope} type, mostly for convenience access to
 * its underlying {@link Configuration} properties, including the
 * {@link #data()} map, which it shares with the {@link Configuration}. It does
 * not have an independent lifecycle.
 *
 * @see DSL
 * @see Configuration
 * @author Lukas Eder
 */
public interface DSLContext extends Scope {

    // -------------------------------------------------------------------------
    // XXX Configuration API
    // -------------------------------------------------------------------------

    /**
     * Map a schema to another one.
     * 

     * This will map a schema onto another one, depending on configured schema
     * mapping in this DSLContext. If no applicable schema mapping
     * can be found, the schema itself is returned.
     *
     * @param schema A schema
     * @return The mapped schema
     */
    @Nullable
    Schema map(Schema schema);

    /**
     * Map a table to another one.
     * 

     * This will map a table onto another one, depending on configured table
     * mapping in this DSLContext. If no applicable table mapping can
     * be found, the table itself is returned.
     *
     * @param table A table
     * @return The mapped table
     */
    @Nullable
     Table map(Table table);

    // -------------------------------------------------------------------------
    // XXX Convenience methods accessing the underlying Connection
    // -------------------------------------------------------------------------

    /**
     * Access the parser API.
     */
    @NotNull
    Parser parser();

    /**
     * A JDBC connection that runs each statement through the {@link #parser()}
     * first, prior to re-generating and running the SQL.
     * 

     * Static statements are translated eagerly upon execution, e.g. of
     * {@link java.sql.Statement#executeQuery(String)}. Prepared statements are
     * prepared lazily once all bind variables are available, because the
     * specific bind value and type may influence the generated SQL. As such, a
     * {@link PreparedStatement} created from a parsing connection does not yet
     * allocate any server side resources until it is executed for the first
     * time.
     * 

     * The {@link Configuration#cacheProvider()} is called for
     * {@link CacheType#CACHE_PARSING_CONNECTION} to provide a translation cache
     * to avoid the overhead of re-parsing and re-generating the same SQL string
     * all the time. By default, this is an LRU cache.
     * 

     * The resulting {@link Connection} wraps an underlying JDBC connection that
     * has been obtained from {@link ConnectionProvider#acquire()} and must be
     * released by calling {@link Connection#close()}, which calls
     * {@link ConnectionProvider#release(Connection)}.
     */
    @NotNull
    Connection parsingConnection();

    /**
     * A JDBC data source that runs each statement through the {@link #parser()}
     * first, prior to re-generating and running the SQL.
     * 

     * This simply wraps the {@link #parsingConnection()} in a
     * {@link DataSource}.
     */
    @NotNull
    DataSource parsingDataSource();

    /**
     * An R2DBC {@link ConnectionFactory} that runs each statement through the
     * {@link #parser()} first, prior to re-generating and running the SQL.
     */
    @NotNull
    ConnectionFactory parsingConnectionFactory();

    /**
     * A JDBC connection that proxies the underlying connection to run the jOOQ
     * Diagnostics Pack on executed queries.
     * 

     * This is experimental functionality.
     */
    @NotNull
    Connection diagnosticsConnection();

    /**
     * A JDBC connection that proxies the underlying connection to run the jOOQ
     * Diagnostics Pack on executed queries.
     * 

     * This simply wraps the {@link #diagnosticsConnection()} in a {@link DataSource}.
     */
    @NotNull
    DataSource diagnosticsDataSource();

    /**
     * The experimental migrations API.
     * 

     * This is EXPERIMENTAL functionality and subject to change in future jOOQ
     * versions.
     */
    @Experimental
    @NotNull
    Migrations migrations();

    /**
     * Access the database meta data.
     * 

     * This method returns meta information provided by
     * {@link Configuration#metaProvider()}, which defaults to a wrapper type
     * that gives access to your JDBC connection's {@link DatabaseMetaData} as
     * obtained from your {@link ConnectionProvider}.
     *
     * @see #meta(DatabaseMetaData)
     */
    @NotNull
    Meta meta();

    /**
     * Access the database meta data from an explicit JDBC
     * {@link DatabaseMetaData}.
     */
    @NotNull
    Meta meta(DatabaseMetaData meta);

    /**
     * Access the database meta data from explicit catalog information.
     * 

     * This will not connect to your database to get live meta information,
     * unlike {@link #meta()} and {@link #meta(DatabaseMetaData)}.
     */
    @NotNull
    Meta meta(Catalog... catalogs);

    /**
     * Access the database meta data from explicit schema information.
     * 

     * This will not connect to your database to get live meta information,
     * unlike {@link #meta()} and {@link #meta(DatabaseMetaData)}.
     */
    @NotNull
    Meta meta(Schema... schemas);

    /**
     * Access the database meta data from explicit table information.
     * 

     * This will not connect to your database to get live meta information,
     * unlike {@link #meta()} and {@link #meta(DatabaseMetaData)}.
     */
    @NotNull
    Meta meta(Table... tables);

    /**
     * Access the database meta data from an explicit JAXB-annotated meta model.
     * 

     * This will not connect to your database to get live meta information,
     * unlike {@link #meta()} and {@link #meta(DatabaseMetaData)}.
     */
    @NotNull
    Meta meta(InformationSchema schema);

    /**
     * Create meta data from a set of sources.
     * 

     * This is convenience for wrapping all argument {@link String}s in
     * {@link Source}. The same set of content types are supported as in
     * {@link #meta(Source...)}.
     *
     * @throws DataDefinitionException if the sources do not produce consistent
     *             meta data.
     * @throws ParserException if there is a parser error parsing the sources.
     */
    @NotNull
    Meta meta(String... sources) throws DataDefinitionException, ParserException;

    /**
     * Create meta data from a set of sources.
     * 

     * This method creates a {@link Meta} representation from a set of source
     * content, which can be any of:
     * 

     * 
A set of DDL scripts, which will be parsed using
     * {@link #parser()}.
     * 
A set of XML files, which will be unmarshalled into
     * {@link InformationSchema} objects.
     * 
     * 

     * This will not connect to your database to get live meta information,
     * unlike {@link #meta()} and {@link #meta(DatabaseMetaData)}.
     *
     * @throws DataDefinitionException if the sources do not produce consistent
     *             meta data.
     * @throws ParserException if there is a parser error parsing the sources.
     */
    @NotNull
    Meta meta(Source... sources) throws DataDefinitionException, ParserException;

    /**
     * Create meta data from a set of DDL queries.
     * 

     * This works the same way as {@link #meta(Source...)}, without the need of
     * parsing the DDL scripts.
     *
     * @throws DataDefinitionException if the sources do not produce consistent
     *             meta data.
     */
    @NotNull
    Meta meta(Query... queries) throws DataDefinitionException;

    /**
     * Convenience method for {@link Meta#informationSchema()}.
     *
     * @see #meta(Catalog...)
     * @see Meta#informationSchema()
     */
    @NotNull
    InformationSchema informationSchema(Catalog catalog);

    /**
     * Convenience method for {@link Meta#informationSchema()}.
     *
     * @see #meta(Catalog...)
     * @see Meta#informationSchema()
     */
    @NotNull
    InformationSchema informationSchema(Catalog... catalogs);

    /**
     * Convenience method for {@link Meta#informationSchema()}.
     *
     * @see #meta(Schema...)
     * @see Meta#informationSchema()
     */
    @NotNull
    InformationSchema informationSchema(Schema schema);

    /**
     * Convenience method for {@link Meta#informationSchema()}.
     *
     * @see #meta(Schema...)
     * @see Meta#informationSchema()
     */
    @NotNull
    InformationSchema informationSchema(Schema... schemas);

    /**
     * Convenience method for {@link Meta#informationSchema()}.
     *
     * @see #meta(Table...)
     * @see Meta#informationSchema()
     */
    @NotNull
    InformationSchema informationSchema(Table table);

    /**
     * Convenience method for {@link Meta#informationSchema()}.
     *
     * @see #meta(Table...)
     * @see Meta#informationSchema()
     */
    @NotNull
    InformationSchema informationSchema(Table... table);

    // -------------------------------------------------------------------------
    // XXX APIs related to query optimisation
    // -------------------------------------------------------------------------

    /**
     * Run an EXPLAIN statement in the database to estimate the
     * cardinality of the query.
     */
    @NotNull
    @Support({ H2, HSQLDB, MARIADB, MYSQL, POSTGRES, SQLITE })
    Explain explain(Query query);

    // -------------------------------------------------------------------------
    // XXX APIs for creating scope for transactions, mocking, batching, etc.
    // -------------------------------------------------------------------------

    /**
     * Run a {@link TransactionalCallable} in the context of this
     * DSLContext's underlying {@link #configuration()}'s
     * {@link Configuration#transactionProvider()}, and return the
     * transactional's outcome.
     * 

     * The argument transactional code should not capture any scope but derive
     * its {@link Configuration} from the
     * {@link TransactionalCallable#run(Configuration)} argument in order to
     * create new statements.
     *
     * @param transactional The transactional code
     * @return The transactional outcome
     * @throws RuntimeException any runtime exception thrown by the
     *             transactional logic, indicating that a rollback
     *             has occurred.
     * @throws DataAccessException any database problem that may have arised
     *             when executing the transactional logic, or a
     *             wrapper for any checked exception thrown by the
     *             transactional logic, indicating that a rollback
     *             has occurred.
     */
    @Blocking
     T transactionResult(TransactionalCallable transactional);

    /**
     * Run a {@link ContextTransactionalRunnable} in the context of this
     * DSLContext's underlying {@link #configuration()}'s
     * {@link Configuration#transactionProvider()}, and return the
     * transactional's outcome.
     * 

     * The argument transactional code may capture scope to derive its
     * {@link Configuration} from the "context" in order to create new
     * statements. This context can be provided, for instance, by
     * {@link ThreadLocalTransactionProvider} automatically.
     *
     * @param transactional The transactional code
     * @return The transactional outcome
     * @throws ConfigurationException if the underlying
     *             {@link Configuration#transactionProvider()} is not able to
     *             provide context (i.e. currently, it is not a
     *             {@link ThreadLocalTransactionProvider}).
     * @throws RuntimeException any runtime exception thrown by the
     *             transactional logic, indicating that a rollback
     *             has occurred.
     * @throws DataAccessException any database problem that may have arised
     *             when executing the transactional logic, or a
     *             wrapper for any checked exception thrown by the
     *             transactional logic, indicating that a rollback
     *             has occurred.
     */
    @Blocking
     T transactionResult(ContextTransactionalCallable transactional) throws ConfigurationException;

    /**
     * Run a {@link TransactionalRunnable} in the context of this
     * DSLContext's underlying {@link #configuration()}'s
     * {@link Configuration#transactionProvider()}.
     * 

     * The argument transactional code should not capture any scope but derive
     * its {@link Configuration} from the
     * {@link TransactionalCallable#run(Configuration)} argument in order to
     * create new statements.
     *
     * @param transactional The transactional code
     * @throws RuntimeException any runtime exception thrown by the
     *             transactional logic, indicating that a rollback
     *             has occurred.
     * @throws DataAccessException any database problem that may have arised
     *             when executing the transactional logic, or a
     *             wrapper for any checked exception thrown by the
     *             transactional logic, indicating that a rollback
     *             has occurred.
     */
    @Blocking
    void transaction(TransactionalRunnable transactional);

    /**
     * Run a {@link ContextTransactionalRunnable} in the context of this
     * DSLContext's underlying {@link #configuration()}'s
     * {@link Configuration#transactionProvider()}.
     * 

     * The argument transactional code may capture scope to derive its
     * {@link Configuration} from the "context" in order to create new
     * statements. This context can be provided, for instance, by
     * {@link ThreadLocalTransactionProvider} automatically.
     *
     * @param transactional The transactional code
     * @throws ConfigurationException if the underlying
     *             {@link Configuration#transactionProvider()} is not able to
     *             provide context (i.e. currently, it is not a
     *             {@link ThreadLocalTransactionProvider}).
     * @throws RuntimeException any runtime exception thrown by the
     *             transactional logic, indicating that a rollback
     *             has occurred.
     * @throws DataAccessException any database problem that may have arised
     *             when executing the transactional logic, or a
     *             wrapper for any checked exception thrown by the
     *             transactional logic, indicating that a rollback
     *             has occurred.
     */
    @Blocking
    void transaction(ContextTransactionalRunnable transactional) throws ConfigurationException;

    /**
     * Run a {@link TransactionalCallable} asynchronously.
     * 

     * The TransactionCallable is run in the context of this
     * DSLContext's underlying {@link #configuration()}'s
     * {@link Configuration#transactionProvider()}, and returns the
     * transactional's outcome in a new {@link CompletionStage}
     * that is asynchronously completed by a task run by an {@link Executor}
     * provided by the underlying {@link #configuration()}'s
     * {@link Configuration#executorProvider()}.
     *
     * @param transactional The transactional code
     * @return The transactional outcome
     * @throws ConfigurationException If this is run with a
     *             {@link ThreadLocalTransactionProvider}.
     */
    @NotNull
     CompletionStage transactionResultAsync(TransactionalCallable transactional) throws ConfigurationException;

    /**
     * Run a {@link TransactionalRunnable} asynchronously.
     * 

     * The TransactionRunnable is run in the context of this
     * DSLContext's underlying {@link #configuration()}'s
     * {@link Configuration#transactionProvider()}, and returns the
     * transactional's outcome in a new {@link CompletionStage}
     * that is asynchronously completed by a task run by an {@link Executor}
     * provided by the underlying {@link #configuration()}'s
     * {@link Configuration#executorProvider()}.
     *
     * @param transactional The transactional code
     * @throws ConfigurationException If this is run with a
     *             {@link ThreadLocalTransactionProvider}.
     */
    @NotNull
    CompletionStage transactionAsync(TransactionalRunnable transactional) throws ConfigurationException;

    /**
     * Run a {@link TransactionalCallable} asynchronously.
     * 

     * The TransactionCallable is run in the context of this
     * DSLContext's underlying {@link #configuration()}'s
     * {@link Configuration#transactionProvider()}, and returns the
     * transactional's outcome in a new {@link CompletionStage}
     * that is asynchronously completed by a task run by a given
     * {@link Executor}.
     *
     * @param transactional The transactional code
     * @return The transactional outcome
     * @throws ConfigurationException If this is run with a
     *             {@link ThreadLocalTransactionProvider}.
     */
    @NotNull
     CompletionStage transactionResultAsync(Executor executor, TransactionalCallable transactional) throws ConfigurationException;

    /**
     * Run a {@link TransactionalRunnable} asynchronously.
     * 

     * The TransactionRunnable is run in the context of this
     * DSLContext's underlying {@link #configuration()}'s
     * {@link Configuration#transactionProvider()}, and returns the
     * transactional's outcome in a new {@link CompletionStage}
     * that is asynchronously completed by a task run by a given
     * {@link Executor}.
     *
     * @param transactional The transactional code
     * @throws ConfigurationException If this is run with a
     *             {@link ThreadLocalTransactionProvider}.
     */
    @NotNull
    CompletionStage transactionAsync(Executor executor, TransactionalRunnable transactional) throws ConfigurationException;

    /**
     * Run a {@link TransactionalPublishable} reactively.
     *
     * @param transactional The transactional code
     * @return The transactional outcome
     * @throws ConfigurationException If this is run with a
     *             {@link ThreadLocalTransactionProvider}.
     */
    @NotNull
     Publisher transactionPublisher(TransactionalPublishable transactional);

    /**
     * Run a {@link ConnectionCallable} in the context of this
     * DSLContext's underlying {@link #configuration()}'s
     * {@link Configuration#connectionProvider()}.
     *
     * @param callable The code running statements against the
     *            connection.
     * @return The outcome of the callable
     */
    @Blocking
     T connectionResult(ConnectionCallable callable);

    /**
     * Run a {@link ConnectionRunnable} in the context of this
     * DSLContext's underlying {@link #configuration()}'s
     * {@link Configuration#connectionProvider()}.
     *
     * @param runnable The code running statements against the
     *            connection.
     */
    @Blocking
    void connection(ConnectionRunnable runnable);

    /**
     * Run a {@link MockRunnable} in the context of this DSLContext
     * 's underlying {@link #configuration()}'s, and of a
     * {@link MockDataProvider} and return the mockable's outcome.
     */
     T mockResult(MockDataProvider provider, MockCallable mockable);

    /**
     * Run a {@link MockRunnable} in the context of this DSLContext
     * 's underlying {@link #configuration()}'s, and of a
     * {@link MockDataProvider}.
     */
    void mock(MockDataProvider provider, MockRunnable mockable);

    // -------------------------------------------------------------------------
    // XXX RenderContext and BindContext accessors
    // -------------------------------------------------------------------------

    /**
     * Get a new {@link RenderContext} for the context of this DSLContext.
     * 

     * This will return an initialised render context as such:
     * 

     * 

     * {@link RenderContext#castMode()} == {@link org.jooq.RenderContext.CastMode#DEFAULT DEFAULT}
     * 
     * 
 {@link RenderContext#declareFields()} == false
     * 
 {@link RenderContext#declareTables()} == false
     * 
 {@link RenderContext#format()} == false
     * 
 {@link RenderContext#paramType()} == {@link ParamType#INDEXED}
     * 
 {@link RenderContext#qualify()} == true
     * 
 {@link RenderContext#subquery()} == false
     * 
     *
     * @deprecated - [#6280] - 3.10 - Do not reuse this method. It will be
     *             completely internal with jOOQ 4.0
     */
    @Deprecated(forRemoval = true, since = "3.10")
    @Internal
    @NotNull
    RenderContext renderContext();

    /**
     * Render a QueryPart in the context of this DSLContext.
     * 

     * This is the same as calling renderContext().render(part)
     *
     * @param part The {@link QueryPart} to be rendered
     * @return The rendered SQL
     */
    @NotNull
    String render(QueryPart part);

    /**
     * Render a QueryPart in the context of this DSLContext, rendering bind
     * variables as named parameters.
     * 

     * This is the same as calling
     * renderContext().paramType(NAMED).render(part)
     *
     * @param part The {@link QueryPart} to be rendered
     * @return The rendered SQL
     */
    @NotNull
    String renderNamedParams(QueryPart part);

    /**
     * Render a QueryPart in the context of this DSLContext, rendering bind
     * variables as named parameters, or inlined parameters if they have no name.
     * 

     * This is the same as calling
     * renderContext().paramType(NAMED_OR_INLINED).render(part)
     *
     * @param part The {@link QueryPart} to be rendered
     * @return The rendered SQL
     */
    @NotNull
    String renderNamedOrInlinedParams(QueryPart part);

    /**
     * Render a QueryPart in the context of this DSLContext, inlining all bind
     * variables.
     * 

     * This is the same as calling
     * renderContext().inline(true).render(part)
     *
     * @param part The {@link QueryPart} to be rendered
     * @return The rendered SQL
     */
    @NotNull
    String renderInlined(QueryPart part);

    /**
     * Retrieve the bind values that will be bound by a given
     * QueryPart.
     * 

     * The returned List is immutable. To modify bind values, use
     * {@link #extractParams(QueryPart)} instead.
     * 

     * Unlike {@link #extractParams(QueryPart)}, which returns also inlined
     * parameters, this returns only actual bind values that will render an
     * actual bind value as a question mark "?"
     */
    @NotNull
    List