The DSLContext API
Applies to ✅ Open Source Edition ✅ Express Edition ✅ Professional Edition ✅ Enterprise Edition
DSLContext references a org.jooq.Configuration, an object that configures jOOQ's behaviour when executing queries (see SQL execution for more details). Unlike the static DSL, the DSLContext allow for creating SQL statements that are already "configured" and ready for execution.
The DSLContext object can be created fluently from the DSL type:
// Create it from a pre-existing configuration DSLContext create = DSL.using(configuration); // Create it from ad-hoc arguments DSLContext create = DSL.using(connection, dialect);
If you do not have a reference to a pre-existing Configuration object (e.g. created from org.jooq.impl.DefaultConfiguration), the various overloaded
DSL.using() methods will create one for you.
A Configuration can be supplied with these objects:
- org.jooq.SQLDialect : The dialect of your database. This may be any of the currently supported database types (see SQL Dialect for more details)
- org.jooq.conf.Settings : An optional runtime configuration (see Custom Settings for more details)
- org.jooq.ExecuteListenerProvider : An optional reference to a provider class that can provide execute listeners to jOOQ (see ExecuteListeners for more details)
- org.jooq.RecordMapperProvider : An optional reference to a provider class that can provide record mappers to jOOQ (see POJOs with RecordMappers for more details)
Any of these:
- java.sql.Connection : An optional JDBC Connection that will be re-used for the whole lifecycle of your Configuration (see Connection vs. DataSource for more details). For simplicity, this is the use-case referenced from this manual, most of the time.
- java.sql.DataSource : An optional JDBC DataSource that will be re-used for the whole lifecycle of your Configuration. If you prefer using DataSources over Connections, jOOQ will internally fetch new Connections from your DataSource, conveniently closing them again after query execution. This is particularly useful in J2EE or Spring contexts (see Connection vs. DataSource for more details)
- org.jooq.ConnectionProvider : A custom abstraction that is used by jOOQ to "acquire" and "release" connections. jOOQ will internally "acquire" new Connections from your ConnectionProvider, conveniently "releasing" them again after query execution. (see Connection vs. DataSource for more details)
// The DSLContext is "configured" with a Connection and a SQLDialect DSLContext create = DSL.using(connection, dialect); // This select statement contains an internal reference to the DSLContext's Configuration: Select<?> select = create.selectOne(); // Using the internally referenced Configuration, the select statement can now be executed: Result<?> result = select.fetch();
Note that you do not need to keep a reference to a DSLContext. You may as well inline your local variable, and fluently execute a SQL statement as such:
// Execute a statement from a single execution chain: Result<?> result = DSL.using(connection, dialect) .select() .from(BOOK) .where(BOOK.TITLE.like("Animal%")) .fetch();
Configuration, and by consequence
DSLContext, make no thread safety guarantees, but by carefully observing a few rules, they can be shared in a thread safe way. We encourage sharing
Configuration instances, because they contain caches for work not worth repeating, such as reflection field and method lookups for org.jooq.impl.DefaultRecordMapper. If you're using Spring or CDI for dependency injection, you will want to be able to inject a
DSLContext instance everywhere you use it.
The following needs to be considered when attempting to share
DSLContext among threads:
Configurationis mutable for historic reasons. Calls to various
Configuration.set()methods must be avoided after initialisation, should a
Configuration(and by consequence
DSLContext) instance be shared among threads. If you wish to modify some elements of a
Configurationfor single use, use the
Configuration.derive()methods instead, which create a copy.
Configurationcomponents, such as org.jooq.conf.Settings are mutable as well. The same rules for modification apply here.
Configurationallows for supplying user-defined SPI implementations (see above for examples). All of these must be thread safe as well, for their wrapping
Configurationto be thread safe. If you are using a org.jooq.impl.DataSourceConnectionProvider, for instance, you must make sure that your javax.sql.DataSource is thread safe as well. This is usually the case when you use a third party connection pool.
As can be seen above,
Configuration was designed to work in a thread safe way, despite it not making any such guarantee.
- SQL Dialect
- SQL Dialect Family
- Connection vs. DataSource
- Custom data
- Custom ExecuteListeners
- Custom Settings
- Object qualification
- Runtime schema and table mapping
- Identifier style
- Keyword style
- Parameter types
- Statement Type
- Execute Logging
- Optimistic Locking
- Auto-attach Records
- Updatable Primary Keys
- Reflection caching
- Fetch Warnings
- Backslash Escaping
- Scalar subqueries for stored functions
|The jOOQ User Manual. Multiple Pages : SQL building : The DSLContext API||previous : next|