• Home
• org.jooq
• jooq
• 3.10.4
• 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
 *
 *  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 static org.jooq.SQLDialect.CUBRID;
// ...
import static org.jooq.SQLDialect.DERBY;
import static org.jooq.SQLDialect.FIREBIRD;
import static org.jooq.SQLDialect.FIREBIRD_3_0;
import static org.jooq.SQLDialect.H2;
// ...
import static org.jooq.SQLDialect.HSQLDB;
// ...
// ...
import static org.jooq.SQLDialect.MARIADB;
import static org.jooq.SQLDialect.MYSQL;
import static org.jooq.SQLDialect.MYSQL_8_0;
// ...
import static org.jooq.SQLDialect.POSTGRES;
import static org.jooq.SQLDialect.POSTGRES_9_5;
// ...
import static org.jooq.SQLDialect.SQLITE;
// ...
// ...
// ...
// ...

import java.math.BigInteger;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.Properties;
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.annotation.Generated;

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.InvalidResultException;
import org.jooq.exception.MappingException;
import org.jooq.exception.NoDataFoundException;
import org.jooq.exception.TooManyRowsException;
import org.jooq.impl.DSL;
import org.jooq.impl.ThreadLocalTransactionProvider;
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;

/**
 * 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.
 *
 * @see DSL
 * @see Configuration
 * @author Lukas Eder
 */
public interface DSLContext extends Scope , AutoCloseable  {

    // -------------------------------------------------------------------------
    // XXX AutoCloseable API
    // -------------------------------------------------------------------------

    /**
     * Close the underlying resources, if any resources have been allocated when
     * constructing this DSLContext.
     * 

     * Some {@link DSLContext} constructors, such as {@link DSL#using(String)},
     * {@link DSL#using(String, Properties)}, or
     * {@link DSL#using(String, String, String)} allocate a {@link Connection}
     * resource, which is inaccessible to the outside of the {@link DSLContext}
     * implementation. Proper resource management must thus be done via this
     * {@link #close()} method.
     *
     * @throws DataAccessException When something went wrong closing the
     *             underlying resources.
     */

    @Override

    void close() throws DataAccessException;

    // -------------------------------------------------------------------------
    // 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
     */
    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
     */
     Table map(Table table);

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

    /**
     * Access the parser API.
     * 

     * This is experimental functionality.
     */
    Parser parser();

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

     * 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()}.
     * 

     * This is experimental functionality:
     * 

     * 
While this works well for static {@link Statement} executions, bind
     * variables and their position calculation might cause issues when the
     * generated SQL output involves more complex SQL transformation. See also
     * https://github.com/jOOQ/jOOQ/issues/5759.
     * 
Batching statements is currently not supported. See also https://github.com/jOOQ/jOOQ/issues/5757.
     * 
     */
    Connection parsingConnection();

    /**
     * Access the database meta data.
     * 

     * This method returns a wrapper type that gives access to your JDBC
     * connection's database meta data.
     */
    Meta meta();

    /**
     * Access the databse meta data from its serialised form.
     */
    Meta meta(InformationSchema schema);

    /**
     * Export a catalog to the {@link InformationSchema} format.
     * 

     * This allows for serialising schema meta information as XML using JAXB.
     * See also {@link Constants#XSD_META} for details.
     */
    InformationSchema informationSchema(Catalog catalog);

    /**
     * Export a set of catalogs to the {@link InformationSchema} format.
     * 

     * This allows for serialising schema meta information as XML using JAXB.
     * See also {@link Constants#XSD_META} for details.
     */
    InformationSchema informationSchema(Catalog... catalogs);

    /**
     * Export a schema to the {@link InformationSchema} format.
     * 

     * This allows for serialising schema meta information as XML using JAXB.
     * See also {@link Constants#XSD_META} for details.
     */
    InformationSchema informationSchema(Schema schema);

    /**
     * Export a set of schemas to the {@link InformationSchema} format.
     * 

     * This allows for serialising schema meta information as XML using JAXB.
     * See also {@link Constants#XSD_META} for details.
     */
    InformationSchema informationSchema(Schema... schemas);

    /**
     * Export a table to the {@link InformationSchema} format.
     * 

     * Exporting a single table will not include any foreign key definitions in
     * the exported data.
     * 

     * This allows for serialising schema meta information as XML using JAXB.
     * See also {@link Constants#XSD_META} for details.
     */
    InformationSchema informationSchema(Table table);

    /**
     * Export a set of tables to the {@link InformationSchema} format.
     * 

     * Only those foreign keys whose referenced table is also included in the
     * export will be exported.
     * 

     * This allows for serialising schema meta information as XML using JAXB.
     * See also {@link Constants#XSD_META} for details.
     */
    InformationSchema informationSchema(Table... table);

    // -------------------------------------------------------------------------
    // 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.
     */
     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.
     */
     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.
     */
    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.
     */
    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}.
     */
     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}.
     */
    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}.
     */
     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}.
     */
    CompletionStage transactionAsync(Executor executor, TransactionalRunnable transactional) throws ConfigurationException;



    /**
     * 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
     */
     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.
     */
    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
    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
     */
    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
     */
    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
     */
    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
     */
    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 "?"
     */
    List