Skip to content

Instantly share code, notes, and snippets.

@lukaseder

lukaseder/gist:435ef3c3dede01b8e405

Created May 4, 2015 07:35
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save lukaseder/435ef3c3dede01b8e405 to your computer and use it in GitHub Desktop.
Save lukaseder/435ef3c3dede01b8e405 to your computer and use it in GitHub Desktop.
Download ZIP
jOOQ manual raw XML
Raw
gistfile1.xml
<?xml version="1.0" encoding="UTF-8"?>
<!--
* Copyright (c) 2009-2015, Data Geekery GmbH (http://www.datageekery.com)
* All rights reserved.
*
* This work is dual-licensed
* - under the Apache Software License 2.0 (the "ASL")
* - under the jOOQ License and Maintenance Agreement (the "jOOQ License")
* ===========================================================================
* You may choose which license applies to you:
*
* - If you're using this work with Open Source databases, you may choose
* either ASL or jOOQ License.
* - If you're using this work with at least one commercial database, you must
* choose jOOQ License
*
* For more information, please visit http://www.jooq.org/licenses
*
* Apache Software License 2.0:
* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* 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.
*
* jOOQ License and Maintenance Agreement:
* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* Data Geekery grants the Customer the non-exclusive, timely limited and
* non-transferable license to install and use the Software under the terms of
* the jOOQ License and Maintenance Agreement.
*
* This library is distributed with a LIMITED WARRANTY. See the jOOQ License
* and Maintenance Agreement for more details: http://www.jooq.org/licensing
-->
<manual version="3.6" end-of-life="false">
<section id="manual">
<title>The jOOQ User Manual. Multiple Pages</title>
<content><html>
<h2 id="Overview"><a href="#Overview" name="Overview">Overview</a></h2>
<p>This manual is divided into six main sections:</p>
<ul>
<li>
<reference id="getting-started"/>
<p>
This section will get you started with jOOQ quickly. It contains
simple explanations about what jOOQ is, what jOOQ isn't and how
to set it up for the first time
</p>
</li>
<li>
<reference id="sql-building"/>
<p>
This section explains all about the jOOQ syntax used for building
queries through the query DSL and the query model API. It explains
the central factories, the supported SQL statements and various other syntax elements
</p>
</li>
<li>
<reference id="code-generation"/>
<p>
This section explains how to configure and use the built-in source code
generator
</p>
</li>
<li>
<reference id="sql-execution"/>
<p>
This section will get you through the specifics of what can be done
with jOOQ at runtime, in order to execute queries, perform CRUD
operations, import and export data, and hook into the jOOQ execution
lifecycle for debugging
</p>
</li>
<li>
<reference id="tools"/>
<p>
This section is dedicated to tools that ship with jOOQ, such as the
jOOQ's JDBC mocking feature
</p>
</li>
<li>
<reference id="reference"/>
<p>
This section is a reference for elements in this manual
</p>
</li>
</ul>
</html></content>
<sections>
<section id="preface">
<title>Preface</title>
<content><html>
<h3>jOOQ's reason for being - compared to JPA</h3>
<p>
Java and SQL have come a long way. SQL is an "old", yet established and well-understood technology. Java is a legacy too, although its platform JVM allows for many new and contemporary languages built on top of it. Yet, after all these years, libraries dealing with the interface between SQL and Java have come and gone, leaving JPA to be a standard that is accepted only with doubts, short of any surviving options.
</p>
<p>
So far, there had been only few database abstraction frameworks or libraries, that truly respected SQL as a first class citizen among languages. Most frameworks, including the industry standards JPA, EJB, Hibernate, JDO, Criteria Query, and many others try to hide SQL itself, minimising its scope to things called JPQL, HQL, JDOQL and various other inferior query languages
</p>
<p>
jOOQ has come to fill this gap.
</p>
<h3>jOOQ's reason for being - compared to LINQ</h3>
<p>
Other platforms incorporate ideas such as LINQ (with LINQ-to-SQL), or Scala's SLICK, or also Java's QueryDSL to better integrate querying as a concept into their respective language. By querying, they understand querying of arbitrary targets, such as SQL, XML, Collections and other heterogeneous data stores. jOOQ claims that this is going the wrong way too.
</p>
<p>
In more advanced querying use-cases (more than simple CRUD and the occasional JOIN), people will want to profit from the expressivity of SQL. Due to the relational nature of SQL, this is quite different from what object-oriented and partially functional languages such as C#, Scala, or Java can offer.
</p>
<p>
It is very hard to formally express and validate joins and the ad-hoc table expression types they create. It gets even harder when you want support for more advanced table expressions, such as pivot tables, unnested cursors, or just arbitrary projections from derived tables. With a very strong object-oriented typing model, these features will probably stay out of scope.
</p>
<p>
In essence, the decision of creating an API that looks like SQL or one that looks like C#, Scala, Java is a definite decision in favour of one or the other platform. While it will be easier to evolve SLICK in similar ways as LINQ (or QueryDSL in the Java world), SQL feature scope that clearly communicates its underlying intent will be very hard to add, later on (e.g. how would you model Oracle's partitioned outer join syntax? How would you model ANSI/ISO SQL:1999 grouping sets? How can you support scalar subquery caching? etc...).
</p>
<p>
jOOQ has come to fill this gap.
</p>
<h3>jOOQ's reason for being - compared to SQL / JDBC</h3>
<p>
So why not just use SQL?
</p>
<p>
SQL can be written as plain text and passed through the JDBC API. Over the years, people have become wary of this approach for many reasons:
</p>
<ul>
<li>No typesafety</li>
<li>No syntax safety</li>
<li>No bind value index safety</li>
<li>Verbose SQL String concatenation</li>
<li>Boring bind value indexing techniques</li>
<li>Verbose resource and exception handling in JDBC</li>
<li>A very "stateful", not very object-oriented JDBC API, which is hard to use</li>
</ul>
<p>
For these many reasons, other frameworks have tried to abstract JDBC away in the past in one way or another. Unfortunately, many have completely abstracted SQL away as well
</p>
<p>
jOOQ has come to fill this gap.
</p>
<h3>jOOQ is different</h3>
<p>
SQL was never meant to be abstracted. To be confined in the narrow boundaries of heavy mappers, hiding the beauty and simplicity of relational data. SQL was never meant to be object-oriented. SQL was never meant to be anything other than... SQL!
</p>
</html></content>
</section>
<section id="copyright">
<title>Copyright, License, and Trademarks</title>
<content>
<html>
<p>
This section lists the various licenses that apply to different versions of jOOQ. Prior to version 3.2, jOOQ was shipped for free under the terms of the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache Software License 2.0</a>. With jOOQ 3.2, jOOQ became dual-licensed: <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache Software License 2.0</a> (for use with Open Source databases) and <a href="http://www.jooq.org/licensing">commercial</a> (for use with commercial databases).
</p>
<p>
This manual itself (as well as the <a href="http://www.jooq.org">www.jooq.org</a> public website) is licensed to you under the terms of the <a href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA 4.0</a> license.
</p>
<p>
Please contact <a href="mailto:legal@datageekery.com">legal@datageekery.com</a>, should you have any questions regarding licensing.
</p>
<h3>License for jOOQ 3.2 and later</h3>
</html>
<text>Copyright (c) 2009-2015, Data Geekery GmbH (http://www.datageekery.com)
All rights reserved.
This work is dual-licensed
- under the Apache Software License 2.0 (the "ASL")
- under the jOOQ License and Maintenance Agreement (the "jOOQ License")
=============================================================================
You may choose which license applies to you:
- If you're using this work with Open Source databases, you may choose
either ASL or jOOQ License.
- If you're using this work with at least one commercial database, you must
choose jOOQ License
For more information, please visit http://www.jooq.org/licenses
Apache Software License 2.0:
-----------------------------------------------------------------------------
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.
jOOQ License and Maintenance Agreement:
-----------------------------------------------------------------------------
Data Geekery grants the Customer the non-exclusive, timely limited and
non-transferable license to install and use the Software under the terms of
the jOOQ License and Maintenance Agreement.
This library is distributed with a LIMITED WARRANTY. See the jOOQ License
and Maintenance Agreement for more details: http://www.jooq.org/licensing</text>
<html>
<h3>Historic license for jOOQ 1.x, 2.x, 3.0, 3.1</h3>
</html>
<text>Copyright (c) 2009-2015, Lukas Eder, lukas.eder@gmail.com
All rights reserved.
This software is licensed to you under the Apache License, Version 2.0
(the "License"); You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
. Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
. Neither the name "jOOQ" nor the names of its contributors may be
used to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.</text>
<html>
<h3>Trademarks owned by Data Geekery™ GmbH</h3>
<ul>
<li>jOOλ™ is a trademark by Data Geekery™ GmbH</li>
<li>jOOQ™ is a trademark by Data Geekery™ GmbH</li>
<li>jOOR™ is a trademark by Data Geekery™ GmbH</li>
<li>jOOU™ is a trademark by Data Geekery™ GmbH</li>
<li>jOOX™ is a trademark by Data Geekery™ GmbH</li>
</ul>
<h3>Trademarks owned by Data Geekery™ GmbH partners</h3>
<ul>
<li>GSP and General SQL Parser are trademarks by Gudu Software Limited</li>
<li>SQL 2 jOOQ is a trademark by Data Geekery™ GmbH and Gudu Software Limited</li>
<li>Flyway is a trademark by Snow Mountain Labs UG (haftungsbeschränkt)</li>
</ul>
<h3>Trademarks owned by database vendors with no affiliation to Data Geekery™ GmbH</h3>
<ul>
<li>Access® is a registered trademark of Microsoft® Inc.</li>
<li>Adaptive Server® Enterprise is a registered trademark of Sybase®, Inc.</li>
<li>CUBRID™ is a trademark of NHN® Corp.</li>
<li>DB2® is a registered trademark of IBM® Corp.</li>
<li>Derby is a trademark of the Apache™ Software Foundation</li>
<li>H2 is a trademark of the H2 Group</li>
<li>HSQLDB is a trademark of The hsql Development Group</li>
<li>Ingres is a trademark of Actian™ Corp.</li>
<li>MariaDB is a trademark of Monty Program Ab</li>
<li>MySQL® is a registered trademark of Oracle® Corp.</li>
<li>Firebird® is a registered trademark of Firebird Foundation Inc.</li>
<li>Oracle® database is a registered trademark of Oracle® Corp.</li>
<li>PostgreSQL® is a registered trademark of The PostgreSQL Global Development Group</li>
<li>Postgres Plus® is a registered trademark of EnterpriseDB® software</li>
<li>SQL Anywhere® is a registered trademark of Sybase®, Inc.</li>
<li>SQL Server® is a registered trademark of Microsoft® Inc.</li>
<li>SQLite is a trademark of Hipp, Wyrick &amp; Company, Inc.</li>
</ul>
<h3>Other trademarks by vendors with no affiliation to Data Geekery™ GmbH</h3>
<ul>
<li>Java® is a registered trademark by Oracle® Corp. and/or its affiliates</li>
<li>Scala is a trademark of EPFL</li>
</ul>
<h3>Other trademark remarks</h3>
<p>
Other names may be trademarks of their respective owners.
</p>
<p>
Throughout the manual, the above trademarks are referenced without a formal ® (R) or ™ (TM) symbol. It is believed that referencing third-party trademarks in this manual or on the jOOQ website constitutes "fair use". Please <a href="mailto:contact@datageekery.com">contact us</a> if you think that your trademark(s) are not properly attributed.
</p>
</html>
</content>
</section>
<section id="getting-started">
<title>Getting started with jOOQ</title>
<content><html>
<p>
These chapters contain a quick overview of how to get started with this manual and with jOOQ. While the subsequent chapters contain a lot of reference information, this chapter here just wraps up the essentials.
</p>
</html></content>
<sections>
<section id="the-manual">
<title>How to read this manual</title>
<content><html>
<p>
This section helps you correctly interpret this manual in the context of jOOQ.
</p>
<h3>Code blocks</h3>
<p>
The following are code blocks:
</p>
</html><sql><![CDATA[-- A SQL code block
SELECT 1 FROM DUAL]]></sql>
<java><![CDATA[// A Java code block
for (int i = 0; i < 10; i++);]]></java>
<xml><![CDATA[<!-- An XML code block -->
<hello what="world"></hello>]]></xml>
<config><![CDATA[# A config file code block
org.jooq.property=value]]></config><html>
<p>
These are useful to provide examples in code. Often, with jOOQ, it is even more useful to compare SQL code with its corresponding Java/jOOQ code. When this is done, the blocks are aligned side-by-side, with SQL usually being on the left, and an equivalent jOOQ DSL query in Java usually being on the right:
</p>
</html><code-pair>
<sql><![CDATA[-- In SQL:
SELECT 1 FROM DUAL]]></sql>
<java><![CDATA[// Using jOOQ:
create.selectOne().fetch()]]></java>
</code-pair><html>
<h3>Code block contents</h3>
<p>
The contents of code blocks follow conventions, too. If nothing else is mentioned next to any given code block, then the following can be assumed:
</p>
</html><sql><![CDATA[-- SQL assumptions
------------------
-- If nothing else is specified, assume that the Oracle syntax is used
SELECT 1 FROM DUAL]]></sql>
<java><![CDATA[// Java assumptions
// ----------------
// Whenever you see "standalone functions", assume they were static imported from org.jooq.impl.DSL
// "DSL" is the entry point of the static query DSL
exists(); max(); min(); val(); inline(); // correspond to DSL.exists(); DSL.max(); DSL.min(); etc...
// Whenever you see BOOK/Book, AUTHOR/Author and similar entities, assume they were (static) imported from the generated schema
BOOK.TITLE, AUTHOR.LAST_NAME // correspond to com.example.generated.Tables.BOOK.TITLE, com.example.generated.Tables.BOOK.TITLE
FK_BOOK_AUTHOR // corresponds to com.example.generated.Keys.FK_BOOK_AUTHOR
// Whenever you see "create" being used in Java code, assume that this is an instance of org.jooq.DSLContext.
// The reason why it is called "create" is the fact, that a jOOQ QueryPart is being created from the DSL object.
// "create" is thus the entry point of the non-static query DSL
DSLContext create = DSL.using(connection, SQLDialect.ORACLE);]]></java><html>
<p>
Your naming may differ, of course. For instance, you could name the "create" instance "db", instead.
</p>
<h3>Degree (arity)</h3>
<p>
jOOQ records (and many other API elements) have a degree N between 1 and {max-row-degree}. The variable degree of an API element is denoted as [N], e.g. Row[N] or Record[N]. The term "degree" is preferred over arity, as "degree" is the term used in the SQL standard, whereas "arity" is used more often in mathematics and relational theory.
</p>
<h3>Settings</h3>
<p>
jOOQ allows to override runtime behaviour using <reference class="org.jooq.conf.Settings"/>. If nothing is specified, the default runtime settings are assumed.
</p>
<h3>Sample database</h3>
<p>
jOOQ query examples run against the sample database. See the manual's section about <reference id="sample-database" title="the sample database used in this manual"/> to learn more about the sample database.
</p>
</html></content>
</section>
<section id="sample-database">
<title>The sample database used in this manual</title>
<content><html>
<p>
For the examples in this manual, the same database will always be referred to. It essentially consists of these entities created using the Oracle dialect
</p>
</html><sql>CREATE TABLE language (
id NUMBER(7) NOT NULL PRIMARY KEY,
cd CHAR(2) NOT NULL,
description VARCHAR2(50)
)
CREATE TABLE author (
id NUMBER(7) NOT NULL PRIMARY KEY,
first_name VARCHAR2(50),
last_name VARCHAR2(50) NOT NULL,
date_of_birth DATE,
year_of_birth NUMBER(7),
distinguished NUMBER(1)
)
CREATE TABLE book (
id NUMBER(7) NOT NULL PRIMARY KEY,
author_id NUMBER(7) NOT NULL,
title VARCHAR2(400) NOT NULL,
published_in NUMBER(7) NOT NULL,
language_id NUMBER(7) NOT NULL,
CONSTRAINT fk_book_author FOREIGN KEY (author_id) REFERENCES author(id),
CONSTRAINT fk_book_language FOREIGN KEY (language_id) REFERENCES language(id)
)
CREATE TABLE book_store (
name VARCHAR2(400) NOT NULL UNIQUE
)
CREATE TABLE book_to_book_store (
name VARCHAR2(400) NOT NULL,
book_id INTEGER NOT NULL,
stock INTEGER,
PRIMARY KEY(name, book_id),
CONSTRAINT fk_b2bs_book_store FOREIGN KEY (name) REFERENCES book_store (name) ON DELETE CASCADE,
CONSTRAINT fk_b2bs_book FOREIGN KEY (book_id) REFERENCES book (id) ON DELETE CASCADE
)</sql><html>
<p>
More entities, types (e.g. UDT's, ARRAY types, ENUM types, etc), stored procedures and packages are introduced for specific examples
</p>
</html></content>
</section>
<section id="use-cases">
<title>Different use cases for jOOQ</title>
<content><html>
<p>
jOOQ has originally been created as a library for complete abstraction of JDBC and all database interaction. Various best practices that are frequently encountered in pre-existing software products are applied to this library. This includes:
</p>
<ul>
<li>Typesafe database object referencing through generated schema, table, column, record, procedure, type, dao, pojo artefacts (see the chapter about <reference id="code-generation" title="code generation"/>)</li>
<li>Typesafe SQL construction / SQL building through a complete querying DSL API modelling SQL as a domain specific language in Java (see the chapter about <reference id="dsl-and-non-dsl" title="the query DSL API"/>)</li>
<li>Convenient query execution through an improved API for result fetching (see the chapters about <reference id="fetching" title="the various types of data fetching"/>)</li>
<li>SQL dialect abstraction and SQL clause simulation to improve cross-database compatibility and to enable missing features in simpler databases (see the chapter about <reference id="sql-dialects" title="SQL dialects"/>)</li>
<li>SQL logging and debugging using jOOQ as an integral part of your development process (see the chapters about <reference id="logging" title="logging"/>)</li>
</ul>
<p>
Effectively, jOOQ was originally designed to replace any other database abstraction framework short of the ones handling connection pooling (and more sophisticated <reference id="transaction-management" title="transaction management"/>)
</p>
<h3>Use jOOQ the way you prefer</h3>
<p>
... but open source is community-driven. And the community has shown various ways of using jOOQ that diverge from its original intent. Some use cases encountered are:
</p>
<ul>
<li>Using Hibernate for 70% of the queries (i.e. <reference id="crud-with-updatablerecords" title="CRUD"/>) and jOOQ for the remaining 30% where SQL is really needed</li>
<li>Using jOOQ for SQL building and JDBC for SQL execution</li>
<li>Using jOOQ for SQL building and Spring Data for SQL execution</li>
<li>Using jOOQ without the <reference id="code-generation" title="source code generator"/> to build the basis of a framework for dynamic SQL execution.</li>
</ul>
<p>
The following sections explain about various use cases for using jOOQ in your application.
</p>
</html></content>
<sections>
<section id="jooq-as-a-standalone-sql-builder">
<title>jOOQ as a SQL builder</title>
<content><html>
<p>
This is the most simple of all use cases, allowing for construction of valid SQL for any database. In this use case, you will not use <reference id="jooq-as-a-sql-builder-with-code-generation" title="jOOQ's code generator"/> and probably not even <reference id="jooq-as-a-sql-executor" title="jOOQ's query execution facilities"/>. Instead, you'll use <reference id="dsl-and-non-dsl" title="jOOQ's query DSL API"/> to wrap strings, literals and other user-defined objects into an object-oriented, type-safe AST modelling your SQL statements. An example is given here:
</p>
</html><java><![CDATA[// Fetch a SQL string from a jOOQ Query in order to manually execute it with another tool.
String sql = create.select(field("BOOK.TITLE"), field("AUTHOR.FIRST_NAME"), field("AUTHOR.LAST_NAME"))
.from(table("BOOK"))
.join(table("AUTHOR"))
.on(field("BOOK.AUTHOR_ID").equal(field("AUTHOR.ID")))
.where(field("BOOK.PUBLISHED_IN").equal(1948))
.getSQL();]]></java><html>
<p>
The SQL string built with the jOOQ query DSL can then be executed using JDBC directly, using Spring's JdbcTemplate, using Apache DbUtils and many other tools.
</p>
<p>
If you wish to use jOOQ only as a SQL builder, the following sections of the manual will be of interest to you:
</p>
<ul>
<li><reference id="sql-building" title="SQL building"/>: This section contains a lot of information about creating SQL statements using the jOOQ API</li>
<li><reference id="plain-sql" title="Plain SQL"/>: This section contains information useful in particular to those that want to supply <reference id="table-expressions" title="table expressions"/>, <reference id="column-expressions" title="column expressions"/>, etc. as plain SQL to jOOQ, rather than through generated artefacts</li>
</ul>
</html></content>
</section>
<section id="jooq-as-a-sql-builder-with-code-generation">
<title>jOOQ as a SQL builder with code generation</title>
<content><html>
<p>
In addition to using jOOQ as a <reference id="jooq-as-a-standalone-sql-builder" title="standalone SQL builder"/>, you can also use jOOQ's code generation features in order to compile your SQL statements using a Java compiler against an actual database schema. This adds a lot of power and expressiveness to just simply constructing SQL using the query DSL and custom strings and literals, as you can be sure that all database artefacts actually exist in the database, and that their type is correct. An example is given here:
</p>
</html><java><![CDATA[// Fetch a SQL string from a jOOQ Query in order to manually execute it with another tool.
String sql = create.select(BOOK.TITLE, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME)
.from(BOOK)
.join(AUTHOR)
.on(BOOK.AUTHOR_ID.equal(AUTHOR.ID))
.where(BOOK.PUBLISHED_IN.equal(1948))
.getSQL();]]></java><html>
<p>
The SQL string that you can generate as such can then be executed using JDBC directly, using Spring's JdbcTemplate, using Apache DbUtils and many other tools.
</p>
<p>
If you wish to use jOOQ only as a SQL builder with code generation, the following sections of the manual will be of interest to you:
</p>
<ul>
<li><reference id="sql-building" title="SQL building"/>: This section contains a lot of information about creating SQL statements using the jOOQ API</li>
<li><reference id="code-generation" title="Code generation"/>: This section contains the necessary information to run jOOQ's code generator against your developer database</li>
</ul>
</html></content>
</section>
<section id="jooq-as-a-sql-executor">
<title>jOOQ as a SQL executor</title>
<content><html>
<p>
Instead of any tool mentioned in the previous chapters, you can also use jOOQ directly to execute your jOOQ-generated SQL statements. This will add a lot of convenience on top of the previously discussed API for typesafe SQL construction, when you can re-use the information from generated classes to fetch records and custom data types. An example is given here:
</p>
</html><java><![CDATA[// Typesafely execute the SQL statement directly with jOOQ
Result<Record3<String, String, String>> result =
create.select(BOOK.TITLE, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME)
.from(BOOK)
.join(AUTHOR)
.on(BOOK.AUTHOR_ID.equal(AUTHOR.ID))
.where(BOOK.PUBLISHED_IN.equal(1948))
.fetch();]]></java><html>
<p>
By having jOOQ execute your SQL, the jOOQ query DSL becomes truly embedded SQL.
</p>
<p>
jOOQ doesn't stop here, though! You can execute any SQL with jOOQ. In other words, you can use any other SQL building tool and run the SQL statements with jOOQ. An example is given here:
</p>
</html><java><![CDATA[// Use your favourite tool to construct SQL strings:
String sql = "SELECT title, first_name, last_name FROM book JOIN author ON book.author_id = author.id " +
"WHERE book.published_in = 1984";
// Fetch results using jOOQ
Result<Record> result = create.fetch(sql);
// Or execute that SQL with JDBC, fetching the ResultSet with jOOQ:
ResultSet rs = connection.createStatement().executeQuery(sql);
Result<Record> result = create.fetch(rs);]]></java><html>
<p>
If you wish to use jOOQ as a SQL executor with (or without) code generation, the following sections of the manual will be of interest to you:
</p>
<ul>
<li><reference id="sql-building" title="SQL building"/>: This section contains a lot of information about creating SQL statements using the jOOQ API</li>
<li><reference id="code-generation" title="Code generation"/>: This section contains the necessary information to run jOOQ's code generator against your developer database</li>
<li><reference id="sql-execution" title="SQL execution"/>: This section contains a lot of information about executing SQL statements using the jOOQ API</li>
<li><reference id="fetching"/>: This section contains some useful information about the various ways of fetching data with jOOQ</li>
</ul>
</html></content>
</section>
<section id="jooq-for-crud">
<title>jOOQ for CRUD</title>
<content><html>
<p>
This is probably the most complete use-case for jOOQ: Use all of jOOQ's features. Apart from jOOQ's fluent API for query construction, jOOQ can also help you execute everyday CRUD operations. An example is given here:
</p>
</html><java><![CDATA[// Fetch all authors
for (AuthorRecord author : create.fetch(AUTHOR)) {
// Skip previously distinguished authors
if ((int) author.getDistinguished() == 1)
continue;
// Check if the author has written more than 5 books
if (author.fetchChildren(Keys.FK_BOOK_AUTHOR).size() > 5) {
// Mark the author as a "distinguished" author
author.setDistinguished(1);
author.store();
}
}]]></java><html>
<p>
If you wish to use all of jOOQ's features, the following sections of the manual will be of interest to you (including all sub-sections):
</p>
<ul>
<li><reference id="sql-building" title="SQL building"/>: This section contains a lot of information about creating SQL statements using the jOOQ API</li>
<li><reference id="code-generation" title="Code generation"/>: This section contains the necessary information to run jOOQ's code generator against your developer database</li>
<li><reference id="sql-execution" title="SQL execution"/>: This section contains a lot of information about executing SQL statements using the jOOQ API</li>
</ul>
</html></content>
</section>
<section id="jooq-for-pros">
<title>jOOQ for PROs</title>
<content><html>
<p>
jOOQ isn't just a library that helps you <reference id="sql-building" title="build"/> and <reference id="sql-execution" title="execute"/> SQL against your <reference id="code-generation" title="generated, compilable schema"/>. jOOQ ships with a lot of tools. Here are some of the most important tools shipped with jOOQ:
</p>
<ul>
<li><reference id="execute-listeners" title="jOOQ's Execute Listeners"/>: jOOQ allows you to hook your custom execute listeners into jOOQ's SQL statement execution lifecycle in order to centrally coordinate any arbitrary operation performed on SQL being executed. Use this for logging, identity generation, SQL tracing, performance measurements, etc.</li>
<li><reference id="logging" title="Logging"/>: jOOQ has a standard DEBUG logger built-in, for logging and tracing all your executed SQL statements and fetched result sets</li>
<li><reference id="stored-procedures" title="Stored Procedures"/>: jOOQ supports stored procedures and functions of your favourite database. All routines and user-defined types are generated and can be included in jOOQ's SQL building API as function references.</li>
<li><reference id="batch-execution" title="Batch execution"/>: Batch execution is important when executing a big load of SQL statements. jOOQ simplifies these operations compared to JDBC</li>
<li><reference id="exporting" title="Exporting"/> and <reference id="importing" title="Importing"/>: jOOQ ships with an API to easily export/import data in various formats</li>
</ul>
<p>
If you're a power user of your favourite, feature-rich database, jOOQ will help you access all of your database's vendor-specific features, such as OLAP features, stored procedures, user-defined types, vendor-specific SQL, functions, etc. Examples are given throughout this manual.
</p>
</html></content>
</section>
</sections>
</section>
<section id="tutorials">
<title>Tutorials</title>
<content><html>
<p>
Don't have time to read the full manual? Here are a couple of tutorials that will get you into the most essential parts of jOOQ as quick as possible.
</p>
</html></content>
<sections>
<section id="jooq-in-7-steps">
<title>jOOQ in 7 easy steps</title>
<content><html>
<p>
This manual section is intended for new users, to help them get a running application with jOOQ, quickly.
</p>
</html></content>
<sections>
<section id="jooq-in-7-steps-step1">
<title>Step 1: Preparation</title>
<content><html>
<p>
If you haven't already downloaded it, download jOOQ:<br/>
<a href="http://www.jooq.org/download" title="jOOQ download">http://www.jooq.org/download</a>
</p>
<p>
Alternatively, you can create a Maven dependency to download jOOQ artefacts:
</p>
</html><xml><![CDATA[<dependency>
<groupId>org.jooq</groupId>
<artifactId>jooq</artifactId>
<version>{jooq-version}</version>
</dependency>
<dependency>
<groupId>org.jooq</groupId>
<artifactId>jooq-meta</artifactId>
<version>{jooq-version}</version>
</dependency>
<dependency>
<groupId>org.jooq</groupId>
<artifactId>jooq-codegen</artifactId>
<version>{jooq-version}</version>
</dependency>]]></xml><html>
<p>
Note that only the jOOQ Open Source Edition is available from Maven Central. If you're using the jOOQ Professional Edition or the jOOQ Enterprise Edition, you will have to manually install jOOQ in your local Nexus, or in your local Maven cache. For more information, please refer to the <a href="http://www.jooq.org/licensing">licensing pages</a>.
</p>
<p>
Please refer to the manual's section about <reference id="codegen-configuration" title="Code generation configuration"/> to learn how to use jOOQ's code generator with Maven.
</p>
<p>
For this example, we'll be using MySQL. If you haven't already downloaded MySQL Connector/J, download it here:<br/>
<a href="http://dev.mysql.com/downloads/connector/j/" target="_blank" title="MySQL JDBC driver">http://dev.mysql.com/downloads/connector/j/</a>
</p>
<p>
If you don't have a MySQL instance up and running yet, get <a href="http://www.apachefriends.org/en/xampp.html" title="XAMPP">XAMPP</a> now! XAMPP is a simple installation bundle for Apache, MySQL, PHP and Perl
</p>
</html></content>
</section>
<section id="jooq-in-7-steps-step2">
<title>Step 2: Your database</title>
<content><html>
<p>
We're going to create a database called "library" and a corresponding "author" table. Connect to MySQL via your command line client and type the following:
</p>
</html><sql>CREATE DATABASE `library`;
USE `library`;
CREATE TABLE `author` (
`id` int NOT NULL,
`first_name` varchar(255) DEFAULT NULL,
`last_name` varchar(255) DEFAULT NULL,
PRIMARY KEY (`id`)
);
</sql>
</content>
</section>
<section id="jooq-in-7-steps-step3">
<title>Step 3: Code generation</title>
<content><html>
<p>
In this step, we're going to use jOOQ's command line tools to generate classes that map to the Author table we just created. More detailed information about how to set up the jOOQ code generator can be found here:<br/>
<reference id="code-generation" title="jOOQ manual pages about setting up the code generator"/>
</p>
<p>
The easiest way to generate a schema is to copy the jOOQ jar files (there should be 3) and the MySQL Connector jar file to a temporary directory. Then, create a library.xml that looks like this:
</p>
</html><xml><![CDATA[<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<configuration xmlns="http://www.jooq.org/xsd/jooq-codegen-{codegen-xsd-version}.xsd">
<!-- Configure the database connection here -->
<jdbc>
<driver>com.mysql.jdbc.Driver</driver>
<url>jdbc:mysql://localhost:3306/library</url>
<user>root</user>
<password></password>
</jdbc>
<generator>
<!-- The default code generator. You can override this one, to generate your own code style
Defaults to org.jooq.util.DefaultGenerator -->
<name>org.jooq.util.DefaultGenerator</name>
<database>
<!-- The database type. The format here is:
org.util.[database].[database]Database -->
<name>org.jooq.util.mysql.MySQLDatabase</name>
<!-- The database schema (or in the absence of schema support, in your RDBMS this
can be the owner, user, database name) to be generated -->
<inputSchema>library</inputSchema>
<!-- All elements that are generated from your schema
(A Java regular expression. Use the pipe to separate several expressions)
Watch out for case-sensitivity. Depending on your database, this might be important! -->
<includes>.*</includes>
<!-- All elements that are excluded from your schema
(A Java regular expression. Use the pipe to separate several expressions).
Excludes match before includes -->
<excludes></excludes>
</database>
<target>
<!-- The destination package of your generated classes (within the destination directory) -->
<packageName>test.generated</packageName>
<!-- The destination directory of your generated classes -->
<directory>C:/workspace/MySQLTest/src</directory>
</target>
</generator>
</configuration>]]></xml><html>
<p>
Replace the username with whatever user has the appropriate privileges to query the database meta data. You'll also want to look at the other values and replace as necessary. Here are the two interesting properties:
</p>
<p>
<code>generator.target.package</code> - set this to the parent package you want to create for the generated classes. The setting of <code>test.generated</code> will cause the <code>test.generated.Author</code> and <code>test.generated.AuthorRecord</code> to be created
</p>
<p>
<code>generator.target.directory</code> - the directory to output to.
</p>
<p>
Once you have the JAR files and library.xml in your temp directory, type this on a Windows machine:
</p>
</html><text>java -classpath jooq-{jooq-version}.jar;jooq-meta-{jooq-version}.jar;jooq-codegen-{jooq-version}.jar;mysql-connector-java-5.1.18-bin.jar;.
org.jooq.util.GenerationTool library.xml
</text><html>
<p>
... or type this on a UNIX / Linux / Mac system (colons instead of semi-colons):
</p>
</html><text>java -classpath jooq-{jooq-version}.jar:jooq-meta-{jooq-version}.jar:jooq-codegen-{jooq-version}.jar:mysql-connector-java-5.1.18-bin.jar:.
org.jooq.util.GenerationTool library.xml
</text><html>
<p>
Note: jOOQ will try loading the <strong>library.xml</strong> from your classpath. This is also why there is a trailing period (<code>.</code>) on the classpath. If the file cannot be found on the classpath, jOOQ will look on the file system from the current working directory.
</p>
<p>
Replace the filenames with your actual filenames. In this example, jOOQ {jooq-version} is being used. If everything has worked, you should see this in your console output:
</p>
</html><text>Nov 1, 2011 7:25:06 PM org.jooq.impl.JooqLogger info
INFO: Initialising properties : /library.xml
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: Database parameters
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: ----------------------------------------------------------
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: dialect : MYSQL
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: schema : library
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: target dir : C:/workspace/MySQLTest/src
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: target package : test.generated
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: ----------------------------------------------------------
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: Emptying : C:/workspace/MySQLTest/src/test/generated
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: Generating classes in : C:/workspace/MySQLTest/src/test/generated
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: Generating schema : Library.java
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: Schema generated : Total: 122.18ms
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: Sequences fetched : 0 (0 included, 0 excluded)
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: Tables fetched : 5 (5 included, 0 excluded)
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: Generating tables : C:/workspace/MySQLTest/src/test/generated/tables
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: ARRAYs fetched : 0 (0 included, 0 excluded)
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: Enums fetched : 0 (0 included, 0 excluded)
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: UDTs fetched : 0 (0 included, 0 excluded)
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: Generating table : Author.java
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: Tables generated : Total: 680.464ms, +558.284ms
Nov 1, 2011 7:25:07 PM org.jooq.impl.JooqLogger info
INFO: Generating Keys : C:/workspace/MySQLTest/src/test/generated/tables
Nov 1, 2011 7:25:08 PM org.jooq.impl.JooqLogger info
INFO: Keys generated : Total: 718.621ms, +38.157ms
Nov 1, 2011 7:25:08 PM org.jooq.impl.JooqLogger info
INFO: Generating records : C:/workspace/MySQLTest/src/test/generated/tables/records
Nov 1, 2011 7:25:08 PM org.jooq.impl.JooqLogger info
INFO: Generating record : AuthorRecord.java
Nov 1, 2011 7:25:08 PM org.jooq.impl.JooqLogger info
INFO: Table records generated : Total: 782.545ms, +63.924ms
Nov 1, 2011 7:25:08 PM org.jooq.impl.JooqLogger info
INFO: Routines fetched : 0 (0 included, 0 excluded)
Nov 1, 2011 7:25:08 PM org.jooq.impl.JooqLogger info
INFO: Packages fetched : 0 (0 included, 0 excluded)
Nov 1, 2011 7:25:08 PM org.jooq.impl.JooqLogger info
INFO: GENERATION FINISHED! : Total: 791.688ms, +9.143ms
</text>
</content>
</section>
<section id="jooq-in-7-steps-step4">
<title>Step 4: Connect to your database</title>
<content><html>
<p>
Let's just write a vanilla main class in the project containing the generated classes:
</p>
</html><java><![CDATA[// For convenience, always static import your generated tables and jOOQ functions to decrease verbosity:
import static test.generated.Tables.*;
import static org.jooq.impl.DSL.*;
import java.sql.*;gi
public class Main {
public static void main(String[] args) {
String userName = "root";
String password = "";
String url = "jdbc:mysql://localhost:3306/library";
// Connection is the only JDBC resource that we need
// PreparedStatement and ResultSet are handled by jOOQ, internally
try (Connection conn = DriverManager.getConnection(url, userName, password)) {
// ...
}
// For the sake of this tutorial, let's keep exception handling simple
catch (Exception e) {
e.printStackTrace();
}
}
}]]></java><html>
<p>
This is pretty standard code for establishing a MySQL connection.
</p>
</html></content>
</section>
<section id="jooq-in-7-steps-step5">
<title>Step 5: Querying</title>
<content><html>
<p>
Let's add a simple query constructed with jOOQ's query DSL:
</p>
</html><java><![CDATA[DSLContext create = DSL.using(conn, SQLDialect.MYSQL);
Result<Record> result = create.select().from(AUTHOR).fetch();]]></java><html>
<p>
First get an instance of <code>DSLContext</code> so we can write a simple <code>SELECT</code> query. We pass an instance of the MySQL connection to <code>DSL</code>. Note that the DSLContext doesn't close the connection. We'll have to do that ourselves.
</p>
<p>
We then use jOOQ's query DSL to return an instance of Result. We'll be using this result in the next step.
</p>
</html></content>
</section>
<section id="jooq-in-7-steps-step6">
<title>Step 6: Iterating</title>
<content><html>
<p>
After the line where we retrieve the results, let's iterate over the results and print out the data:
</p>
</html><java><![CDATA[for (Record r : result) {
Integer id = r.getValue(AUTHOR.ID);
String firstName = r.getValue(AUTHOR.FIRST_NAME);
String lastName = r.getValue(AUTHOR.LAST_NAME);
System.out.println("ID: " + id + " first name: " + firstName + " last name: " + lastName);
}]]></java><html>
<p>
The full program should now look like this:
</p>
</html><java><![CDATA[package test;
// For convenience, always static import your generated tables and
// jOOQ functions to decrease verbosity:
import static test.generated.Tables.*;
import static org.jooq.impl.DSL.*;
import java.sql.*;
import org.jooq.*;
import org.jooq.impl.*;
public class Main {
/**
* @param args
*/
public static void main(String[] args) {
String userName = "root";
String password = "";
String url = "jdbc:mysql://localhost:3306/library";
// Connection is the only JDBC resource that we need
// PreparedStatement and ResultSet are handled by jOOQ, internally
try (Connection conn = DriverManager.getConnection(url, userName, password)) {
DSLContext create = DSL.using(conn, SQLDialect.MYSQL);
Result<Record> result = create.select().from(AUTHOR).fetch();
for (Record r : result) {
Integer id = r.getValue(AUTHOR.ID);
String firstName = r.getValue(AUTHOR.FIRST_NAME);
String lastName = r.getValue(AUTHOR.LAST_NAME);
System.out.println("ID: " + id + " first name: " + firstName + " last name: " + lastName);
}
}
// For the sake of this tutorial, let's keep exception handling simple
catch (Exception e) {
e.printStackTrace();
}
}
}]]></java>
</content>
</section>
<section id="jooq-in-7-steps-step7">
<title>Step 7: Explore!</title>
<content><html>
<p>
jOOQ has grown to be a comprehensive SQL library. For more information, please consider the documentation:<br/>
<a href="http://www.jooq.org/learn.php" title="jOOQ Manual">http://www.jooq.org/learn.php</a>
</p>
<p>
... explore the Javadoc:<br/>
<a href="http://www.jooq.org/javadoc/latest/" title="jOOQ Javadoc">http://www.jooq.org/javadoc/latest/</a>
</p>
<p>
... or join the news group:<br/>
<a href="https://groups.google.com/forum/#!forum/jooq-user" title="jOOQ news group">https://groups.google.com/forum/#!forum/jooq-user</a>
</p>
<p>
This tutorial is the courtesy of Ikai Lan. See the original source here:<br/>
<a href="http://ikaisays.com/2011/11/01/getting-started-with-jooq-a-tutorial/" target="_blank" title="Ikai Lan's jOOQ tutorial">http://ikaisays.com/2011/11/01/getting-started-with-jooq-a-tutorial/</a>
</p>
</html></content>
</section>
</sections>
</section>
<section id="jooq-in-modern-ides">
<title>Using jOOQ in modern IDEs</title>
<content><html>
<p>Feel free to contribute a tutorial!</p>
</html></content>
</section>
<section id="jooq-with-spring">
<title>Using jOOQ with Spring and Apache DBCP</title>
<content><html>
<p>
jOOQ and Spring are easy to integrate. In this example, we shall integrate:
</p>
<ul>
<li><a href="http://commons.apache.org/proper/commons-dbcp">Apache DBCP</a> (but you may as well use some other connection pool, like <a href="http://jolbox.com/">BoneCP</a>, <a href="https://sourceforge.net/projects/c3p0/">C3P0</a>, <a href="https://github.com/brettwooldridge/HikariCP">HikariCP</a>, and various others).</li>
<li><a href="http://spring.io/guides/gs/managing-transactions">Spring TX</a> as the transaction management library.</li>
<li><a href="http://www.jooq.org">jOOQ</a> as the <reference id="sql-building" title="SQL building"/> and <reference id="sql-execution" title="execution"/> library.</li>
</ul>
<p>Before you copy the manual examples, consider also these further resources:</p>
<ul>
<li><a href="https://github.com/jOOQ/jOOQ/tree/master/jOOQ-examples/jOOQ-spring-example">The complete example can also be downloaded from GitHub</a>.</li>
<li><a href="https://github.com/jOOQ/jOOQ/tree/master/jOOQ-examples/jOOQ-spring-guice-example">Another example using Spring and Guice for transaction management can be downloaded from GitHub</a>.</li>
<li><a href="http://www.petrikainulainen.net/programming/jooq/using-jooq-with-spring-configuration/">Another, excellent tutorial by Petri Kainulainen can be found here</a>.</li>
</ul>
<h3>Add the required Maven dependencies</h3>
<p>
For this example, we'll create the following Maven dependencies
</p>
</html><xml><![CDATA[<!-- Use this or the latest Spring RELEASE version -->
<properties>
<org.springframework.version>3.2.3.RELEASE</org.springframework.version>
</properties>
<dependencies>
<!-- Database access -->
<dependency>
<groupId>org.jooq</groupId>
<artifactId>jooq</artifactId>
<version>{jooq.version}</version>
</dependency>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-dbcp2</artifactId>
<version>2.0</version>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<version>1.3.168</version>
</dependency>
<!-- Logging -->
<dependency>
<groupId>log4j</groupId>
<artifactId>log4j</artifactId>
<version>1.2.16</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-log4j12</artifactId>
<version>1.7.5</version>
</dependency>
<!-- Spring (transitive dependencies are not listed explicitly) -->
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-context</artifactId>
<version>${org.springframework.version}</version>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-jdbc</artifactId>
<version>${org.springframework.version}</version>
</dependency>
<!-- Testing -->
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.11</version>
<type>jar</type>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-test</artifactId>
<version>${org.springframework.version}</version>
<scope>test</scope>
</dependency>
</dependencies>
]]></xml><html>
<p>
Note that only the jOOQ Open Source Edition is available from Maven Central. If you're using the jOOQ Professional Edition or the jOOQ Enterprise Edition, you will have to manually install jOOQ in your local Nexus, or in your local Maven cache. For more information, please refer to the <a href="http://www.jooq.org/licensing">licensing pages</a>.
</p>
<h3>Create a minimal Spring configuration file</h3>
<p>
The above dependencies are configured together using a Spring Beans configuration:
</p>
</html><xml><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:tx="http://www.springframework.org/schema/tx"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-3.2.xsd">
<!-- This is needed if you want to use the @Transactional annotation -->
<tx:annotation-driven transaction-manager="transactionManager"/>
<bean id="dataSource" class="org.apache.commons.dbcp2.BasicDataSource" destroy-method="close" >
<!-- These properties are replaced by Maven "resources" -->
<property name="url" value="${db.url}" />
<property name="driverClassName" value="${db.driver}" />
<property name="username" value="${db.username}" />
<property name="password" value="${db.password}" />
</bean>
<!-- Configure Spring's transaction manager to use a DataSource -->
<bean id="transactionManager"
class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
<property name="dataSource" ref="dataSource" />
</bean>
<!-- Configure jOOQ's ConnectionProvider to use Spring's TransactionAwareDataSourceProxy,
which can dynamically discover the transaction context -->
<bean id="transactionAwareDataSource"
class="org.springframework.jdbc.datasource.TransactionAwareDataSourceProxy">
<constructor-arg ref="dataSource" />
</bean>
<bean class="org.jooq.impl.DataSourceConnectionProvider" name="connectionProvider">
<constructor-arg ref="transactionAwareDataSource" />
</bean>
<!-- Configure the DSL object, optionally overriding jOOQ Exceptions with Spring Exceptions -->
<bean id="dsl" class="org.jooq.impl.DefaultDSLContext">
<constructor-arg ref="config" />
</bean>
<bean id="exceptionTranslator" class="org.jooq.example.spring.exception.ExceptionTranslator" />
<!-- Invoking an internal, package-private constructor for the example
Implement your own Configuration for more reliable behaviour -->
<bean class="org.jooq.impl.DefaultConfiguration" name="config">
<property name="SQLDialect"><value type="org.jooq.SQLDialect">H2</value></property>
<property name="connectionProvider" ref="connectionProvider" />
<property name="executeListenerProvider">
<array>
<bean class="org.jooq.impl.DefaultExecuteListenerProvider">
<constructor-arg index="0" ref="exceptionTranslator"/>
</bean>
</array>
</property>
</bean>
<!-- This is the "business-logic" -->
<bean id="books" class="org.jooq.example.spring.impl.DefaultBookService"/>
</beans>]]></xml><html>
<h3>Run a query using the above configuration:</h3>
<p>
With the above configuration, you should be ready to run queries pretty quickly. For instance, in an integration-test, you could use Spring to run JUnit:
</p>
</html><java><![CDATA[@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = {"/jooq-spring.xml"})
public class QueryTest {
@Autowired
DSLContext create;
@Test
public void testJoin() throws Exception {
// All of these tables were generated by jOOQ's Maven plugin
Book b = BOOK.as("b");
Author a = AUTHOR.as("a");
BookStore s = BOOK_STORE.as("s");
BookToBookStore t = BOOK_TO_BOOK_STORE.as("t");
Result<Record3<String, String, Integer>> result =
create.select(a.FIRST_NAME, a.LAST_NAME, countDistinct(s.NAME))
.from(a)
.join(b).on(b.AUTHOR_ID.equal(a.ID))
.join(t).on(t.BOOK_ID.equal(b.ID))
.join(s).on(t.BOOK_STORE_NAME.equal(s.NAME))
.groupBy(a.FIRST_NAME, a.LAST_NAME)
.orderBy(countDistinct(s.NAME).desc())
.fetch();
assertEquals(2, result.size());
assertEquals("Paulo", result.getValue(0, a.FIRST_NAME));
assertEquals("George", result.getValue(1, a.FIRST_NAME));
assertEquals("Coelho", result.getValue(0, a.LAST_NAME));
assertEquals("Orwell", result.getValue(1, a.LAST_NAME));
assertEquals(Integer.valueOf(3), result.getValue(0, countDistinct(s.NAME)));
assertEquals(Integer.valueOf(2), result.getValue(1, countDistinct(s.NAME)));
}
}]]></java><html>
<h3>Run a queries in an explicit transaction:</h3>
<p>
The following example shows how you can use Spring's TransactionManager to explicitly handle transactions:
</p>
</html><java><![CDATA[@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = {"/jooq-spring.xml"})
@TransactionConfiguration(transactionManager="transactionManager")
public class TransactionTest {
@Autowired DSLContext dsl;
@Autowired DataSourceTransactionManager txMgr;
@Autowired BookService books;
@After
public void teardown() {
// Delete all books that were created in any test
dsl.delete(BOOK).where(BOOK.ID.gt(4)).execute();
}
@Test
public void testExplicitTransactions() {
boolean rollback = false;
TransactionStatus tx = txMgr.getTransaction(new DefaultTransactionDefinition());
try {
// This is a "bug". The same book is created twice, resulting in a
// constraint violation exception
for (int i = 0; i < 2; i++)
dsl.insertInto(BOOK)
.set(BOOK.ID, 5)
.set(BOOK.AUTHOR_ID, 1)
.set(BOOK.TITLE, "Book 5")
.execute();
Assert.fail();
}
// Upon the constraint violation, we explicitly roll back the transaction.
catch (DataAccessException e) {
txMgr.rollback(tx);
rollback = true;
}
assertEquals(4, dsl.fetchCount(BOOK));
assertTrue(rollback);
}
}]]></java><html>
<h3>Run queries using declarative transactions</h3>
<p>
Spring-TX has very powerful means to handle transactions declaratively, using the <code><a href="http://docs.spring.io/spring/docs/4.0.0.RELEASE/javadoc-api/org/springframework/transaction/annotation/Transactional.html">@Transactional</a></code> annotation. The <code>BookService</code> that we had defined in the previous Spring configuration can be seen here:
</p>
</html><java><![CDATA[public interface BookService {
/**
* Create a new book.
* <p>
* The implementation of this method has a bug, which causes this method to
* fail and roll back the transaction.
*/
@Transactional
void create(int id, int authorId, String title);
}]]></java><html>
<p>
And here is how we interact with it:
</p>
</html><java><![CDATA[
@Test
public void testDeclarativeTransactions() {
boolean rollback = false;
try {
// The service has a "bug", resulting in a constraint violation exception
books.create(5, 1, "Book 5");
Assert.fail();
}
catch (DataAccessException ignore) {
rollback = true;
}
assertEquals(4, dsl.fetchCount(BOOK));
assertTrue(rollback);
}
]]></java><html>
<h3>Run queries using jOOQ's transaction API</h3>
<p>
jOOQ has its own programmatic transaction API that can be used with Spring transactions by implementing the jOOQ <reference class="org.jooq.TransactionProvider"/> SPI and passing that to your jOOQ <reference id="dsl-context" title="Configuration"/>. More details about this transaction API can be found in the <reference id="transaction-management" title="manual's section about transaction management"/>.
</p>
<p>
<a href="https://github.com/jOOQ/jOOQ/tree/master/jOOQ-examples/jOOQ-spring-example">You can try the above example yourself by downloading it from GitHub</a>.
</p>
</html></content>
</section>
<section id="jooq-with-flyway">
<title>Using jOOQ with Flyway</title>
<content><html>
<p>
<a href="http://www.flywaydb.org"><img src="&lt;?=$root?&gt;/img/partner/flyway-logo-transparent-300.png" alt="Flyway - Database Migrations Made Easy" align="left" width="200"/></a>When performing database migrations, we at Data Geekery recommend using jOOQ with Flyway - Database Migrations Made Easy. In this chapter, we're going to look into a simple way to get started with the two frameworks.
</p>
<h3>Philosophy</h3>
<p>
There are a variety of ways how jOOQ and Flyway could interact with each other in various development setups. In this tutorial we're going to show just one variant of such framework team play - a variant that we find particularly compelling for most use cases.
</p>
<p>
The general philosophy behind the following approach can be summarised as this:
</p>
<ul>
<li><strong>1. Database increment</strong></li>
<li><strong>2. Database migration</strong></li>
<li><strong>3. Code re-generation</strong></li>
<li><strong>4. Development</strong></li>
</ul>
<p>
The four steps above can be repeated time and again, every time you need to modify something in your database. More concretely, let's consider:
</p>
<ul>
<li><strong>1. Database increment</strong> - You need a new column in your database, so you write the necessary DDL in a Flyway script</li>
<li><strong>2. Database migration</strong> - This Flyway script is now part of your deliverable, which you can share with all developers who can migrate their databases with it, the next time they check out your change</li>
<li><strong>3. Code re-generation</strong> - Once the database is migrated, you regenerate all jOOQ artefacts (see <reference id="code-generation" title="code generation"/>), locally</li>
<li><strong>4. Development</strong> - You continue developing your business logic, writing code against the udpated, generated database schema</li>
</ul>
<h3>Maven Project Configuration - Properties</h3>
<p>
The following properties are defined in our pom.xml, to be able to reuse them between plugin configurations:
</p>
</html><xml><![CDATA[<properties>
<db.url>jdbc:h2:~/flyway-test</db.url>
<db.username>sa</db.username>
</properties>
]]></xml><html>
<h3>0. Maven Project Configuration - Dependencies</h3>
<p>
While jOOQ and Flyway could be used in standalone migration scripts, in this tutorial, we'll be using Maven for the standard project setup. You will also find the source code of this tutorial on GitHub at <a href="https://github.com/jOOQ/jOOQ/tree/master/jOOQ-examples/jOOQ-flyway-example">https://github.com/jOOQ/jOOQ/tree/master/jOOQ-examples/jOOQ-flyway-example</a>, and the full <a href="https://github.com/jOOQ/jOOQ/blob/master/jOOQ-examples/jOOQ-flyway-example/pom.xml">pom.xml file here</a>.
</p>
<p>
These are the dependencies that we're using in our Maven configuration:
</p>
</html><xml><![CDATA[<!-- We'll add the latest version of jOOQ and our JDBC driver - in this case H2 -->
<dependency>
<groupId>org.jooq</groupId>
<artifactId>jooq</artifactId>
<version>{jooq-version}</version>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<version>1.4.177</version>
</dependency>
<!-- For improved logging, we'll be using log4j via slf4j to see what's going on during migration and code generation -->
<dependency>
<groupId>log4j</groupId>
<artifactId>log4j</artifactId>
<version>1.2.16</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-log4j12</artifactId>
<version>1.7.5</version>
</dependency>
<!-- To esnure our code is working, we're using JUnit -->
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.11</version>
<scope>test</scope>
</dependency>
]]></xml><html>
<h3>0. Maven Project Configuration - Plugins</h3>
<p>
After the dependencies, let's simply add the Flyway and jOOQ Maven plugins like so. The Flyway plugin:
</p>
</html><xml><![CDATA[<plugin>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-maven-plugin</artifactId>
<version>3.0</version>
<!-- Note that we're executing the Flyway plugin in the "generate-sources" phase -->
<executions>
<execution>
<phase>generate-sources</phase>
<goals>
<goal>migrate</goal>
</goals>
</execution>
</executions>
<!-- Note that we need to prefix the db/migration path with filesystem: to prevent Flyway
from looking for our migration scripts only on the classpath -->
<configuration>
<url>${db.url}</url>
<user>${db.username}</user>
<locations>
<location>filesystem:src/main/resources/db/migration</location>
</locations>
</configuration>
</plugin>
]]></xml><html>
<p>
The above Flyway Maven plugin configuration will read and execute all database migration scripts from <code>src/main/resources/db/migration</code> prior to compiling Java source code. While <a href="http://flywaydb.org/documentation/maven/migrate.html">the official Flyway documentation</a> suggests that migrations be done in the <code>compile</code> phase, the jOOQ code generator relies on such migrations having been done <em>prior</em> to code generation.
</p>
<p>
After the Flyway plugin, we'll add the jOOQ Maven Plugin. For more details, please refer to the <reference id="codegen-configuration" title="manual's section about the code generation configuration"/>.
</p>
</html><xml><![CDATA[<plugin>
<groupId>org.jooq</groupId>
<artifactId>jooq-codegen-maven</artifactId>
<version>${org.jooq.version}</version>
<!-- The jOOQ code generation plugin is also executed in the generate-sources phase, prior to compilation -->
<executions>
<execution>
<phase>generate-sources</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
<!-- This is a minimal working configuration. See the manual's section about the code generator for more details -->
<configuration>
<jdbc>
<url>${db.url}</url>
<user>${db.username}</user>
</jdbc>
<generator>
<database>
<includes>.*</includes>
<inputSchema>FLYWAY_TEST</inputSchema>
</database>
<target>
<packageName>org.jooq.example.flyway.db.h2</packageName>
<directory>target/generated-sources/jooq-h2</directory>
</target>
</generator>
</configuration>
</plugin>
]]></xml><html>
<p>
This configuration will now read the <code>FLYWAY_TEST</code> schema and reverse-engineer it into the <code>target/generated-sources/jooq-h2</code> directory, and within that, into the <code>org.jooq.example.flyway.db.h2</code> package.
</p>
<h3>1. Database increments</h3>
<p>
Now, when we start developing our database. For that, we'll create database increment scripts, which we put into the <code>src/main/resources/db/migration</code> directory, as previously configured for the Flyway plugin. We'll add these files:
</p>
<ul>
<li>V1__initialise_database.sql</li>
<li>V2__create_author_table.sql</li>
<li>V3__create_book_table_and_records.sql</li>
</ul>
<p>
These three scripts model our schema versions 1-3 (note the capital V!). Here are the scripts' contents
</p>
</html><sql><![CDATA[-- V1__initialise_database.sql
DROP SCHEMA flyway_test IF EXISTS;
CREATE SCHEMA flyway_test;
]]></sql>
<sql><![CDATA[-- V2__create_author_table.sql
CREATE SEQUENCE flyway_test.s_author_id START WITH 1;
CREATE TABLE flyway_test.author (
id INT NOT NULL,
first_name VARCHAR(50),
last_name VARCHAR(50) NOT NULL,
date_of_birth DATE,
year_of_birth INT,
address VARCHAR(50),
CONSTRAINT pk_t_author PRIMARY KEY (ID)
);
]]></sql>
<sql><![CDATA[-- V3__create_book_table_and_records.sql
CREATE TABLE flyway_test.book (
id INT NOT NULL,
author_id INT NOT NULL,
title VARCHAR(400) NOT NULL,
CONSTRAINT pk_t_book PRIMARY KEY (id),
CONSTRAINT fk_t_book_author_id FOREIGN KEY (author_id) REFERENCES flyway_test.author(id)
);
INSERT INTO flyway_test.author VALUES (next value for flyway_test.s_author_id, 'George', 'Orwell', '1903-06-25', 1903, null);
INSERT INTO flyway_test.author VALUES (next value for flyway_test.s_author_id, 'Paulo', 'Coelho', '1947-08-24', 1947, null);
INSERT INTO flyway_test.book VALUES (1, 1, '1984');
INSERT INTO flyway_test.book VALUES (2, 1, 'Animal Farm');
INSERT INTO flyway_test.book VALUES (3, 2, 'O Alquimista');
INSERT INTO flyway_test.book VALUES (4, 2, 'Brida');
]]></sql><html>
<h3>2. Database migration and 3. Code regeneration</h3>
<p>
The above three scripts are picked up by Flyway and executed in the order of the versions. This can be seen very simply by executing:
</p>
</html><text>mvn clean install</text><html>
<p>
And then observing the log output from Flyway...
</p>
</html><text><![CDATA[[INFO] --- flyway-maven-plugin:3.0:migrate (default) @ jooq-flyway-example ---
[INFO] Database: jdbc:h2:~/flyway-test (H2 1.4)
[INFO] Validated 3 migrations (execution time 00:00.004s)
[INFO] Creating Metadata table: "PUBLIC"."schema_version"
[INFO] Current version of schema "PUBLIC": << Empty Schema >>
[INFO] Migrating schema "PUBLIC" to version 1
[INFO] Migrating schema "PUBLIC" to version 2
[INFO] Migrating schema "PUBLIC" to version 3
[INFO] Successfully applied 3 migrations to schema "PUBLIC" (execution time 00:00.073s).]]></text><html>
<p>
... and from jOOQ on the console:
</p>
</html><text><![CDATA[[INFO] --- jooq-codegen-maven:{jooq-version}:generate (default) @ jooq-flyway-example ---
[INFO] --- jooq-codegen-maven:{jooq-version}:generate (default) @ jooq-flyway-example ---
[INFO] Using this configuration:
...
[INFO] Generating schemata : Total: 1
[INFO] Generating schema : FlywayTest.java
[INFO] ----------------------------------------------------------
[....]
[INFO] GENERATION FINISHED! : Total: 337.576ms, +4.299ms]]>
</text><html>
<h3>4. Development</h3>
<p>
Note that all of the previous steps are executed automatically, every time someone adds new migration scripts to the Maven module. For instance, a team member might have committed a new migration script, you check it out, rebuild and get the latest jOOQ-generated sources for your own development or integration-test database.
</p>
<p>
Now, that these steps are done, you can proceed writing your database queries. Imagine the following test case
</p>
</html><java><![CDATA[import org.jooq.Result;
import org.jooq.impl.DSL;
import org.junit.Test;
import java.sql.DriverManager;
import static java.util.Arrays.asList;
import static org.jooq.example.flyway.db.h2.Tables.*;
import static org.junit.Assert.assertEquals;
public class AfterMigrationTest {
@Test
public void testQueryingAfterMigration() throws Exception {
try (Connection c = DriverManager.getConnection("jdbc:h2:~/flyway-test", "sa", "")) {
Result<?> result =
DSL.using(c)
.select(
AUTHOR.FIRST_NAME,
AUTHOR.LAST_NAME,
BOOK.ID,
BOOK.TITLE
)
.from(AUTHOR)
.join(BOOK)
.on(AUTHOR.ID.eq(BOOK.AUTHOR_ID))
.orderBy(BOOK.ID.asc())
.fetch();
assertEquals(4, result.size());
assertEquals(asList(1, 2, 3, 4), result.getValues(BOOK.ID));
}
}
}
]]></java><html>
<h3>Reiterate</h3>
<p>
The power of this approach becomes clear once you start performing database modifications this way. Let's assume that the French guy on our team prefers to have things his way:
</p>
</html><sql><![CDATA[-- V4__le_french.sql
ALTER TABLE flyway_test.book ALTER COLUMN title RENAME TO le_titre;
]]></sql><html>
<p>
They check it in, you check out the new database migration script, run
</p>
</html><text>mvn clean install</text><html>
<p>
And then observing the log output:
</p>
</html><text><![CDATA[[INFO] --- flyway-maven-plugin:3.0:migrate (default) @ jooq-flyway-example ---
[INFO] --- flyway-maven-plugin:3.0:migrate (default) @ jooq-flyway-example ---
[INFO] Database: jdbc:h2:~/flyway-test (H2 1.4)
[INFO] Validated 4 migrations (execution time 00:00.005s)
[INFO] Current version of schema "PUBLIC": 3
[INFO] Migrating schema "PUBLIC" to version 4
[INFO] Successfully applied 1 migration to schema "PUBLIC" (execution time 00:00.016s).]]></text><html>
<p>
So far so good, but later on:
</p>
</html><text><![CDATA[[ERROR] COMPILATION ERROR :
[INFO] -------------------------------------------------------------
[ERROR] C:\...\jOOQ-flyway-example\src\test\java\AfterMigrationTest.java:[24,19] error: cannot find symbol
[INFO] 1 error]]></text><html>
<p>
When we go back to our Java integration test, we can immediately see that the TITLE column is still being referenced, but it no longer exists:
</p>
</html><java><![CDATA[public class AfterMigrationTest {
@Test
public void testQueryingAfterMigration() throws Exception {
try (Connection c = DriverManager.getConnection("jdbc:h2:~/flyway-test", "sa", "")) {
Result<?> result =
DSL.using(c)
.select(
AUTHOR.FIRST_NAME,
AUTHOR.LAST_NAME,
BOOK.ID,
BOOK.TITLE
// ^^^^^ This column no longer exists. We'll have to rename it to LE_TITRE
)
.from(AUTHOR)
.join(BOOK)
.on(AUTHOR.ID.eq(BOOK.AUTHOR_ID))
.orderBy(BOOK.ID.asc())
.fetch();
assertEquals(4, result.size());
assertEquals(asList(1, 2, 3, 4), result.getValues(BOOK.ID));
}
}
}
]]></java><html>
<h3>Conclusion</h3>
<p>
This tutorial shows very easily how you can build a rock-solid development process using Flyway and jOOQ to prevent SQL-related errors very early in your development lifecycle - immediately at compile time, rather than in production!
</p>
<p>
Please, visit the <a href="http://www.flywaydb.org">Flyway website</a> for more information about Flyway.
</p>
</html></content>
</section>
<section id="jooq-with-jax-rs">
<title>Using jOOQ with JAX-RS</title>
<content><html>
<p>
In some use-cases, having a lean, single-tier server-side architecture is desirable. Typically, such architectures expose a <a href="http://en.wikipedia.org/wiki/Representational_state_transfer">RESTful</a> API implementing client code and the UI using something like <a href="http://angularjs.org">AngularJS</a>.
</p>
<p>
In Java, the standard API for RESTful applications is <a href="http://docs.oracle.com/javaee/7/tutorial/doc/jaxrs.htm">JAX-RS</a>, which is part of <a href="http://www.oracle.com/us/corporate/press/1957557">JEE 7</a>, along with a standard <a href="http://docs.oracle.com/javaee/7/tutorial/doc/jsonp.htm">JSON implementation</a>. But you can use JAX-RS also outside of a JEE container. The following example shows how to set up a simple license server using these technologies:
</p>
<ul>
<li><a href="http://maven.apache.org/">Maven</a> for building and running</li>
<li><a href="http://www.eclipse.org/jetty/">Jetty</a> as a lightweight Servlet implementation</li>
<li><a href="https://jersey.java.net/">Jersey</a>, the JAX-RS (<a href="http://www.jcp.org/en/jsr/detail?id=311">JSR 311</a> &amp; <a href="http://www.jcp.org/en/jsr/detail?id=339">JSR 339</a>) reference implementation</li>
<li><a href="http://www.jooq.org">jOOQ</a> as a data access layer</li>
</ul>
<p>
For the example, we'll use a PostgreSQL database.
</p>
<h3>Creating the license server database</h3>
<p>
We'll keep the example simple and use a <code>LICENSE</code> table to store all license keys and associated information, whereas a <code>LOG_VERIFY</code> table is used to log access to the license server. Here's the DDL:
</p>
</html><sql><![CDATA[CREATE TABLE LICENSE_SERVER.LICENSE (
ID SERIAL8 NOT NULL,
LICENSE_DATE TIMESTAMP NOT NULL, -- The date when the license was issued
LICENSEE TEXT NOT NULL, -- The e-mail address of the licensee
LICENSE TEXT NOT NULL, -- The license key
VERSION VARCHAR(50) NOT NULL DEFAULT '.*', -- The licensed version(s), a regular expression
CONSTRAINT PK_LICENSE PRIMARY KEY (ID),
CONSTRAINT UK_LICENSE UNIQUE (LICENSE)
);
CREATE TABLE LICENSE_SERVER.LOG_VERIFY (
ID SERIAL8 NOT NULL,
LICENSEE TEXT NOT NULL, -- The licensee whose license is being verified
LICENSE TEXT NOT NULL, -- The license key that is being verified
REQUEST_IP VARCHAR(50) NOT NULL, -- The request IP verifying the license
VERSION VARCHAR(50) NOT NULL, -- The version that is being verified
MATCH BOOLEAN NOT NULL, -- Whether the verification was successful
CONSTRAINT PK_LOG_VERIFY PRIMARY KEY (ID)
);]]></sql><html>
<p>
To make things a bit more interesting (and secure), we'll also push license key generation into the database, by generating it from a stored function as such:
</p>
</html><sql><![CDATA[CREATE OR REPLACE FUNCTION LICENSE_SERVER.GENERATE_KEY(
IN license_date TIMESTAMP WITH TIME ZONE,
IN email TEXT
) RETURNS VARCHAR
AS $$
BEGIN
RETURN 'license-key';
END;
$$ LANGUAGE PLPGSQL;
]]></sql><html>
<p>
The actual algorithm might be using a secret salt to hash the function arguments. For the sake of a tutorial, a constant string will suffice.
</p>
<h3>Setting up the project</h3>
<p>
We're going to be setting up the <reference id="codegen-configuration" title="jOOQ code generator using Maven"/>
</p>
</html><xml><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.jooq</groupId>
<artifactId>jooq-webservices</artifactId>
<packaging>war</packaging>
<version>1.0</version>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.0.2</version>
<configuration>
<source>1.7</source>
<target>1.7</target>
</configuration>
</plugin>
<plugin>
<groupId>org.mortbay.jetty</groupId>
<artifactId>maven-jetty-plugin</artifactId>
<version>6.1.26</version>
<configuration>
<reload>manual</reload>
<stopKey>stop</stopKey>
<stopPort>9966</stopPort>
</configuration>
</plugin>
<plugin>
<groupId>org.jooq</groupId>
<artifactId>jooq-codegen-maven</artifactId>
<version>{jooq-version}</version>
<!-- See GitHub for details -->
</plugin>
</plugins>
</build>
<dependencies>
<dependency>
<groupId>com.sun.jersey</groupId>
<artifactId>jersey-server</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.sun.jersey</groupId>
<artifactId>jersey-json</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.sun.jersey.contribs</groupId>
<artifactId>jersey-spring</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>servlet-api</artifactId>
<version>2.5</version>
</dependency>
<dependency>
<groupId>org.jooq</groupId>
<artifactId>jooq</artifactId>
<version>3.1.0</version>
</dependency>
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>9.2-1003-jdbc4</version>
</dependency>
<dependency>
<groupId>log4j</groupId>
<artifactId>log4j</artifactId>
<version>1.2.16</version>
</dependency>
</dependencies>
</project>]]></xml><html>
<p>
With the above setup, we're now pretty ready to start developing our license service as a JAX-RS service.
</p>
<h3>The license service class</h3>
<p>
Once we've run the <reference id="codegen-configuration" title="jOOQ code generator using Maven"/>, we can write the following service class:
</p>
</html><java><![CDATA[/**
* The license server.
*/
@Path("/license/")
@Component
@Scope("request")
public class LicenseService {
/**
* <code>/license/generate</code> generates and returns a new license key.
*
* @param mail The input email address of the licensee.
*/
@GET
@Produces("text/plain")
@Path("/generate")
public String generate(
final @QueryParam("mail") String mail
) {
return run(new CtxRunnable() {
@Override
public String run(DSLContext ctx) {
Timestamp licenseDate = new Timestamp(System.currentTimeMillis());
// Use the jOOQ query DSL API to generate a license key
return
ctx.insertInto(LICENSE)
.set(LICENSE.LICENSE_, generateKey(inline(licenseDate), inline(mail)))
.set(LICENSE.LICENSE_DATE, licenseDate)
.set(LICENSE.LICENSEE, mail)
.returning()
.fetchOne()
.getLicense();
}
});
}
/**
* <code>/license/verify</code> checks if a given licensee has access to version using a license.
*
* @param request The servlet request from the JAX-RS context.
* @param mail The input email address of the licensee.
* @param license The license used by the licensee.
* @param version The product version being accessed.
*/
@GET
@Produces("text/plain")
@Path("/verify")
public String verify(
final @Context HttpServletRequest request,
final @QueryParam("mail") String mail,
final @QueryParam("license") String license,
final @QueryParam("version") String version
) {
return run(new CtxRunnable() {
@Override
public String run(DSLContext ctx) {
String v = (version == null || version.equals("")) ? "" : version;
// Use the jOOQ query DSL API to generate a log entry
return
ctx.insertInto(LOG_VERIFY)
.set(LOG_VERIFY.LICENSE, license)
.set(LOG_VERIFY.LICENSEE, mail)
.set(LOG_VERIFY.REQUEST_IP, request.getRemoteAddr())
.set(LOG_VERIFY.MATCH, field(
selectCount()
.from(LICENSE)
.where(LICENSE.LICENSEE.eq(mail))
.and(LICENSE.LICENSE_.eq(license))
.and(val(v).likeRegex(LICENSE.VERSION))
.asField().gt(0)))
.set(LOG_VERIFY.VERSION, v)
.returning(LOG_VERIFY.MATCH)
.fetchOne()
.getValue(LOG_VERIFY.MATCH, String.class);
}
});
}
// [...]
}]]></java><html>
<p>
The <code>INSERT INTO LOG_VERIFY</code> query is actually rather interesting. In plain SQL, it would look like this:
</p>
</html><sql><![CDATA[INSERT INTO LOG_VERIFY (LICENSE, LICENSEE, REQUEST_IP, MATCH, VERSION)
VALUES (
:license,
:mail,
:remoteAddr,
(SELECT COUNT(*) FROM LICENSE WHERE LICENSEE = :mail AND LICENSE = :license AND :version ~ VERSION) > 0,
:version
)
RETURNING MATCH;]]></sql><html>
<p>
Apart from the foregoing, the <code>LicenseService</code> also contains a couple of simple utilities:
</p>
</html><java><![CDATA[ /**
* This method encapsulates a transaction and initialises a jOOQ DSLcontext.
* This could also be achieved with Spring and DBCP for connection pooling.
*/
private String run(CtxRunnable runnable) {
Connection c = null;
try {
Class.forName("org.postgresql.Driver");
c = getConnection("jdbc:postgresql:postgres", "postgres", System.getProperty("pw", "test"));
DSLContext ctx = DSL.using(new DefaultConfiguration()
.set(new DefaultConnectionProvider(c))
.set(SQLDialect.POSTGRES)
.set(new Settings().withExecuteLogging(false)));
return runnable.run(ctx);
}
catch (Exception e) {
e.printStackTrace();
Response.status(Status.SERVICE_UNAVAILABLE);
return "Service Unavailable - Please contact support@datageekery.com for help";
}
finally {
JDBCUtils.safeClose(c);
}
}
private interface CtxRunnable {
String run(DSLContext ctx);
}]]></java><html>
<h3>Configuring Spring and Jetty</h3>
<p>
All we need now is to configure Spring...
</p>
</html><xml><![CDATA[<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd">
<context:component-scan base-package="org.jooq.example.jaxrs" />
</beans>]]></xml><html>
<p>
... and Jetty ...
</p>
</html><xml><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>classpath:applicationContext.xml</param-value>
</context-param>
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
<listener>
<listener-class>org.springframework.web.context.request.RequestContextListener</listener-class>
</listener>
<servlet>
<servlet-name>Jersey Spring Web Application</servlet-name>
<servlet-class>com.sun.jersey.spi.spring.container.servlet.SpringServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>Jersey Spring Web Application</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>]]></xml><html>
<p>
... and we're done! We can now run the server with the following command:
</p>
</html><text><![CDATA[mvn jetty:run]]></text><html>
<p>
Or if you need a custom port:
</p>
</html><text><![CDATA[mvn jetty:run -Djetty.port=8088]]></text><html>
<h3>Using the license server</h3>
<p>
You can now use the license server at the following URLs
</p>
</html><text><![CDATA[http://localhost:8088/jooq-jax-rs-example/license/generate?mail=test@example.com
-> license-key
http://localhost:8088/jooq-jax-rs-example/license/verify?mail=test@example.com&license=license-key&version=3.2.0
-> true
http://localhost:8088/jooq-jax-rs-example/license/verify?mail=test@example.com&license=wrong&version=3.2.0
-> false]]></text><html>
<p>
Let's verify what happened, in the database:
</p>
</html><sql><![CDATA[select * from license_server.license
-- id | license_date | licensee | license | version
--------------------------------------------------------------------------
-- 3 | 2013-11-22 14:26:07.768 | test@example.com | license-key | .*
select * from license_server.log_verify
-- id | licensee | license | request_ip | version | match
--------------------------------------------------------------------------
-- 2 | test@example.com | license-key | 0:0:0:0:0:0:0:1 | 3.2.0 | t
-- 5 | test@example.com | wrong | 0:0:0:0:0:0:0:1 | 3.2.0 | f
]]></sql><html>
<h3>Downloading the complete example</h3>
<p>
The complete example can be downloaded for free and under the terms of the <a href="www.apache.org/licenses/LICENSE-2.0">Apache Software License 2.0</a> from here:<br/>
<a href="https://github.com/jOOQ/jOOQ/tree/master/jOOQ-examples/jOOQ-jax-rs-example">https://github.com/jOOQ/jOOQ/tree/master/jOOQ-examples/jOOQ-jax-rs-example</a>
</p>
</html></content>
</section>
<section id="a-simple-web-application">
<title>A simple web application with jOOQ</title>
<content><html>
<p>Feel free to contribute a tutorial!</p>
</html></content>
</section>
</sections>
</section>
<section id="jooq-and-java-8">
<title>jOOQ and Java 8</title>
<content><html>
<p>
Java 8 has introduced a great set of enhancements, among which lambda expressions and the new <reference class="java.util.stream.Stream">Streams API</reference>. These new constructs align very well with jOOQ's fluent API as can be seen in the following examples:
</p>
<h3>
jOOQ and lambda expressions
</h3>
<p>
jOOQ's <reference id="recordmapper" title="RecordMapper"/> API is fully Java-8-ready, which basically means that it is a SAM (Single Abstract Method) type, which can be instanciated using a lambda expression. Consider this example:
</p>
</html><java><![CDATA[try (Connection c = getConnection()) {
String sql = "select schema_name, is_default " +
"from information_schema.schemata " +
"order by schema_name";
DSL.using(c)
.fetch(sql)
// We can use lambda expressions to map jOOQ Records
.map(rs -> new Schema(
rs.getValue("SCHEMA_NAME", String.class),
rs.getValue("IS_DEFAULT", boolean.class)
))
// ... and then profit from the new Collection methods
.forEach(System.out::println);
}]]></java><html>
<p>
The above example shows how jOOQ's <reference class="org.jooq.Result" anchor="#map()" title="Result.map()"/> method can receive a lambda expression that implements <reference id="recordmapper" title="RecordMapper"/> to map from jOOQ <reference class="org.jooq.Record" title="Records"/> to your custom types.
</p>
<h3>
jOOQ and the Streams API
</h3>
<p>
jOOQ's <reference class="org.jooq.Result" title="Result"/> type extends <reference class="java.util.List"/>, which opens up access to a variety of new Java features in Java 8. The following example shows how easy it is to transform a jOOQ <code>Result</code> containing <code>INFORMATION_SCHEMA</code> meta data to produce DDL statements:
</p>
</html><java><![CDATA[DSL.using(c)
.select(
COLUMNS.TABLE_NAME,
COLUMNS.COLUMN_NAME,
COLUMNS.TYPE_NAME
)
.from(COLUMNS)
.orderBy(
COLUMNS.TABLE_CATALOG,
COLUMNS.TABLE_SCHEMA,
COLUMNS.TABLE_NAME,
COLUMNS.ORDINAL_POSITION
)
.fetch() // jOOQ ends here
.stream() // JDK 8 Streams start here
.collect(groupingBy(
r -> r.getValue(COLUMNS.TABLE_NAME),
LinkedHashMap::new,
mapping(
r -> new Column(
r.getValue(COLUMNS.COLUMN_NAME),
r.getValue(COLUMNS.TYPE_NAME)
),
toList()
)
))
.forEach(
(table, columns) -> {
// Just emit a CREATE TABLE statement
System.out.println(
"CREATE TABLE " + table + " (");
// Map each "Column" type into a String
// containing the column specification,
// and join them using comma and
// newline. Done!
System.out.println(
columns.stream()
.map(col -> " " + col.name +
" " + col.type)
.collect(Collectors.joining(",\n"))
);
System.out.println(");");
}
);]]></java><html>
<p>
The above example is explained more in depth in this blog post: <a href="http://blog.jooq.org/2014/04/11/java-8-friday-no-more-need-for-orms/">http://blog.jooq.org/2014/04/11/java-8-friday-no-more-need-for-orms/</a>. For more information about Java 8, consider these resources:
</p>
<ul>
<li>Our <a href="http://blog.jooq.org/tag/java-8/">Java 8 Friday blog series</a></li>
<li>A great <a href="http://www.baeldung.com/java8">Java 8 resources collection by the folks at Baeldung.com</a></li>
</ul>
</html></content>
</section>
<section id="jooq-and-javafx">
<title>jOOQ and JavaFX</title>
<content><html>
<p>
One of the major improvements of Java 8 is the introduction of JavaFX into the JavaSE. With jOOQ and <reference id="jooq-and-javafx" title="Java 8 Streams and lambdas"/>, it is now very easy and idiomatic to transform SQL results into JavaFX <a href="https://docs.oracle.com/javafx/2/api/javafx/scene/chart/XYChart.Series.html"><code>XYChart.Series</code></a> or other, related objects:
</p>
<h3>
Creating a bar chart from a jOOQ Result
</h3>
<p>
As we've seen in the previous <reference id="jooq-and-java-8" title="section about jOOQ and Java 8"/>, jOOQ integrates seamlessly with Java 8's Streams API. The fluent style can be maintained throughout the data transformation chain.
</p>
<p>
In this example, we're going to use Open Data from the <a href="http://data.worldbank.org">world bank</a> to show a comparison of countries GDP and debts:
</p>
</html><sql><![CDATA[DROP SCHEMA IF EXISTS world;
CREATE SCHEMA world;
CREATE TABLE world.countries (
code CHAR(2) NOT NULL,
year INT NOT NULL,
gdp_per_capita DECIMAL(10, 2) NOT NULL,
govt_debt DECIMAL(10, 2) NOT NULL
);
INSERT INTO world.countries
VALUES ('CA', 2009, 40764, 51.3),
('CA', 2010, 47465, 51.4),
('CA', 2011, 51791, 52.5),
('CA', 2012, 52409, 53.5),
('DE', 2009, 40270, 47.6),
('DE', 2010, 40408, 55.5),
('DE', 2011, 44355, 55.1),
('DE', 2012, 42598, 56.9),
('FR', 2009, 40488, 85.0),
('FR', 2010, 39448, 89.2),
('FR', 2011, 42578, 93.2),
('FR', 2012, 39759,103.8),
('GB', 2009, 35455,121.3),
('GB', 2010, 36573, 85.2),
('GB', 2011, 38927, 99.6),
('GB', 2012, 38649,103.2),
('IT', 2009, 35724,121.3),
('IT', 2010, 34673,119.9),
('IT', 2011, 36988,113.0),
('IT', 2012, 33814,131.1),
('JP', 2009, 39473,166.8),
('JP', 2010, 43118,174.8),
('JP', 2011, 46204,189.5),
('JP', 2012, 46548,196.5),
('RU', 2009, 8616, 8.7),
('RU', 2010, 10710, 9.1),
('RU', 2011, 13324, 9.3),
('RU', 2012, 14091, 9.4),
('US', 2009, 46999, 76.3),
('US', 2010, 48358, 85.6),
('US', 2011, 49855, 90.1),
('US', 2012, 51755, 93.8);]]></sql><html>
<p>
Once this data is set up (e.g. in an H2 or PostgreSQL database), we'll run jOOQ's <reference id="code-generation" title="code generator"/> and implement the following code to display our chart:
</p>
</html><java><![CDATA[CategoryAxis xAxis = new CategoryAxis();
NumberAxis yAxis = new NumberAxis();
xAxis.setLabel("Country");
yAxis.setLabel("% of GDP");
BarChart<String, Number> bc = new BarChart<String, Number>(xAxis, yAxis);
bc.setTitle("Government Debt");
bc.getData().addAll(
// SQL data transformation, executed in the database
// -------------------------------------------------
DSL.using(connection)
.select(
COUNTRIES.YEAR,
COUNTRIES.CODE,
COUNTRIES.GOVT_DEBT)
.from(COUNTRIES)
.join(
table(
select(COUNTRIES.CODE, avg(COUNTRIES.GOVT_DEBT).as("avg"))
.from(COUNTRIES)
.groupBy(COUNTRIES.CODE)
).as("c1")
)
.on(COUNTRIES.CODE.eq(fieldByName(String.class, "c1", COUNTRIES.CODE.getName())))
// order countries by their average projected value
.orderBy(
fieldByName("avg"),
COUNTRIES.CODE,
COUNTRIES.YEAR)
// The result produced by the above statement looks like this:
// +----+----+---------+
// |year|code|govt_debt|
// +----+----+---------+
// |2009|RU | 8.70|
// |2010|RU | 9.10|
// |2011|RU | 9.30|
// |2012|RU | 9.40|
// |2009|CA | 51.30|
// +----+----+---------+
// Java data transformation, executed in application memory
// --------------------------------------------------------
// Group results by year, keeping sort order in place
.fetchGroups(COUNTRIES.YEAR)
// Stream<Entry<Integer, Result<Record3<BigDecimal, String, Integer>>>>
.entrySet()
.stream()
// Map each entry into a { Year -> Projected value } series
.map(entry -> new XYChart.Series<>(
entry.getKey().toString(),
observableArrayList(
// Map each country record into a chart Data object
entry.getValue()
.map(country -> new XYChart.Data<String, Number>(
country.getValue(COUNTRIES.CODE),
country.getValue(COUNTRIES.GOVT_DEBT)
))
)
))
.collect(toList())
);]]></java><html>
<p>
The above example uses basic SQL-92 syntax where the countries are ordered using aggregate information from a <reference id="nested-selects" title="nested SELECT"/>, which is supported in all databases. If you're using a database that supports <reference id="window-functions" title="window functions"/>, e.g. PostgreSQL or any commercial database, you could have also written a simpler query like this:00
</p>
</html><java><![CDATA[DSL.using(connection)
.select(
COUNTRIES.YEAR,
COUNTRIES.CODE,
COUNTRIES.GOVT_DEBT)
.from(COUNTRIES)
// order countries by their average projected value
.orderBy(
DSL.avg(COUNTRIES.GOVT_DEBT).over(partitionBy(COUNTRIES.CODE)),
COUNTRIES.CODE,
COUNTRIES.YEAR)
.fetch()
;
return bc;]]></java><html>
<p>
When executed, we'll get nice-looking bar charts like these:
<br/>
<img class="screenshot" src="&lt;?=$root?&gt;/img/jooq-javafx-example-1.png" alt="jOOQ and JavaFX Example"/>
</p>
<p>
The complete example can be downloaded and run from GitHub:
<br/>
<a href="https://github.com/jOOQ/jOOQ/tree/master/jOOQ-examples/jOOQ-javafx-example">https://github.com/jOOQ/jOOQ/tree/master/jOOQ-examples/jOOQ-javafx-example</a>
</p>
</html></content>
</section>
<section id="jooq-and-nashorn">
<title>jOOQ and Nashorn</title>
<content><html>
<p>
With Java 8 and the new built-in JavaScript engine Nashorn, a whole new ecosystem of software can finally make easy use of jOOQ in server-side JavaScript. A very simple example can be seen here:
</p>
</html><javascript><![CDATA[
// Let's assume these objects were generated
// by the jOOQ source code generator
var Tables = Java.type("org.jooq.db.h2.information_schema.Tables");
var t = Tables.TABLES;
var c = Tables.COLUMNS;
// This is the equivalent of Java's static imports
var count = DSL.count;
var row = DSL.row;
// We can now execute the following query:
print(
DSL.using(conn)
.select(
t.TABLE_SCHEMA,
t.TABLE_NAME,
c.COLUMN_NAME)
.from(t)
.join(c)
.on(row(t.TABLE_SCHEMA, t.TABLE_NAME)
.eq(c.TABLE_SCHEMA, c.TABLE_NAME))
.orderBy(
t.TABLE_SCHEMA.asc(),
t.TABLE_NAME.asc(),
c.ORDINAL_POSITION.asc())
.fetch()
);]]></javascript><html>
<p>
<a href="http://blog.jooq.org/2014/06/06/java-8-friday-javascript-goes-sql-with-nashorn-and-jooq/">More details about how to use jOOQ, JDBC, and SQL with Nashorn can be seen here.</a>
</p>
</html></content>
</section>
<section id="jooq-and-scala">
<title>jOOQ and Scala</title>
<content><html>
<p>
As any other library, jOOQ can be easily used in Scala, taking advantage of the many Scala language features such as for example:
</p>
<ul>
<li>Optional "." to dereference methods from expressions</li>
<li>Optional "(" and ")" to delimit method argument lists</li>
<li>Optional ";" at the end of a Scala statement</li>
<li>Type inference using "var" and "val" keywords</li>
<li>Lambda expressions and for-comprehension syntax for record iteration and data type conversion</li>
</ul>
<p>
But jOOQ also leverages other useful Scala features, such as
</p>
<ul>
<li>implicit defs for operator overloading</li>
<li>Scala Macros (soon to come)</li>
</ul>
<p>
All of the above heavily improve jOOQ's querying DSL API experience for Scala developers.
</p>
<p>
A short example jOOQ application in Scala might look like this:
</p>
</html><scala><![CDATA[
import collection.JavaConversions._ // Import implicit defs for iteration over org.jooq.Result
//
import java.sql.DriverManager //
//
import org.jooq._ //
import org.jooq.impl._ //
import org.jooq.impl.DSL._ //
import org.jooq.scala.example.h2.Tables._ //
import org.jooq.scala.Conversions._ // Import implicit defs for overloaded jOOQ/SQL operators
//
object Test { //
def main(args: Array[String]): Unit = { //
val c = DriverManager.getConnection("jdbc:h2:~/test", "sa", ""); // Standard JDBC connection
val e = DSL.using(c, SQLDialect.H2); //
val x = AUTHOR as "x" // SQL-esque table aliasing
//
for (r <- e // Iteration over Result. "r" is an org.jooq.Record3
select ( //
BOOK.ID * BOOK.AUTHOR_ID, // Using the overloaded "*" operator
BOOK.ID + BOOK.AUTHOR_ID * 3 + 4, // Using the overloaded "+" operator
BOOK.TITLE || " abc" || " xy" // Using the overloaded "||" operator
) //
from BOOK // No need to use parentheses or "." here
leftOuterJoin ( //
select (x.ID, x.YEAR_OF_BIRTH) // Dereference fields from aliased table
from x //
limit 1 //
asTable x.getName() //
) //
on BOOK.AUTHOR_ID === x.ID // Using the overloaded "===" operator
where (BOOK.ID <> 2) // Using the olerloaded "<>" operator
or (BOOK.TITLE in ("O Alquimista", "Brida")) // Neat IN predicate expression
fetch //
) { //
println(r) //
} //
} //
}]]></scala><html>
<p>
For more details about jOOQ's Scala integration, please refer to the manual's section about <reference id="scala-sql-building" title="SQL building with Scala"/>.
</p>
</html></content>
</section>
<section id="jooq-and-groovy">
<title>jOOQ and Groovy</title>
<content><html>
<p>
As any other library, jOOQ can be easily used in Groovy, taking advantage of the many Groovy language features such as for example:
</p>
<ul>
<li>Optional ";" at the end of a Groovy statement</li>
<li>Type inference for local variables</li>
</ul>
<p>
While this is less impressive than the features available from a <reference id="jooq-and-scala" title="Scala integration"/>, it is still useful for those of you using jOOQ's querying DSL with Groovy.
</p>
<p>
A short example jOOQ application in Groovy might look like this:
</p>
</html><groovy><![CDATA[package org.jooq.groovy
import static org.jooq.impl.DSL.*
import static org.jooq.groovy.example.h2.Tables.*
import groovy.sql.Sql
import org.jooq.*
import org.jooq.impl.DSL
sql = Sql.newInstance('jdbc:h2:~/groovy-test', 'sa', '', 'org.h2.Driver');
a = AUTHOR.as("a");
b = BOOK.as("b")
DSL.using(sql.connection)
.select(a.FIRST_NAME, a.LAST_NAME, b.TITLE)
.from(a)
.join(b).on(a.ID.eq(b.AUTHOR_ID))
.fetchInto ({
r -> println(
"${r.getValue(a.FIRST_NAME)} " +
"${r.getValue(a.LAST_NAME)} " +
"has written ${r.getValue(b.TITLE)}"
)
} as RecordHandler)]]></groovy><html>
<p>
Note that while Groovy supports <a href="http://groovy.codehaus.org/Operator+Overloading">some means of operator overloading</a>, we think that these means should be avoided in a jOOQ integration. For instance, <code>a + b</code> in Groovy maps to a formal <code>a.plus(b)</code> method invocation, and jOOQ provides the required synonyms in its API to help you write such expressions. Nonetheless, Groovy only offers little typesafety, and as such, operator overloading can lead to many runtime issues.
</p>
<p>
Another caveat of Groovy operator overloading is the fact that operators such as <code>==</code> or <code>>=</code> map to <code>a.equals(b)</code>, <code>a.compareTo(b) == 0</code>, <code>a.compareTo(b) >= 0</code> respectively. This behaviour does not make sense in a fluent API such as jOOQ.
</p>
</html></content>
</section>
<section id="jooq-and-nosql">
<title>jOOQ and NoSQL</title>
<content><html>
<p>
jOOQ users often get excited about jOOQ's intuitive API and would then wish for NoSQL support.
</p>
<p>
There are a variety of NoSQL databases that implement some sort of proprietary query language. Some of these query languages even look like SQL. Examples are <a href="http://www.h2database.com/jcr/grammar.html">JCR-SQL2</a>, <a href="https://cassandra.apache.org/doc/cql/CQL.html">CQL (Cassandra Query Language)</a>, <a href="http://docs.neo4j.org/chunked/stable/cypher-query-lang.html">Cypher (Neo4j's Query Language)</a>, <a href="http://www.salesforce.com/us/developer/docs/officetoolkit/Content/sforce_api_calls_soql.htm">SOQL (Salesforce Query Language)</a> and many more.
</p>
<p>
Mapping the jOOQ API onto these alternative query languages would be a very poor fit and a leaky abstraction. We believe in the power and expressivity of the SQL standard and its various dialects. Databases that extend this standard too much, or implement it not thoroughly enough are often not suitable targets for jOOQ. It would be better to build a new, dedicated API for just that one particular query language.
</p>
<p>
jOOQ is about SQL, and about SQL alone. Read more about our visions in the <reference id="preface" title="manual's preface"/>.
</p>
</html></content>
</section>
<section id="dependencies">
<title>Dependencies</title>
<content><html>
<p>
Dependencies are a big hassle in modern software. Many libraries depend on other, non-JDK library parts that come in different, incompatible versions, potentially causing trouble in your runtime environment. jOOQ has no external dependencies on any third-party libraries.
</p>
<p>
However, the above rule has some exceptions:
</p>
<ul>
<li><reference id="logging" title="logging APIs"/> are referenced as "optional dependencies". jOOQ tries to find <a href="http://www.slf4j.org/">slf4j</a> or <a href="http://logging.apache.org/log4j">log4j</a> on the classpath. If it fails, it will use the <reference class="java.util.logging.Logger"/></li>
<li>Oracle ojdbc types used for array creation are loaded using reflection. The same applies to Postgres PG* types.</li>
<li>Small libraries with compatible licenses are incorporated into jOOQ. These include <a href="https://github.com/jOOQ/jOOR">jOOR</a>, <a href="https://github.com/jOOQ/jOOU">jOOU</a>, parts of <a href="http://opencsv.sourceforge.net/">OpenCSV</a>, <a href="http://code.google.com/p/json-simple/">json simple</a>, parts of <a href="http://commons.apache.org/lang/">commons-lang</a></li>
<li><a href="http://docs.oracle.com/javaee/6/api/javax/persistence/package-summary.html">javax.persistence</a> and <a href="http://docs.oracle.com/javaee/6/api/javax/validation/package-summary.html">javax.validation</a> will be needed if you activate the relevant <reference id="code-generation" title="code generation flags"/></li>
</ul>
</html></content>
</section>
<section id="build-your-own">
<title>Build your own</title>
<content><html>
<p>
In order to build jOOQ (Open Source Edition) yourself, please download the sources from <a href="https://github.com/jOOQ/jOOQ">https://github.com/jOOQ/jOOQ</a> and use Maven to build jOOQ, preferably in Eclipse. jOOQ requires Java 6+ to compile and run.
</p>
<p>
Some useful hints to build jOOQ yourself:
</p>
<ul>
<li>Get the latest version of <a href="http://git-scm.com">Git</a> or <a href="http://www.eclipse.org/egit">EGit</a></li>
<li>Get the latest version of <a href="http://maven.apache.org">Maven</a> or <a href="http://eclipse.org/m2e">M2E</a></li>
<li>Check out the jOOQ sources from <a href="https://github.com/jOOQ/jOOQ">https://github.com/jOOQ/jOOQ</a></li>
<li>Optionally, import Maven artefacts into an Eclipse workspace using the following command (see the <a href="http://maven.apache.org/plugins/maven-eclipse-plugin/">maven-eclipse-plugin</a> documentation for details):
<ul>
<li><code>mvn eclipse:eclipse</code></li>
</ul>
</li>
<li>Build the <code>jooq-parent</code> artefact by using any of these commands:
<ul>
<li><code>mvn clean package</code><br/>create .jar files in <code>${project.build.directory}</code></li>
<li><code>mvn clean install</code><br/>install the .jar files in your local repository (e.g. <code>~/.m2</code>)</li>
<li><code>mvn clean {goal} -Dmaven.test.skip=true</code><br/>don't run unit tests when building artefacts</li>
</ul>
</li>
</ul>
</html></content>
</section>
<section id="semantic-versioning">
<title>jOOQ and backwards-compatibility</title>
<content><html>
<p>
jOOQ follows the rules of semantic versioning according to <a href="http://semver.org">http://semver.org</a> quite strictly. Those rules impose a versioning scheme [X].[Y].[Z] that can be summarised as follows:
</p>
<ul>
<li>If a patch release includes bugfixes, performance improvements and API-irrelevant new features, [Z] is incremented by one.</li>
<li>If a minor release includes backwards-compatible, API-relevant new features, [Y] is incremented by one and [Z] is reset to zero.</li>
<li>If a major release includes backwards-incompatible, API-relevant new features, [X] is incremented by one and [Y], [Z] are reset to zero.</li>
</ul>
<h3>jOOQ's understanding of backwards-compatibility</h3>
<p>
Backwards-compatibility is important to jOOQ. You've chosen jOOQ as a strategic SQL engine and you don't want your SQL to break. That is why there is at most one major release per year, which changes only those parts of jOOQ's API and functionality, which were agreed upon on the user group. During the year, only minor releases are shipped, adding new features in a backwards-compatible way
</p>
<p>
However, there are some elements of API evolution that would be considered backwards-incompatible in other APIs, but not in jOOQ. As discussed later on in the section about <reference id="dsl-and-non-dsl" title="jOOQ's query DSL API"/>, much of jOOQ's API is indeed an internal domain-specific language implemented mostly using Java interfaces. Adding language elements to these interfaces means any of these actions:
</p>
<ul>
<li>Adding methods to the interface</li>
<li>Overloading methods for convenience</li>
<li>Changing the type hierarchy of interfaces</li>
</ul>
<p>
It becomes obvious that it would be impossible to add new language elements (e.g. new <reference id="column-expressions" title="SQL functions"/>, new <reference id="select-statement" title="SELECT clauses"/>) to the API without breaking any client code that actually implements those interfaces. Hence, the following rule should be observed:
</p>
<p>
jOOQ's DSL interfaces should not be implemented by client code! Extend only those extension points that are explicitly documented as "extendable" (e.g. <reference id="custom-queryparts" title="custom QueryParts"/>)
</p>
<h3>jOOQ-codegen and jOOQ-meta</h3>
<p>
While a reasonable amount of care is spent to maintain these two modules under the rules of semantic versioning, it may well be that minor releases introduce backwards-incompatible changes. This will be announced in the respective release notes and should be the exception.
</p>
</html></content>
</section>
</sections>
</section>
<section id="sql-building">
<title>SQL building</title>
<content><html>
<p>
SQL is a declarative language that is hard to integrate into procedural, object-oriented, functional or any other type of programming languages. jOOQ's philosophy is to give SQL the credit it deserves and integrate SQL itself as an <a href="http://en.wikipedia.org/wiki/Domain_Specific_Language">"internal domain specific language"</a> directly into Java.
</p>
<p>
With this philosophy in mind, SQL building is the main feature of jOOQ. All other features (such as <reference id="sql-execution" title="SQL execution"/> and <reference id="code-generation" title="code generation"/>) are mere convenience built on top of jOOQ's SQL building capabilities.
</p>
<p>
This section explains all about the various syntax elements involved with jOOQ's SQL building capabilities. For a complete overview of all syntax elements, please refer to the manual's sections about <reference id="dsl-mapping-rules" title="SQL to DSL mapping rules"/> as well as <reference id="reference-bnf-notation" title="jOOQ's BNF notation"/>
</p>
</html></content>
<sections>
<redirect id="factory" redirect-to="dsl">
<redirect id="factory-subclasses" redirect-to="dsl-subclasses"/>
</redirect>
<section id="dsl">
<title>The query DSL type</title>
<content><html>
<p>
jOOQ exposes a lot of interfaces and hides most implementation facts from client code. The reasons for this are:
</p>
<ul>
<li>Interface-driven design. This allows for modelling queries in a fluent API most efficiently</li>
<li>Reduction of complexity for client code.</li>
<li>API guarantee. You only depend on the exposed interfaces, not concrete (potentially dialect-specific) implementations.</li>
</ul>
<p>
The <reference class="org.jooq.impl.DSL"/> class is the main class from where you will create all jOOQ objects. It serves as a static factory for <reference id="table-expressions" title="table expressions"/>, <reference id="column-expressions" title="column expressions"/> (or "fields"), <reference id="conditional-expressions" title="conditional expressions"/> and many other <reference id="queryparts" title="QueryParts"/>.
</p>
<h3>The static query DSL API</h3>
<p>
With jOOQ 2.0, static factory methods have been introduced in order to make client code look more like SQL. Ideally, when working with jOOQ, you will simply static import all methods from the DSL class:
</p>
</html><java>import static org.jooq.impl.DSL.*;</java><html>
<p>
Note, that when working with Eclipse, you could also add the DSL to your favourites. This will allow to access functions even more fluently:
</p>
</html><java>concat(trim(FIRST_NAME), trim(LAST_NAME));
// ... which is in fact the same as:
DSL.concat(DSL.trim(FIRST_NAME), DSL.trim(LAST_NAME));</java>
</content>
<sections>
<section id="dsl-subclasses">
<title>DSL subclasses</title>
<content><html>
<p>
There are a couple of subclasses for the general query DSL. Each SQL dialect has its own dialect-specific DSL. For instance, if you're only using the MySQL dialect, you can choose to reference the MySQLDSL instead of the standard DSL:
</p>
<p>
The advantage of referencing a dialect-specific DSL lies in the fact that you have access to more proprietary RDMBS functionality. This may include:
</p>
<ul>
<li>MySQL's encryption functions</li>
<li>PL/SQL constructs, pgplsql, or any other dialect's ROUTINE-language (maybe in the future)</li>
</ul>
</html></content>
</section>
</sections>
</section>
<redirect id="executor" redirect-to="dsl-context">
<redirect id="sql-dialects" redirect-to="sql-dialects"/>
<redirect id="connection-vs-datasource" redirect-to="connection-vs-datasource"/>
<redirect id="custom-data" redirect-to="custom-data"/>
<redirect id="custom-execute-listeners" redirect-to="custom-execute-listeners"/>
<redirect id="custom-settings" redirect-to="custom-settings"/>
<redirect id="runtime-schema-mapping" redirect-to="runtime-schema-mapping"/>
</redirect>
<section id="dsl-context">
<title>The DSLContext class</title>
<content><html>
<p>
DSLContext references a <reference class="org.jooq.Configuration"/>, an object that configures jOOQ's behaviour when executing queries (see <reference id="sql-execution"/> for more details). Unlike the static DSL, the DSLContext allow for creating <reference id="sql-statements" title="SQL statements"/> that are already "configured" and ready for execution.
</p>
<h3>Fluent creation of a DSLContext object</h3>
<p>
The DSLContext object can be created fluently from the <reference id="dsl" title="DSL type"/>:
</p>
</html><java><![CDATA[// Create it from a pre-existing configuration
DSLContext create = DSL.using(configuration);
// Create it from ad-hoc arguments
DSLContext create = DSL.using(connection, dialect);]]></java><html>
<p>
If you do not have a reference to a pre-existing Configuration object (e.g. created from <reference class="org.jooq.impl.DefaultConfiguration"/>), the various overloaded <code>DSL.using()</code> methods will create one for you.
</p>
<h3>Contents of a Configuration object</h3>
<p>
A Configuration can be supplied with these objects:
</p>
<ul>
<li><reference class="org.jooq.SQLDialect"/> : The dialect of your database. This may be any of the currently supported database types (see <reference id="sql-dialects"/> for more details)</li>
<li><reference class="org.jooq.conf.Settings"/> : An optional runtime configuration (see <reference id="custom-settings"/> for more details)</li>
<li><reference class="org.jooq.ExecuteListenerProvider"/> : An optional reference to a provider class that can provide execute listeners to jOOQ (see <reference id="execute-listeners"/> for more details)</li>
<li><reference class="org.jooq.RecordMapperProvider"/> : An optional reference to a provider class that can provide record mappers to jOOQ (see <reference id="pojos-with-recordmapper-provider"/> for more details)</li>
<li>
Any of these:
<ul>
<li><reference class="java.sql.Connection"/> : An optional JDBC Connection that will be re-used for the whole lifecycle of your Configuration (see <reference id="connection-vs-datasource"/> for more details). For simplicity, this is the use-case referenced from this manual, most of the time.</li>
<li><reference class="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 <reference id="connection-vs-datasource"/> for more details)</li>
<li><reference class="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 <reference id="connection-vs-datasource"/> for more details)</li>
</ul>
</li>
</ul>
<p>
Wrapping a Configuration object, a DSLContext can construct <reference id="sql-statements" title="statements"/>, for later <reference id="sql-execution" title="execution"/>. An example is given here:
</p>
</html><java><![CDATA[// 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();]]></java><html>
<p>
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:
</p>
</html><java><![CDATA[// Execute a statement from a single execution chain:
Result<?> result =
DSL.using(connection, dialect)
.select()
.from(BOOK)
.where(BOOK.TITLE.like("Animal%"))
.fetch();]]></java>
</content>
<sections>
<section id="sql-dialects">
<title>SQL Dialect</title>
<content><html>
<p>
While jOOQ tries to represent the SQL standard as much as possible, many features are vendor-specific to a given database and to its "SQL dialect". jOOQ models this using the <reference class="org.jooq.SQLDialect"/> enum type.
</p>
<p>
The SQL dialect is one of the main attributes of a <reference id="dsl-context" title="Configuration"/>. Queries created from DSLContexts will assume dialect-specific behaviour when <reference id="sql-rendering" title="rendering SQL"/> and <reference id="variable-binding" title="binding bind values"/>.
</p>
<p>
Some parts of the jOOQ API are officially supported only by a given subset of the supported SQL dialects. For instance, the <reference id="connect-by-clause" title="Oracle CONNECT BY clause"/>, which is supported by the Oracle and CUBRID databases, is annotated with a <reference class="org.jooq.Support"/> annotation, as such:
</p>
</html><java><![CDATA[/**
* Add an Oracle-specific <code>CONNECT BY</code> clause to the query
*/
@Support({ SQLDialect.CUBRID, SQLDialect.ORACLE })
SelectConnectByConditionStep<R> connectBy(Condition condition);]]></java><html>
<p>
jOOQ API methods which are not annotated with the <reference class="org.jooq.Support"/> annotation, or which are annotated with the Support annotation, but without any SQL dialects can be safely used in all SQL dialects. An example for this is the <reference id="select-statement" title="SELECT statement"/> factory method:
</p>
</html><java><![CDATA[/**
* Create a new DSL select statement.
*/
@Support
SelectSelectStep<R> select(Field<?>... fields);]]></java><html>
<h3>jOOQ's SQL clause simulation capabilities</h3>
<p>
The aforementioned Support annotation does not only designate, which databases natively support a feature. It also indicates that a feature is simulated by jOOQ for some databases lacking this feature. An example of this is the <reference id="distinct-predicate" title="DISTINCT predicate"/>, a predicate syntax defined by SQL:1999 and implemented only by H2, HSQLDB, and Postgres:
</p>
</html><sql><![CDATA[A IS DISTINCT FROM B]]></sql><html>
<p>
Nevertheless, the <code>IS DISTINCT FROM</code> predicate is supported by jOOQ in all dialects, as its semantics can be expressed with an equivalent <reference id="case-expressions" title="CASE expression"/>. For more details, see the manual's section about the <reference id="distinct-predicate" title="DISTINCT predicate"/>.
</p>
<h3>jOOQ and the Oracle SQL dialect</h3>
<p>
Oracle SQL is much more expressive than many other SQL dialects. It features many unique keywords, clauses and functions that are out of scope for the SQL standard. Some examples for this are
</p>
<ul>
<li>The <reference id="connect-by-clause" title="CONNECT BY clause"/>, for hierarchical queries</li>
<li>The <reference id="pivot-tables" title="PIVOT"/> keyword for creating PIVOT tables</li>
<li><reference id="oracle-packages" title="Packages"/>, <reference id="oracle-member-procedures" title="object-oriented user-defined types, member procedures"/> as described in the section about <reference id="stored-procedures" title="stored procedures and functions"/></li>
<li>Advanced analytical functions as described in the section about <reference id="window-functions" title="window functions"/></li>
</ul>
<p>
jOOQ has a historic affinity to Oracle's SQL extensions. If something is supported in Oracle SQL, it has a high probability of making it into the jOOQ API
</p>
</html></content>
</section>
<section id="sql-dialect-family">
<title>SQL Dialect Family</title>
<content><html>
<p>
In jOOQ 3.1, the notion of a <code>SQLDialect.family()</code> was introduced, in order to group several similar <reference id="sql-dialects" title="SQL dialects"/> into a common family. An example for this is SQL Server, which is supported by jOOQ in various versions:
</p>
<ul>
<li> <reference class="org.jooq.SQLDialect" title="SQL Server" anchor="#SQLSERVER"/>: The "version-less" SQL Server version. This always maps to the latest supported version of SQL Server</li>
<li> <reference class="org.jooq.SQLDialect" title="SQL Server 2012" anchor="#SQLSERVER2012"/>: The SQL Server version 2012</li>
<li> <reference class="org.jooq.SQLDialect" title="SQL Server 2008" anchor="#SQLSERVER2008"/>: The SQL Server version 2008</li>
</ul>
<p>
In the above list, <code>SQLSERVER</code> is both a dialect and a family of three dialects. This distinction is used internally by jOOQ to distinguish whether to use the <reference id="limit-clause" title="OFFSET .. FETCH"/> clause (SQL Server 2012), or whether to simulate it using <code>ROW_NUMBER() OVER()</code> (SQL Server 2008).
</p>
</html></content>
</section>
<section id="connection-vs-datasource">
<title>Connection vs. DataSource</title>
<content><html>
<h3>Interact with JDBC Connections</h3>
<p>
While you can use jOOQ for <reference id="sql-building" title="SQL building"/> only, you can also run queries against a JDBC <reference class="java.sql.Connection"/>. Internally, jOOQ creates <reference class="java.sql.Statement"/> or <reference class="java.sql.PreparedStatement"/> objects from such a Connection, in order to execute statements. The normal operation mode is to provide a <reference id="dsl-context" title="Configuration"/> with a JDBC Connection, whose lifecycle you will control yourself. This means that jOOQ will not actively close connections, rollback or commit transactions.
</p>
<p>
Note, in this case, jOOQ will internally use a <reference class="org.jooq.impl.DefaultConnectionProvider"/>, which you can reference directly if you prefer that. The DefaultConnectionProvider exposes various transaction-control methods, such as commit(), rollback(), etc.
</p>
<h3>Interact with JDBC DataSources</h3>
<p>
If you're in a J2EE or Spring context, however, you may wish to use a <reference class="javax.sql.DataSource"/> instead. Connections obtained from such a DataSource will be closed after query execution by jOOQ. The semantics of such a close operation should be the returning of the connection into a connection pool, not the actual closing of the underlying connection. Typically, this makes sense in an environment using distributed JTA transactions. An example of using DataSources with jOOQ can be seen in the tutorial section about <reference id="jooq-with-spring" title="using jOOQ with Spring"/>.
</p>
<p>
Note, in this case, jOOQ will internally use a <reference class="org.jooq.impl.DataSourceConnectionProvider"/>, which you can reference directly if you prefer that.
</p>
<h3>Inject custom behaviour</h3>
<p>
If your specific environment works differently from any of the above approaches, you can inject your own custom implementation of a ConnectionProvider into jOOQ. This is the API contract you have to fulfil:
</p>
</html><java><![CDATA[public interface ConnectionProvider {
// Provide jOOQ with a connection
Connection acquire() throws DataAccessException;
// Get a connection back from jOOQ
void release(Connection connection) throws DataAccessException;
}]]></java><html>
<p>
Note that <code>acquire()</code> should always return the same Connection until this connection is returned via <code>release()</code>
</p>
</html></content>
</section>
<section id="custom-data">
<title>Custom data</title>
<content><html>
<p>
In advanced use cases of integrating your application with jOOQ, you may want to put custom data into your <reference id="dsl-context" title="Configuration"/>, which you can then access from your...
</p>
<ul>
<li><reference id="custom-execute-listeners" title="Custom ExecuteListeners"/></li>
<li><reference id="custom-queryparts" title="Custom QueryParts"/></li>
</ul>
<p>
Here is an example of how to use the custom data API. Let's assume that you have written an <reference id="execute-listeners" title="ExecuteListener"/>, that prevents <code>INSERT</code> statements, when a given flag is set to <code>true</code>:
</p>
</html><java><![CDATA[// Implement an ExecuteListener
public class NoInsertListener extends DefaultExecuteListener {
@Override
public void start(ExecuteContext ctx) {
// This listener is active only, when your custom flag is set to true
if (Boolean.TRUE.equals(ctx.configuration().data("com.example.my-namespace.no-inserts"))) {
// If active, fail this execution, if an INSERT statement is being executed
if (ctx.query() instanceof Insert) {
throw new DataAccessException("No INSERT statements allowed");
}
}
}
}]]></java><html>
<p>
See the manual's section about <reference id="execute-listeners" title="ExecuteListeners"/> to learn more about how to implement an <code>ExecuteListener</code>.
</p>
<p>
Now, the above listener can be added to your <reference id="dsl-context" title="Configuration"/>, but you will also need to pass the flag to the <code>Configuration</code>, in order for the listener to work:
</p>
</html><java><![CDATA[// Create your Configuration
Configuration configuration = new DefaultConfiguration().set(connection).set(dialect);
// Set a new execute listener provider onto the configuration:
configuration.set(new DefaultExecuteListenerProvider(new NoInsertListener()));
// Use any String literal to identify your custom data
configuration.data("com.example.my-namespace.no-inserts", true);
// Try to execute an INSERT statement
try {
DSL.using(configuration)
.insertInto(AUTHOR, AUTHOR.ID, AUTHOR.LAST_NAME)
.values(1, "Orwell")
.execute();
// You shouldn't get here
Assert.fail();
}
// Your NoInsertListener should be throwing this exception here:
catch (DataAccessException expected) {
Assert.assertEquals("No INSERT statements allowed", expected.getMessage());
}]]></java><html>
<p>
Using the <code>data()</code> methods, you can store and retrieve custom data in your <code>Configurations</code>.
</p>
</html></content>
</section>
<section id="custom-execute-listeners">
<title>Custom ExecuteListeners</title>
<content><html>
<p>
<code>ExecuteListeners</code> are a useful tool to...
</p>
<ul>
<li>implement custom logging</li>
<li>apply triggers written in Java</li>
<li>collect query execution statistics</li>
</ul>
<p>
ExecuteListeners are hooked into your <reference id="dsl-context" title="Configuration"/> by returning them from an <reference class="org.jooq.ExecuteListenerProvider"/>:
</p>
</html><java><![CDATA[// Create your Configuration
Configuration configuration = new DefaultConfiguration().set(connection).set(dialect);
// Hook your listener providers into the configuration:
configuration.set(
new DefaultExecuteListenerProvider(new MyFirstListener()),
new DefaultExecuteListenerProvider(new PerformanceLoggingListener()),
new DefaultExecuteListenerProvider(new NoInsertListener())
);]]></java><html>
<p>
See the manual's section about <reference id="execute-listeners" title="ExecuteListeners"/> to see examples of such listener implementations.
</p>
</html></content>
</section>
<section id="custom-settings">
<title>Custom Settings</title>
<content><html>
<p>
The jOOQ Configuration allows for some optional configuration elements to be used by advanced users. The <reference class="org.jooq.conf.Settings" /> class is a JAXB-annotated type, that can be provided to a Configuration in several ways:
</p>
<ul>
<li>In the DSLContext constructor (<code>DSL.using()</code>). This will override default settings below</li>
<li>in the <reference class="org.jooq.impl.DefaultConfiguration"/> constructor. This will override default settings below</li>
<li>From a location specified by a JVM parameter: -Dorg.jooq.settings</li>
<li>From the classpath at /jooq-settings.xml</li>
<li>From the settings defaults, as specified in <a href="http://www.jooq.org/xsd/jooq-runtime-{runtime-xsd-version}.xsd" title="The jOOQ Runtime configuration XSD">http://www.jooq.org/xsd/jooq-runtime-{runtime-xsd-version}.xsd</a></li>
</ul>
<h3>Example</h3>
<p>
For example, if you want to indicate to jOOQ, that it should inline all bind variables, and execute static <reference class="java.sql.Statement"/> instead of binding its variables to <reference class="java.sql.PreparedStatement"/>, you can do so by creating the following DSLContext:
</p>
</html><java><![CDATA[Settings settings = new Settings();
settings.setStatementType(StatementType.STATIC_STATEMENT);
DSLContext create = DSL.using(connection, dialect, settings);]]></java><html>
<p>
Subsequent sections of the manual contain some more in-depth explanations about these settings and what is controlled by these settings:
</p>
<ul>
<li>
<reference id="schema-mapping" title="Runtime schema and table mapping"/>
</li>
<li>
<reference id="names" title="Names and identifiers"/>
</li>
<li>
<reference id="optimistic-locking" title="Execute CRUD with optimistic locking enabled"/>
</li>
<li>
<reference id="logging" title="Enabling DEBUG logging of all executed SQL"/>
</li>
</ul>
<h3>All Settings</h3>
<p>
This section of the manual explains all the available Settings flags as available from the <a href="http://www.jooq.org/xsd/jooq-runtime-{runtime-xsd-version}.xsd" title="The jOOQ Runtime configuration XSD">XSD specification</a>.
</p>
</html>
<xml><![CDATA[<settings>
<!-- Whether any schema name should be rendered at all.
Use this for single-schema environments, or when all objects are made
available using synonyms.
Defaults to "true" -->
<renderSchema>false</renderSchema>
<!-- Configure render mapping for runtime schema / table rewriting in
generated SQL. This is described in another section of the manual -->
<renderMapping>...</renderMapping>
<!-- Whether rendered schema, table, column names, etc should be quoted
in rendered SQL, or transformed in any other way.
- "Quoted", `Quoted`, or [Quoted] : QUOTED
- UPPER_CASED : UPPER
- lower_cased : LOWER
- CasedAsReportedByTheDatabase : AS_IS
Defaults to "QUOTED" -->
<renderNameStyle>LOWER</renderNameStyle>
<!-- Whether SQL keywords should be rendered with upper or lower case.
Defaults to "LOWER" -->
<renderKeywordStyle>UPPER</renderKeywordStyle>
<!-- Whether rendered SQL should be pretty-printed.
Defaults to "false" -->
<renderFormatted>false</renderFormatted>
<!-- Whether rendered bind values should be rendered as:
- question marks : INDEXED
- named parameters : NAMED
- inlined values : INLINED
Defaults to "INDEXED".
This value is overridden by statementType == STATIC_STATEMENT, in
case of which, this defaults to INLINED -->
<paramType>INDEXED</paramType>
<!-- The type of statement that is to be executed.
- PreparedStatement with bind values : PREPARED_STATEMENT
- Statement without bind values : STATIC_STATEMENT
Defaults to "PREPARED_STATEMENT" -->
<statementType>PREPARED_STATEMENT</statementType>
<!-- When set to true, this will add jOOQ's default logging ExecuteListeners
Defaults to "true" -->
<executeLogging>true</executeLogging>
<!-- Whether store() and delete() methods should be executed with optimistic locking.
Defaults to "false" -->
<executeWithOptimisticLocking>false</executeWithOptimisticLocking>
<!-- Whether fetched records should be attached to the fetching configuration.
Defaults to "true" -->
<attachRecords>true</attachRecords>
<!-- Whether primary key values are deemed to be "updatable" in jOOQ
Setting this to "true" will allow for updating primary key values through
UpdatableRecord.store() and UpdatableRecord.update()
Defaults to "false" -->
<updatablePrimaryKeys>false</updatablePrimaryKeys>
</settings>]]></xml>
<html>
<h3>More details</h3>
<p>
Please refer to the jOOQ runtime configuration XSD for more details:<br/>
<a href="http://www.jooq.org/xsd/jooq-runtime-{runtime-xsd-version}.xsd" title="The jOOQ Runtime configuration XSD">http://www.jooq.org/xsd/jooq-runtime-{runtime-xsd-version}.xsd</a>
</p>
</html></content>
</section>
<section id="runtime-schema-mapping">
<title>Runtime schema and table mapping</title>
<content><html>
<h3>Mapping your DEV schema to a productive environment</h3>
<p>
You may wish to design your database in a way that you have several instances of your schema. This is useful when you want to cleanly separate data belonging to several customers / organisation units / branches / users and put each of those entities' data in a separate database or schema.
</p>
<p>
In our AUTHOR example this would mean that you provide a book reference database to several companies, such as My Book World and Books R Us. In that case, you'll probably have a schema setup like this:
</p>
<ul>
<li>DEV: Your development schema. This will be the schema that you base code generation upon, with jOOQ </li>
<li>MY_BOOK_WORLD: The schema instance for My Book World </li>
<li>BOOKS_R_US: The schema instance for Books R Us </li>
</ul>
<h3>Mapping DEV to MY_BOOK_WORLD with jOOQ</h3>
<p>
When a user from My Book World logs in, you want them to access the MY_BOOK_WORLD schema using classes generated from DEV. This can be achieved with the <reference class="org.jooq.conf.RenderMapping"/> class, that you can equip your Configuration's <reference id="custom-settings" title="settings"/> with. Take the following example:
</p>
</html><java>Settings settings = new Settings()
.withRenderMapping(new RenderMapping()
.withSchemata(
new MappedSchema().withInput("DEV")
.withOutput("MY_BOOK_WORLD")));
// Add the settings to the DSLContext
DSLContext create = DSL.using(connection, SQLDialect.ORACLE, settings);
// Run queries with the "mapped" Configuration
create.selectFrom(AUTHOR).fetch();</java><html>
<p>
The query executed with a Configuration equipped with the above mapping will in fact produce this SQL statement:
</p>
</html><sql>SELECT * FROM MY_BOOK_WORLD.AUTHOR</sql><html>
<p>
Even if AUTHOR was generated from DEV.
</p>
<h3>Mapping several schemata</h3>
<p>
Your development database may not be restricted to hold only one DEV schema. You may also have a LOG schema and a MASTER schema. Let's say the MASTER schema is shared among all customers, but each customer has their own LOG schema instance. Then you can enhance your RenderMapping like this (e.g. using an XML configuration file):
</p>
</html><xml><![CDATA[<settings xmlns="http://www.jooq.org/xsd/jooq-runtime-{runtime-xsd-version}.xsd">
<renderMapping>
<schemata>
<schema>
<input>DEV</input>
<output>MY_BOOK_WORLD</output>
</schema>
<schema>
<input>LOG</input>
<output>MY_BOOK_WORLD_LOG</output>
</schema>
</schemata>
</renderMapping>
</settings>]]></xml><html>
<p>
Note, you can load the above XML file like this:
</p>
</html><java>Settings settings = JAXB.unmarshal(new File("jooq-runtime.xml"), Settings.class);</java><html>
<p>
This will map generated classes from DEV to MY_BOOK_WORLD, from LOG to MY_BOOK_WORLD_LOG, but leave the MASTER schema alone. Whenever you want to change your mapping configuration, you will have to create a new Configuration.
</p>
<h3>Using a default schema</h3>
<p>
If you wish not to render any schema name at all, use the following Settings property for this:
</p>
</html><java>Settings settings = new Settings()
.withRenderSchema(false);
// Add the settings to the Configuration
DSLContext create = DSL.using(connection, SQLDialect.ORACLE, settings);
// Run queries that omit rendering schema names
create.selectFrom(AUTHOR).fetch();</java><html>
<h3>Mapping of tables</h3>
<p>
Not only schemata can be mapped, but also tables. If you are not the owner of the database your application connects to, you might need to install your schema with some sort of prefix to every table. In our examples, this might mean that you will have to map DEV.AUTHOR to something MY_BOOK_WORLD.MY_APP__AUTHOR, where MY_APP__ is a prefix applied to all of your tables. This can be achieved by creating the following mapping:
</p>
</html><java>Settings settings = new Settings()
.withRenderMapping(new RenderMapping()
.withSchemata(
new MappedSchema().withInput("DEV")
.withOutput("MY_BOOK_WORLD")
.withTables(
new MappedTable().withInput("AUTHOR")
.withOutput("MY_APP__AUTHOR"))));
// Add the settings to the Configuration
DSLContext create = DSL.using(connection, SQLDialect.ORACLE, settings);
// Run queries with the "mapped" configuration
create.selectFrom(AUTHOR).fetch();</java><html>
<p>
The query executed with a Configuration equipped with the above mapping will in fact produce this SQL statement:
</p>
</html><sql>SELECT * FROM MY_BOOK_WORLD.MY_APP__AUTHOR</sql><html>
<p>
Table mapping and schema mapping can be applied independently, by specifying several MappedSchema entries in the above configuration. jOOQ will process them in order of appearance and map at first match. Note that you can always omit a MappedSchema's output value, in case of which, only the table mapping is applied. If you omit a MappedSchema's input value, the table mapping is applied to all schemata!
</p>
<h3>Hard-wiring mappings at code-generation time</h3>
<p>
Note that the manual's section about <reference id="schema-mapping" title="code generation schema mapping"/> explains how you can hard-wire your schema mappings at code generation time
</p>
</html></content>
</section>
</sections>
</section>
<section id="sql-statements">
<title>SQL Statements (DML)</title>
<content><html>
<p>
jOOQ currently supports 5 types of SQL statements. All of these statements are constructed from a DSLContext instance with an optional <reference id="connection-vs-datasource" title="JDBC Connection or DataSource"/>. If supplied with a Connection or DataSource, they can be executed. Depending on the <reference id="query-vs-resultquery" title="query type"/>, executed queries can return results.
</p>
</html></content>
<sections>
<section id="dsl-and-non-dsl">
<title>jOOQ's DSL and model API</title>
<content><html>
<p>
jOOQ ships with its own DSL (or <a href="http://en.wikipedia.org/wiki/Domain-specific_language" title="Domain Specific Language">Domain Specific Language</a>) that simulates SQL in Java. This means, that you can write SQL statements almost as if Java natively supported it, just like .NET's C# does with <a href="http://msdn.microsoft.com/en-us/library/bb425822.aspx">LINQ to SQL.</a>
</p>
<p>
Here is an example to illustrate what that means:
</p>
</html><code-pair><sql><![CDATA[-- Select all books by authors born after 1920,
-- named "Paulo" from a catalogue:
SELECT *
FROM author a
JOIN book b ON a.id = b.author_id
WHERE a.year_of_birth > 1920
AND a.first_name = 'Paulo'
ORDER BY b.title]]></sql>
<java><![CDATA[Result<Record> result =
create.select()
.from(AUTHOR.as("a"))
.join(BOOK.as("b")).on(a.ID.equal(b.AUTHOR_ID))
.where(a.YEAR_OF_BIRTH.greaterThan(1920)
.and(a.FIRST_NAME.equal("Paulo")))
.orderBy(b.TITLE)
.fetch();]]></java></code-pair><html>
<p>
We'll see how the aliasing works later in the section about <reference id="aliased-tables" title="aliased tables"/>
</p>
<h3>jOOQ as an internal domain specific language in Java (a.k.a. the DSL API)</h3>
<p>
Many other frameworks have similar APIs with similar feature sets. Yet, what makes jOOQ special is its informal <reference id="reference-bnf-notation" title="BNF notation"/> modelling a unified SQL dialect suitable for many vendor-specific dialects, and implementing that BNF notation as a hierarchy of interfaces in Java. This concept is extremely powerful, when <reference id="jooq-in-modern-ides" title="using jOOQ in modern IDEs" /> with syntax completion. Not only can you code much faster, your SQL code will be compile-checked to a certain extent. An example of a DSL query equivalent to the previous one is given here:
</p>
</html><java><![CDATA[DSLContext create = DSL.using(connection, dialect);
Result<?> result = create.select()
.from(AUTHOR)
.join(BOOK).on(BOOK.AUTHOR_ID.equal(AUTHOR.ID))
.fetch();]]></java><html>
<p>
Unlike other, simpler frameworks that use <a href="http://en.wikipedia.org/wiki/Fluent_interface">"fluent APIs"</a> or <a href="http://en.wikipedia.org/wiki/Method_chaining">"method chaining"</a>, jOOQ's BNF-based interface hierarchy will not allow bad query syntax. The following will not compile, for instance:
</p>
</html><java><![CDATA[DSLContext create = DSL.using(connection, dialect);
Result<?> result = create.select()
.join(BOOK).on(BOOK.AUTHOR_ID.equal(AUTHOR.ID))
// ^^^^ "join" is not possible here
.from(AUTHOR)
.fetch();
Result<?> result = create.select()
.from(AUTHOR)
.join(BOOK)
.fetch();
// ^^^^^ "on" is missing here
Result<?> result = create.select(rowNumber())
// ^^^^^^^^^ "over()" is missing here
.from(AUTHOR)
.fetch();
Result<?> result = create.select()
.from(AUTHOR)
.where(AUTHOR.ID.in(select(BOOK.TITLE).from(BOOK)))
// ^^^^^^^^^^^^^^^^^^
// AUTHOR.ID is of type Field<Integer> but subselect returns Record1<String>
.fetch();
Result<?> result = create.select()
.from(AUTHOR)
.where(AUTHOR.ID.in(select(BOOK.AUTHOR_ID, BOOK.ID).from(BOOK)))
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
// AUTHOR.ID is of degree 1 but subselect returns Record2<Integer, Integer>
.fetch();]]></java><html>
<h3>History of SQL building and incremental query building (a.k.a. the model API)</h3>
<p>
Historically, jOOQ started out as an object-oriented SQL builder library like any other. This meant that all queries and their syntactic components were modeled as so-called <reference id="queryparts" title="QueryParts"/>, which delegate <reference id="sql-rendering" title="SQL rendering"/> and <reference id="variable-binding" title="variable binding"/> to child components. This part of the API will be referred to as the model API (or non-DSL API), which is still maintained and used internally by jOOQ for incremental query building. An example of incremental query building is given here:
</p>
</html><java><![CDATA[DSLContext create = DSL.using(connection, dialect);
SelectQuery<Record> query = create.selectQuery();
query.addFrom(AUTHOR);
// Join books only under certain circumstances
if (join) {
query.addJoin(BOOK, BOOK.AUTHOR_ID.equal(AUTHOR.ID));
}
Result<?> result = query.fetch();]]></java><html>
<p>
This query is equivalent to the one shown before using the DSL syntax. In fact, internally, the DSL API constructs precisely this SelectQuery object. Note, that you can always access the SelectQuery object to switch between DSL and model APIs:
</p>
</html><java><![CDATA[DSLContext create = DSL.using(connection, dialect);
SelectFinalStep<?> select = create.select().from(AUTHOR);
// Add the JOIN clause on the internal QueryObject representation
SelectQuery<?> query = select.getQuery();
query.addJoin(BOOK, BOOK.AUTHOR_ID.equal(AUTHOR.ID));]]></java><html>
<h3>Mutability</h3>
<p>
Note, that for historic reasons, the DSL API mixes mutable and immutable behaviour with respect to the internal representation of the <reference id="queryparts" title="QueryPart"/> being constructed. While creating <reference id="conditional-expressions" title="conditional expressions"/>, <reference id="column-expressions" title="column expressions"/> (such as functions) assumes immutable behaviour, creating <reference id="sql-statements" title="SQL statements"/> does not. In other words, the following can be said:
</p>
</html><java><![CDATA[// Conditional expressions (immutable)
// -----------------------------------
Condition a = BOOK.TITLE.equal("1984");
Condition b = BOOK.TITLE.equal("Animal Farm");
// The following can be said
a != a.or(b); // or() does not modify a
a.or(b) != a.or(b); // or() always creates new objects
// Statements (mutable)
// --------------------
SelectFromStep<?> s1 = select();
SelectJoinStep<?> s2 = s1.from(BOOK);
SelectJoinStep<?> s3 = s1.from(AUTHOR);
// The following can be said
s1 == s2; // The internal object is always the same
s2 == s3; // The internal object is always the same]]></java><html>
<p>
On the other hand, beware that you can always extract and modify <reference id="bind-values" title="bind values"/> from any <code>QueryPart</code>.
</p>
</html></content>
</section>
<section id="with-clause">
<title>The WITH clause</title>
<content><html>
<p>
The SQL:1999 standard specifies the <code>WITH</code> clause to be an optional clause for the <reference id="select-statement" title="SELECT statement"/>, in order to specify common table expressions (also: CTE). Many other databases (such as PostgreSQL, SQL Server) also allow for using common table expressions also in other DML clauses, such as the <reference id="insert-statement" title="INSERT statement"/>, <reference id="update-statement" title="UPDATE statement"/>, <reference id="delete-statement" title="DELETE statement"/>, or <reference id="merge-statement" title="MERGE statement"/>.
</p>
<p>
When using common table expressions with jOOQ, there are essentially two approaches:
</p>
<ul>
<li>Declaring and assigning common table expressions explicitly to <reference id="names" title="names"/></li>
<li>Inlining common table expressions into a <reference id="select-statement" title="SELECT statement"/></li>
</ul>
<h3>Explicit common table expressions</h3>
<p>
The following example makes use of <reference id="names" title="names"/> to construct common table expressions, which can then be supplied to a <code>WITH</code> clause or a <code>FROM</code> clause of a <reference id="select-statement" title="SELECT statement"/>:
</p>
</html><code-pair>
<sql><![CDATA[-- Pseudo-SQL for a common table expression specification
"t1" ("f1", "f2") AS (SELECT 1, 'a')
]]></sql>
<java><![CDATA[// Code for creating a CommonTableExpression instance
name("t1").fields("f1", "f2").as(select(val(1), val("a")));]]></java>
</code-pair><html>
<p>
The above expression can be assigned to a variable in Java and then be used to create a full <reference id="select-statement" title="SELECT statement"/>:
</p>
</html><code-pair>
<sql><![CDATA[
WITH "t1" ("f1", "f2") AS (SELECT 1, 'a'),
"t2" ("f3", "f4") AS (SELECT 2, 'b')
SELECT
"t1"."f1" + "t2"."f3" AS "add",
"t1"."f2" || "t2"."f4" AS "concat"
FROM "t1", "t2"
;
]]></sql>
<java><![CDATA[CommonTableExpression<Record2<Integer, String>> t1 =
name("t1").fields("f1", "f2").as(select(val(1), val("a")));
CommonTableExpression<Record2<Integer, String>> t2 =
name("t2").fields("f3", "f4").as(select(val(2), val("b")));
Result<?> result2 =
create.with(t1)
.with(t2)
.select(
t1.field("f1").add(t2.field("f3")).as("add"),
t1.field("f2").concat(t2.field("f4")).as("concat"))
.from(t1, t2)
.fetch();
]]></java>
</code-pair><html>
<p>
Note that the <reference class="org.jooq.CommonTableExpression"/> type extends the commonly used <reference class="org.jooq.Table"/> type, and can thus be used wherever a table can be used.
</p>
<h3>Inlined common table expressions</h3>
<p>
If you're just operating on <reference id="plain-sql" title="plain SQL"/>, you may not need to keep intermediate references to such common table expressions. An example of such usage would be this:
</p>
</html><code-pair>
<sql><![CDATA[
WITH "a" AS (SELECT
1 AS "x",
'a' AS "y"
)
SELECT
FROM "a"
;
]]></sql>
<java><![CDATA[create.with("a").as(select(
val(1).as("x"),
val("a").as("y")
))
.select()
.from(tableByName("a"))
.fetch();
]]></java>
</code-pair><html>
<h3>Recursive common table expressions</h3>
<p>
The various SQL dialects do not agree on the use of <code>RECURSIVE</code> when writing recursive common table expressions. When using jOOQ, always use the <reference class="org.jooq.DSLContext" title="DSLContext.withRecursive()" anchor="#withRecursive-org.jooq.CommonTableExpression...-"/> or <reference class="org.jooq.impl.DSL" title="DSL.withRecursive()" anchor="#withRecursive-org.jooq.CommonTableExpression...-"/> methods, and jOOQ will render the <code>RECURSIVE</code> keyword, if needed.
</p>
</html></content>
</section>
<section id="select-statement">
<title>The SELECT statement</title>
<content><html>
<p>
When you don't just perform <reference id="crud-with-updatablerecords" title="CRUD"/> (i.e. SELECT * FROM your_table WHERE ID = ?), you're usually generating new record types using custom projections. With jOOQ, this is as intuitive, as if using SQL directly. A more or less complete example of the "standard" SQL syntax, plus some extensions, is provided by a query like this:
</p>
<h3>SELECT from a complex table expression</h3>
</html><code-pair>
<sql><![CDATA[-- get all authors' first and last names, and the number
-- of books they've written in German, if they have written
-- more than five books in German in the last three years
-- (from 2011), and sort those authors by last names
-- limiting results to the second and third row, locking
-- the rows for a subsequent update... whew!
SELECT AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME, COUNT(*)
FROM AUTHOR
JOIN BOOK ON AUTHOR.ID = BOOK.AUTHOR_ID
WHERE BOOK.LANGUAGE = 'DE'
AND BOOK.PUBLISHED > '2008-01-01'
GROUP BY AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME
HAVING COUNT(*) > 5
ORDER BY AUTHOR.LAST_NAME ASC NULLS FIRST
LIMIT 2
OFFSET 1
FOR UPDATE]]></sql>
<java><![CDATA[// And with jOOQ...
DSLContext create = DSL.using(connection, dialect);
create.select(AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME, count())
.from(AUTHOR)
.join(BOOK).on(BOOK.AUTHOR_ID.equal(AUTHOR.ID))
.where(BOOK.LANGUAGE.equal("DE"))
.and(BOOK.PUBLISHED.greaterThan("2008-01-01"))
.groupBy(AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME)
.having(count().greaterThan(5))
.orderBy(AUTHOR.LAST_NAME.asc().nullsFirst())
.limit(1)
.offset(2)
.forUpdate()
.fetch();]]></java>
</code-pair><html>
<p>
Details about the various clauses of this query will be provided in subsequent sections.
</p>
<h3>SELECT from single tables</h3>
<p>
A very similar, but limited API is available, if you want to select from single tables in order to retrieve <reference id="crud-with-updatablerecords" title="TableRecords or even UpdatableRecords"/>. The decision, which type of select to create is already made at the very first step, when you create the <code>SELECT</code> statement with the DSL or DSLContext types:
</p>
</html><java><![CDATA[public <R extends Record> SelectWhereStep<R> selectFrom(Table<R> table);]]></java><html>
<p>
As you can see, there is no way to further restrict/project the selected fields. This just selects all known TableFields in the supplied Table, and it also binds &lt;R extends Record&gt; to your Table's associated Record. An example of such a Query would then be:
</p>
</html><java><![CDATA[BookRecord book = create.selectFrom(BOOK)
.where(BOOK.LANGUAGE.equal("DE"))
.orderBy(BOOK.TITLE)
.fetchAny();]]></java><html>
<p>
The "reduced" SELECT API is limited in the way that it skips DSL access to any of these clauses:
</p>
<ul>
<li><reference id="select-clause"/></li>
<li><reference id="join-clause"/></li>
</ul>
<p>
In most parts of this manual, it is assumed that you do not use the "reduced" SELECT API. For more information about the simple SELECT API, see the manual's section about <reference id="record-vs-tablerecord" title="fetching strongly or weakly typed records"/>.
</p>
</html></content>
<sections>
<section id="select-clause">
<title>The SELECT clause</title>
<content><html>
<p>
The SELECT clause lets you project your own record types, referencing table fields, functions, arithmetic expressions, etc. The DSL type provides several methods for expressing a SELECT clause:
</p>
</html><code-pair>
<sql><![CDATA[-- The SELECT clause
SELECT BOOK.ID, BOOK.TITLE
SELECT BOOK.ID, TRIM(BOOK.TITLE)
]]></sql>
<java><![CDATA[// Provide a varargs Fields list to the SELECT clause:
Select<?> s1 = create.select(BOOK.ID, BOOK.TITLE);
Select<?> s2 = create.select(BOOK.ID, trim(BOOK.TITLE));]]></java>
</code-pair><html>
<p>
Some commonly used projections can be easily created using convenience methods:
</p>
</html><code-pair>
<sql><![CDATA[-- Simple SELECTs
SELECT COUNT(*)
SELECT 0 -- Not a bind variable
SELECT 1 -- Not a bind variable
]]></sql>
<java><![CDATA[// Select commonly used values
Select<?> select1 = create.selectCount().fetch();
Select<?> select2 = create.selectZero().fetch();
Select<?> select2 = create.selectOne().fetch();]]></java>
</code-pair><html>
<p>
See more details about functions and expressions in the manual's section about <reference id="column-expressions"/>
</p>
<h3>The SELECT DISTINCT clause</h3>
<p>
The DISTINCT keyword can be included in the method name, constructing a SELECT clause
</p>
</html><code-pair>
<sql><![CDATA[SELECT DISTINCT BOOK.TITLE]]></sql>
<java><![CDATA[Select<?> select1 = create.selectDistinct(BOOK.TITLE).fetch();]]></java>
</code-pair><html>
<h3>SELECT *</h3>
<p>
jOOQ does not explicitly support the asterisk operator in projections. However, you can omit the projection as in these examples:
</p>
</html><java><![CDATA[// Explicitly selects all columns available from BOOK
create.select().from(BOOK).fetch();
// Explicitly selects all columns available from BOOK and AUTHOR
create.select().from(BOOK, AUTHOR).fetch();
create.select().from(BOOK).crossJoin(AUTHOR).fetch();
// Renders a SELECT * statement, as columns are unknown to jOOQ
create.select().from(tableByName("BOOK")).fetch();]]></java><html>
<h3>Typesafe projections with degree up to {max-row-degree}</h3>
<p>
Since jOOQ 3.0, <reference id="record-n" title="records"/> and <reference id="row-value-expressions" title="row value expressions"/> up to degree {max-row-degree} are now generically typesafe. This is reflected by an overloaded <code>SELECT</code> (and <code>SELECT DISTINCT</code>) API in both DSL and DSLContext. An extract from the DSL type:
</p>
</html><java><![CDATA[// Non-typesafe select methods:
public static SelectSelectStep<Record> select(Collection<? extends Field<?>> fields);
public static SelectSelectStep<Record> select(Field<?>... fields);
// Typesafe select methods:
public static <T1> SelectSelectStep<Record1<T1>> select(Field<T1> field1);
public static <T1, T2> SelectSelectStep<Record2<T1, T2>> select(Field<T1> field1, Field<T2> field2);
public static <T1, T2, T3> SelectSelectStep<Record3<T1, T2, T3>> select(Field<T1> field1, Field<T2> field2, Field<T3> field3);
// [...]]]></java><html>
<p>
Since the generic R type is bound to some <reference id="record-n" title="Record[N]"/>, the associated T type information can be used in various other contexts, e.g. the <reference id="in-predicate" title="IN predicate"/>. Such a <code>SELECT</code> statement can be assigned typesafely:
</p>
</html><java><![CDATA[Select<Record2<Integer, String>> s1 = create.select(BOOK.ID, BOOK.TITLE);
Select<Record2<Integer, String>> s2 = create.select(BOOK.ID, trim(BOOK.TITLE));]]></java><html>
<p>
For more information about typesafe record types with degree up to {max-row-degree}, see the manual's section about <reference id="record-n" title="Record1 to Record{max-row-degree}"/>.
</p>
</html></content>
</section>
<section id="from-clause">
<title>The FROM clause</title>
<content><html>
<p>
The SQL FROM clause allows for specifying any number of <reference id="table-expressions" title="table expressions"/> to select data from. The following are examples of how to form normal FROM clauses:
</p>
</html><code-pair>
<sql><![CDATA[SELECT 1 FROM BOOK
SELECT 1 FROM BOOK, AUTHOR
SELECT 1 FROM BOOK "b", AUTHOR "a"]]></sql>
<java><![CDATA[create.selectOne().from(BOOK).fetch();
create.selectOne().from(BOOK, AUTHOR).fetch();
create.selectOne().from(BOOK.as("b"), AUTHOR.as("a")).fetch();]]></java>
</code-pair><html>
<p>
Read more about aliasing in the manual's section about <reference id="aliased-tables" title="aliased tables"/>.
</p>
<h3>More advanced table expressions</h3>
<p>
Apart from simple tables, you can pass any arbitrary <reference id="table-expressions" title="table expression"/> to the jOOQ FROM clause. This may include <reference id="array-and-cursor-unnesting" title="unnested cursors"/> in Oracle:
</p>
</html><code-pair>
<sql><![CDATA[SELECT *
FROM TABLE(
DBMS_XPLAN.DISPLAY_CURSOR(null, null, 'ALLSTATS')
);]]></sql>
<java><![CDATA[create.select()
.from(table(
DbmsXplan.displayCursor(null, null, "ALLSTATS")
).fetch();]]></java>
</code-pair><html>
<p>
Note, in order to access the DbmsXplan package, you can use the <reference id="code-generation" title="code generator"/> to generate Oracle's SYS schema.
</p>
<h3>Selecting FROM DUAL with jOOQ</h3>
<p>
In many SQL dialects, FROM is a mandatory clause, in some it isn't. jOOQ allows you to omit the FROM clause, returning just one record. An example:
</p>
</html><code-pair>
<sql><![CDATA[SELECT 1 FROM DUAL
SELECT 1]]></sql>
<java><![CDATA[DSL.using(SQLDialect.ORACLE).selectOne().fetch();
DSL.using(SQLDialect.POSTGRES).selectOne().fetch();]]></java>
</code-pair><html>
<p>
Read more about dual or dummy tables in the manual's section about <reference id="dual" title="the DUAL table"/>. The following are examples of how to form normal FROM clauses:
</p>
</html></content>
</section>
<section id="join-clause">
<title>The JOIN clause</title>
<content><html>
<p>
jOOQ supports many different types of standard SQL JOIN operations:
</p>
<ul>
<li>[ INNER ] JOIN</li>
<li>LEFT [ OUTER ] JOIN</li>
<li>RIGHT [ OUTER ] JOIN</li>
<li>FULL OUTER JOIN</li>
<li>CROSS JOIN</li>
<li>NATURAL JOIN</li>
<li>NATURAL LEFT [ OUTER ] JOIN</li>
<li>NATURAL RIGHT [ OUTER ] JOIN</li>
</ul>
<p>
Besides, jOOQ also supports
</p>
<ul>
<li>CROSS APPLY (T-SQL and Oracle 12c specific)</li>
<li>OUTER APPLY (T-SQL and Oracle 12c specific)</li>
<li>LATERAL derived tables (PostgreSQL and Oracle 12c)</li>
<li>partitioned outer join</li>
</ul>
<p>
All of these JOIN methods can be called on <reference class="org.jooq.Table"/> types, or directly after the FROM clause for convenience. The following example joins AUTHOR and BOOK
</p>
</html><java><![CDATA[DSLContext create = DSL.using(connection, dialect);
// Call "join" directly on the AUTHOR table
Result<?> result = create.select()
.from(AUTHOR.join(BOOK)
.on(BOOK.AUTHOR_ID.equal(AUTHOR.ID)))
.fetch();
// Call "join" on the type returned by "from"
Result<?> result = create.select()
.from(AUTHOR)
.join(BOOK)
.on(BOOK.AUTHOR_ID.equal(AUTHOR.ID))
.fetch();]]></java><html>
<p>
The two syntaxes will produce the same SQL statement. However, calling "join" on <reference class="org.jooq.Table"/> objects allows for more powerful, nested JOIN expressions (if you can handle the parentheses):
</p>
</html><code-pair>
<sql><![CDATA[SELECT *
FROM AUTHOR
LEFT OUTER JOIN (
BOOK JOIN BOOK_TO_BOOK_STORE
ON BOOK_TO_BOOK_STORE.BOOK_ID = BOOK.ID
)
ON BOOK.AUTHOR_ID = AUTHOR.ID
]]>&#160;</sql>
<java><![CDATA[// Nest joins and provide JOIN conditions only at the end
create.select()
.from(AUTHOR
.leftOuterJoin(BOOK
.join(BOOK_TO_BOOK_STORE)
.on(BOOK_TO_BOOK_STORE.BOOK_ID.equal(BOOK.ID)))
.on(BOOK.AUTHOR_ID.equal(AUTHOR.ID)))
.fetch();]]></java></code-pair><html>
<ul>
<li>See the section about <reference id="conditional-expressions" title="conditional expressions"/> to learn more about the many ways to create <reference class="org.jooq.Condition"/> objects in jOOQ.</li>
<li>See the section about <reference id="table-expressions" title="table expressions"/> to learn about the various ways of referencing <reference class="org.jooq.Table"/> objects in jOOQ</li>
</ul>
<h3>JOIN ON KEY, convenience provided by jOOQ</h3>
<p>
Surprisingly, the SQL standard does not allow to formally JOIN on well-known foreign key relationship information. Naturally, when you join BOOK to AUTHOR, you will want to do that based on the BOOK.AUTHOR_ID foreign key to AUTHOR.ID primary key relation. Not being able to do this in SQL leads to a lot of repetitive code, re-writing the same JOIN predicate again and again - especially, when your foreign keys contain more than one column. With jOOQ, when you use <reference id="code-generation" title="code generation"/>, you can use foreign key constraint information in JOIN expressions as such:
</p>
</html><code-pair>
<sql><![CDATA[SELECT *
FROM AUTHOR
JOIN BOOK ON BOOK.AUTHOR_ID = AUTHOR.ID
]]>&#160;</sql>
<java><![CDATA[create.select()
.from(AUTHOR)
.join(BOOK).onKey()
.fetch();]]></java></code-pair><html>
<p>
In case of ambiguity, you can also supply field references for your foreign keys, or the generated foreign key reference to the onKey() method.
</p>
<p>
Note that formal support for the Sybase <code>JOIN ON KEY</code> syntax is on the roadmap.
</p>
<h3>The JOIN USING syntax</h3>
<p>
Most often, you will provide jOOQ with JOIN conditions in the JOIN .. ON clause. SQL supports a different means of specifying how two tables are to be joined. This is the JOIN .. USING clause. Instead of a condition, you supply a set of fields whose names are common to both tables to the left and right of a JOIN operation. This can be useful when your database schema has a high degree of <a href="http://en.wikipedia.org/wiki/Database_normalization">relational normalisation</a>. An example:
</p>
</html><code-pair>
<sql><![CDATA[-- Assuming that both tables contain AUTHOR_ID columns
SELECT *
FROM AUTHOR
JOIN BOOK USING (AUTHOR_ID)
]]>&#160;</sql>
<java><![CDATA[// join(...).using(...)
create.select()
.from(AUTHOR)
.join(BOOK).using(AUTHOR.AUTHOR_ID)
.fetch();]]></java></code-pair><html>
<p>
In schemas with high degrees of normalisation, you may also choose to use NATURAL JOIN, which takes no JOIN arguments as it joins using all fields that are common to the table expressions to the left and to the right of the JOIN operator. An example:
</p>
</html><code-pair>
<sql><![CDATA[-- Assuming that both tables contain AUTHOR_ID columns
SELECT *
FROM AUTHOR
NATURAL JOIN BOOK
]]>&#160;</sql>
<java><![CDATA[// naturalJoin(...)
create.select()
.from(AUTHOR)
.naturalJoin(BOOK)
.fetch();]]></java></code-pair><html>
<h3>Oracle's partitioned OUTER JOIN</h3>
<p>
Oracle SQL ships with a special syntax available for OUTER JOIN clauses. According to the <a href="http://docs.oracle.com/cd/B28359_01/server.111/b28286/statements_10002.htm#i2196190">Oracle documentation about partitioned outer joins</a> this can be used to fill gaps for simplified analytical calculations. jOOQ only supports putting the PARTITION BY clause to the right of the OUTER JOIN clause. The following example will create at least one record per AUTHOR and per existing value in BOOK.PUBLISHED_IN, regardless if an AUTHOR has actually published a book in that year.
</p>
</html><code-pair>
<sql><![CDATA[SELECT *
FROM AUTHOR
LEFT OUTER JOIN BOOK
PARTITION BY (PUBLISHED_IN)
ON BOOK.AUTHOR_ID = AUTHOR.ID
]]>&#160;</sql>
<java><![CDATA[create.select()
.from(AUTHOR)
.leftOuterJoin(BOOK)
.partitionBy(BOOK.PUBLISHED_IN)
.on(BOOK.AUTHOR_ID.equal(AUTHOR.ID))
.fetch();]]></java></code-pair><html>
<h3>T-SQL's CROSS APPLY and OUTER APPLY</h3>
<p>
T-SQL has long known what the SQL standard calls lateral derived tables, lateral joins using the <code>APPLY</code> keyword. To every row resulting from the table expression on the left, we apply the table expression on the right. This is extremely useful for table-valued functions, which are also supported by jOOQ. Some examples:
</p>
</html><java><![CDATA[DSL.using(configuration)
.select()
.from(AUTHOR,
lateral(select(count().as("c"))
.from(BOOK)
.where(BOOK.AUTHOR_ID.eq(AUTHOR.ID)))
)
.fetch("c", int.class);]]></java><html>
<p>
The above example shows standard usage of the <code>LATERAL</code> keyword to connect a derived table to the previous table in the <reference id="from-clause" title="FROM clause"/>. A similar statement can be written in T-SQL:
</p>
</html><java><![CDATA[DSL.using(configuration)
.from(AUTHOR)
.crossApply(
select(count().as("c"))
.from(BOOK)
.where(BOOK.AUTHOR_ID.eq(AUTHOR.ID))
)
.fetch("c", int.class)]]></java><html>
<p>
<code>LATERAL JOIN</code> or <code>CROSS APPLY</code> are particularly useful together with <reference id="table-valued-functions" title="table valued functions"/>, which are also supported by jOOQ.
</p>
</html></content>
</section>
<section id="where-clause">
<title>The WHERE clause</title>
<content><html>
<p>
The WHERE clause can be used for JOIN or filter predicates, in order to restrict the data returned by the <reference id="table-expressions" title="table expressions"/> supplied to the previously specified <reference id="from-clause" title="from clause"/> and <reference id="join-clause" title="join clause"/>. Here is an example:
</p>
</html><code-pair>
<sql><![CDATA[SELECT *
FROM BOOK
WHERE AUTHOR_ID = 1
AND TITLE = '1984'
]]>&#160;</sql>
<java><![CDATA[create.select()
.from(BOOK)
.where(BOOK.AUTHOR_ID.equal(1))
.and(BOOK.TITLE.equal("1984"))
.fetch();]]></java></code-pair><html>
<p>
The above syntax is convenience provided by jOOQ, allowing you to connect the <reference class="org.jooq.Condition"/> supplied in the WHERE clause with another condition using an AND operator. You can of course also create a more complex condition and supply that to the WHERE clause directly (observe the different placing of parentheses). The results will be the same:
</p>
</html><code-pair>
<sql><![CDATA[SELECT *
FROM BOOK
WHERE AUTHOR_ID = 1
AND TITLE = '1984'
]]>&#160;</sql>
<java><![CDATA[create.select()
.from(BOOK)
.where(BOOK.AUTHOR_ID.equal(1).and(
BOOK.TITLE.equal("1984")))
.fetch();]]></java></code-pair><html>
<p>
You will find more information about creating <reference id="conditional-expressions" title="conditional expressions"/> later in the manual.
</p>
</html></content>
</section>
<section id="connect-by-clause">
<title>The CONNECT BY clause</title>
<content><html>
<p>
The Oracle database knows a very succinct syntax for creating hierarchical queries: the CONNECT BY clause, which is fully supported by jOOQ, including all related functions and pseudo-columns. A more or less formal definition of this clause is given here:
</p>
</html><sql>-- SELECT ..
-- FROM ..
-- WHERE ..
CONNECT BY [ NOCYCLE ] condition [ AND condition, ... ] [ START WITH condition ]
-- GROUP BY ..
-- ORDER [ SIBLINGS ] BY ..</sql><html>
<p>
An example for an iterative query, iterating through values between 1 and 5 is this:
</p>
</html><code-pair>
<sql><![CDATA[SELECT LEVEL
FROM DUAL
CONNECT BY LEVEL <= 5
]]>&#160;</sql>
<java><![CDATA[// Get a table with elements 1, 2, 3, 4, 5
create.select(level())
.connectBy(level().lessOrEqual(5))
.fetch();]]></java></code-pair><html>
<p>
Here's a more complex example where you can recursively fetch directories in your database, and concatenate them to a path:
</p>
</html><code-pair>
<sql><![CDATA[SELECT
SUBSTR(SYS_CONNECT_BY_PATH(DIRECTORY.NAME, '/'), 2)
FROM DIRECTORY
CONNECT BY
PRIOR DIRECTORY.ID = DIRECTORY.PARENT_ID
START WITH DIRECTORY.PARENT_ID IS NULL
ORDER BY 1
]]>&#160;</sql>
<java><![CDATA[.select(
sysConnectByPath(DIRECTORY.NAME, "/").substring(2))
.from(DIRECTORY)
.connectBy(
prior(DIRECTORY.ID).equal(DIRECTORY.PARENT_ID))
.startWith(DIRECTORY.PARENT_ID.isNull())
.orderBy(1)
.fetch();]]></java>
</code-pair><html>
<p>
The output might then look like this
</p>
</html><text>+------------------------------------------------+
|substring |
+------------------------------------------------+
|C: |
|C:/eclipse |
|C:/eclipse/configuration |
|C:/eclipse/dropins |
|C:/eclipse/eclipse.exe |
+------------------------------------------------+
|...21 record(s) truncated...
</text><html>
<p>
Some of the supported functions and pseudo-columns are these (available from the <reference id="dsl" title="DSL"/>):
</p>
<ul>
<li>LEVEL</li>
<li>CONNECT_BY_IS_CYCLE</li>
<li>CONNECT_BY_IS_LEAF</li>
<li>CONNECT_BY_ROOT</li>
<li>SYS_CONNECT_BY_PATH</li>
<li>PRIOR</li>
</ul>
<p>
Note that this syntax is also supported in the CUBRID database and might be simulated in other dialects supporting common table expressions in the future.
</p>
<h3>ORDER SIBLINGS</h3>
<p>
The Oracle database allows for specifying a SIBLINGS keyword in the <reference id="order-by-clause" title="ORDER BY clause"/>. Instead of ordering the overall result, this will only order siblings among each other, keeping the hierarchy intact. An example is given here:
</p>
</html><code-pair>
<sql><![CDATA[SELECT DIRECTORY.NAME
FROM DIRECTORY
CONNECT BY
PRIOR DIRECTORY.ID = DIRECTORY.PARENT_ID
START WITH DIRECTORY.PARENT_ID IS NULL
ORDER SIBLINGS BY 1
]]>&#160;</sql>
<java><![CDATA[.select(DIRECTORY.NAME)
.from(DIRECTORY)
.connectBy(
prior(DIRECTORY.ID).equal(DIRECTORY.PARENT_ID))
.startWith(DIRECTORY.PARENT_ID.isNull())
.orderSiblingsBy(1)
.fetch();]]></java>
</code-pair>
</content>
</section>
<section id="group-by-clause">
<title>The GROUP BY clause</title>
<content><html>
<p>
GROUP BY can be used to create unique groups of data, to form aggregations, to remove duplicates and for other reasons. It will transform your previously defined <reference id="table-expressions" title="set of table expressions"/>, and return only one record per unique group as specified in this clause. For instance, you can group books by BOOK.AUTHOR_ID:
</p>
</html><code-pair>
<sql><![CDATA[SELECT AUTHOR_ID, COUNT(*)
FROM BOOK
GROUP BY AUTHOR_ID
]]>&#160;</sql>
<java><![CDATA[create.select(BOOK.AUTHOR_ID, count())
.from(BOOK)
.groupBy(BOOK.AUTHOR_ID)
.fetch();]]></java></code-pair><html>
<p>
The above example counts all books per author.
</p>
<p>
Note, as defined in the SQL standard, when grouping, you may no longer project any columns that are not a formal part of the GROUP BY clause, or <reference id="aggregate-functions" title="aggregate functions"/>.
</p>
<h3>MySQL's deviation from the SQL standard</h3>
<p>
MySQL has a peculiar way of not adhering to this standard behaviour. This is documented in the <a href="http://dev.mysql.com/doc/refman/5.6/en/group-by-hidden-columns.html">MySQL manual</a>. In short, with MySQL, you can also project any other field that is not part of the GROUP BY clause. The projected values will just be arbitrary values from within the group. You cannot rely on any ordering. For example:
</p>
</html><code-pair>
<sql><![CDATA[SELECT AUTHOR_ID, TITLE
FROM BOOK
GROUP BY AUTHOR_ID
]]>&#160;</sql>
<java><![CDATA[create.select(BOOK.AUTHOR_ID, BOOK.TITLE)
.from(BOOK)
.groupBy(AUTHOR_ID)
.fetch();]]></java></code-pair><html>
<p>
This will return an arbitrary title per author. jOOQ supports this syntax, as jOOQ is not doing any checks internally, about the consistence of tables/fields/functions that you provide it.
</p>
<h3>Empty GROUP BY clauses</h3>
<p>
jOOQ supports empty <code>GROUP BY ()</code> clause as well. This will result in <reference id="select-statement" title="SELECT statements"/> that return only one record.
</p>
</html><code-pair>
<sql><![CDATA[SELECT COUNT(*)
FROM BOOK
GROUP BY ()
]]>&#160;</sql>
<java><![CDATA[create.selectCount()
.from(BOOK)
.groupBy()
.fetch();]]></java></code-pair><html>
<h3>ROLLUP(), CUBE() and GROUPING SETS()</h3>
<p>
Some databases support the SQL standard grouping functions and some extensions thereof. See the manual's section about <reference id="grouping-functions" title="grouping functions"/> for more details.
</p>
</html></content>
</section>
<section id="having-clause">
<title>The HAVING clause</title>
<content><html>
<p>
The HAVING clause is commonly used to further restrict data resulting from a previously issued <reference id="group-by-clause" title="GROUP BY clause"/>. An example, selecting only those authors that have written at least two books:
</p>
</html><code-pair>
<sql><![CDATA[SELECT AUTHOR_ID, COUNT(*)
FROM BOOK
GROUP BY AUTHOR_ID
HAVING COUNT(*) >= 2
]]>&#160;</sql>
<java><![CDATA[create.select(BOOK.AUTHOR_ID, count(*))
.from(BOOK)
.groupBy(AUTHOR_ID)
.having(count().greaterOrEqual(2))
.fetch();]]></java></code-pair><html>
<p>
According to the SQL standard, you may omit the GROUP BY clause and still issue a HAVING clause. This will implicitly GROUP BY (). jOOQ also supports this syntax. The following example selects one record, only if there are at least 4 books in the books table:
</p>
</html><code-pair>
<sql><![CDATA[SELECT COUNT(*)
FROM BOOK
HAVING COUNT(*) >= 4
]]>&#160;</sql>
<java><![CDATA[create.select(count(*))
.from(BOOK)
.having(count().greaterOrEqual(4))
.fetch();]]></java></code-pair>
</content>
</section>
<section id="window-clause">
<title>The WINDOW clause</title>
<content><html>
<p>
The SQL:2003 standard as well as PostgreSQL and Sybase SQL Anywhere support a <code>WINDOW</code> clause that allows for specifying <code>WINDOW</code> frames for reuse in <reference id="select-clause" title="SELECT clauses" /> and <reference id="order-by-clause" title="ORDER BY clauses" />.
</p>
</html><code-pair>
<sql><![CDATA[
SELECT
LAG(first_name, 1) OVER w "prev",
first_name,
LEAD(first_name, 1) OVER w "next"
FROM author
WINDOW w AS (ORDER first_name)
ORDER BY first_name DESC
]]>&#160;</sql>
<java><![CDATA[WindowDefinition w = name("w").as(
orderBy(PEOPLE.FIRST_NAME));
select(
lag(AUTHOR.FIRST_NAME, 1).over(w).as("prev"),
AUTHOR.FIRST_NAME,
lead(AUTHOR.FIRST_NAME, 1).over(w).as("next"))
.from(AUTHOR)
.window(w)
.orderBy(AUTHOR.FIRST_NAME.desc())
.fetch();]]></java>
</code-pair><html>
<p>
Note that in order to create such a window definition, we need to first create a <reference id="names" title="name reference"/> using <reference class="org.jooq.impl.DSL" title="DSL.name()" anchor="#name-java.lang.String...-"/>.
</p>
<p>
Even if only PostgreSQL and Sybase SQL Anywhere natively support this great feature, jOOQ can emulate it by expanding any <reference class="org.jooq.WindowDefinition" /> and <reference class="org.jooq.WindowSpecification"/> types that you pass to the <code>window()</code> method - if the database supports window functions at all.
</p>
<p>
Some more information about <reference id="window-functions" title="window functions"/> and the <code>WINDOW</code> clause can be found on our blog: <a href="http://blog.jooq.org/2013/11/03/probably-the-coolest-sql-feature-window-functions/">http://blog.jooq.org/2013/11/03/probably-the-coolest-sql-feature-window-functions/</a>
</p>
</html></content>
</section>
<section id="order-by-clause">
<title>The ORDER BY clause</title>
<content><html>
<p>
Databases are allowed to return data in any arbitrary order, unless you explicitly declare that order in the ORDER BY clause. In jOOQ, this is straight-forward:
</p>
</html><code-pair>
<sql><![CDATA[SELECT AUTHOR_ID, TITLE
FROM BOOK
ORDER BY AUTHOR_ID ASC, TITLE DESC
]]>&#160;</sql>
<java><![CDATA[create.select(BOOK.AUTHOR_ID, BOOK.TITLE)
.from(BOOK)
.orderBy(BOOK.AUTHOR_ID.asc(), BOOK.TITLE.desc())
.fetch();]]></java></code-pair><html>
<p>
Any jOOQ <reference id="column-expressions" title="column expression (or field)"/> can be transformed into an <reference class="org.jooq.SortField"/> by calling the asc() and desc() methods.
</p>
<h3>Ordering by field index</h3>
<p>
The SQL standard allows for specifying integer literals (<reference id="inlined-parameters" title="literals"/>, not <reference id="bind-values" title="bind values"/>!) to reference column indexes from the projection (<reference id="select-clause" title="SELECT clause"/>). This may be useful if you do not want to repeat a lengthy expression, by which you want to order - although most databases also allow for referencing <reference id="aliased-columns" title="aliased column references"/> in the ORDER BY clause. An example of this is given here:
</p>
</html><code-pair>
<sql><![CDATA[SELECT AUTHOR_ID, TITLE
FROM BOOK
ORDER BY 1 ASC, 2 DESC
]]>&#160;</sql>
<java><![CDATA[create.select(BOOK.AUTHOR_ID, BOOK.TITLE)
.from(BOOK)
.orderBy(one().asc(), inline(2).desc())
.fetch();]]></java></code-pair><html>
<p>
Note, how <code>one()</code> is used as a convenience short-cut for <code>inline(1)</code>
</p>
<h3>Ordering and NULLS</h3>
<p>
A few databases support the SQL standard "null ordering" clause in sort specification lists, to define whether <code>NULL</code> values should come first or last in an ordered result.
</p>
</html><code-pair>
<sql><![CDATA[SELECT
AUTHOR.FIRST_NAME,
AUTHOR.LAST_NAME
FROM AUTHOR
ORDER BY LAST_NAME ASC,
FIRST_NAME ASC NULLS LAST
]]>&#160;</sql>
<java><![CDATA[create.select(
AUTHOR.FIRST_NAME,
AUTHOR.LAST_NAME)
.from(AUTHOR)
.orderBy(AUTHOR.LAST_NAME.asc(),
AUTHOR.FIRST_NAME.asc().nullsLast())
.fetch();]]></java></code-pair><html>
<p>
If your database doesn't support this syntax, jOOQ simulates it using a <reference id="case-expressions" title="CASE expression"/> as follows
</p>
</html>
<sql><![CDATA[SELECT
AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME
FROM AUTHOR
ORDER BY LAST_NAME ASC,
CASE WHEN FIRST_NAME IS NULL
THEN 1 ELSE 0 END ASC,
FIRST_NAME ASC]]></sql><html>
<h3>Ordering using CASE expressions</h3>
<p>
Using <reference id="case-expressions" title="CASE expressions"/> in SQL ORDER BY clauses is a common pattern, if you want to introduce some sort indirection / sort mapping into your queries. As with SQL, you can add any type of <reference id="column-expressions" title="column expression"/> into your ORDER BY clause. For instance, if you have two favourite books that you always want to appear on top, you could write:
</p>
</html><code-pair>
<sql><![CDATA[SELECT *
FROM BOOK
ORDER BY CASE TITLE
WHEN '1984' THEN 0
WHEN 'Animal Farm' THEN 1
ELSE 2 END ASC
]]>&#160;</sql>
<java><![CDATA[create.select()
.from(BOOK)
.orderBy(choose(BOOK.TITLE)
.when("1984", 0)
.when("Animal Farm", 1)
.otherwise(2).asc())
.fetch();]]></java></code-pair><html>
<p>
But writing these things can become quite verbose. jOOQ supports a convenient syntax for specifying sort mappings. The same query can be written in jOOQ as such:
</p>
</html><java><![CDATA[create.select()
.from(BOOK)
.orderBy(BOOK.TITLE.sortAsc("1984", "Animal Farm"))
.fetch();]]></java><html>
<p>
More complex sort indirections can be provided using a Map:
</p>
</html><java><![CDATA[create.select()
.from(BOOK)
.orderBy(BOOK.TITLE.sort(new HashMap<String, Integer>() {{
put("1984", 1);
put("Animal Farm", 13);
put("The jOOQ book", 10);
}}))
.fetch();]]></java><html>
<p>
Of course, you can combine this feature with the previously discussed NULLS FIRST / NULLS LAST feature. So, if in fact these two books are the ones you like least, you can put all NULLS FIRST (all the other books):
</p>
</html><java><![CDATA[create.select()
.from(BOOK)
.orderBy(BOOK.TITLE.sortAsc("1984", "Animal Farm").nullsFirst())
.fetch();]]></java><html>
<h3>jOOQ's understanding of SELECT .. ORDER BY</h3>
<p>
The SQL standard defines that a "query expression" can be ordered, and that query expressions can contain <reference id="union-clause" title="UNION, INTERSECT and EXCEPT clauses"/>, whose subqueries cannot be ordered. While this is defined as such in the SQL standard, many databases allowing for the <reference id="limit-clause" title="LIMIT clause"/> in one way or another, do not adhere to this part of the SQL standard. Hence, jOOQ allows for ordering all SELECT statements, regardless whether they are constructed as a part of a UNION or not. Corner-cases are handled internally by jOOQ, by introducing synthetic subselects to adhere to the correct syntax, where this is needed.
</p>
<h3>Oracle's ORDER SIBLINGS BY clause</h3>
<p>
jOOQ also supports Oracle's SIBLINGS keyword to be used with ORDER BY clauses for <reference id="connect-by-clause" title="hierarchical queries using CONNECT BY"/>
</p>
</html></content>
</section>
<section id="limit-clause">
<title>The LIMIT .. OFFSET clause</title>
<content><html>
<p>
While being extremely useful for every application that does paging, or just to limit result sets to reasonable sizes, this clause is not yet part of any SQL standard (up until SQL:2008). Hence, there exist a variety of possible implementations in various SQL dialects, concerning this limit clause. jOOQ chose to implement the LIMIT .. OFFSET clause as understood and supported by MySQL, H2, HSQLDB, Postgres, and SQLite. Here is an example of how to apply limits with jOOQ:
</p>
</html><java><![CDATA[create.select().from(BOOK).limit(1).offset(2).fetch();]]></java><html>
<p>
This will limit the result to 1 books starting with the 2nd book (starting at offset 0!). limit() is supported in all dialects, offset() in all but Sybase ASE, which has no reasonable means to emulate it. This is how jOOQ trivially emulates the above query in various SQL dialects with native <code>OFFSET</code> pagination support:
</p>
</html><sql><![CDATA[-- MySQL, H2, HSQLDB, Postgres, and SQLite
SELECT * FROM BOOK LIMIT 1 OFFSET 2
-- CUBRID supports a MySQL variant of the LIMIT .. OFFSET clause
SELECT * FROM BOOK LIMIT 2, 1
-- Derby, SQL Server 2012, Oracle 12c, the SQL:2008 standard
SELECT * FROM BOOK OFFSET 2 ROWS FETCH NEXT 1 ROWS ONLY
-- Informix has SKIP .. FIRST support
SELECT SKIP 2 FIRST 1 * FROM BOOK
-- Ingres (almost the SQL:2008 standard)
SELECT * FROM BOOK OFFSET 2 FETCH FIRST 1 ROWS ONLY
-- Firebird
SELECT * FROM BOOK ROWS 2 TO 3
-- Sybase SQL Anywhere
SELECT TOP 1 ROWS START AT 3 * FROM BOOK
-- DB2 (almost the SQL:2008 standard, without OFFSET)
SELECT * FROM BOOK FETCH FIRST 1 ROWS ONLY
-- Sybase ASE, SQL Server 2008 (without OFFSET)
SELECT TOP 1 * FROM BOOK
]]></sql><html>
<p>
Things get a little more tricky in those databases that have no native idiom for <code>OFFSET</code> pagination (actual queries may vary):
</p>
</html><sql><![CDATA[
-- DB2 (with OFFSET), SQL Server 2008 (with OFFSET)
SELECT * FROM (
SELECT BOOK.*,
ROW_NUMBER() OVER (ORDER BY ID ASC) AS RN
FROM BOOK
) AS X
WHERE RN > 1
AND RN <= 3
-- DB2 (with OFFSET), SQL Server 2008 (with OFFSET)
SELECT * FROM (
SELECT DISTINCT BOOK.ID, BOOK.TITLE
DENSE_RANK() OVER (ORDER BY ID ASC, TITLE ASC) AS RN
FROM BOOK
) AS X
WHERE RN > 1
AND RN <= 3
-- Oracle 11g and less
SELECT *
FROM (
SELECT b.*, ROWNUM RN
FROM (
SELECT *
FROM BOOK
ORDER BY ID ASC
) b
WHERE ROWNUM <= 3
)
WHERE RN > 1]]></sql><html>
<p>
As you can see, jOOQ will take care of the incredibly painful ROW_NUMBER() OVER() (or ROWNUM for Oracle) filtering in subselects for you, you'll just have to write limit(1).offset(2) in any dialect.
</p>
<h3>SQL Server's ORDER BY, TOP and subqueries</h3>
<p>
As can be seen in the above example, writing correct SQL can be quite tricky, depending on the SQL dialect. For instance, with SQL Server, you cannot have an ORDER BY clause in a subquery, unless you also have a TOP clause. This is illustrated by the fact that jOOQ renders a TOP 100 PERCENT clause for you. The same applies to the fact that ROW_NUMBER() OVER() needs an ORDER BY windowing clause, even if you don't provide one to the jOOQ query. By default, jOOQ adds ordering by the first column of your projection.
</p>
</html></content>
</section>
<section id="seek-clause">
<title>The SEEK clause</title>
<content><html>
<p>
The previous chapter talked about <reference id="limit-clause" title="OFFSET paging"/> using <code>LIMIT .. OFFSET</code>, or <code>OFFSET .. FETCH</code> or some other vendor-specific variant of the same. This can lead to significant performance issues when reaching a high page number, as all unneeded records need to be skipped by the database.
</p>
<p>
A much faster and more stable way to perform paging is the so-called <em>keyset paging method</em> also called <em>seek method</em>. jOOQ supports a synthetic <code>seek()</code> clause, that can be used to perform keyset paging. Imagine we have these data:
</p>
</html><text><![CDATA[| ID | VALUE | PAGE_BOUNDARY |
|------|-------|---------------|
| ... | ... | ... |
| 474 | 2 | 0 |
| 533 | 2 | 1 | <-- Before page 6
| 640 | 2 | 0 |
| 776 | 2 | 0 |
| 815 | 2 | 0 |
| 947 | 2 | 0 |
| 37 | 3 | 1 | <-- Last on page 6
| 287 | 3 | 0 |
| 450 | 3 | 0 |
| ... | ... | ... |]]></text><html>
<p>
Now, if we want to display page 6 to the user, instead of going to page 6 by using a record <code>OFFSET</code>, we could just fetch the record strictly after the last record on page 5, which yields the values <code>(533, 2)</code>. This is how you would do it with SQL or with jOOQ:
</p>
</html><code-pair>
<sql><![CDATA[
SELECT id, value
FROM t
WHERE (value, id) > (2, 533)
ORDER BY value, id
LIMIT 5
]]>&#160;</sql>
<java><![CDATA[DSL.using(configuration)
.select(T.ID, T.VALUE)
.from(T)
.orderBy(T.VALUE, T.ID)
.seek(2, 533)
.limit(5)
.fetch();]]></java>
</code-pair><html>
<p>
As you can see, the jOOQ <code>SEEK</code> clause is a synthetic clause that does not really exist in SQL. However, the jOOQ syntax is far more intuitive for a variety of reasons:
</p>
<ul>
<li>It replaces <code>OFFSET</code> where you would expect</li>
<li>It doesn't force you to mix regular predicates with <em>"seek"</em> predicates</li>
<li>It is typesafe</li>
<li>It emulates <reference id="comparison-predicate-degree-n" title="row value expression predicates"/> for you, in those databases that do not support them</li>
</ul>
<p>
This query now yields:
</p>
</html><text><![CDATA[| ID | VALUE |
|-----|-------|
| 640 | 2 |
| 776 | 2 |
| 815 | 2 |
| 947 | 2 |
| 37 | 3 |]]></text><html>
<p>
Note that you cannot combine the <code>SEEK</code> clause with the <code>OFFSET</code> clause.
</p>
<p>
More information about this great feature can be found in the jOOQ blog:
</p>
<ul>
<li><a href="http://blog.jooq.org/2013/10/26/faster-sql-paging-with-jooq-using-the-seek-method/">http://blog.jooq.org/2013/10/26/faster-sql-paging-with-jooq-using-the-seek-method/</a></li>
<li><a href="http://blog.jooq.org/2013/11/18/faster-sql-pagination-with-keysets-continued/">http://blog.jooq.org/2013/11/18/faster-sql-pagination-with-keysets-continued/</a></li>
</ul>
<p>
Further information about offset pagination vs. keyset pagination performance can be found on our <a href="http://use-the-index-luke.com/no-offset">partner page</a>:
</p>
<div class="screenshot">
<a href="http://use-the-index-luke.com/no-offset">
<img class="screenshot" src="&lt;?=$root?&gt;/img/no-offset-banner-728x90.white.png" alt="No more offset"/>
</a>
</div>
</html></content>
</section>
<section id="for-update-clause">
<title>The FOR UPDATE clause</title>
<content><html>
<p>
For inter-process synchronisation and other reasons, you may choose to use the SELECT .. FOR UPDATE clause to indicate to the database, that a set of cells or records should be locked by a given transaction for subsequent updates. With jOOQ, this can be achieved as such:
</p>
</html><code-pair>
<sql><![CDATA[SELECT *
FROM BOOK
WHERE ID = 3
FOR UPDATE
]]>&#160;</sql>
<java><![CDATA[create.select()
.from(BOOK)
.where(BOOK.ID.equal(3))
.forUpdate()
.fetch();]]></java></code-pair><html>
<p>
The above example will produce a record-lock, locking the whole record for updates. Some databases also support cell-locks using FOR UPDATE OF ..
</p>
</html><code-pair>
<sql><![CDATA[SELECT *
FROM BOOK
WHERE ID = 3
FOR UPDATE OF TITLE
]]>&#160;</sql>
<java><![CDATA[create.select()
.from(BOOK)
.where(BOOK.ID.equal(3))
.forUpdate().of(BOOK.TITLE)
.fetch();]]></java></code-pair><html>
<p>
Oracle goes a bit further and also allows to specify the actual locking behaviour. It features these additional clauses, which are all supported by jOOQ:
</p>
<ul>
<li><code>FOR UPDATE NOWAIT</code>: This is the default behaviour. If the lock cannot be acquired, the query fails immediately</li>
<li><code>FOR UPDATE WAIT n</code>: Try to wait for [n] seconds for the lock acquisition. The query will fail only afterwards</li>
<li><code>FOR UPDATE SKIP LOCKED</code>: This peculiar syntax will skip all locked records. This is particularly useful when implementing queue tables with multiple consumers</li>
</ul>
<p>
With jOOQ, you can use those Oracle extensions as such:
</p>
</html><java><![CDATA[create.select().from(BOOK).where(BOOK.ID.equal(3)).forUpdate().nowait().fetch();
create.select().from(BOOK).where(BOOK.ID.equal(3)).forUpdate().wait(5).fetch();
create.select().from(BOOK).where(BOOK.ID.equal(3)).forUpdate().skipLocked().fetch();]]></java><html>
<h3>FOR UPDATE in CUBRID and SQL Server</h3>
<p>
The SQL standard specifies a <code>FOR UPDATE</code> clause to be applicable for cursors. Most databases interpret this as being applicable for all <code>SELECT</code> statements. An exception to this rule are the CUBRID and SQL Server databases, that do not allow for any <code>FOR UPDATE</code> clause in a regular SQL <code>SELECT</code> statement. jOOQ simulates the <code>FOR UPDATE</code> behaviour, by locking record by record with JDBC. JDBC allows for specifying the flags <code>TYPE_SCROLL_SENSITIVE</code>, <code>CONCUR_UPDATABLE</code> for any statement, and then using ResultSet.updateXXX() methods to produce a cell-lock / row-lock. Here's a simplified example in JDBC:
</p>
</html><java><![CDATA[try (
PreparedStatement stmt = connection.prepareStatement(
"SELECT * FROM author WHERE id IN (3, 4, 5)",
ResultSet.TYPE_SCROLL_SENSITIVE,
ResultSet.CONCUR_UPDATABLE);
ResultSet rs = stmt.executeQuery()
) {
while (rs.next()) {
// UPDATE the primary key for row-locks, or any other columns for cell-locks
rs.updateObject(1, rs.getObject(1));
rs.updateRow();
// Do more stuff with this record
}
}]]></java><html>
<p>
The main drawback of this approach is the fact that the database has to maintain a scrollable cursor, whose records are locked one by one. This can cause a major risk of deadlocks or race conditions if the JDBC driver can recover from the unsuccessful locking, if two Java threads execute the following statements:
</p>
</html><sql><![CDATA[-- thread 1
SELECT * FROM author ORDER BY id ASC;
-- thread 2
SELECT * FROM author ORDER BY id DESC;]]></sql><html>
<p>
So use this technique with care, possibly only ever locking single rows!
</p>
<h3>Pessimistic (shared) locking with the <code>FOR SHARE</code> clause</h3>
<p>
Some databases (MySQL, Postgres) also allow to issue a non-exclusive lock explicitly using a <code>FOR SHARE</code> clause. This is also supported by jOOQ
</p>
<h3>Optimistic locking in jOOQ</h3>
<p>
Note, that jOOQ also supports optimistic locking, if you're doing simple CRUD. This is documented in the section's manual about <reference id="optimistic-locking" title="optimistic locking"/>.
</p>
</html></content>
</section>
<section id="union-clause">
<title>UNION, INTERSECTION and EXCEPT</title>
<content><html>
<p>
SQL allows to perform set operations as understood in standard set theory on result sets. These operations include unions, intersections, subtractions. For two subselects to be combinable by such a set operator, each subselect must return a <reference id="table-expressions" title="table expression"/> of the same degree and type.
</p>
<h3>UNION and UNION ALL</h3>
<p>
These operators combine two results into one. While <code>UNION</code> removes all duplicate records resulting from this combination, <code>UNION ALL</code> leaves subselect results as they are. Typically, you should prefer <code>UNION ALL</code> over <code>UNION</code>, if you don't really need to remove duplicates. The following example shows how to use such a <code>UNION</code> operation in jOOQ.
</p>
</html><code-pair>
<sql><![CDATA[SELECT * FROM BOOK WHERE ID = 3
UNION ALL
SELECT * FROM BOOK WHERE ID = 5
]]>&#160;</sql>
<java><![CDATA[create.selectFrom(BOOK).where(BOOK.ID.equal(3))
.unionAll(
create.selectFrom(BOOK).where(BOOK.ID.equal(5)))
.fetch();]]></java></code-pair><html>
<h3>INTERSECT [ ALL ] and EXCEPT [ ALL ]</h3>
<p>
<code>INTERSECT</code> is the operation that produces only those values that are returned by both subselects. <code>EXCEPT</code> is the operation that returns only those values that are returned exclusively in the first subselect. Both operators will remove duplicates from their results. The SQL standard allows to specify the <code>ALL</code> keyword for both of these operators as well, but this is hardly supported in any database. jOOQ does not support <code>INTERSECT ALL</code>, <code>EXEPT ALL</code> operations either.
</p>
<h3>jOOQ's set operators and how they're different from standard SQL</h3>
<p>
As previously mentioned in the manual's section about the <reference id="order-by-clause" title="ORDER BY clause"/>, jOOQ has slightly changed the semantics of these set operators. While in SQL, a subselect may not contain any <reference id="order-by-clause" title="ORDER BY clause"/> or <reference id="limit-clause" title="LIMIT clause"/> (unless you wrap the subselect into a <reference id="nested-selects" title="nested SELECT"/>), jOOQ allows you to do so. In order to select both the youngest and the oldest author from the database, you can issue the following statement with jOOQ (rendered to the MySQL dialect):
</p>
</html><code-pair>
<sql><![CDATA[ (SELECT * FROM AUTHOR
ORDER BY DATE_OF_BIRTH ASC LIMIT 1)
UNION
(SELECT * FROM AUTHOR
ORDER BY DATE_OF_BIRTH DESC LIMIT 1)
ORDER BY 1
]]>&#160;</sql>
<java><![CDATA[create.selectFrom(AUTHOR)
.orderBy(AUTHOR.DATE_OF_BIRTH.asc()).limit(1)
.union(
selectFrom(AUTHOR)
.orderBy(AUTHOR.DATE_OF_BIRTH.desc()).limit(1))
.orderBy(1)
.fetch();]]></java></code-pair><html>
<p>
In case your database doesn't support ordered <code>UNION</code> subselects, the subselects are nested in derived tables:
</p>
</html>
<sql><![CDATA[SELECT * FROM (
SELECT * FROM AUTHOR
ORDER BY DATE_OF_BIRTH ASC LIMIT 1
)
UNION
SELECT * FROM (
SELECT * FROM AUTHOR
ORDER BY DATE_OF_BIRTH DESC LIMIT 1
)
ORDER BY 1]]></sql>
<html>
<h3>Projection typesafety for degrees between 1 and {max-row-degree}</h3>
<p>
Two subselects that are combined by a set operator are required to be of the same degree and, in most databases, also of the same type. jOOQ 3.0's introduction of <reference id="record-n" title="Typesafe Record[N] types"/> helps compile-checking these constraints:
</p>
</html><java><![CDATA[// Some sample SELECT statements
Select<Record2<Integer, String>> s1 = select(BOOK.ID, BOOK.TITLE).from(BOOK);
Select<Record1<Integer>> s2 = selectOne();
Select<Record2<Integer, Integer>> s3 = select(one(), zero());
Select<Record2<Integer, String>> s4 = select(one(), inline("abc"));
// Let's try to combine them:
s1.union(s2); // Doesn't compile because of a degree mismatch. Expected: Record2<...>, got: Record1<...>
s1.union(s3); // Doesn't compile because of a type mismatch. Expected: <Integer, String>, got: <Integer, Integer>
s1.union(s4); // OK. The two Record[N] types match]]></java>
</content>
</section>
<section id="oracle-hints">
<title>Oracle-style hints</title>
<content><html>
<p>
If you are closely coupling your application to an Oracle (or CUBRID) database, you might need to be able to pass hints of the form <code>/*+HINT*/</code> with your SQL statements to the Oracle database. For example:
</p>
</html><sql>SELECT /*+ALL_ROWS*/ FIRST_NAME, LAST_NAME
FROM AUTHOR</sql><html>
<p>
This can be done in jOOQ using the <code>.hint()</code> clause in your SELECT statement:
</p>
</html><java>create.select(AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME)
.hint("/*+ALL_ROWS*/")
.from(AUTHOR)
.fetch();</java><html>
<p>
Note that you can pass any string in the <code>.hint()</code> clause. If you use that clause, the passed string will always be put in between the <code>SELECT [DISTINCT]</code> keywords and the actual projection list. This can be useful in other databases too, such as MySQL, for instance:
</p>
</html><code-pair>
<sql><![CDATA[SELECT SQL_CALC_FOUND_ROWS field1, field2
FROM table1
]]>&#160;</sql>
<java><![CDATA[create.select(field1, field2)
.hint("SQL_CALC_FOUND_ROWS")
.from(table1)
.fetch()]]></java>
</code-pair>
</content>
</section>
<section id="select-lexical-vs-logical-order">
<title>Lexical and logical SELECT clause order</title>
<content><html>
<p>
SQL has a lexical and a logical order of <code>SELECT</code> clauses. The lexical order of <code>SELECT</code> clauses is inspired by the English language. As SQL statements are commands for the database, it is natural to express a statement in an imperative tense, such as "SELECT this and that!".
</p>
<h3>Logical SELECT clause order</h3>
<p>
The logical order of <code>SELECT</code> clauses, however, does not correspond to the syntax. In fact, the logical order is this:
</p>
<ul>
<li><reference id="from-clause" title="The FROM clause"/>: First, all data sources are defined and joined</li>
<li><reference id="where-clause" title="The WHERE clause"/>: Then, data is filtered as early as possible</li>
<li><reference id="connect-by-clause" title="The CONNECT BY clause"/>: Then, data is traversed iteratively or recursively, to produce new tuples</li>
<li><reference id="group-by-clause" title="The GROUP BY clause"/>: Then, data is reduced to groups, possibly producing new tuples if <reference id="grouping-functions" title="grouping functions like ROLLUP(), CUBE(), GROUPING SETS()"/> are used</li>
<li><reference id="having-clause" title="The HAVING clause"/>: Then, data is filtered again</li>
<li><reference id="select-clause" title="The SELECT clause"/>: Only now, the projection is evaluated. In case of a <code>SELECT DISTINCT</code> statement, data is further reduced to remove duplicates</li>
<li><reference id="union-clause" title="The UNION clause"/>: Optionally, the above is repeated for several <code>UNION</code>-connected subqueries. Unless this is a <code>UNION ALL</code> clause, data is further reduced to remove duplicates</li>
<li><reference id="order-by-clause" title="The ORDER BY clause"/>: Now, all remaining tuples are ordered</li>
<li><reference id="limit-clause" title="The LIMIT clause"/>: Then, a paging view is created for the ordered tuples</li>
<li><reference id="for-update-clause" title="The FOR UPDATE clause"/>: Finally, pessimistic locking is applied</li>
</ul>
<p>
The <a href="http://msdn.microsoft.com/en-us/library/ms189499.aspx">SQL Server documentation</a> also explains this, with slightly different clauses:
</p>
<ul>
<li><code>FROM</code></li>
<li><code>ON</code></li>
<li><code>JOIN</code></li>
<li><code>WHERE</code></li>
<li><code>GROUP BY</code></li>
<li><code>WITH CUBE</code> or <code>WITH ROLLUP</code></li>
<li><code>HAVING</code></li>
<li><code>SELECT</code></li>
<li><code>DISTINCT</code></li>
<li><code>ORDER BY</code></li>
<li><code>TOP</code></li>
</ul>
<p>
As can be seen, databases have to logically reorder a SQL statement in order to determine the best execution plan.
</p>
<h3>Alternative syntaxes: LINQ, SLICK</h3>
<p>
Some "higher-level" abstractions, such as C#'s LINQ or Scala's SLICK try to inverse the lexical order of <code>SELECT</code> clauses to what appears to be closer to the logical order. The obvious advantage of moving the <code>SELECT</code> clause to the end is the fact that the projection type, which is the record type returned by the <code>SELECT</code> statement can be re-used more easily in the target environment of the internal domain specific language.
</p>
<p>
A LINQ example:
</p>
</html><java><![CDATA[// LINQ-to-SQL looks somewhat similar to SQL
// AS clause // FROM clause
From p In db.Products
// WHERE clause
Where p.UnitsInStock <= p.ReorderLevel AndAlso Not p.Discontinued
// SELECT clause
Select p]]></java><html>
<p>
A SLICK example:
</p>
</html><scala><![CDATA[// "for" is the "entry-point" to the DSL
val q = for {
// FROM clause WHERE clause
c <- Coffees if c.supID === 101
// SELECT clause and projection to a tuple
} yield (c.name, c.price)]]></scala><html>
<p>
While this looks like a good idea at first, it only complicates translation to more advanced SQL statements while impairing readability for those users that are used to writing SQL. jOOQ is designed to look just like SQL. This is specifically true for SLICK, which not only changed the <code>SELECT</code> clause order, but also heavily "integrated" SQL clauses with the Scala language.
</p>
<p>
For these reasons, the jOOQ DSL API is modelled in SQL's lexical order.
</p>
</html></content>
</section>
</sections>
</section>
<section id="insert-statement">
<title>The INSERT statement</title>
<content><html>
<p>
The <code>INSERT</code> statement is used to insert new records into a database table. The following sections describe the various operation modes of the jOOQ <code>INSERT</code> statement.
</p>
</html></content>
<sections>
<section id="insert-values">
<title>INSERT .. VALUES</title>
<content><html>
<h3>INSERT .. VALUES with a single row</h3>
<p>
Records can either be supplied using a <code>VALUES()</code> constructor, or a <code>SELECT</code> statement. jOOQ supports both types of <code>INSERT</code> statements. An example of an <code>INSERT</code> statement using a <code>VALUES()</code> constructor is given here:
</p>
</html><code-pair>
<sql><![CDATA[INSERT INTO AUTHOR
(ID, FIRST_NAME, LAST_NAME)
VALUES (100, 'Hermann', 'Hesse');
]]>&#160;</sql>
<java>create.insertInto(AUTHOR,
AUTHOR.ID, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME)
.values(100, "Hermann", "Hesse")
.execute();</java></code-pair><html>
<p>
Note that for explicit degrees up to {max-row-degree}, the <code>VALUES()</code> constructor provides additional typesafety. The following example illustrates this:
</p>
</html><java><![CDATA[InsertValuesStep3<AuthorRecord, Integer, String, String> step =
create.insertInto(AUTHOR, AUTHOR.ID, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME);
step.values("A", "B", "C");
// ^^^ Doesn't compile, the expected type is Integer]]></java><html>
<h3>INSERT .. VALUES with multiple rows</h3>
<p>
The SQL standard specifies that multiple rows can be supplied to the VALUES() constructor in an INSERT statement. Here's an example of a multi-record INSERT
</p>
</html><code-pair>
<sql><![CDATA[INSERT INTO AUTHOR
(ID, FIRST_NAME, LAST_NAME)
VALUES (100, 'Hermann', 'Hesse'),
(101, 'Alfred', 'Döblin');
]]>&#160;</sql>
<java>create.insertInto(AUTHOR,
AUTHOR.ID, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME)
.values(100, "Hermann", "Hesse")
.values(101, "Alfred", "Döblin")
.execute()</java></code-pair><html>
<p>
jOOQ tries to stay close to actual SQL. In detail, however, Java's expressiveness is limited. That's why the values() clause is repeated for every record in multi-record inserts.
</p>
<p>
Some RDBMS do not support inserting several records in a single statement. In those cases, jOOQ simulates multi-record INSERTs using the following SQL:
</p>
</html><code-pair>
<sql><![CDATA[INSERT INTO AUTHOR
(ID, FIRST_NAME, LAST_NAME)
SELECT 100, 'Hermann', 'Hesse' FROM DUAL UNION ALL
SELECT 101, 'Alfred', 'Döblin' FROM DUAL;
]]>&#160;</sql>
<java>create.insertInto(AUTHOR,
AUTHOR.ID, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME)
.values(100, "Hermann", "Hesse")
.values(101, "Alfred", "Döblin")
.execute();
</java></code-pair>
</content>
</section>
<section id="insert-default-values">
<title>INSERT .. DEFAULT VALUES</title>
<content><html>
<p>
A lesser-known syntactic feature of SQL is the <code>INSERT .. DEFAULT VALUES</code> statement, where a single record is inserted, containing only <code>DEFAULT</code> values for every row. It is written as such:
</p>
</html><code-pair>
<sql><![CDATA[INSERT INTO AUTHOR
DEFAULT VALUES;
]]>&#160;</sql>
<java>create.insertInto(AUTHOR)
.defaultValues()
.execute();</java></code-pair><html>
<p>
This can make a lot of sense in situations where you want to "reserve" a row in the database for an subsequent <reference id="update-statement" title="UPDATE statement"/> within the same transaction. Or if you just want to send an event containing trigger-generated default values, such as IDs or timestamps.
</p>
<p>
The <code>DEFAULT VALUES</code> clause is not supported in all databases, but jOOQ can emulate it using the equivalent statement:
</p>
</html><code-pair>
<sql><![CDATA[INSERT INTO AUTHOR
(ID, FIRST_NAME, LAST_NAME, ...)
VALUES (
DEFAULT,
DEFAULT,
DEFAULT, ...);
]]>&#160;</sql>
<java>create.insertInto(
AUTHOR, AUTHOR.ID, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME, ...)
.values(
defaultValue(AUTHOR.ID),
defaultValue(AUTHOR.FIRST_NAME),
defaultValue(AUTHOR.LAST_NAME), ...)
.execute();</java></code-pair><html>
<p>
The <code>DEFAULT</code> keyword (or <reference class="org.jooq.impl.DSL" anchor="#defaultValue--" title="DSL#defaultValue()"/> method) can also be used for individual columns only, although that will have the same effect as leaving the column away entirely.
</p>
</html></content>
</section>
<section id="insert-set">
<title>INSERT .. SET</title>
<content><html>
<p>
MySQL (and some other RDBMS) allow for using a non-SQL-standard, UPDATE-like syntax for INSERT statements. This is also supported in jOOQ, should you prefer that syntax. The above INSERT statement can also be expressed as follows:
</p>
</html><java>create.insertInto(AUTHOR)
.set(AUTHOR.ID, 100)
.set(AUTHOR.FIRST_NAME, "Hermann")
.set(AUTHOR.LAST_NAME, "Hesse")
.newRecord()
.set(AUTHOR.ID, 101)
.set(AUTHOR.FIRST_NAME, "Alfred")
.set(AUTHOR.LAST_NAME, "Döblin")
.execute();</java><html>
<p>
As you can see, this syntax is a bit more verbose, but also more readable, as every field can be matched with its value. Internally, the two syntaxes are strictly equivalent.
</p>
</html></content>
</section>
<section id="insert-select">
<title>INSERT .. SELECT</title>
<content><html>
<p>
In some occasions, you may prefer the INSERT SELECT syntax, for instance, when you copy records from one table to another:
</p>
</html><java>create.insertInto(AUTHOR_ARCHIVE)
.select(selectFrom(AUTHOR).where(AUTHOR.DECEASED.isTrue()))
.execute();</java>
</content>
</section>
<section id="insert-on-duplicate-key">
<title>INSERT .. ON DUPLICATE KEY</title>
<content><html>
<h3>The synthetic ON DUPLICATE KEY UPDATE clause</h3>
<p>
The MySQL database supports a very convenient way to INSERT or UPDATE a record. This is a non-standard extension to the SQL syntax, which is supported by jOOQ and simulated in other RDBMS, where this is possible (i.e. if they support the SQL standard <reference id="merge-statement" title="MERGE statement"/>). Here is an example how to use the ON DUPLICATE KEY UPDATE clause:
</p>
</html><java>// Add a new author called "Koontz" with ID 3.
// If that ID is already present, update the author's name
create.insertInto(AUTHOR, AUTHOR.ID, AUTHOR.LAST_NAME)
.values(3, "Koontz")
.onDuplicateKeyUpdate()
.set(AUTHOR.LAST_NAME, "Koontz")
.execute();</java><html>
<h3>The synthetic ON DUPLICATE KEY IGNORE clause</h3>
<p>
The MySQL database also supports an INSERT IGNORE INTO clause. This is supported by jOOQ using the more convenient SQL syntax variant of ON DUPLICATE KEY IGNORE, which can be equally simulated in other databases using a <reference id="merge-statement" title="MERGE statement"/>:
</p>
</html><java>// Add a new author called "Koontz" with ID 3.
// If that ID is already present, ignore the INSERT statement
create.insertInto(AUTHOR, AUTHOR.ID, AUTHOR.LAST_NAME)
.values(3, "Koontz")
.onDuplicateKeyIgnore()
.execute();</java>
</content>
</section>
<section id="insert-returning">
<title>INSERT .. RETURNING</title>
<content><html>
<p>
The Postgres database has native support for an INSERT .. RETURNING clause. This is a very powerful concept that is simulated for all other dialects using JDBC's <reference class="java.sql.Statement" anchor="#getGeneratedKeys()" title="getGeneratedKeys()"/> method. Take this example:
</p>
</html><java><![CDATA[// Add another author, with a generated ID
Record<?> record =
create.insertInto(AUTHOR, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME)
.values("Charlotte", "Roche")
.returning(AUTHOR.ID)
.fetchOne();
System.out.println(record.getValue(AUTHOR.ID));
// For some RDBMS, this also works when inserting several values
// The following should return a 2x2 table
Result<?> result =
create.insertInto(AUTHOR, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME)
.values("Johann Wolfgang", "von Goethe")
.values("Friedrich", "Schiller")
// You can request any field. Also trigger-generated values
.returning(AUTHOR.ID, AUTHOR.CREATION_DATE)
.fetch();]]></java><html>
<p>
Some databases have poor support for returning generated keys after INSERTs. In those cases, jOOQ might need to issue another <reference id="select-statement" title="SELECT statement"/> in order to fetch an @@identity value. Be aware, that this can lead to race-conditions in those databases that cannot properly return generated ID values. For more information, please consider the jOOQ Javadoc for the returning() clause.
</p>
</html></content>
</section>
</sections>
</section>
<section id="update-statement">
<title>The UPDATE statement</title>
<content><html>
<p>
The UPDATE statement is used to modify one or several pre-existing records in a database table. UPDATE statements are only possible on single tables. Support for multi-table updates will be implemented in the near future. An example update query is given here:
</p>
</html><code-pair>
<sql><![CDATA[UPDATE AUTHOR
SET FIRST_NAME = 'Hermann',
LAST_NAME = 'Hesse'
WHERE ID = 3;
]]>&#160;</sql>
<java>create.update(AUTHOR)
.set(AUTHOR.FIRST_NAME, "Hermann")
.set(AUTHOR.LAST_NAME, "Hesse")
.where(AUTHOR.ID.equal(3))
.execute();</java>
</code-pair><html>
<p>
Most databases allow for using scalar subselects in UPDATE statements in one way or another. jOOQ models this through a <code>set(Field&lt;T>, Select&lt;? extends Record1&lt;T>>)</code> method in the <code>UPDATE</code> DSL API:
</p>
</html><code-pair>
<sql><![CDATA[UPDATE AUTHOR
SET FIRST_NAME = (
SELECT FIRST_NAME
FROM PERSON
WHERE PERSON.ID = AUTHOR.ID
),
WHERE ID = 3;
]]>&#160;</sql>
<java>create.update(AUTHOR)
.set(AUTHOR.FIRST_NAME,
select(PERSON.FIRST_NAME)
.from(PERSON)
.where(PERSON.ID.equal(AUTHOR.ID))
)
.where(AUTHOR.ID.equal(3))
.execute();</java>
</code-pair><html>
<h3>Using row value expressions in an UPDATE statement</h3>
<p>
jOOQ supports formal <reference id="row-value-expressions" title="row value expressions"/> in various contexts, among which the UPDATE statement. Only one row value expression can be updated at a time. Here's an example:
</p>
</html><code-pair>
<sql><![CDATA[UPDATE AUTHOR
SET (FIRST_NAME, LAST_NAME) =
('Hermann', 'Hesse')
WHERE ID = 3;
]]>&#160;</sql>
<java>create.update(AUTHOR)
.set(row(AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME),
row("Herman", "Hesse"))
.where(AUTHOR.ID.equal(3))
.execute();</java>
</code-pair><html>
<p>
This can be particularly useful when using subselects:
</p>
</html><code-pair>
<sql><![CDATA[UPDATE AUTHOR
SET (FIRST_NAME, LAST_NAME) = (
SELECT PERSON.FIRST_NAME, PERSON.LAST_NAME
FROM PERSON
WHERE PERSON.ID = AUTHOR.ID
)
WHERE ID = 3;
]]>&#160;</sql>
<java>create.update(AUTHOR)
.set(row(AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME),
select(PERSON.FIRST_NAME, PERSON.LAST_NAME)
.from(PERSON)
.where(PERSON.ID.equal(AUTHOR.ID))
)
.where(AUTHOR.ID.equal(3))
.execute();</java>
</code-pair><html>
<p>
The above row value expressions usages are completely typesafe.
</p>
<h3>UPDATE .. RETURNING</h3>
<p>
The Firebird and Postgres databases support a <code>RETURNING</code> clause on their <code>UPDATE</code> statements, similar as the <code>RETURNING</code> clause in <reference id="insert-statement" title="INSERT statements"/>. This is useful to fetch trigger-generated values in one go. An example is given here:
</p>
</html><code-pair>
<sql><![CDATA[-- Fetch a trigger-generated value
UPDATE BOOK
SET TITLE = 'Animal Farm'
WHERE ID = 5
RETURNING TITLE]]></sql>
<java><![CDATA[int count = create.update(BOOK)
.set(BOOK.TITLE, "Animal Farm")
.where(BOOK.ID.equal(5))
.returning(BOOK.TITLE)
.fetchOne().getValue(BOOK.TITLE);]]></java>
</code-pair><html>
<p>
The <code>UPDATE .. RETURNING</code> clause is currently not simulated for other databases. Future versions might execute an additional <reference id="select-statement" title="SELECT statement"/> to fetch results.
</p>
</html></content>
</section>
<section id="delete-statement">
<title>The DELETE statement</title>
<content><html>
<p>
The DELETE statement removes records from a database table. DELETE statements are only possible on single tables. Support for multi-table deletes will be implemented in the near future. An example delete query is given here:
</p>
</html><code-pair>
<sql><![CDATA[DELETE AUTHOR
WHERE ID = 100;
]]>&#160;</sql>
<java>create.delete(AUTHOR)
.where(AUTHOR.ID.equal(100))
.execute();</java>
</code-pair>
</content>
</section>
<section id="merge-statement">
<title>The MERGE statement</title>
<content><html>
<p>
The MERGE statement is one of the most advanced standardised SQL constructs, which is supported by DB2, HSQLDB, Oracle, SQL Server and Sybase (MySQL has the similar INSERT .. ON DUPLICATE KEY UPDATE construct)
</p>
<p>
The point of the standard MERGE statement is to take a TARGET table, and merge (INSERT, UPDATE) data from a SOURCE table into it. DB2, Oracle, SQL Server and Sybase also allow for DELETING some data and for adding many additional clauses. With jOOQ {jooq-version}, only Oracle's MERGE extensions are supported. Here is an example:
</p>
</html><code-pair>
<sql><![CDATA[-- Check if there is already an author called 'Hitchcock'
-- If there is, rename him to John. If there isn't add him.
MERGE INTO AUTHOR
USING (SELECT 1 FROM DUAL)
ON (LAST_NAME = 'Hitchcock')
WHEN MATCHED THEN UPDATE SET FIRST_NAME = 'John'
WHEN NOT MATCHED THEN INSERT (LAST_NAME) VALUES ('Hitchcock');
]]>&#160;</sql>
<java>create.mergeInto(AUTHOR)
.using(create().selectOne())
.on(AUTHOR.LAST_NAME.equal("Hitchcock"))
.whenMatchedThenUpdate()
.set(AUTHOR.FIRST_NAME, "John")
.whenNotMatchedThenInsert(AUTHOR.LAST_NAME)
.values("Hitchcock")
.execute();
</java></code-pair><html>
<h3>MERGE Statement (H2-specific syntax)</h3>
<p>
The H2 database ships with a somewhat less powerful but a little more intuitive syntax for its own version of the MERGE statement. An example more or less equivalent to the previous one can be seen here:
</p>
</html><code-pair>
<sql>-- Check if there is already an author called 'Hitchcock'
-- If there is, rename him to John. If there isn't add him.
MERGE INTO AUTHOR (FIRST_NAME, LAST_NAME)
KEY (LAST_NAME)
VALUES ('John', 'Hitchcock')</sql>
<java>create.mergeInto(AUTHOR,
AUTHOR.FIRST_NAME,
AUTHOR.LAST_NAME)
.key(AUTHOR.LAST_NAME)
.values("John", "Hitchcock")
.execute();
</java></code-pair><html>
<p>
This syntax can be fully emulated by jOOQ for all other databases that support the SQL standard MERGE statement. For more information about the H2 MERGE syntax, see the documentation here:<br/>
<a href="http://www.h2database.com/html/grammar.html#merge">http://www.h2database.com/html/grammar.html#merge</a>
</p>
<h3>Typesafety of VALUES() for degrees up to {max-row-degree}</h3>
<p>
Much like the <reference id="insert-statement" title="INSERT statement"/>, the <code>MERGE</code> statement's <code>VALUES()</code> clause provides typesafety for degrees up to {max-row-degree}, in both the standard syntax variant as well as the H2 variant.
</p>
</html></content>
</section>
<redirect id="truncate-statement" redirect-to="truncate-statement"/>
</sections>
</section>
<section id="ddl-statements">
<title>SQL Statements (DDL)</title>
<content><html>
<p>
jOOQ's DDL support is currently still very limited. In the long run, jOOQ will support the most important statement types for frequent informal database migrations, though. Note that jOOQ will not aim to replace existing database migration frameworks. At <a href="http://www.datageekery.com">Data Geekery</a>, we usually recommend using <a href="http://www.flywaydb.org">Flyway</a> for migrations. See also the <reference id="jooq-with-flyway" title="tutorial about using jOOQ with Flyway"/> for more information.
</p>
</html></content>
<sections>
<section id="alter-statement">
<title>The ALTER statement</title>
<content><html>
<p>
jOOQ currently supports the following <code>ALTER</code> statements (SQL examples in PostgreSQL syntax):
</p>
<h3>Tables</h3>
</html><code-pair>
<sql><![CDATA[ALTER TABLE AUTHOR
ADD TITLE VARCHAR(5) NULL;
ALTER TABLE AUTHOR
ADD TITLE VARCHAR(5) NOT NULL;
ALTER TABLE AUTHOR
ALTER TITLE SET DEFAULT 'no title';
ALTER TABLE AUTHOR
ALTER TITLE TYPE VARCHAR(5);
ALTER TABLE AUTHOR
ALTER TITLE TYPE VARCHAR(5) NOT NULL;
ALTER TABLE AUTHOR DROP TITLE;]]></sql>
<java><![CDATA[create.alterTable(AUTHOR)
.add(AUTHOR.TITLE, VARCHAR.length(5)).execute();
create.alterTable(AUTHOR)
.add(AUTHOR.TITLE, VARCHAR.length(5).nullable(false)).execute();
create.alterTable(AUTHOR)
.alter(TITLE).defaultValue("no title").execute();
create.alterTable(AUTHOR)
.alter(TITLE).set(VARCHAR.length(5)).execute();
create.alterTable(AUTHOR)
.alter(TITLE).set(VARCHAR.length(5).nullable(false)).execute();
create.alterTable(AUTHOR).drop(TITLE).execute();]]></java>
</code-pair><html>
<h3>Sequences</h3>
</html><code-pair>
<sql><![CDATA[ALTER SEQUENCE S_AUTHOR_ID RESTART;
ALTER SEQUENCE S_AUTHOR_ID RESTART WITH n;]]></sql>
<java><![CDATA[create.alterSequence(S_AUTHOR_ID).restart().execute();
create.alterSequence(S_AUTHOR_ID).restartWith(n).execute();]]></java>
</code-pair><html>
</html></content>
</section>
<section id="create-statement">
<title>The CREATE statement</title>
<content><html>
<p>
jOOQ currently supports the following <code>CREATE</code> statements (SQL examples in PostgreSQL syntax):
</p>
<h3>Indexes</h3>
</html><code-pair>
<sql><![CDATA[CREATE INDEX I_AUTHOR_LAST_NAME
ON AUTHOR(LAST_NAME);]]></sql>
<java><![CDATA[create.createIndex("I_AUTHOR_LAST_NAME")
.on(AUTHOR, AUTHOR.LAST_NAME).execute();]]></java>
</code-pair><html>
<h3>Sequences</h3>
</html><code-pair>
<sql><![CDATA[CREATE SEQUENCE S_AUTHOR_ID;]]></sql>
<java><![CDATA[create.createSequence(S_AUTHOR_ID).execute();]]></java>
</code-pair><html>
<h3>Tables</h3>
</html><code-pair>
<sql><![CDATA[CREATE TABLE AUTHOR (
ID INT,
FIRST_NAME VARCHAR(50),
LAST_NAME VARCHAR(50)
);
CREATE TABLE TOP_AUTHORS AS
SELECT
ID,
FIRST_NAME,
LAST_NAME
FROM AUTHOR
WHERE 50 < (
SELECT COUNT(*) FROM BOOK
WHERE BOOK.AUTHOR_ID = AUTHOR.ID
);]]></sql>
<java><![CDATA[create.createTable(AUTHOR)
.column(AUTHOR.ID, SQLDataType.INTEGER)
.column(AUTHOR.FIRST_NAME, SQLDataType.VARCHAR.length(50))
.column(AUTHOR_LAST_NAME, SQLDataType.VARCHAR.length(50))
.execute();
create.createTable("TOP_AUTHORS").as(
select(
AUTHOR.ID,
AUTHOR.FIRST_NAME,
AUTHOR.LAST_NAME)
.from(AUTHOR)
.where(val(50).lt(
selectCount().from(BOOK)
.where(BOOK.AUTHOR_ID.eq(AUTHOR.ID))
))).execute();]]></java>
</code-pair><html>
<h3>Views</h3>
</html><code-pair>
<sql><![CDATA[CREATE VIEW V_TOP_AUTHORS AS
SELECT
ID,
FIRST_NAME,
LAST_NAME
FROM AUTHOR
WHERE 50 < (
SELECT COUNT(*) FROM BOOK
WHERE BOOK.AUTHOR_ID = AUTHOR.ID
);]]></sql>
<java><![CDATA[create.createView("V_TOP_AUTHORS").as(
select(
AUTHOR.ID,
AUTHOR.FIRST_NAME,
AUTHOR.LAST_NAME)
.from(AUTHOR)
.where(val(50).lt(
selectCount().from(BOOK)
.where(BOOK.AUTHOR_ID.eq(AUTHOR.ID))
))).execute();]]></java>
</code-pair><html>
</html></content>
</section>
<section id="drop-statement">
<title>The DROP statement</title>
<content><html>
<p>
jOOQ currently supports the following <code>DROP</code> statements (SQL examples in PostgreSQL syntax):
</p>
<h3>Indexes</h3>
</html><code-pair>
<sql><![CDATA[DROP INDEX I_AUTHOR_LAST_NAME;
DROP INDEX IF EXISTS I_AUTHOR_LAST_NAME;]]></sql>
<java><![CDATA[create.dropIndex("I_AUTHOR_LAST_NAME").execute();
create.dropIndexIfExists("I_AUTHOR_LAST_NAME").execute();]]></java>
</code-pair><html>
<h3>Sequences</h3>
</html><code-pair>
<sql><![CDATA[DROP SEQUENCE S_AUTHOR_ID;
DROP SEQUENCE IF EXISTS S_AUTHOR_ID;]]></sql>
<java><![CDATA[create.dropSequence(S_AUTHOR_ID).execute();
create.dropSequenceIfExists(S_AUTHOR_ID).execute();]]></java>
</code-pair><html>
<h3>Tables</h3>
</html><code-pair>
<sql><![CDATA[DROP TABLE AUTHOR;
DROP TABLE IF EXISTS AUTHOR;]]></sql>
<java><![CDATA[create.dropTable(AUTHOR).execute();
create.dropTableIfExists(AUTHOR).execute();]]></java>
</code-pair><html>
<h3>Views</h3>
</html><code-pair>
<sql><![CDATA[DROP VIEW V_AUTHOR;
DROP VIEW IF EXISTS V_AUTHOR;]]></sql>
<java><![CDATA[create.dropView(V_AUTHOR).execute();
create.dropViewIfExists(V_AUTHOR).execute();]]></java>
</code-pair><html>
</html></content>
</section>
<section id="truncate-statement">
<title>The TRUNCATE statement</title>
<content><html>
<p>
Even if the <code>TRUNCATE</code> statement mainly modifies data, it is generally considered to be a DDL statement. It is popular in many databases when you want to bypass constraints for table truncation. Databases may behave differently, when a truncated table is referenced by other tables. For instance, they may fail if records from a truncated table are referenced, even with <code>ON DELETE CASCADE</code> clauses in place. Please, consider your database manual to learn more about its <code>TRUNCATE</code> implementation.
</p>
<p>
The <code>TRUNCATE</code> syntax is trivial:
</p>
</html><code-pair>
<sql>TRUNCATE TABLE AUTHOR;</sql>
<java>create.truncate(AUTHOR).execute();</java>
</code-pair><html>
<p>
<code>TRUNCATE</code> is not supported by Ingres and SQLite. jOOQ will execute a <code>DELETE FROM AUTHOR</code> statement instead.
</p>
</html></content>
</section>
</sections>
</section>
<section id="table-expressions">
<title>Table expressions</title>
<content><html>
<p>
The following sections explain the various types of table expressions supported by jOOQ
</p>
</html></content>
<sections>
<section id="generated-tables">
<title>Generated Tables</title>
<content><html>
<p>
Most of the times, when thinking about a <reference id="table-expressions" title="table expression"/> you're probably thinking about an actual table in your database schema. If you're using jOOQ's <reference id="code-generation" title="code generator"/>, you will have all tables from your database schema available to you as type safe Java objects. You can then use these tables in SQL <reference id="from-clause" title="FROM clauses"/>, <reference id="join-clause" title="JOIN clauses"/> or in other <reference id="sql-statements" title="SQL statements"/>, just like any other table expression. An example is given here:
</p>
</html><code-pair>
<sql><![CDATA[SELECT *
FROM AUTHOR -- Table expression AUTHOR
JOIN BOOK -- Table expression BOOK
ON (AUTHOR.ID = BOOK.AUTHOR_ID)
]]>&#160;</sql>
<java><![CDATA[create.select()
.from(AUTHOR) // Table expression AUTHOR
.join(BOOK) // Table expression BOOK
.on(AUTHOR.ID.equal(BOOK.AUTHOR_ID))
.fetch();]]></java></code-pair><html>
<p>
The above example shows how AUTHOR and BOOK tables are joined in a <reference id="select-statement" title="SELECT statement"/>. It also shows how you can access <reference id="table-columns" title="table columns"/> by dereferencing the relevant Java attributes of their tables.
</p>
<p>
See the manual's section about <reference id="codegen-tables" title="generated tables"/> for more information about what is really generated by the <reference id="code-generation" title="code generator"/>
</p>
</html></content>
</section>
<section id="aliased-tables">
<title>Aliased Tables</title>
<content><html>
<p>
The strength of jOOQ's <reference id="code-generation" title="code generator"/> becomes more obvious when you perform table aliasing and dereference fields from generated aliased tables. This can best be shown by example:
</p>
</html><code-pair><sql><![CDATA[-- Select all books by authors born after 1920,
-- named "Paulo" from a catalogue:
SELECT *
FROM author a
JOIN book b ON a.id = b.author_id
WHERE a.year_of_birth > 1920
AND a.first_name = 'Paulo'
ORDER BY b.title
]]>&#160;</sql>
<java><![CDATA[// Declare your aliases before using them in SQL:
Author a = AUTHOR.as("a");
Book b = BOOK.as("b");
// Use aliased tables in your statement
create.select()
.from(a)
.join(b).on(a.ID.equal(b.AUTHOR_ID))
.where(a.YEAR_OF_BIRTH.greaterThan(1920)
.and(a.FIRST_NAME.equal("Paulo")))
.orderBy(b.TITLE)
.fetch();]]></java></code-pair><html>
<p>
As you can see in the above example, calling <code>as()</code> on generated tables returns an object of the same type as the table. This means that the resulting object can be used to dereference fields from the aliased table. This is quite powerful in terms of having your Java compiler check the syntax of your SQL statements. If you remove a column from a table, dereferencing that column from that table alias will cause compilation errors.
</p>
<h3>Dereferencing columns from other table expressions</h3>
<p>
Only few table expressions provide the SQL syntax typesafety as shown above, where generated tables are used. Most tables, however, expose their fields through <code>field()</code> methods:
</p>
</html><java><![CDATA[// "Type-unsafe" aliased table:
Table<?> a = AUTHOR.as("a");
// Get fields from a:
Field<?> id = a.field("ID");
Field<?> firstName = a.field("FIRST_NAME");]]></java><html>
<h3>Derived column lists</h3>
<p>
The SQL standard specifies how a table can be renamed / aliased in one go along with its columns. It references the term "derived column list" for the following syntax (as supported by Postgres, for instance):
</p>
</html><sql><![CDATA[SELECT t.a, t.b
FROM (
SELECT 1, 2
) t(a, b)]]></sql><html>
<p>
This feature is useful in various use-cases where column names are not known in advance (but the table's degree is!). An example for this are <reference id="array-and-cursor-unnesting" title="unnested tables"/>, or the <reference id="values" title="VALUES() table constructor"/>:
</p>
</html><sql><![CDATA[-- Unnested tables
SELECT t.a, t.b
FROM unnest(my_table_function()) t(a, b)
-- VALUES() constructor
SELECT t.a, t.b
FROM VALUES(1, 2),(3, 4) t(a, b)]]></sql><html>
<p>
Only few databases really support such a syntax, but fortunately, jOOQ can simulate it easily using <code>UNION ALL</code> and an empty dummy record specifying the new column names. The two statements are equivalent:
</p>
</html><sql><![CDATA[-- Using derived column lists
SELECT t.a, t.b
FROM (
SELECT 1, 2
) t(a, b)
-- Using UNION ALL and a dummy record
SELECT t.a, t.b
FROM (
SELECT null a, null b FROM DUAL WHERE 1 = 0
UNION ALL
SELECT 1, 2 FROM DUAL
) t]]></sql><html>
<p>
In jOOQ, you would simply specify a varargs list of column aliases as such:
</p>
</html><java><![CDATA[// Unnested tables
create.select().from(unnest(myTableFunction()).as("t", "a", "b")).fetch();
// VALUES() constructor
create.select().from(values(
row(1, 2),
row(3, 4)
).as("t", "a", "b"))
.fetch();]]></java>
</content>
</section>
<section id="joined-tables">
<title>Joined tables</title>
<content><html>
<p>
The <reference id="join-clause" title="JOIN operators"/> that can be used in <reference id="select-statement" title="SQL SELECT statements"/> are the most powerful and best supported means of creating new <reference id="table-expressions" title="table expressions"/> in SQL. Informally, the following can be said:
</p>
</html><text>A(colA1, ..., colAn) "join" B(colB1, ..., colBm) "produces" C(colA1, ..., colAn, colB1, ..., colBm)</text><html>
<p>
SQL and relational algebra distinguish between at least the following JOIN types (upper-case: SQL, lower-case: relational algebra):
</p>
<ul>
<li><strong>CROSS JOIN or cartesian product</strong>: The basic JOIN in SQL, producing a relational cross product, combining every record of table A with every record of table B. Note that cartesian products can also be produced by listing comma-separated <reference id="table-expressions" title="table expressions"/> in the <reference id="from-clause" title="FROM clause"/> of a <reference id="select-statement" title="SELECT statement"/></li>
<li><strong>NATURAL JOIN</strong>: The basic JOIN in relational algebra, yet a rarely used JOIN in databases with everyday degree of normalisation. This JOIN type unconditionally equi-joins two tables by all columns with the same name (requiring foreign keys and primary keys to share the same name). Note that the JOIN columns will only figure once in the resulting <reference id="table-expressions" title="table expression"/>.</li>
<li><strong>INNER JOIN or equi-join</strong>: This JOIN operation performs a cartesian product (CROSS JOIN) with a <reference id="conditional-expressions" title="filtering predicate"/> being applied to the resulting <reference id="table-expressions" title="table expression"/>. Most often, a <reference id="comparison-predicate" title="equal comparison predicate"/> comparing foreign keys and primary keys will be applied as a filter, but any other predicate will work, too.</li>
<li><strong>OUTER JOIN</strong>: This JOIN operation performs a cartesian product (CROSS JOIN) with a <reference id="conditional-expressions" title="filtering predicate"/> being applied to the resulting <reference id="table-expressions" title="table expression"/>. Most often, a <reference id="comparison-predicate" title="equal comparison predicate"/> comparing foreign keys and primary keys will be applied as a filter, but any other predicate will work, too. Unlike the INNER JOIN, an OUTER JOIN will add "empty records" to the left (table A) or right (table B) or both tables, in case the conditional expression fails to produce a .</li>
<li><strong>semi-join</strong>: In SQL, this JOIN operation can only be expressed implicitly using <reference id="in-predicate" title="IN predicates"/> or <reference id="exists-predicate" title="EXISTS predicates"/>. The <reference id="table-expressions" title="table expression"/> resulting from a semi-join will only contain the left-hand side table A</li>
<li><strong>anti-join</strong>: In SQL, this JOIN operation can only be expressed implicitly using <reference id="in-predicate" title="NOT IN predicates"/> or <reference id="exists-predicate" title="NOT EXISTS predicates"/>. The <reference id="table-expressions" title="table expression"/> resulting from a semi-join will only contain the left-hand side table A</li>
<li><strong>division</strong>: This JOIN operation is hard to express at all, in SQL. See the manual's chapter about <reference id="relational-division" title="relational division"/> for details on how jOOQ simulates this operation.</li>
</ul>
<p>
jOOQ supports all of these JOIN types (except semi-join and anti-join) directly on any <reference id="table-expressions" title="table expression"/>:
</p>
</html><java><![CDATA[// jOOQ's relational division convenience syntax
DivideByOnStep divideBy(Table<?> table)
// Various overloaded INNER JOINs
TableOnStep join(TableLike<?>)
TableOnStep join(String)
TableOnStep join(String, Object...)
TableOnStep join(String, QueryPart...)
// Various overloaded OUTER JOINs (supporting Oracle's partitioned OUTER JOIN)
// Overloading is similar to that of INNER JOIN
TablePartitionByStep leftOuterJoin(TableLike<?>)
TablePartitionByStep rightOuterJoin(TableLike<?>)
// Various overloaded FULL OUTER JOINs
TableOnStep fullOuterJoin(TableLike<?>)
// Various overloaded CROSS JOINs
Table<Record> crossJoin(TableLike<?>)
// Various overloaded NATURAL JOINs
Table<Record> naturalJoin(TableLike<?>)
Table<Record> naturalLeftOuterJoin(TableLike<?>)
Table<Record> naturalRightOuterJoin(TableLike<?>)]]></java><html>
<p>
Note that most of jOOQ's JOIN operations give way to a similar DSL API hierarchy as previously seen in the manual's section about the <reference id="join-clause" title="JOIN clause"/>
</p>
</html></content>
</section>
<section id="values">
<title>The VALUES() table constructor</title>
<content><html>
<p>
Some databases allow for expressing in-memory temporary tables using a <code>VALUES()</code> constructor. This constructor usually works the same way as the <code>VALUES()</code> clause known from the <reference id="insert-statement" title="INSERT statement"/> or from the <reference id="merge-statement" title="MERGE statement"/>. With jOOQ, you can also use the <code>VALUES()</code> table constructor, to create tables that can be used in a <reference id="select-statement" title="SELECT statement's"/> <reference id="from-clause" title="FROM clause"/>:
</p>
</html><code-pair>
<sql><![CDATA[SELECT a, b
FROM VALUES(1, 'a'),
(2, 'b') t(a, b)
]]>&#160;</sql>
<java><![CDATA[create.select()
.from(values(row(1, "a"),
row(2, "b")).as("t", "a", "b"))
.fetch();]]></java>
</code-pair><html>
<p>
Note, that it is usually quite useful to provide column aliases ("derived column lists") along with the table alias for the <code>VALUES()</code> constructor.
</p>
<p>
The above statement is simulated by jOOQ for those databases that do not support the <code>VALUES()</code> constructor, natively (actual simulations may vary):
</p>
</html><sql><![CDATA[-- If derived column expressions are supported:
SELECT a, b
FROM (
SELECT 1, 'a' FROM DUAL UNION ALL
SELECT 2, 'b' FROM DUAL
) t(a, b)
-- If derived column expressions are not supported:
SELECT a, b
FROM (
-- An empty dummy record is added to provide column names for the simulated derived column expression
SELECT NULL a, NULL b FROM DUAL WHERE 1 = 0 UNION ALL
-- Then, the actual VALUES() constructor is simulated
SELECT 1, 'a' FROM DUAL UNION ALL
SELECT 2, 'b' FROM DUAL
) t
]]></sql>
</content>
</section>
<section id="nested-selects">
<title>Nested SELECTs</title>
<content><html>
<p>
A <reference id="select-statement" title="SELECT statement"/> can appear almost anywhere a <reference id="table-expressions" title="table expression"/> can. Such a "nested SELECT" is often called a "derived table". Apart from many convenience methods accepting <reference class="org.jooq.Select"/> objects directly, a SELECT statement can always be transformed into a <reference class="org.jooq.Table"/> object using the asTable() method.
</p>
<h3>Example: Scalar subquery</h3>
</html><code-pair>
<sql><![CDATA[SELECT *
FROM BOOK
WHERE BOOK.AUTHOR_ID = (
SELECT ID
FROM AUTHOR
WHERE LAST_NAME = 'Orwell')
]]>&#160;</sql>
<java>create.select()
.from(BOOK)
.where(BOOK.AUTHOR_ID.equal(create
.select(AUTHOR.ID)
.from(AUTHOR)
.where(AUTHOR.LAST_NAME.equal("Orwell"))))
.fetch();</java>
</code-pair><html>
<h3>Example: Derived table</h3>
</html><code-pair>
<sql>&#160;<![CDATA[
SELECT nested.* FROM (
SELECT AUTHOR_ID, count(*) books
FROM BOOK
GROUP BY AUTHOR_ID
) nested
ORDER BY nested.books DESC
]]>&#160;</sql>
<java><![CDATA[Table<Record> nested =
create.select(BOOK.AUTHOR_ID, count().as("books"))
.from(BOOK)
.groupBy(BOOK.AUTHOR_ID).asTable("nested");
create.select(nested.fields())
.from(nested)
.orderBy(nested.field("books"))
.fetch();]]></java>
</code-pair><html>
<h3>Example: Correlated subquery</h3>
</html><code-pair>
<sql>&#160;<![CDATA[
SELECT LAST_NAME, (
SELECT COUNT(*)
FROM BOOK
WHERE BOOK.AUTHOR_ID = AUTHOR.ID) books
FROM AUTHOR
ORDER BY books DESC
]]>&#160;</sql>
<java><![CDATA[// The type of books cannot be inferred from the Select<?>
Field<Object> books =
create.selectCount()
.from(BOOK)
.where(BOOK.AUTHOR_ID.equal(AUTHOR.ID))
.asField("books");
create.select(AUTHOR.ID, books)
.from(AUTHOR)
.orderBy(books, AUTHOR.ID))
.fetch();]]></java>
</code-pair>
</content>
</section>
<section id="pivot-tables">
<title>The Oracle 11g PIVOT clause</title>
<content><html>
<p>
If you are closely coupling your application to an Oracle database, you can take advantage of some Oracle-specific features, such as the PIVOT clause, used for statistical analyses. The formal syntax definition is as follows:
</p>
</html><sql>-- SELECT ..
FROM table PIVOT (aggregateFunction [, aggregateFunction] FOR column IN (expression [, expression]))
-- WHERE ..</sql><html>
<p>
The PIVOT clause is available from the <reference class="org.jooq.Table"/> type, as pivoting is done directly on a table. Currently, only Oracle's PIVOT clause is supported. Support for SQL Server's slightly different PIVOT clause will be added later. Also, jOOQ may simulate PIVOT for other dialects in the future.
</p>
</html></content>
</section>
<section id="relational-division">
<title>jOOQ's relational division syntax</title>
<content><html>
<p>
There is one operation in relational algebra that is not given a lot of attention, because it is rarely used in real-world applications. It is the relational division, the opposite operation of the cross product (or, relational multiplication). The following is an approximate definition of a relational division:
</p>
</html><config>Assume the following cross join / cartesian product
C = A × B
Then it can be said that
A = C ÷ B
B = C ÷ A</config><html>
<p>
With jOOQ, you can simplify using relational divisions by using the following syntax:
</p>
</html><java>C.divideBy(B).on(C.ID.equal(B.C_ID)).returning(C.TEXT)</java><html>
<p>
The above roughly translates to
</p>
</html><sql>SELECT DISTINCT C.TEXT FROM C "c1"
WHERE NOT EXISTS (
SELECT 1 FROM B
WHERE NOT EXISTS (
SELECT 1 FROM C "c2"
WHERE "c2".TEXT = "c1".TEXT
AND "c2".ID = B.C_ID
)
)</sql><html>
<p>
Or in plain text: Find those TEXT values in C whose ID's correspond to all ID's in B. Note that from the above SQL statement, it is immediately clear that proper indexing is of the essence. Be sure to have indexes on all columns referenced from the on(...) and returning(...) clauses.
</p>
<p>
For more information about relational division and some nice, real-life examples, see
</p>
<ul>
<li><a href="http://en.wikipedia.org/wiki/Relational_algebra#Division" title="Wikipedia article on relational division">http://en.wikipedia.org/wiki/Relational_algebra#Division</a></li>
<li><a href="http://www.simple-talk.com/sql/t-sql-programming/divided-we-stand-the-sql-of-relational-division/" title="A nice summary of what relational division is and how it is best implemented in SQL">http://www.simple-talk.com/sql/t-sql-programming/divided-we-stand-the-sql-of-relational-division/</a></li>
</ul>
</html></content>
</section>
<section id="array-and-cursor-unnesting">
<title>Array and cursor unnesting</title>
<content><html>
<p>
The SQL standard specifies how SQL databases should implement ARRAY and TABLE types, as well as CURSOR types. Put simply, a CURSOR is a pointer to any materialised <reference id="table-expressions" title="table expression"/>. Depending on the cursor's features, this table expression can be scrolled through in both directions, records can be locked, updated, removed, inserted, etc. Often, CURSOR types contain s, whereas ARRAY and TABLE types contain simple scalar values, although that is not a requirement
</p>
<p>
ARRAY types in SQL are similar to Java's array types. They contain a "component type" or "element type" and a "dimension". This sort of ARRAY type is implemented in H2, HSQLDB and Postgres and supported by jOOQ as such. Oracle uses strongly-typed arrays, which means that an ARRAY type (VARRAY or TABLE type) has a name and possibly a maximum capacity associated with it.
</p>
<h3>Unnesting array and cursor types</h3>
<p>
The real power of these types become more obvious when you fetch them from <reference id="stored-procedures" title="stored procedures"/> to unnest them as <reference id="table-expressions" title="table expressions"/> and use them in your <reference id="from-clause" title="FROM clause"/>. An example is given here, where Oracle's DBMS_XPLAN package is used to fetch a cursor containing data about the most recent execution plan:
</p>
</html><code-pair>
<sql><![CDATA[SELECT *
FROM TABLE(DBMS_XPLAN.DISPLAY_CURSOR(null, null, 'ALLSTATS'));
]]>&#160;</sql>
<java><![CDATA[create.select()
.from(table(DbmsXplan.displayCursor(null, null, "ALLSTATS"))
.fetch();]]></java>
</code-pair><html>
<p>
Note, in order to access the DbmsXplan package, you can use the <reference id="code-generation" title="code generator"/> to generate Oracle's SYS schema.
</p>
</html></content>
</section>
<section id="table-valued-functions">
<title>Table-valued functions</title>
<content><html>
<p>
Some databases support functions that can produce tables for use in arbitrary <reference id="select-statement" title="SELECT statements"/>. jOOQ supports these functions out-of-the-box for such databases. For instance, in SQL Server, the following function produces a table of <code>(ID, TITLE)</code> columns containing either all the books or just one book by ID:
</p>
</html><sql><![CDATA[CREATE FUNCTION f_books (@id INTEGER)
RETURNS @out_table TABLE (
id INTEGER,
title VARCHAR(400)
)
AS
BEGIN
INSERT @out_table
SELECT id, title
FROM book
WHERE @id IS NULL OR id = @id
ORDER BY id
RETURN
END]]></sql><html>
<p>
The jOOQ code generator will now produce a <reference id="generated-tables" title="generated table"/> from the above, which can be used as a SQL function:
</p>
</html><java><![CDATA[// Fetching all books records
Result<FBooksRecord> r1 = create.selectFrom(fBooks(null)).fetch();
// Lateral joining the table-valued function to another table using CROSS APPLY:
create.select(BOOK.ID, F_BOOKS.TITLE)
.from(BOOK.crossApply(fBooks(BOOK.ID)))
.fetch();]]></java><html>
</html></content>
</section>
¨
<section id="dual">
<title>The DUAL table</title>
<content><html>
<p>
The SQL standard specifies that the <reference id="from-clause" title="FROM clause"/> is optional in a <reference id="select-statement" title="SELECT statement"/>. However, according to the standard, you may then no longer use some other clauses, such as the <reference id="where-clause" title="WHERE clause"/>. In the real world, there exist three types of databases:
</p>
<ul>
<li>The ones that always require a <code>FROM</code> clause (as required by the SQL standard)</li>
<li>The ones that never require a <code>FROM</code> clause (and still allow a <code>WHERE</code> clause)</li>
<li>The ones that require a <code>FROM</code> clause only with a <code>WHERE</code> clause, <code>GROUP BY</code> clause, or <code>HAVING</code> clause</li>
</ul>
<p>
With jOOQ, you don't have to worry about the above distinction of SQL dialects. jOOQ never requires a <code>FROM</code> clause, but renders the necessary <code>"DUAL"</code> table, if needed. The following program shows how jOOQ renders <code>"DUAL"</code> tables
</p>
</html><code-pair>
<sql><![CDATA[SELECT 1 FROM (SELECT COUNT(*) FROM MSysResources) AS dual
SELECT 1
SELECT 1 FROM "db_root"
SELECT 1 FROM "SYSIBM"."DUAL"
SELECT 1 FROM "SYSIBM"."SYSDUMMY1"
SELECT 1 FROM "RDB$DATABASE"
SELECT 1 FROM dual
SELECT 1 FROM "INFORMATION_SCHEMA"."SYSTEM_USERS"
SELECT 1 FROM (SELECT 1 AS dual FROM systables WHERE tabid = 1)
SELECT 1 FROM (SELECT 1 AS dual) AS dual
SELECT 1 FROM dual
SELECT 1 FROM dual
SELECT 1 FROM dual
SELECT 1
SELECT 1
SELECT 1
SELECT 1 FROM [SYS].[DUMMY]
]]></sql>
<java><![CDATA[DSL.using(SQLDialect.ACCESS ).selectOne().getSQL();
DSL.using(SQLDialect.ASE ).selectOne().getSQL();
DSL.using(SQLDialect.CUBRID ).selectOne().getSQL();
DSL.using(SQLDialect.DB2 ).selectOne().getSQL();
DSL.using(SQLDialect.DERBY ).selectOne().getSQL();
DSL.using(SQLDialect.FIREBIRD ).selectOne().getSQL();
DSL.using(SQLDialect.H2 ).selectOne().getSQL();
DSL.using(SQLDialect.HSQLDB ).selectOne().getSQL();
DSL.using(SQLDialect.INFORMIX ).selectOne().getSQL();
DSL.using(SQLDialect.INGRES ).selectOne().getSQL();
DSL.using(SQLDialect.MARIADB ).selectOne().getSQL();
DSL.using(SQLDialect.MYSQL ).selectOne().getSQL();
DSL.using(SQLDialect.ORACLE ).selectOne().getSQL();
DSL.using(SQLDialect.POSTGRES ).selectOne().getSQL();
DSL.using(SQLDialect.SQLITE ).selectOne().getSQL();
DSL.using(SQLDialect.SQLSERVER).selectOne().getSQL();
DSL.using(SQLDialect.SYBASE ).selectOne().getSQL();]]></java>
</code-pair><html>
<p>
Note, that some databases (H2, MySQL) can normally do without <code>"DUAL"</code>. However, there exist some corner-cases with complex nested <code>SELECT</code> statements, where this will cause syntax errors (or parser bugs). To stay on the safe side, jOOQ will always render "dual" in those dialects.
</p>
</html></content>
</section>
</sections>
</section>
<section id="column-expressions">
<title>Column expressions</title>
<content><html>
<p>
Column expressions can be used in various SQL clauses in order to refer to one or several columns. This chapter explains how to form various types of column expressions with jOOQ. A particular type of column expression is given in the section about <reference id="row-value-expressions" title="tuples or row value expressions"/>, where an expression may have a degree of more than one.
</p>
<h3>Using column expressions in jOOQ</h3>
<p>
jOOQ allows you to freely create arbitrary column expressions using a fluent expression construction API. Many expressions can be formed as functions from <reference id="dsl" title="DSL methods"/>, other expressions can be formed based on a pre-existing column expression. For example:
</p>
</html><java><![CDATA[// A regular table column expression
Field<String> field1 = BOOK.TITLE;
// A function created from the DSL using "prefix" notation
Field<String> field2 = trim(BOOK.TITLE);
// The same function created from a pre-existing Field using "postfix" notation
Field<String> field3 = BOOK.TITLE.trim();
// More complex function with advanced DSL syntax
Field<String> field4 = listAgg(BOOK.TITLE)
.withinGroupOrderBy(BOOK.ID.asc())
.over().partitionBy(AUTHOR.ID);]]></java><html>
<p>
In general, it is up to you whether you want to use the "prefix" notation or the "postfix" notation to create new column expressions based on existing ones. The "SQL way" would be to use the "prefix notation", with functions created from the <reference id="dsl" title="DSL"/>. The "Java way" or "object-oriented way" would be to use the "postfix" notation with functions created from <reference class="org.jooq.Field"/> objects. Both ways ultimately create the same query part, though.
</p>
</html></content>
<sections>
<section id="table-columns">
<title>Table columns</title>
<content><html>
<p>
Table columns are the most simple implementations of a <reference id="column-expressions" title="column expression"/>. They are mainly produced by jOOQ's <reference id="code-generation" title="code generator"/> and can be dereferenced from the generated tables. This manual is full of examples involving table columns. Another example is given in this query:
</p>
</html><code-pair>
<sql><![CDATA[SELECT BOOK.ID, BOOK.TITLE
FROM BOOK
WHERE BOOK.TITLE LIKE '%SQL%'
ORDER BY BOOK.TITLE
]]>&#160;</sql>
<java><![CDATA[create.select(BOOK.ID, BOOK.TITLE)
.from(BOOK)
.where(BOOK.TITLE.like("%SQL%"))
.orderBy(BOOK.TITLE)
.fetch();]]></java>
</code-pair><html>
<p>
Table columns implement a more specific interface called <reference class="org.jooq.TableField"/>, which is parameterised with its associated <code>&lt;R extends Record&gt;</code> record type.
</p>
<p>
See the manual's section about <reference id="codegen-tables" title="generated tables"/> for more information about what is really generated by the <reference id="code-generation" title="code generator"/>
</p>
</html></content>
</section>
<section id="aliased-columns">
<title>Aliased columns</title>
<content><html>
<p>
Just like <reference id="aliased-tables" title="tables"/>, columns can be renamed using aliases. Here is an example:
</p>
</html><sql> SELECT FIRST_NAME || ' ' || LAST_NAME author, COUNT(*) books
FROM AUTHOR
JOIN BOOK ON AUTHOR.ID = AUTHOR_ID
GROUP BY FIRST_NAME, LAST_NAME;</sql><html>
<p>
Here is how it's done with jOOQ:
</p>
</html><java>Record record = create.select(
concat(AUTHOR.FIRST_NAME, val(" "), AUTHOR.LAST_NAME).as("author"),
count().as("books"))
.from(AUTHOR)
.join(BOOK).on(AUTHOR.ID.equal(BOOK.AUTHOR_ID))
.groupBy(AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME)
.fetchAny();</java><html>
<p>
When you alias Fields like above, you can access those Fields' values using the alias name:
</p>
</html><java>System.out.println("Author : " + record.getValue("author"));
System.out.println("Books : " + record.getValue("books"));</java>
</content>
</section>
<section id="cast-expressions">
<title>Cast expressions</title>
<content><html>
<p>
jOOQ's source code generator tries to find the most accurate type mapping between your vendor-specific data types and a matching Java type. For instance, most <code>VARCHAR</code>, <code>CHAR</code>, <code>CLOB</code> types will map to String. Most <code>BINARY</code>, <code>BYTEA</code>, <code>BLOB</code> types will map to <code>byte[]</code>. <code>NUMERIC</code> types will default to <reference class="java.math.BigDecimal"/>, but can also be any of <reference class="java.math.BigInteger"/>, <reference class="java.lang.Long"/>, <reference class="java.lang.Integer"/>, <reference class="java.lang.Short"/>, <reference class="java.lang.Byte"/>, <reference class="java.lang.Double"/>, <reference class="java.lang.Float"/>.
</p>
<p>
Sometimes, this automatic mapping might not be what you needed, or jOOQ cannot know the type of a field. In those cases you would write SQL type <code>CAST</code> like this:
</p>
</html><sql>-- Let's say, your Postgres column LAST_NAME was VARCHAR(30)
-- Then you could do this:
SELECT CAST(AUTHOR.LAST_NAME AS TEXT) FROM DUAL</sql><html>
<p>
in jOOQ, you can write something like that:
</p>
</html><java>create.select(TAuthor.LAST_NAME.cast(PostgresDataType.TEXT)).fetch();</java><html>
<p>
The same thing can be achieved by casting a Field directly to String.class, as <code>TEXT</code> is the default data type in Postgres to map to Java's String
</p>
</html><java>create.select(TAuthor.LAST_NAME.cast(String.class)).fetch();</java><html>
<p>
The complete <code>CAST</code> API in <reference class="org.jooq.Field"/> consists of these three methods:
</p>
</html><java><![CDATA[public interface Field<T> {
// Cast this field to the type of another field
<Z> Field<Z> cast(Field<Z> field);
// Cast this field to a given DataType
<Z> Field<Z> cast(DataType<Z> type);
// Cast this field to the default DataType for a given Class
<Z> Field<Z> cast(Class<? extends Z> type);
}
// And additional convenience methods in the DSL:
public class DSL {
<T> Field<T> cast(Object object, Field<T> field);
<T> Field<T> cast(Object object, DataType<T> type);
<T> Field<T> cast(Object object, Class<? extends T> type);
<T> Field<T> castNull(Field<T> field);
<T> Field<T> castNull(DataType<T> type);
<T> Field<T> castNull(Class<? extends T> type);
}]]></java>
</content>
</section>
<section id="datatype-coercions">
<title>Datatype coercions</title>
<content><html>
<p>
A slightly different use case than <reference id="cast-expressions" title="CAST expressions"/> are data type coercions, which are not rendered through to generated SQL. Sometimes, you may want to pretend that a numeric value is really treated as a string value, for instance when binding a numeric <reference id="variable-binding" title="bind value"/>:
</p>
</html><java><![CDATA[Field<String> field1 = val(1).coerce(String.class);
Field<Integer> field2 = val("1").coerce(Integer.class);]]></java><html>
<p>
In the above example, <code>field1</code> will be treated by jOOQ as a <code>Field&lt;String></code>, binding the numeric literal <code>1</code> as a <code>VARCHAR</code> value. The same applies to <code>field2</code>, whose string literal <code>"1"</code> will be bound as an <code>INTEGER</code> value.
</p>
<p>
This technique is better than performing unsafe or rawtype casting in Java, if you cannot access the "right" field type from any given expression.
</p>
</html></content>
</section>
<section id="arithmetic-expressions">
<title>Arithmetic expressions</title>
<content><html>
<h3>Numeric arithmetic expressions</h3>
<p>
Your database can do the math for you. Arithmetic operations are implemented just like <reference id="numeric-functions" title="numeric functions"/>, with similar limitations as far as type restrictions are concerned. You can use any of these operators:
</p>
</html><config> + - * / %</config><html>
<p>
In order to express a SQL query like this one:
</p>
</html><sql>SELECT ((1 + 2) * (5 - 3) / 2) % 10 FROM DUAL</sql><html>
<p>
You can write something like this in jOOQ:
</p>
</html><java>create.select(val(1).add(2).mul(val(5).sub(3)).div(2).mod(10)).fetch();</java><html>
<h3>Operator precedence</h3>
<p>
jOOQ does not know any operator precedence (see also <reference id="boolean-operator-precedence" title="boolean operator precedence"/>). All operations are evaluated from left to right, as with any object-oriented API. The two following expressions are the same:
</p>
</html><java> val(1).add(2) .mul(val(5).sub(3)) .div(2) .mod(10);
(((val(1).add(2)).mul(val(5).sub(3))).div(2)).mod(10);</java><html>
<h3>Datetime arithmetic expressions</h3>
<p>
jOOQ also supports the Oracle-style syntax for adding days to a Field&lt;? extends java.util.Date&gt;
</p>
</html><code-pair>
<sql>SELECT SYSDATE + 3 FROM DUAL;</sql>
<java>create.select(currentTimestamp().add(3)).fetch();</java>
</code-pair><html>
<p>
For more advanced datetime arithmetic, use the DSL's timestampDiff() and dateDiff() functions, as well as jOOQ's built-in SQL standard <code>INTERVAL</code> data type support:
</p>
<ul>
<li><code>INTERVAL YEAR TO MONTH</code>: <reference class="org.jooq.types.YearToMonth"/></li>
<li><code>INTERVAL DAY TO SECOND</code>: <reference class="org.jooq.types.DayToSecond"/></li>
</ul>
</html></content>
</section>
<section id="string-concatenation">
<title>String concatenation</title>
<content><html>
<p>
The SQL standard defines the concatenation operator to be an infix operator, similar to the ones we've seen in the chapter about <reference id="arithmetic-expressions" title="arithmetic expressions"/>. This operator looks like this: <code>||</code>. Some other dialects do not support this operator, but expect a <code>concat()</code> function, instead. jOOQ renders the right operator / function, depending on your <reference id="sql-dialects" title="SQL dialect"/>:
</p>
</html><code-pair>
<sql>SELECT 'A' || 'B' || 'C' FROM DUAL
-- Or in MySQL:
SELECT concat('A', 'B', 'C') FROM DUAL</sql>
<java>&#160;
// For all RDBMS, including MySQL:
create.select(concat("A", "B", "C")).fetch();
</java>
</code-pair>
</content>
</section>
<section id="general-functions">
<title>General functions</title>
<content><html>
<p>
There are a variety of general functions supported by jOOQ As discussed in the chapter about <reference id="sql-dialects" title="SQL dialects"/> functions are mostly simulated in your database, in case they are not natively supported.
</p>
<p>
This is a list of general functions supported by jOOQ's <reference id="dsl" title="DSL"/>:
</p>
<ul>
<li><strong><code>COALESCE</code></strong>: Get the first non-null value in a list of arguments.</li>
<li><strong><code>NULLIF</code></strong>: Return <code>NULL</code> if both arguments are equal, or the first argument, otherwise.</li>
<li><strong><code>NVL</code></strong>: Get the first non-null value among two arguments.</li>
<li><strong><code>NVL2</code></strong>: Get the second argument if the first is null, or the third argument, otherwise.</li>
</ul>
<p>
Please refer to the <reference class="org.jooq.impl.DSL" title="DSL Javadoc"/> for more details.
</p>
</html></content>
</section>
<section id="numeric-functions">
<title>Numeric functions</title>
<content><html>
<p>
Math can be done efficiently in the database before returning results to your Java application. In addition to the <reference id="arithmetic-expressions" title="arithmetic expressions" /> discussed previously, jOOQ also supports a variety of numeric functions. As discussed in the chapter about <reference id="sql-dialects" title="SQL dialects"/> numeric functions (as any function type) are mostly simulated in your database, in case they are not natively supported.
</p>
<p>
This is a list of numeric functions supported by jOOQ's <reference id="dsl" title="DSL"/>:
</p>
<ul>
<li><strong><code>ABS</code></strong>: Get the absolute value of a value.</li>
<li><strong><code>ACOS</code></strong>: Get the arc cosine of a value.</li>
<li><strong><code>ASIN</code></strong>: Get the arc sine of a value.</li>
<li><strong><code>ATAN</code></strong>: Get the arc tangent of a value.</li>
<li><strong><code>ATAN2</code></strong>: Get the atan2 function of two values.</li>
<li><strong><code>CEIL</code></strong>: Get the smalles integer value larger than a given numeric value.</li>
<li><strong><code>COS</code></strong>: Get the cosine of a value.</li>
<li><strong><code>COSH</code></strong>: Get the hyperbolic cosine of a value.</li>
<li><strong><code>COT</code></strong>: Get the cotangent of a value.</li>
<li><strong><code>COTH</code></strong>: Get the hyperbolic cotangent of a value.</li>
<li><strong><code>DEG</code></strong>: Transform radians into degrees.</li>
<li><strong><code>EXP</code></strong>: Calculate e^value.</li>
<li><strong><code>FLOOR</code></strong>: Get the largest integer value smaller than a given numeric value.</li>
<li><strong><code>GREATEST</code></strong>: Finds the greatest among all argument values (can also be used with non-numeric values).</li>
<li><strong><code>LEAST</code></strong>: Finds the least among all argument values (can also be used with non-numeric values).</li>
<li><strong><code>LN</code></strong>: Get the natural logarithm of a value.</li>
<li><strong><code>LOG</code></strong>: Get the logarithm of a value given a base.</li>
<li><strong><code>POWER</code></strong>: Calculate value^exponent.</li>
<li><strong><code>RAD</code></strong>: Transform degrees into radians.</li>
<li><strong><code>RAND</code></strong>: Get a random number.</li>
<li><strong><code>ROUND</code></strong>: Rounds a value to the nearest integer.</li>
<li><strong><code>SIGN</code></strong>: Get the sign of a value (-1, 0, 1).</li>
<li><strong><code>SIN</code></strong>: Get the sine of a value.</li>
<li><strong><code>SINH</code></strong>: Get the hyperbolic sine of a value.</li>
<li><strong><code>SQRT</code></strong>: Calculate the square root of a value.</li>
<li><strong><code>TAN</code></strong>: Get the tangent of a value.</li>
<li><strong><code>TANH</code></strong>: Get the hyperbolic tangent of a value.</li>
<li><strong><code>TRUNC</code></strong>: Truncate the decimals off a given value.</li>
</ul>
<p>
Please refer to the <reference class="org.jooq.impl.DSL" title="DSL Javadoc"/> for more details.
</p>
</html></content>
</section>
<section id="bitwise-functions">
<title>Bitwise functions</title>
<content><html>
<p>
Interestingly, bitwise functions and bitwise arithmetic is not very popular among SQL databases. Most databases only support a few bitwise operations, while others ship with the full set of operators. jOOQ's API includes most bitwise operations as listed below. In order to avoid ambiguities with <reference id="conditional-expressions" title="conditional operators"/>, all bitwise functions are prefixed with "bit"
</p>
<ul>
<li><strong><code>BIT_COUNT</code></strong>: Count the number of bits set to 1 in a number</li>
<li><strong><code>BIT_AND</code></strong>: Set only those bits that are set in two numbers</li>
<li><strong><code>BIT_OR</code></strong>: Set all bits that are set in at least one number</li>
<li><strong><code>BIT_NAND</code></strong>: Set only those bits that are set in two numbers, and inverse the result</li>
<li><strong><code>BIT_NOR</code></strong>: Set all bits that are set in at least one number, and inverse the result</li>
<li><strong><code>BIT_NOT</code></strong>: Inverse the bits in a number</li>
<li><strong><code>BIT_XOR</code></strong>: Set all bits that are set in at exactly one number</li>
<li><strong><code>BIT_XNOR</code></strong>: Set all bits that are set in at exactly one number, and inverse the result</li>
<li><strong><code>SHL</code></strong>: Shift bits to the left</li>
<li><strong><code>SHR</code></strong>: Shift bits to the right</li>
</ul>
<h3>Some background about bitwise operation simulation</h3>
<p>
As stated before, not all databases support all of these bitwise operations. jOOQ simulates them wherever this is possible. More details can be seen in this blog post: <br/>
<a href="http://blog.jooq.org/2011/10/30/the-comprehensive-sql-bitwise-operations-compatibility-list/">http://blog.jooq.org/2011/10/30/the-comprehensive-sql-bitwise-operations-compatibility-list/</a>
</p>
</html></content>
</section>
<section id="string-functions">
<title>String functions</title>
<content><html>
<p>
String formatting can be done efficiently in the database before returning results to your Java application. As discussed in the chapter about <reference id="sql-dialects" title="SQL dialects"/> string functions (as any function type) are mostly simulated in your database, in case they are not natively supported.
</p>
<p>
This is a list of numeric functions supported by jOOQ's <reference id="dsl" title="DSL"/>:
</p>
<ul>
<li><strong><code>ASCII</code></strong>: Get the <code>ASCII</code> code of a character.</li>
<li><strong><code>BIT_LENGTH</code></strong>: Get the length of a string in bits.</li>
<li><strong><code>CHAR_LENGTH</code></strong>: Get the length of a string in characters.</li>
<li><strong><code>CONCAT</code></strong>: Concatenate several strings.</li>
<li><strong><code>ESCAPE</code></strong>: Escape a string for use with the <reference id="like-predicate" title="LIKE predicate"/>.</li>
<li><strong><code>LENGTH</code></strong>: Get the length of a string.</li>
<li><strong><code>LOWER</code></strong>: Get a string in lower case letters.</li>
<li><strong><code>LPAD</code></strong>: Pad a string on the left side.</li>
<li><strong><code>LTRIM</code></strong>: Trim a string on the left side.</li>
<li><strong><code>OCTET_LENGTH</code></strong>: Get the length of a string in octets.</li>
<li><strong><code>POSITION</code></strong>: Find a string within another string.</li>
<li><strong><code>REPEAT</code></strong>: Repeat a string a given number of times.</li>
<li><strong><code>REPLACE</code></strong>: Replace a string within another string.</li>
<li><strong><code>RPAD</code></strong>: Pad a string on the right side.</li>
<li><strong><code>RTRIM</code></strong>: Trim a string on the right side.</li>
<li><strong><code>SUBSTRING</code></strong>: Get a substring of a string.</li>
<li><strong><code>TRIM</code></strong>: Trim a string on both sides.</li>
<li><strong><code>UPPER</code></strong>: Get a string in upper case letters.</li>
</ul>
<p>
Please refer to the <reference class="org.jooq.impl.DSL" title="DSL Javadoc"/> for more details.
</p>
<h3>Regular expressions, <code>REGEXP</code>, <code>REGEXP_LIKE</code>, etc.</h3>
<p>
Various databases have some means of searching through columns using regular expressions if the <reference id="like-predicate" title="LIKE predicate"/> does not provide sufficient pattern matching power. While there are many different functions and operators in the various databases, jOOQ settled for the SQL:2008 standard <code>REGEX_LIKE</code> operator. Being an operator (and not a function), you should use the corresponding method on <reference class="org.jooq.Field"/>:
</p>
</html><java><![CDATA[create.selectFrom(BOOK).where(TITLE.likeRegex("^.*SQL.*$")).fetch();]]></java><html>
<p>
Note that the SQL standard specifies that patterns should follow the XQuery standards. In the real world, the POSIX regular expression standard is the most used one, some use Java regular expressions, and only a few ones use Perl regular expressions. jOOQ does not make any assumptions about regular expression syntax. For cross-database compatibility, please read the relevant database manuals carefully, to learn about the appropriate syntax. Please refer to the <reference class="org.jooq.impl.DSL" title="DSL Javadoc"/> for more details.
</p>
</html></content>
<!-- don't forget regex here! -->
</section>
<section id="date-and-time-functions">
<title>Date and time functions</title>
<content><html>
<p>
This is a list of date and time functions supported by jOOQ's <reference id="dsl" title="DSL"/>:
</p>
<ul>
<li><strong><code>CURRENT_DATE</code></strong>: Get current date as a <code>DATE</code> object.</li>
<li><strong><code>CURRENT_TIME</code></strong>: Get current time as a <code>TIME</code> object.</li>
<li><strong><code>CURRENT_TIMESTAMP</code></strong>: Get current date as a <code>TIMESTAMP</code> object.</li>
<li><strong><code>DATE_ADD</code></strong>: Add a number of days or an interval to a date.</li>
<li><strong><code>DATE_DIFF</code></strong>: Get the difference in days between two dates.</li>
<li><strong><code>TIMESTAMP_ADD</code></strong>: Add a number of days or an interval to a timestamp.</li>
<li><strong><code>TIMESTAMP_DIFF</code></strong>: Get the difference as an <code>INTERVAL DAY TO SECOND</code> between two dates.</li>
</ul>
<h3>Intervals in jOOQ</h3>
<p>
jOOQ fills a gap opened by JDBC, which neglects an important SQL data type as defined by the SQL standards: <code>INTERVAL</code> types. See the manual's section about <reference id="data-types-intervals" title="INTERVAL data types"/> for more details.
</p>
</html></content>
</section>
<section id="system-functions">
<title>System functions</title>
<content><html>
<p>
This is a list of system functions supported by jOOQ's <reference id="dsl" title="DSL"/>:
</p>
<ul>
<li><strong><code>CURRENT_USER</code></strong>: Get current user.</li>
</ul>
</html></content>
</section>
<section id="aggregate-functions">
<title>Aggregate functions</title>
<content><html>
<p>
Aggregate functions work just like functions, even if they have a slightly different semantics. Here are some example aggregate functions from the <reference id="dsl" title="DSL"/>:
</p>
</html><java><![CDATA[// Every-day, SQL standard aggregate functions
AggregateFunction<Integer> count();
AggregateFunction<Integer> count(Field<?> field);
AggregateFunction<T> max (Field<T> field);
AggregateFunction<T> min (Field<T> field);
AggregateFunction<BigDecimal> sum (Field<? extends Number> field);
AggregateFunction<BigDecimal> avg (Field<? extends Number> field);
// DISTINCT keyword in aggregate functions
AggregateFunction<Integer> countDistinct(Field<?> field);
AggregateFunction<T> maxDistinct (Field<T> field);
AggregateFunction<T> minDistinct (Field<T> field);
AggregateFunction<BigDecimal> sumDistinct (Field<? extends Number> field);
AggregateFunction<BigDecimal> avgDistinct (Field<? extends Number> field);
// String aggregate functions
AggregateFunction<String> groupConcat (Field<?> field);
AggregateFunction<String> groupConcatDistinct(Field<?> field);
OrderedAggregateFunction<String> listAgg(Field<?> field);
OrderedAggregateFunction<String> listAgg(Field<?> field, String separator);
// Statistical functions
AggregateFunction<BigDecimal> median (Field<? extends Number> field);
AggregateFunction<BigDecimal> stddevPop (Field<? extends Number> field);
AggregateFunction<BigDecimal> stddevSamp(Field<? extends Number> field);
AggregateFunction<BigDecimal> varPop (Field<? extends Number> field);
AggregateFunction<BigDecimal> varSamp (Field<? extends Number> field);
// Linear regression functions
AggregateFunction<BigDecimal> regrAvgX (Field<? extends Number> y, Field<? extends Number> x);
AggregateFunction<BigDecimal> regrAvgY (Field<? extends Number> y, Field<? extends Number> x);
AggregateFunction<BigDecimal> regrCount (Field<? extends Number> y, Field<? extends Number> x);
AggregateFunction<BigDecimal> regrIntercept(Field<? extends Number> y, Field<? extends Number> x);
AggregateFunction<BigDecimal> regrR2 (Field<? extends Number> y, Field<? extends Number> x);
AggregateFunction<BigDecimal> regrSlope (Field<? extends Number> y, Field<? extends Number> x);
AggregateFunction<BigDecimal> regrSXX (Field<? extends Number> y, Field<? extends Number> x);
AggregateFunction<BigDecimal> regrSXY (Field<? extends Number> y, Field<? extends Number> x);
AggregateFunction<BigDecimal> regrSYY (Field<? extends Number> y, Field<? extends Number> x);]]></java><html>
<p>
Here's an example, counting the number of books any author has written:
</p>
</html><code-pair>
<sql>SELECT AUTHOR_ID, COUNT(*)
FROM BOOK
GROUP BY AUTHOR_ID
&#160;</sql>
<java>create.select(BOOK.AUTHOR_ID, count())
.from(BOOK)
.groupBy(BOOK.AUTHOR_ID)
.fetch();</java>
</code-pair><html>
<p>
Aggregate functions have strong limitations about when they may be used and when not. For instance, you can use aggregate functions in scalar queries. Typically, this means you only select aggregate functions, no <reference id="table-columns" title="regular columns"/> or other <reference id="column-expressions" title="column expressions"/>. Another use case is to use them along with a <reference id="group-by-clause" title="GROUP BY clause"/> as seen in the previous example. Note, that jOOQ does not check whether your using of aggregate functions is correct according to the SQL standards, or according to your database's behaviour.
</p>
<h3>Ordered aggregate functions</h3>
<p>
Oracle and some other databases support "ordered aggregate functions". This means you can provide an <code>ORDER BY</code> clause to an aggregate function, which will be taken into consideration when aggregating. The best example for this is Oracle's <code>LISTAGG()</code> (also known as <code>GROUP_CONCAT</code> in other <reference id="sql-dialects" title="SQL dialects"/>). The following query groups by authors and concatenates their books' titles
</p>
</html><code-pair>
<sql>SELECT LISTAGG(TITLE, ', ')
WITHIN GROUP (ORDER BY TITLE)
FROM BOOK
GROUP BY AUTHOR_ID
&#160;</sql>
<java>create.select(listAgg(BOOK.TITLE, ", ")
.withinGroupOrderBy(BOOK.TITLE))
.from(BOOK)
.groupBy(BOOK.AUTHOR_ID)
.fetch();</java>
</code-pair><html>
<p>
The above query might yield:
</p>
</html><text>+---------------------+
| LISTAGG |
+---------------------+
| 1984, Animal Farm |
| O Alquimista, Brida |
+---------------------+</text><html>
<h3>FIRST and LAST: Oracle's "ranked" aggregate functions</h3>
<p>
Oracle allows for restricting aggregate functions using the <code>KEEP()</code> clause, which is supported by jOOQ. In Oracle, some aggregate functions (<code>MIN</code>, <code>MAX</code>, <code>SUM</code>, <code>AVG</code>, <code>COUNT</code>, <code>VARIANCE</code>, or <code>STDDEV</code>) can be restricted by this clause, hence <reference class="org.jooq.AggregateFunction"/> also allows for specifying it. Here are a couple of examples using this clause:
</p>
</html><code-pair>
<sql>SUM(BOOK.AMOUNT_SOLD)
KEEP(DENSE_RANK FIRST ORDER BY BOOK.AUTHOR_ID)</sql>
<java>sum(BOOK.AMOUNT_SOLD)
.keepDenseRankFirstOrderBy(BOOK.AUTHOR_ID)</java>
</code-pair><html>
<h3>User-defined aggregate functions</h3>
<p>
jOOQ also supports using your own user-defined aggregate functions. See the manual's section about <reference id="user-defined-aggregate-functions" title="user-defined aggregate functions"/> for more details.
</p>
<h3>Window functions / analytical functions</h3>
<p>
In those databases that support <reference id="window-functions" title="window functions"/>, jOOQ's <reference class="org.jooq.AggregateFunction"/> can be transformed into a window function / analytical function by calling <code>over()</code> on it. See the manual's section about <reference id="window-functions" title="window functions"/> for more details.
</p>
</html></content>
</section>
<section id="window-functions">
<title>Window functions</title>
<content><html>
<p>
Most major RDBMS support the concept of window functions. jOOQ knows of implementations in DB2, Oracle, Postgres, SQL Server, and Sybase SQL Anywhere, and supports most of their specific syntaxes. Note, that H2 and HSQLDB have implemented <code>ROW_NUMBER()</code> functions, without true windowing support.
</p>
<p>
As previously discussed, any <reference class="org.jooq.AggregateFunction"/> can be transformed into a window function using the <code>over()</code> method. See the chapter about <reference id="aggregate-functions" title="aggregate functions"/> for details. In addition to those, there are also some more window functions supported by jOOQ, as declared in the <reference id="dsl" title="DSL"/>:
</p>
</html><java><![CDATA[// Ranking functions
WindowOverStep<Integer> rowNumber();
WindowOverStep<Integer> rank();
WindowOverStep<Integer> denseRank();
WindowOverStep<BigDecimal> percentRank();
// Windowing functions
<T> WindowIgnoreNullsStep<T> firstValue(Field<T> field);
<T> WindowIgnoreNullsStep<T> lastValue(Field<T> field)
<T> WindowIgnoreNullsStep<T> lead(Field<T> field);
<T> WindowIgnoreNullsStep<T> lead(Field<T> field, int offset);
<T> WindowIgnoreNullsStep<T> lead(Field<T> field, int offset, T defaultValue);
<T> WindowIgnoreNullsStep<T> lead(Field<T> field, int offset, Field<T> defaultValue);
<T> WindowIgnoreNullsStep<T> lag(Field<T> field);
<T> WindowIgnoreNullsStep<T> lag(Field<T> field, int offset);
<T> WindowIgnoreNullsStep<T> lag(Field<T> field, int offset, T defaultValue);
<T> WindowIgnoreNullsStep<T> lag(Field<T> field, int offset, Field<T> defaultValue);
// Statistical functions
WindowOverStep<BigDecimal> cumeDist();
WindowOverStep<Integer> ntile(int number);]]></java><html>
<p>
SQL distinguishes between various window function types (e.g. "ranking functions"). Depending on the function, SQL expects mandatory <code>PARTITION BY</code> or <code>ORDER BY</code> clauses within the <code>OVER()</code> clause. jOOQ does not enforce those rules for two reasons:
</p>
<ul>
<li>Your JDBC driver or database already checks SQL syntax semantics</li>
<li>Not all databases behave correctly according to the SQL standard</li>
</ul>
<p>
If possible, however, jOOQ tries to render missing clauses for you, if a given <reference id="sql-dialects" title="SQL dialect"/> is more restrictive.
</p>
<h3>Some examples</h3>
<p>
Here are some simple examples of window functions with jOOQ:
</p>
</html><code-pair>
<sql>-- Sample uses of ROW_NUMBER()
ROW_NUMBER() OVER()
ROW_NUMBER() OVER(PARTITION BY 1)
ROW_NUMBER() OVER(ORDER BY BOOK.ID)
ROW_NUMBER() OVER(PARTITION BY BOOK.AUTHOR_ID ORDER BY BOOK.ID)
-- Sample uses of FIRST_VALUE
FIRST_VALUE(BOOK.ID) OVER()
FIRST_VALUE(BOOK.ID IGNORE NULLS) OVER()
FIRST_VALUE(BOOK.ID RESPECT NULLS) OVER()
</sql>
<java>// Sample uses of rowNumber()
rowNumber().over()
rowNumber().over().partitionByOne()
rowNumber().over().partitionBy(BOOK.AUTHOR_ID)
rowNumber().over().partitionBy(BOOK.AUTHOR_ID).orderBy(BOOK.ID)
// Sample uses of firstValue()
firstValue(BOOK.ID).over()
firstValue(BOOK.ID).ignoreNulls().over()
firstValue(BOOK.ID).respectNulls().over()
</java>
</code-pair><html>
<h3>An advanced window function example</h3>
<p>
Window functions can be used for things like calculating a "running total". The following example fetches transactions and the running total for every transaction going back to the beginning of the transaction table (ordered by booked_at). Window functions are accessible from the previously seen <reference class="org.jooq.AggregateFunction"/> type using the <code>over()</code> method:
</p>
</html><code-pair>
<sql>SELECT booked_at, amount,
SUM(amount) OVER (PARTITION BY 1
ORDER BY booked_at
ROWS BETWEEN UNBOUNDED PRECEDING
AND CURRENT ROW) AS total
FROM transactions
&#160;</sql>
<java>create.select(t.BOOKED_AT, t.AMOUNT,
sum(t.AMOUNT).over().partitionByOne()
.orderBy(t.BOOKED_AT)
.rowsBetweenUnboundedPreceding()
.andCurrentRow().as("total")
.from(TRANSACTIONS.as("t"))
.fetch();</java>
</code-pair><html>
<h3>Window functions created from ordered aggregate functions</h3>
<p>
In the previous chapter about <reference id="aggregate-functions" title="aggregate functions"/>, we have seen the concept of "ordered aggregate functions", such as Oracle's <code>LISTAGG()</code>. These functions have a window function / analytical function variant, as well. For example:
</p>
</html><code-pair>
<sql>SELECT LISTAGG(TITLE, ', ')
WITHIN GROUP (ORDER BY TITLE)
OVER (PARTITION BY BOOK.AUTHOR_ID)
FROM BOOK
&#160;</sql>
<java>create.select(listAgg(BOOK.TITLE, ", ")
.withinGroupOrderBy(BOOK.TITLE)
.over().partitionBy(BOOK.AUTHOR_ID))
.from(BOOK)
.fetch();</java>
</code-pair><html>
<h3>Window functions created from Oracle's <code>FIRST</code> and <code>LAST</code> aggregate functions</h3>
<p>
In the previous chapter about <reference id="aggregate-functions" title="aggregate functions"/>, we have seen the concept of "<code>FIRST</code> and <code>LAST</code> aggregate functions". These functions have a window function / analytical function variant, as well. For example:
</p>
</html><code-pair>
<sql>SUM(BOOK.AMOUNT_SOLD)
KEEP(DENSE_RANK FIRST ORDER BY BOOK.AUTHOR_ID)
OVER(PARTITION BY 1)</sql>
<java>sum(BOOK.AMOUNT_SOLD)
.keepDenseRankFirstOrderBy(BOOK.AUTHOR_ID)
.over().partitionByOne();</java>
</code-pair><html>
<h3>Window functions created from user-defined aggregate functions</h3>
<p>
User-defined aggregate functions also implement <reference class="org.jooq.AggregateFunction"/>, hence they can also be transformed into window functions using <code>over()</code>. This is supported by Oracle in particular. See the manual's section about <reference id="user-defined-aggregate-functions" title="user-defined aggregate functions"/> for more details.
</p>
</html></content>
</section>
<section id="grouping-functions">
<title>Grouping functions</title>
<content><html>
<h3>ROLLUP() explained in SQL</h3>
<p>
The SQL standard defines special functions that can be used in the <reference id="group-by-clause" title="GROUP BY clause"/>: the grouping functions. These functions can be used to generate several groupings in a single clause. This can best be explained in SQL. Let's take <code>ROLLUP()</code> for instance:
</p>
</html><code-pair>
<sql><![CDATA[-- ROLLUP() with one argument
SELECT AUTHOR_ID, COUNT(*)
FROM BOOK
GROUP BY ROLLUP(AUTHOR_ID)
-- ROLLUP() with two arguments
SELECT AUTHOR_ID, PUBLISHED_IN, COUNT(*)
FROM BOOK
GROUP BY ROLLUP(AUTHOR_ID, PUBLISHED_IN)
]]></sql>
<sql><![CDATA[-- The same query using UNION ALL:
SELECT AUTHOR_ID, COUNT(*) FROM BOOK GROUP BY (AUTHOR_ID)
UNION ALL
SELECT NULL, COUNT(*) FROM BOOK GROUP BY ()
ORDER BY 1 NULLS LAST
-- The same query using UNION ALL:
SELECT AUTHOR_ID, PUBLISHED_IN, COUNT(*)
FROM BOOK GROUP BY (AUTHOR_ID, PUBLISHED_IN)
UNION ALL
SELECT AUTHOR_ID, NULL, COUNT(*)
FROM BOOK GROUP BY (AUTHOR_ID)
UNION ALL
SELECT NULL, NULL, COUNT(*)
FROM BOOK GROUP BY ()
ORDER BY 1 NULLS LAST, 2 NULLS LAST
]]></sql>
</code-pair><html>
<p>
In English, the <code>ROLLUP()</code> grouping function provides <code>N+1</code> groupings, when <code>N</code> is the number of arguments to the <code>ROLLUP()</code> function. Each grouping has an additional group field from the <code>ROLLUP()</code> argument field list. The results of the second query might look something like this:
</p>
</html><text><![CDATA[+-----------+--------------+----------+
| AUTHOR_ID | PUBLISHED_IN | COUNT(*) |
+-----------+--------------+----------+
| 1 | 1945 | 1 | <- GROUP BY (AUTHOR_ID, PUBLISHED_IN)
| 1 | 1948 | 1 | <- GROUP BY (AUTHOR_ID, PUBLISHED_IN)
| 1 | NULL | 2 | <- GROUP BY (AUTHOR_ID)
| 2 | 1988 | 1 | <- GROUP BY (AUTHOR_ID, PUBLISHED_IN)
| 2 | 1990 | 1 | <- GROUP BY (AUTHOR_ID, PUBLISHED_IN)
| 2 | NULL | 2 | <- GROUP BY (AUTHOR_ID)
| NULL | NULL | 4 | <- GROUP BY ()
+-----------+--------------+----------+]]></text><html>
<h3>CUBE() explained in SQL</h3>
<p>
<code>CUBE()</code> is different from <code>ROLLUP()</code> in the way that it doesn't just create <code>N+1</code> groupings, it creates all <code>2^N</code> possible combinations between all group fields in the <code>CUBE()</code> function argument list. Let's re-consider our second query from before:
</p>
</html><code-pair>
<sql><![CDATA[-- CUBE() with two arguments
SELECT AUTHOR_ID, PUBLISHED_IN, COUNT(*)
FROM BOOK
GROUP BY CUBE(AUTHOR_ID, PUBLISHED_IN)
]]></sql>
<sql><![CDATA[-- The same query using UNION ALL:
SELECT AUTHOR_ID, PUBLISHED_IN, COUNT(*)
FROM BOOK GROUP BY (AUTHOR_ID, PUBLISHED_IN)
UNION ALL
SELECT AUTHOR_ID, NULL, COUNT(*)
FROM BOOK GROUP BY (AUTHOR_ID)
UNION ALL
SELECT NULL, PUBLISHED_IN, COUNT(*)
FROM BOOK GROUP BY (PUBLISHED_IN)
UNION ALL
SELECT NULL, NULL, COUNT(*)
FROM BOOK GROUP BY ()
ORDER BY 1 NULLS FIRST, 2 NULLS FIRST
]]></sql>
</code-pair><html>
<p>
The results would then hold:
</p>
</html><text><![CDATA[+-----------+--------------+----------+
| AUTHOR_ID | PUBLISHED_IN | COUNT(*) |
+-----------+--------------+----------+
| NULL | NULL | 2 | <- GROUP BY ()
| NULL | 1945 | 1 | <- GROUP BY (PUBLISHED_IN)
| NULL | 1948 | 1 | <- GROUP BY (PUBLISHED_IN)
| NULL | 1988 | 1 | <- GROUP BY (PUBLISHED_IN)
| NULL | 1990 | 1 | <- GROUP BY (PUBLISHED_IN)
| 1 | NULL | 2 | <- GROUP BY (AUTHOR_ID)
| 1 | 1945 | 1 | <- GROUP BY (AUTHOR_ID, PUBLISHED_IN)
| 1 | 1948 | 1 | <- GROUP BY (AUTHOR_ID, PUBLISHED_IN)
| 2 | NULL | 2 | <- GROUP BY (AUTHOR_ID)
| 2 | 1988 | 1 | <- GROUP BY (AUTHOR_ID, PUBLISHED_IN)
| 2 | 1990 | 1 | <- GROUP BY (AUTHOR_ID, PUBLISHED_IN)
+-----------+--------------+----------+]]></text><html>
<h3>GROUPING SETS()</h3>
<p>
<code>GROUPING SETS()</code> are the generalised way to create multiple groupings. From our previous examples
</p>
<ul>
<li><code>ROLLUP(AUTHOR_ID, PUBLISHED_IN)</code> corresponds to <code>GROUPING SETS((AUTHOR_ID, PUBLISHED_IN), (AUTHOR_ID), ())</code></li>
<li><code>CUBE(AUTHOR_ID, PUBLISHED_IN)</code> corresponds to <code>GROUPING SETS((AUTHOR_ID, PUBLISHED_IN), (AUTHOR_ID), (PUBLISHED_IN), ())</code></li>
</ul>
<p>
This is nicely explained in the SQL Server manual pages about <code>GROUPING SETS()</code> and other grouping functions:<br/>
<a href="http://msdn.microsoft.com/en-us/library/bb510427(v=sql.105)">http://msdn.microsoft.com/en-us/library/bb510427(v=sql.105)</a>
</p>
<h3>jOOQ's support for ROLLUP(), CUBE(), GROUPING SETS()</h3>
<p>
jOOQ fully supports all of these functions, as well as the utility functions <code>GROUPING()</code> and <code>GROUPING_ID()</code>, used for identifying the grouping set ID of a record. The <reference id="dsl" title="DSL API"/> thus includes:
</p>
</html><java><![CDATA[// The various grouping function constructors
GroupField rollup(Field<?>... fields);
GroupField cube(Field<?>... fields);
GroupField groupingSets(Field<?>... fields);
GroupField groupingSets(Field<?>[]... fields);
GroupField groupingSets(Collection<? extends Field<?>>... fields);
// The utility functions generating IDs per GROUPING SET
Field<Integer> grouping(Field<?>);
Field<Integer> groupingId(Field<?>...);]]></java><html>
<h3>MySQL's and CUBRID's WITH ROLLUP syntax</h3>
<p>
MySQL and CUBRID don't know any grouping functions, but they support a <code>WITH ROLLUP</code> clause, that is equivalent to simple <code>ROLLUP()</code> grouping functions. jOOQ simulates <code>ROLLUP()</code> in MySQL and CUBRID, by rendering this <code>WITH ROLLUP</code> clause. The following two statements mean the same:
</p>
</html><code-pair>
<sql><![CDATA[-- Statement 1: SQL standard
GROUP BY ROLLUP(A, B, C)
-- Statement 2: SQL standard
GROUP BY A, ROLLUP(B, C)]]></sql>
<sql><![CDATA[-- Statement 1: MySQL
GROUP BY A, B, C WITH ROLLUP
-- Statement 2: MySQL
-- This is not supported in MySQL]]></sql>
</code-pair>
</content>
</section>
<section id="user-defined-functions">
<title>User-defined functions</title>
<content><html>
<p>
Some databases support user-defined functions, which can be embedded in any SQL statement, if you're using jOOQ's <reference id="code-generation" title="code generator"/>. Let's say you have the following simple function in Oracle SQL:
</p>
</html><sql><![CDATA[CREATE OR REPLACE FUNCTION echo (INPUT NUMBER)
RETURN NUMBER
IS
BEGIN
RETURN INPUT;
END echo;
]]></sql><html>
<p>
The above function will be made available from a generated <reference id="codegen-procedures" title="Routines"/> class. You can use it like any other <reference id="column-expressions" title="column expression"/>:
</p>
</html><code-pair>
<sql><![CDATA[SELECT echo(1) FROM DUAL WHERE echo(2) = 2]]></sql>
<java><![CDATA[create.select(echo(1)).where(echo(2).equal(2)).fetch();]]></java>
</code-pair><html>
<p>
Note that user-defined functions returning <reference id="data-types-cursors" title="CURSOR"/> or <reference id="data-types-arrays" title="ARRAY"/> data types can also be used wherever <reference id="table-expressions" title="table expressions"/> can be used, if they are <reference id="array-and-cursor-unnesting" title="unnested"/>
</p>
</html></content>
</section>
<section id="user-defined-aggregate-functions">
<title>User-defined aggregate functions</title>
<content><html>
<p>
Some databases support user-defined aggregate functions, which can then be used along with <reference id="group-by-clause" title="GROUP BY clauses"/> or as <reference id="window-functions" title="window functions"/>. An example for such a database is Oracle. With Oracle, you can define the following <code>OBJECT</code> type (the example was taken from the <a href="http://docs.oracle.com/cd/B28359_01/appdev.111/b28425/ext_agg_ref.htm">Oracle 11g documentation</a>):
</p>
</html><sql><![CDATA[CREATE TYPE U_SECOND_MAX AS OBJECT
(
MAX NUMBER, -- highest value seen so far
SECMAX NUMBER, -- second highest value seen so far
STATIC FUNCTION ODCIAggregateInitialize(sctx IN OUT U_SECOND_MAX) RETURN NUMBER,
MEMBER FUNCTION ODCIAggregateIterate(self IN OUT U_SECOND_MAX, value IN NUMBER) RETURN NUMBER,
MEMBER FUNCTION ODCIAggregateTerminate(self IN U_SECOND_MAX, returnValue OUT NUMBER, flags IN NUMBER) RETURN NUMBER,
MEMBER FUNCTION ODCIAggregateMerge(self IN OUT U_SECOND_MAX, ctx2 IN U_SECOND_MAX) RETURN NUMBER
);
CREATE OR REPLACE TYPE BODY U_SECOND_MAX IS
STATIC FUNCTION ODCIAggregateInitialize(sctx IN OUT U_SECOND_MAX)
RETURN NUMBER IS
BEGIN
SCTX := U_SECOND_MAX(0, 0);
RETURN ODCIConst.Success;
END;
MEMBER FUNCTION ODCIAggregateIterate(self IN OUT U_SECOND_MAX, value IN NUMBER) RETURN NUMBER IS
BEGIN
IF VALUE > SELF.MAX THEN
SELF.SECMAX := SELF.MAX;
SELF.MAX := VALUE;
ELSIF VALUE > SELF.SECMAX THEN
SELF.SECMAX := VALUE;
END IF;
RETURN ODCIConst.Success;
END;
MEMBER FUNCTION ODCIAggregateTerminate(self IN U_SECOND_MAX, returnValue OUT NUMBER, flags IN NUMBER) RETURN NUMBER IS
BEGIN
RETURNVALUE := SELF.SECMAX;
RETURN ODCIConst.Success;
END;
MEMBER FUNCTION ODCIAggregateMerge(self IN OUT U_SECOND_MAX, ctx2 IN U_SECOND_MAX) RETURN NUMBER IS
BEGIN
IF CTX2.MAX > SELF.MAX THEN
IF CTX2.SECMAX > SELF.SECMAX THEN
SELF.SECMAX := CTX2.SECMAX;
ELSE
SELF.SECMAX := SELF.MAX;
END IF;
SELF.MAX := CTX2.MAX;
ELSIF CTX2.MAX > SELF.SECMAX THEN
SELF.SECMAX := CTX2.MAX;
END IF;
RETURN ODCIConst.Success;
END;
END;]]></sql><html>
<p>
The above <code>OBJECT</code> type is then available to function declarations as such:
</p>
</html><sql><![CDATA[
CREATE FUNCTION SECOND_MAX (input NUMBER) RETURN NUMBER
PARALLEL_ENABLE AGGREGATE USING U_SECOND_MAX;]]></sql><html>
<h3>Using the generated aggregate function</h3>
<p>
jOOQ's <reference id="code-generation" title="code generator"/> will detect such aggregate functions and generate them differently from regular <reference id="user-defined-functions" title="user-defined functions"/>. They implement the <reference class="org.jooq.AggregateFunction"/> type, as mentioned in the manual's section about <reference id="aggregate-functions" title="aggregate functions"/>. Here's how you can use the <code>SECOND_MAX()</code> aggregate function with jOOQ:
</p>
</html><code-pair>
<sql><![CDATA[-- Get the second-latest publishing date by author
SELECT SECOND_MAX(PUBLISHED_IN)
FROM BOOK
GROUP BY AUTHOR_ID]]>
&#160;</sql>
<java><![CDATA[// Routines.secondMax() can be static-imported
create.select(secondMax(BOOK.PUBLISHED_IN))
.from(BOOK)
.groupBy(BOOK.AUTHOR_ID)
.fetch();]]></java>
</code-pair>
</content>
</section>
<section id="case-expressions">
<title>The CASE expression</title>
<content><html>
<p>
The <code>CASE</code> expression is part of the standard SQL syntax. While some RDBMS also offer an <code>IF</code> expression, or a <code>DECODE</code> function, you can always rely on the two types of <code>CASE</code> syntax:
</p>
</html><code-pair>
<sql><![CDATA[CASE WHEN AUTHOR.FIRST_NAME = 'Paulo' THEN 'brazilian'
WHEN AUTHOR.FIRST_NAME = 'George' THEN 'english'
ELSE 'unknown'
END
-- OR:
CASE AUTHOR.FIRST_NAME WHEN 'Paulo' THEN 'brazilian'
WHEN 'George' THEN 'english'
ELSE 'unknown'
END]]></sql>
<java><![CDATA[DSL
.when(AUTHOR.FIRST_NAME.equal("Paulo"), "brazilian")
.when(AUTHOR.FIRST_NAME.equal("George"), "english")
.otherwise("unknown");
// OR:
DSL.choose(AUTHOR.FIRST_NAME)
.when("Paulo", "brazilian")
.when("George", "english")
.otherwise("unknown");]]></java>
</code-pair><html>
<p>
In jOOQ, both syntaxes are supported (The second one is simulated in Derby, which only knows the first one). Unfortunately, both case and else are reserved words in Java. jOOQ chose to use decode() from the Oracle <code>DECODE</code> function, or choose(), and otherwise(), which means the same as else.
</p>
<p>
A <code>CASE</code> expression can be used anywhere where you can place a <reference id="column-expressions" title="column expression (or Field)"/>. For instance, you can <code>SELECT</code> the above expression, if you're selecting from <code>AUTHOR</code>:
</p>
</html><sql>SELECT AUTHOR.FIRST_NAME, [... CASE EXPR ...] AS nationality
FROM AUTHOR</sql><html>
<h3>The Oracle DECODE() function</h3>
<p>
Oracle knows a more succinct, but maybe less readable <code>DECODE()</code> function with a variable number of arguments. This function roughly does the same as the second case expression syntax. jOOQ supports the <code>DECODE()</code> function and simulates it using <code>CASE</code> expressions in all dialects other than Oracle:
</p>
</html><code-pair>
<sql><![CDATA[-- Oracle:
DECODE(FIRST_NAME, 'Paulo', 'brazilian',
'George', 'english',
'unknown');
-- Other SQL dialects
CASE AUTHOR.FIRST_NAME WHEN 'Paulo' THEN 'brazilian'
WHEN 'George' THEN 'english'
ELSE 'unknown'
END]]></sql>
<java><![CDATA[
// Use the Oracle-style DECODE() function with jOOQ.
// Note, that you will not be able to rely on type-safety
create.decode(AUTHOR.FIRST_NAME,
"Paulo", "brazilian",
"George", "english",
"unknown");]]></java>
</code-pair><html>
<h3>CASE clauses in an ORDER BY clause</h3>
<p>
Sort indirection is often implemented with a <code>CASE</code> clause of a <code>SELECT</code>'s <code>ORDER BY</code> clause. See the manual's section about the <reference id="order-by-clause" title="ORDER BY clause"/> for more details.
</p>
</html></content>
</section>
<section id="sequences-and-serials">
<title>Sequences and serials</title>
<content><html>
<p>
Sequences implement the <reference class="org.jooq.Sequence"/> interface, providing essentially this functionality:
</p>
</html><java><![CDATA[// Get a field for the CURRVAL sequence property
Field<T> currval();
// Get a field for the NEXTVAL sequence property
Field<T> nextval();]]></java><html>
<p>
So if you have a sequence like this in Oracle:
</p>
</html><sql>CREATE SEQUENCE s_author_id</sql><html>
<p>
You can then use your <reference id="codegen-sequences" title="generated sequence"/> object directly in a SQL statement as such:
</p>
</html><java><![CDATA[// Reference the sequence in a SELECT statement:
BigInteger nextID = create.select(s).fetchOne(S_AUTHOR_ID.nextval());
// Reference the sequence in an INSERT statement:
create.insertInto(AUTHOR, AUTHOR.ID, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME)
.values(S_AUTHOR_ID.nextval(), val("William"), val("Shakespeare"))
.execute();
]]></java><html>
<ul>
<li>For more information about generated sequences, refer to the manual's section about <reference id="codegen-sequences" title="generated sequences"/></li>
<li>For more information about executing standalone calls to sequences, refer to the manual's section about <reference id="sequence-execution" title="sequence execution"/></li>
</ul>
</html></content>
</section>
<section id="row-value-expressions">
<title>Tuples or row value expressions</title>
<content><html>
<p>
According to the SQL standard, row value expressions can have a degree of more than one. This is commonly used in the <reference id="insert-statement" title="INSERT statement"/>, where the <code>VALUES</code> row value constructor allows for providing a row value expression as a source for <code>INSERT</code> data. Row value expressions can appear in various other places, though. They are supported by jOOQ as records / rows. jOOQ's <reference id="dsl" title="DSL"/> allows for the construction of type-safe records up to the degree of {max-row-degree}. Higher-degree Rows are supported as well, but without any type-safety. Row types are modelled as follows:
</p>
</html><java><![CDATA[// The DSL provides overloaded row value expression constructor methods:
public static <T1> Row1<T1> row(T1 t1) { ... }
public static <T1, T2> Row2<T1, T2> row(T1 t1, T2 t2) { ... }
public static <T1, T2, T3> Row3<T1, T2, T3> row(T1 t1, T2 t2, T3 t3) { ... }
public static <T1, T2, T3, T4> Row4<T1, T2, T3, T4> row(T1 t1, T2 t2, T3 t3, T4 t4) { ... }
// [ ... idem for Row5, Row6, Row7, ..., Row{max-row-degree} ]
// Degrees of more than {max-row-degree} are supported without type-safety
public static RowN row(Object... values) { ... }]]></java><html>
<h3>Using row value expressions in predicates</h3>
<p>
Row value expressions are incompatible with most other <reference id="queryparts" title="QueryParts"/>, but they can be used as a basis for constructing various <reference id="conditional-expressions" title="conditional expressions"/>, such as:
</p>
<ul>
<li><reference id="comparison-predicate-degree-n" title="comparison predicates"/></li>
<li><reference id="null-predicate-degree-n" title="NULL predicates"/></li>
<li><reference id="between-predicate-degree-n" title="BETWEEN predicates"/></li>
<li><reference id="in-predicate-degree-n" title="IN predicates"/></li>
<li><reference id="overlaps-predicate" title="OVERLAPS predicate"/> (for degree 2 row value expressions only)</li>
</ul>
<p>
See the relevant sections for more details about how to use row value expressions in predicates.
</p>
<h3>Using row value expressions in UPDATE statements</h3>
<p>
The <reference id="update-statement" title="UPDATE statement"/> also supports a variant where row value expressions are updated, rather than single columns. See the relevant section for more details
</p>
<h3>Higher-degree row value expressions</h3>
<p>
jOOQ chose to explicitly support degrees up to {max-row-degree} to match Scala's typesafe tuple, function and product support. Unlike Scala, however, jOOQ also supports higher degrees without the additional typesafety.
</p>
</html></content>
</section>
</sections>
</section>
<section id="conditional-expressions">
<title>Conditional expressions</title>
<content><html>
<p>
Conditions or conditional expressions are widely used in SQL and in the jOOQ API. They can be used in
</p>
<ul>
<li>The <reference id="case-expressions" title="CASE expression"/></li>
<li>The <reference id="join-clause" title="JOIN clause"/> (or <code>JOIN .. ON</code> clause, to be precise) of a <reference id="select-statement" title="SELECT statement"/>, <reference id="update-statement" title="UPDATE statement"/>, <reference id="delete-statement" title="DELETE statement"/></li>
<li>The <reference id="where-clause" title="WHERE clause"/> of a <reference id="select-statement" title="SELECT statement"/>, <reference id="update-statement" title="UPDATE statement"/>, <reference id="delete-statement" title="DELETE statement"/></li>
<li>The <reference id="connect-by-clause" title="CONNECT BY clause"/> of a <reference id="select-statement" title="SELECT statement"/></li>
<li>The <reference id="having-clause" title="HAVING clause"/> of a <reference id="select-statement" title="SELECT statement"/></li>
<li>The <reference id="merge-statement" title="MERGE statement"/>'s ON clause</li>
</ul>
<h3>Boolean types in SQL</h3>
<p>
Before SQL:1999, boolean types did not really exist in SQL. They were modelled by 0 and 1 numeric/char values. With SQL:1999, true booleans were introduced and are now supported by most databases. In short, these are possible boolean values:
</p>
<ul>
<li><code>1</code> or <code>TRUE</code></li>
<li><code>0</code> or <code>FALSE</code></li>
<li><code>NULL</code> or <code>UNKNOWN</code></li>
</ul>
<p>
It is important to know that SQL differs from many other languages in the way it interprets the <code>NULL</code> boolean value. Most importantly, the following facts are to be remembered:
</p>
<ul>
<li><code>[ANY] = NULL</code> yields <code>NULL</code> (not <code>FALSE</code>)</li>
<li><code>[ANY] != NULL</code> yields <code>NULL</code> (not <code>TRUE</code>)</li>
<li><code>NULL = NULL</code> yields <code>NULL</code> (not <code>TRUE</code>)</li>
<li><code>NULL != NULL</code> yields <code>NULL</code> (not <code>FALSE</code>)</li>
</ul>
<p>
For simplified <code>NULL</code> handling, please refer to the section about the <reference id="distinct-predicate" title="DISTINCT predicate"/>.
</p>
<p>
Note that jOOQ does not model these values as actual <reference id="column-expressions" title="column expression"/> compatible.
</p>
</html></content>
<sections>
<section id="condition-building">
<title>Condition building</title>
<content><html>
<p>
With jOOQ, most <reference id="conditional-expressions" title="conditional expressions"/> are built from <reference id="column-expressions" title="column expressions"/>, calling various methods on them. For instance, to build a <reference id="comparison-predicate" title="comparison predicate"/>, you can write the following expression:
</p>
</html><code-pair>
<sql><![CDATA[TITLE = 'Animal Farm'
TITLE != 'Animal Farm']]></sql>
<java><![CDATA[BOOK.TITLE.equal("Animal Farm")
BOOK.TITLE.notEqual("Animal Farm")]]></java>
</code-pair><html>
<h3>Create conditions from the DSL</h3>
<p>
There are a few types of conditions, that can be created statically from the <reference id="dsl" title="DSL"/>. These are:
</p>
<ul>
<li><reference id="plain-sql" title="plain SQL conditions"/>, that allow you to phrase your own SQL string <reference id="conditional-expressions" title="conditional expression"/></li>
<li>The <reference id="exists-predicate" title="EXISTS predicate"/>, a standalone predicate that creates a conditional expression</li>
<li>Constant <code>TRUE</code> and <code>FALSE</code> conditional expressions</li>
</ul>
<h3>Connect conditions using boolean operators</h3>
<p>
Conditions can also be connected using <reference id="boolean-operators" title="boolean operators"/> as will be discussed in a subsequent chapter.
</p>
</html></content>
</section>
<section id="boolean-operators">
<title>AND, OR, NOT boolean operators</title>
<content><html>
<p>
In SQL, as in most other languages, <reference id="conditional-expressions" title="conditional expressions"/> can be connected using the <code>AND</code> and <code>OR</code> binary operators, as well as the <code>NOT</code> unary operator, to form new conditional expressions. In jOOQ, this is modelled as such:
</p>
</html><code-pair>
<sql><![CDATA[-- A simple conditional expression
TITLE = 'Animal Farm' OR TITLE = '1984'
-- A more complex conditional expression
(TITLE = 'Animal Farm' OR TITLE = '1984')
AND NOT (AUTHOR.LAST_NAME = 'Orwell')]]></sql>
<java><![CDATA[// A simple boolean connection
BOOK.TITLE.equal("Animal Farm").or(BOOK.TITLE.equal("1984"))
// A more complex conditional expression
BOOK.TITLE.equal("Animal Farm").or(BOOK.TITLE.equal("1984"))
.andNot(AUTHOR.LAST_NAME.equal("Orwell"))]]></java>
</code-pair><html>
<p>
The above example shows that the number of parentheses in Java can quickly explode. Proper indentation may become crucial in making such code readable. In order to understand how jOOQ composes combined conditional expressions, let's assign component expressions first:
</p>
</html><java><![CDATA[Condition a = BOOK.TITLE.equal("Animal Farm");
Condition b = BOOK.TITLE.equal("1984");
Condition c = AUTHOR.LAST_NAME.equal("Orwell");
Condition combined1 = a.or(b); // These OR-connected conditions form a new condition, wrapped in parentheses
Condition combined2 = combined1.andNot(c); // The left-hand side of the AND NOT () operator is already wrapped in parentheses]]></java><html>
<h3>The Condition API</h3>
<p>
Here are all boolean operators on the <reference class="org.jooq.Condition"/> interface:
</p>
</html><java><![CDATA[and(Condition) // Combine conditions with AND
and(String) // Combine conditions with AND. Convenience for adding plain SQL to the right-hand side
and(String, Object...) // Combine conditions with AND. Convenience for adding plain SQL to the right-hand side
and(String, QueryPart...) // Combine conditions with AND. Convenience for adding plain SQL to the right-hand side
andExists(Select<?>) // Combine conditions with AND. Convenience for adding an exists predicate to the rhs
andNot(Condition) // Combine conditions with AND. Convenience for adding an inverted condition to the rhs
andNotExists(Select<?>) // Combine conditions with AND. Convenience for adding an inverted exists predicate to the rhs
or(Condition) // Combine conditions with OR
or(String) // Combine conditions with OR. Convenience for adding plain SQL to the right-hand side
or(String, Object...) // Combine conditions with OR. Convenience for adding plain SQL to the right-hand side
or(String, QueryPart...) // Combine conditions with OR. Convenience for adding plain SQL to the right-hand side
orExists(Select<?>) // Combine conditions with OR. Convenience for adding an exists predicate to the rhs
orNot(Condition) // Combine conditions with OR. Convenience for adding an inverted condition to the rhs
orNotExists(Select<?>) // Combine conditions with OR. Convenience for adding an inverted exists predicate to the rhs
not() // Invert a condition (synonym for DSL.not(Condition)]]></java>
</content>
</section>
<section id="comparison-predicate">
<title>Comparison predicate</title>
<content><html>
<p>
In SQL, comparison predicates are formed using common comparison operators:
</p>
<ul>
<li><strong>=</strong> to test for equality</li>
<li><strong>&lt;&gt;</strong> or <strong>!=</strong> to test for non-equality</li>
<li><strong>&gt;</strong> to test for being strictly greater</li>
<li><strong>&gt;=</strong> to test for being greater or equal</li>
<li><strong>&lt;</strong> to test for being strictly less</li>
<li><strong>&lt;=</strong> to test for being less or equal</li>
</ul>
<p>
Unfortunately, Java does not support operator overloading, hence these operators are also implemented as methods in jOOQ, like any other SQL syntax elements. The relevant parts of the <reference class="org.jooq.Field"/> interface are these:
</p>
</html><java><![CDATA[eq or equal(T); // = (some bind value)
eq or equal(Field<T>); // = (some column expression)
eq or equal(Select<? extends Record1<T>>); // = (some scalar SELECT statement)
ne or notEqual(T); // <> (some bind value)
ne or notEqual(Field<T>); // <> (some column expression)
ne or notEqual(Select<? extends Record1<T>>); // <> (some scalar SELECT statement)
lt or lessThan(T); // < (some bind value)
lt or lessThan(Field<T>); // < (some column expression)
lt or lessThan(Select<? extends Record1<T>>); // < (some scalar SELECT statement)
le or lessOrEqual(T); // <= (some bind value)
le or lessOrEqual(Field<T>); // <= (some column expression)
le or lessOrEqual(Select<? extends Record1<T>>); // <= (some scalar SELECT statement)
gt or greaterThan(T); // > (some bind value)
gt or greaterThan(Field<T>); // > (some column expression)
gt or greaterThan(Select<? extends Record1<T>>); // > (some scalar SELECT statement)
ge or greaterOrEqual(T); // >= (some bind value)
ge or greaterOrEqual(Field<T>); // >= (some column expression)
ge or greaterOrEqual(Select<? extends Record1<T>>); // >= (some scalar SELECT statement)]]></java><html>
<p>
Note that every operator is represented by two methods. A verbose one (such as <code>equal()</code>) and a two-character one (such as <code>eq()</code>). Both methods are the same. You may choose either one, depending on your taste. The manual will always use the more verbose one.
</p>
<h3>jOOQ's convenience methods using comparison operators</h3>
<p>
In addition to the above, jOOQ provides a few convenience methods for common operations performed on strings using comparison predicates:
</p>
</html><code-pair>
<sql><![CDATA[-- case insensitivity
LOWER(TITLE) = LOWER('animal farm')
LOWER(TITLE) <> LOWER('animal farm')]]></sql>
<java><![CDATA[// case insensitivity
BOOK.TITLE.equalIgnoreCase("animal farm")
BOOK.TITLE.notEqualIgnoreCase("animal farm")]]></java>
</code-pair>
</content>
</section>
<section id="boolean-operator-precedence">
<title>Boolean operator precedence</title>
<content><html>
<p>
As previously mentioned in the manual's section about <reference id="arithmetic-expressions" title="arithmetic expressions"/>, jOOQ does not implement operator precedence. All operators are evaluated from left to right, as expected in an object-oriented API. This is important to understand when combining <reference id="boolean-operators" title="boolean operators"/>, such as <code>AND</code>, <code>OR</code>, and <code>NOT</code>. The following expressions are equivalent:
</p>
</html><java>
A.and(B) .or(C) .and(D) .or(E)
(((A.and(B)).or(C)).and(D)).or(E)
</java><html>
<p>
In SQL, the two expressions wouldn't be the same, as SQL natively knows operator precedence.
</p>
</html><sql>
A AND B OR C AND D OR E -- Precedence is applied
(((A AND B) OR C) AND D) OR E -- Precedence is overridden
</sql>
</content>
</section>
<section id="comparison-predicate-degree-n">
<title>Comparison predicate (degree > 1)</title>
<content><html>
<p>
All variants of the <reference id="comparison-predicate" title="comparison predicate"/> that we've seen in the previous chapter also work for <reference id="row-value-expressions" title="row value expressions"/>. If your database does not support row value expression comparison predicates, jOOQ simulates them the way they are defined in the SQL standard:
</p>
</html><code-pair>
<sql><![CDATA[-- Row value expressions (equal)
(A, B) = (X, Y)
(A, B, C) = (X, Y, Z)
-- greater than
(A, B) > (X, Y)
(A, B, C) > (X, Y, Z)
-- greater or equal
(A, B) >= (X, Y)
(A, B, C) >= (X, Y, Z)
-- Inverse comparisons
(A, B) <> (X, Y)
(A, B) < (X, Y)
(A, B) <= (X, Y)]]></sql>
<sql><![CDATA[-- Equivalent factored-out predicates (equal)
(A = X) AND (B = Y)
(A = X) AND (B = Y) AND (C = Z)
-- greater than
(A > X)
OR ((A = X) AND (B > Y))
(A > X)
OR ((A = X) AND (B > Y))
OR ((A = X) AND (B = Y) AND (C > Z))
-- greater or equal
(A > X)
OR ((A = X) AND (B > Y))
OR ((A = X) AND (B = Y))
(A > X)
OR ((A = X) AND (B > Y))
OR ((A = X) AND (B = Y) AND (C > Z))
OR ((A = X) AND (B = Y) AND (C = Z))
-- For simplicity, these predicates are shown in terms
-- of their negated counter parts
NOT((A, B) = (X, Y))
NOT((A, B) >= (X, Y))
NOT((A, B) > (X, Y))]]></sql>
</code-pair><html>
<p>
jOOQ supports all of the above row value expression comparison predicates, both with <reference id="column-expressions" title="column expression lists"/> and <reference id="select-statement" title="scalar subselects"/> at the right-hand side:
</p>
</html><code-pair>
<sql><![CDATA[-- With regular column expressions
(BOOK.AUTHOR_ID, BOOK.TITLE) = (1, 'Animal Farm')
-- With scalar subselects
(BOOK.AUTHOR_ID, BOOK.TITLE) = (
SELECT PERSON.ID, 'Animal Farm'
FROM PERSON
WHERE PERSON.ID = 1
)]]></sql>
<java><![CDATA[// Column expressions
row(BOOK.AUTHOR_ID, BOOK.TITLE).equal(1, "Animal Farm");
// Subselects
row(BOOK.AUTHOR_ID, BOOK.TITLE).equal(
select(PERSON.ID, val("Animal Farm"))
.from(PERSON)
.where(PERSON.ID.equal(1))
);]]></java>
</code-pair>
</content>
</section>
<section id="quantified-comparison-predicate">
<title>Quantified comparison predicate</title>
<content><html>
<p>
If the right-hand side of a <reference id="comparison-predicate" title="comparison predicate"/> turns out to be a non-scalar table subquery, you can wrap that subquery in a quantifier, such as <code>ALL</code>, <code>ANY</code>, or <code>SOME</code>. Note that the SQL standard defines <code>ANY</code> and <code>SOME</code> to be equivalent. jOOQ settled for the more intuitive <code>ANY</code> and doesn't support <code>SOME</code>. Here are some examples, supported by jOOQ:
</p>
</html><code-pair>
<sql><![CDATA[TITLE = ANY('Animal Farm', '1982')
PUBLISHED_IN > ALL(1920, 1940)]]></sql>
<java><![CDATA[BOOK.TITLE.equal(any("Animal Farm", "1982"));
BOOK.PUBLISHED_IN.greaterThan(all(1920, 1940));]]></java>
</code-pair><html>
<p>
For the example, the right-hand side of the quantified comparison predicates were filled with argument lists. But it is easy to imagine that the source of values results from a <reference id="nested-selects" title="subselect"/>.
</p>
<h3>ANY and the IN predicate</h3>
<p>
It is interesting to note that the SQL standard defines the <reference id="in-predicate" title="IN predicate"/> in terms of the <code>ANY</code>-quantified predicate. The following two expressions are equivalent:
</p>
</html><code-pair>
<text><![CDATA[[ROW VALUE EXPRESSION] IN [IN PREDICATE VALUE]]]></text>
<text><![CDATA[[ROW VALUE EXPRESSION] = ANY [IN PREDICATE VALUE]]]></text>
</code-pair><html>
<p>
Typically, the <reference id="in-predicate" title="IN predicate"/> is more readable than the quantified comparison predicate.
</p>
</html></content>
</section>
<section id="null-predicate">
<title>NULL predicate</title>
<content><html>
<p>
In SQL, you cannot compare <code>NULL</code> with any value using <reference id="comparison-predicate" title="comparison predicates"/>, as the result would yield <code>NULL</code> again, which is neither <code>TRUE</code> nor <code>FALSE</code> (see also the manual's section about <reference id="conditional-expressions" title="conditional expressions"/>). In order to test a <reference id="column-expressions" title="column expression"/> for <code>NULL</code>, use the <code>NULL</code> predicate as such:
</p>
</html><code-pair>
<sql><![CDATA[TITLE IS NULL
TITLE IS NOT NULL]]></sql>
<java><![CDATA[BOOK.TITLE.isNull()
BOOK.TITLE.isNotNull()]]></java>
</code-pair>
</content>
</section>
<section id="null-predicate-degree-n">
<title>NULL predicate (degree > 1)</title>
<content><html>
<p>
The SQL <code>NULL</code> predicate also works well for <reference id="row-value-expressions" title="row value expressions"/>, although it has some subtle, counter-intuitive features when it comes to inversing predicates with the <code>NOT()</code> operator! Here are some examples:
</p>
</html><code-pair>
<sql><![CDATA[-- Row value expressions
(A, B) IS NULL
(A, B) IS NOT NULL
-- Inverse of the above
NOT((A, B) IS NULL)
NOT((A, B) IS NOT NULL)]]></sql>
<sql><![CDATA[-- Equivalent factored-out predicates
(A IS NULL) AND (B IS NULL)
(A IS NOT NULL) AND (B IS NOT NULL)
-- Inverse
(A IS NOT NULL) OR (B IS NOT NULL)
(A IS NULL) OR (B IS NULL)]]></sql>
</code-pair><html>
<p>
The SQL standard contains a nice truth table for the above rules:
</p>
</html><text>+-----------------------+-----------+---------------+---------------+-------------------+
| Expression | R IS NULL | R IS NOT NULL | NOT R IS NULL | NOT R IS NOT NULL |
+-----------------------+-----------+---------------+---------------+-------------------+
| degree 1: null | true | false | false | true |
| degree 1: not null | false | true | true | false |
| degree > 1: all null | true | false | false | true |
| degree > 1: some null | false | false | true | true |
| degree > 1: none null | false | true | true | false |
+-----------------------+-----------+---------------+---------------+-------------------+</text><html>
<p>
In jOOQ, you would simply use the <code>isNull()</code> and <code>isNotNull()</code> methods on row value expressions. Again, as with the <reference id="comparison-predicate-degree-n" title="row value expression comparison predicate"/>, the row value expression <code>NULL</code> predicate is simulated by jOOQ, if your database does not natively support it:
</p>
</html><java><![CDATA[row(BOOK.ID, BOOK.TITLE).isNull();
row(BOOK.ID, BOOK.TITLE).isNotNull();]]></java>
</content>
</section>
<section id="distinct-predicate">
<title>DISTINCT predicate</title>
<content><html>
<p>
Some databases support the <code>DISTINCT</code> predicate, which serves as a convenient, <code>NULL</code>-safe <reference id="comparison-predicate" title="comparison predicate"/>. With the <code>DISTINCT</code> predicate, the following truth table can be assumed:
</p>
<ul>
<li><code>[ANY] IS DISTINCT FROM NULL</code> yields <code>TRUE</code></li>
<li><code>[ANY] IS NOT DISTINCT FROM NULL</code> yields <code>FALSE</code></li>
<li><code>NULL IS DISTINCT FROM NULL</code> yields <code>FALSE</code></li>
<li><code>NULL IS NOT DISTINCT FROM NULL</code> yields <code>TRUE</code></li>
</ul>
<p>
For instance, you can compare two fields for distinctness, ignoring the fact that any of the two could be <code>NULL</code>, which would lead to funny results. This is supported by jOOQ as such:
</p>
</html><code-pair>
<sql><![CDATA[TITLE IS DISTINCT FROM SUB_TITLE
TITLE IS NOT DISTINCT FROM SUB_TITLE]]></sql>
<java><![CDATA[BOOK.TITLE.isDistinctFrom(BOOK.SUB_TITLE)
BOOK.TITLE.isNotDistinctFrom(BOOK.SUB_TITLE)]]></java>
</code-pair><html>
<p>
If your database does not natively support the <code>DISTINCT</code> predicate, jOOQ emulates it with an equivalent <reference id="case-expressions" title="CASE expression"/>, modelling the above truth table:
</p>
</html><code-pair>
<sql><![CDATA[-- [A] IS DISTINCT FROM [B]
CASE WHEN [A] IS NULL AND [B] IS NULL THEN FALSE
WHEN [A] IS NULL AND [B] IS NOT NULL THEN TRUE
WHEN [A] IS NOT NULL AND [B] IS NULL THEN TRUE
WHEN [A] = [B] THEN FALSE
ELSE TRUE
END
]]></sql>
<sql><![CDATA[-- [A] IS NOT DISTINCT FROM [B]
CASE WHEN [A] IS NULL AND [B] IS NULL THEN TRUE
WHEN [A] IS NULL AND [B] IS NOT NULL THEN FALSE
WHEN [A] IS NOT NULL AND [B] IS NULL THEN FALSE
WHEN [A] = [B] THEN TRUE
ELSE FALSE
END
]]></sql>
</code-pair><html>
<p>
... or better, if the <code>INTERSECT</code> set operation is supported:
</p>
</html><code-pair>
<sql><![CDATA[-- [A] IS DISTINCT FROM [B]
NOT EXISTS(SELECT A INTERSECT SELECT B)
]]></sql>
<sql><![CDATA[-- [A] IS NOT DISTINCT FROM [B]
EXISTS(SELECT a INTERSECT SELECT b)
]]></sql>
</code-pair>
</content>
</section>
<section id="between-predicate">
<title>BETWEEN predicate</title>
<content><html>
<p>
The <code>BETWEEN</code> predicate can be seen as syntactic sugar for a pair of <reference id="comparison-predicate" title="comparison predicates"/>. According to the SQL standard, the following two predicates are equivalent:
</p>
</html><code-pair>
<sql><![CDATA[[A] BETWEEN [B] AND [C]]]></sql>
<sql><![CDATA[[A] >= [B] AND [A] <= [C]]]></sql>
</code-pair><html>
<p>
Note the inclusiveness of range boundaries in the definition of the <code>BETWEEN</code> predicate. Intuitively, this is supported in jOOQ as such:
</p>
</html><code-pair>
<sql><![CDATA[PUBLISHED_IN BETWEEN 1920 AND 1940
PUBLISHED_IN NOT BETWEEN 1920 AND 1940]]></sql>
<java><![CDATA[BOOK.PUBLISHED_IN.between(1920).and(1940)
BOOK.PUBLISHED_IN.notBetween(1920).and(1940)]]></java>
</code-pair><html>
<h3>BETWEEN SYMMETRIC</h3>
<p>
The SQL standard defines the <code>SYMMETRIC</code> keyword to be used along with <code>BETWEEN</code> to indicate that you do not care which bound of the range is larger than the other. A database system should simply swap range bounds, in case the first bound is greater than the second one. jOOQ supports this keyword as well, simulating it if necessary.
</p>
</html><code-pair>
<sql><![CDATA[PUBLISHED_IN BETWEEN SYMMETRIC 1940 AND 1920
PUBLISHED_IN NOT BETWEEN SYMMETRIC 1940 AND 1920]]></sql>
<java><![CDATA[BOOK.PUBLISHED_IN.betweenSymmetric(1940).and(1920)
BOOK.PUBLISHED_IN.notBetweenSymmetric(1940).and(1920)]]></java>
</code-pair><html>
<p>
The simulation is done trivially:
</p>
</html><code-pair>
<sql><![CDATA[[A] BETWEEN SYMMETRIC [B] AND [C]]]></sql>
<sql><![CDATA[([A] BETWEEN [B] AND [C]) OR ([A] BETWEEN [C] AND [B])]]></sql>
</code-pair>
</content>
</section>
<section id="between-predicate-degree-n">
<title>BETWEEN predicate (degree > 1)</title>
<content><html>
<p>
The SQL <code>BETWEEN</code> predicate also works well for <reference id="row-value-expressions" title="row value expressions"/>. Much like the <reference id="between-predicate" title="BETWEEN predicate for degree 1"/>, it is defined in terms of a pair of regular <reference id="comparison-predicate" title="comparison predicates"/>:
</p>
</html><code-pair>
<sql><![CDATA[[A] BETWEEN [B] AND [C]
[A] BETWEEN SYMMETRIC [B] AND [C]]]></sql>
<sql><![CDATA[ [A] >= [B] AND [A] <= [C]
([A] >= [B] AND [A] <= [C]) OR ([A] >= [C] AND [A] <= [B])]]></sql>
</code-pair><html>
<p>
The above can be factored out according to the rules listed in the manual's section about <reference id="comparison-predicate-degree-n" title="row value expression comparison predicates"/>.
</p>
<p>
jOOQ supports the <code>BETWEEN [SYMMETRIC]</code> predicate and simulates it in all SQL dialects where necessary. An example is given here:
</p>
</html><java><![CDATA[row(BOOK.ID, BOOK.TITLE).between(1, "A").and(10, "Z");]]></java>
</content>
</section>
<section id="like-predicate">
<title>LIKE predicate</title>
<content><html>
<p>
<code>LIKE</code> predicates are popular for simple wildcard-enabled pattern matching. Supported wildcards in all SQL databases are:
</p>
<ul>
<li><strong>_</strong>: (single-character wildcard)</li>
<li><strong>%</strong>: (multi-character wildcard)</li>
</ul>
<p>
With jOOQ, the <code>LIKE</code> predicate can be created from any <reference id="column-expressions" title="column expression"/> as such:
</p>
</html><code-pair>
<sql><![CDATA[TITLE LIKE '%abc%'
TITLE NOT LIKE '%abc%']]></sql>
<java><![CDATA[BOOK.TITLE.like("%abc%")
BOOK.TITLE.notLike("%abc%")]]></java>
</code-pair><html>
<h3>Escaping operands with the LIKE predicate</h3>
<p>
Often, your pattern may contain any of the wildcard characters <code>"_"</code> and <code>"%"</code>, in case of which you may want to escape them. jOOQ does not automatically escape patterns in <code>like()</code> and <code>notLike()</code> methods. Instead, you can explicitly define an escape character as such:
</p>
</html><code-pair>
<sql><![CDATA[TITLE LIKE '%The !%-Sign Book%' ESCAPE '!'
TITLE NOT LIKE '%The !%-Sign Book%' ESCAPE '!']]></sql>
<java><![CDATA[BOOK.TITLE.like("%The !%-Sign Book%", '!')
BOOK.TITLE.notLike("%The !%-Sign Book%", '!')]]></java>
</code-pair><html>
<p>
In the above predicate expressions, the exclamation mark character is passed as the escape character to escape wildcard characters <code>"!_"</code> and <code>"!%"</code>, as well as to escape the escape character itself: <code>"!!"</code>
</p>
<p>
Please refer to your database manual for more details about escaping patterns with the <code>LIKE</code> predicate.
</p>
<h3>jOOQ's convenience methods using the LIKE predicate</h3>
<p>
In addition to the above, jOOQ provides a few convenience methods for common operations performed on strings using the <code>LIKE</code> predicate. Typical operations are "contains predicates", "starts with predicates", "ends with predicates", etc. Here is the full convenience API wrapping <code>LIKE</code> predicates:
</p>
</html><code-pair>
<sql><![CDATA[-- case insensitivity
LOWER(TITLE) LIKE LOWER('%abc%')
LOWER(TITLE) NOT LIKE LOWER('%abc%')
-- contains and similar methods
TITLE LIKE '%' || 'abc' || '%'
TITLE LIKE 'abc' || '%'
TITLE LIKE '%' || 'abc']]></sql>
<java><![CDATA[// case insensitivity
BOOK.TITLE.likeIgnoreCase("%abc%")
BOOK.TITLE.notLikeIgnoreCase("%abc%")
// contains and similar methods
BOOK.TITLE.contains("abc")
BOOK.TITLE.startsWith("abc")
BOOK.TITLE.endsWith("abc")]]></java>
</code-pair><html>
<p>
Note, that jOOQ escapes <code>%</code> and <code>_</code> characters in value in some of the above predicate implementations. For simplicity, this has been omitted in this manual.
</p>
</html></content>
</section>
<section id="in-predicate">
<title>IN predicate</title>
<content><html>
<p>
In SQL, apart from comparing a value against several values, the <code>IN</code> predicate can be used to create semi-joins or anti-joins. jOOQ knows the following methods on the <reference class="org.jooq.Field" /> interface, to construct such <code>IN</code> predicates:
</p>
</html><java><![CDATA[in(Collection<T>) // Construct an IN predicate from a collection of bind values
in(T...) // Construct an IN predicate from bind values
in(Field<?>...) // Construct an IN predicate from column expressions
in(Select<? extends Record1<T>>) // Construct an IN predicate from a subselect
notIn(Collection<T>) // Construct a NOT IN predicate from a collection of bind values
notIn(T...) // Construct a NOT IN predicate from bind values
notIn(Field<?>...) // Construct a NOT IN predicate from column expressions
notIn(Select<? extends Record1<T>>) // Construct a NOT IN predicate from a subselect]]></java><html>
<p>
A sample <code>IN</code> predicate might look like this:
</p>
</html><code-pair>
<sql><![CDATA[TITLE IN ('Animal Farm', '1984')
TITLE NOT IN ('Animal Farm', '1984')]]></sql>
<java><![CDATA[BOOK.TITLE.in("Animal Farm", "1984")
BOOK.TITLE.notIn("Animal Farm", "1984")]]></java>
</code-pair><html>
<h3>NOT IN and NULL values</h3>
<p>
Beware that you should probably not have any <code>NULL</code> values in the right hand side of a <code>NOT IN</code> predicate, as the whole expression would evaluate to <code>NULL</code>, which is rarely desired. This can be shown informally using the following reasoning:
</p>
</html><sql>-- The following conditional expressions are formally or informally equivalent
A NOT IN (B, C)
A != ANY(B, C)
A != B AND A != C
-- Substitute C for NULL, you'll get
A NOT IN (B, NULL) -- Substitute C for NULL
A != B AND A != NULL -- From the above rules
A != B AND NULL -- [ANY] != NULL yields NULL
NULL -- [ANY] AND NULL yields NULL</sql><html>
<p>
A good way to prevent this from happening is to use the <reference id="exists-predicate" title="EXISTS predicate"/> for anti-joins, which is <code>NULL</code>-value insensitive. See the manual's section about <reference id="conditional-expressions" title="conditional expressions"/> to see a boolean truth table.
</p>
</html></content>
</section>
<section id="in-predicate-degree-n">
<title>IN predicate (degree > 1)</title>
<content><html>
<p>
The SQL <code>IN</code> predicate also works well for <reference id="row-value-expressions" title="row value expressions"/>. Much like the <reference id="in-predicate" title="IN predicate for degree 1"/>, it is defined in terms of a <reference id="quantified-comparison-predicate" title="quantified comparison predicate"/>. The two expressions are equivalent:
</p>
</html><code-pair>
<sql><![CDATA[R IN [IN predicate value]]]></sql>
<sql><![CDATA[R = ANY [IN predicate value]]]></sql>
</code-pair><html>
<p>
jOOQ supports the <code>IN</code> predicate. Simulation of the <code>IN</code> predicate where row value expressions aren't well supported is currently only available for <code>IN</code> predicates that do not take a subselect as an <code>IN</code> predicate value. An example is given here:
</p>
</html><java><![CDATA[row(BOOK.ID, BOOK.TITLE).in(row(1, "A"), row(2, "B"));]]></java>
</content>
</section>
<section id="exists-predicate">
<title>EXISTS predicate</title>
<content><html>
<p>
Slightly less intuitive, yet more powerful than the previously discussed <reference id="in-predicate" title="IN predicate"/> is the <code>EXISTS</code> predicate, that can be used to form semi-joins or anti-joins. With jOOQ, the <code>EXISTS</code> predicate can be formed in various ways:
</p>
<ul>
<li>From the <reference id="dsl" title="DSL"/>, using static methods. This is probably the most used case</li>
<li>From a <reference id="conditional-expressions" title="conditional expression"/> using <reference id="boolean-operators" title="convenience methods attached to boolean operators"/></li>
<li>From a <reference id="select-statement" title="SELECT statement"/> using <reference id="where-clause" title="convenience methods attached to the where clause"/>, and from other clauses</li>
</ul>
<p>
An example of an <code>EXISTS</code> predicate can be seen here:
</p>
</html><code-pair>
<sql><![CDATA[ EXISTS (SELECT 1 FROM BOOK
WHERE AUTHOR_ID = 3)
NOT EXISTS (SELECT 1 FROM BOOK
WHERE AUTHOR_ID = 3)]]></sql>
<java><![CDATA[ exists(create.selectOne().from(BOOK)
.where(BOOK.AUTHOR_ID.equal(3)));
notExists(create.selectOne().from(BOOK)
.where(BOOK.AUTHOR_ID.equal(3)));]]></java>
</code-pair><html>
<p>
Note that in SQL, the projection of a subselect in an <code>EXISTS</code> predicate is irrelevant. To help you write queries like the above, you can use jOOQ's selectZero() or selectOne() <reference id="dsl" title="DSL"/> methods
</p>
<h3>Performance of IN vs. EXISTS</h3>
<p>
In theory, the two types of predicates can perform equally well. If your database system ships with a sophisticated cost-based optimiser, it will be able to transform one predicate into the other, if you have all necessary constraints set (e.g. referential constraints, not null constraints). However, in reality, performance between the two might differ substantially. An interesting blog post investigating this topic on the MySQL database can be seen here:<br/>
<a href="http://blog.jooq.org/2012/07/27/not-in-vs-not-exists-vs-left-join-is-null-mysql/">http://blog.jooq.org/2012/07/27/not-in-vs-not-exists-vs-left-join-is-null-mysql/</a>
</p>
</html></content>
</section>
<section id="overlaps-predicate">
<title>OVERLAPS predicate</title>
<content><html>
<p>
When comparing dates, the SQL standard allows for using a special <code>OVERLAPS</code> predicate, which checks whether two date ranges overlap each other. The following can be said:
</p>
</html><sql><![CDATA[-- This yields true
(DATE '2010-01-01', DATE '2010-01-03') OVERLAPS (DATE '2010-01-02' DATE '2010-01-04')
-- INTERVAL data types are also supported. This is equivalent to the above
(DATE '2010-01-01', CAST('+2 00:00:00' AS INTERVAL DAY TO SECOND)) OVERLAPS
(DATE '2010-01-02', CAST('+2 00:00:00' AS INTERVAL DAY TO SECOND))]]></sql><html>
<h3>The OVERLAPS predicate in jOOQ</h3>
<p>
jOOQ supports the <code>OVERLAPS</code> predicate on <reference id="row-value-expressions" title="row value expressions of degree 2"/>. The following methods are contained in <reference class="org.jooq.Row2"/>:
</p>
</html><java><![CDATA[Condition overlaps(T1 t1, T2 t2);
Condition overlaps(Field<T1> t1, Field<T2> t2);
Condition overlaps(Row2<T1, T2> row);]]></java><html>
<p>
This allows for expressing the above predicates as such:
</p>
</html><java><![CDATA[// The date range tuples version
row(Date.valueOf('2010-01-01'), Date.valueOf('2010-01-03')).overlaps(Date.valueOf('2010-01-02'), Date.valueOf('2010-01-04'))
// The INTERVAL tuples version
row(Date.valueOf('2010-01-01'), new DayToSecond(2)).overlaps(Date.valueOf('2010-01-02'), new DayToSecond(2))]]></java><html>
<h3>jOOQ's extensions to the standard</h3>
<p>
Unlike the standard (or any database implementing the standard), jOOQ also supports the <code>OVERLAPS</code> predicate for comparing arbitrary <reference id="row-value-expressions" title="row vlaue expressions of degree 2"/>. For instance, <code>(1, 3) OVERLAPS (2, 4)</code> will yield true in jOOQ. This is simulated as such
</p>
</html><sql><![CDATA[-- This predicate
(A, B) OVERLAPS (C, D)
-- can be simulated as such
(C <= B) AND (A <= D)]]></sql>
</content>
</section>
</sections>
</section>
<section id="plain-sql">
<title>Plain SQL</title>
<content><html>
<p>
A DSL is a nice thing to have, it feels "fluent" and "natural", especially if it models a well-known language, such as SQL. But a DSL is always expressed in a host language (Java in this case), which was not made for exactly the same purposes as its hosted DSL. If it were, then jOOQ would be implemented on a compiler-level, similar to LINQ in .NET. But it's not, and so, the DSL is limited by language constraints of its host language. We have seen many functionalities where the DSL becomes a bit verbose. This can be especially true for:
</p>
<ul>
<li><reference id="aliased-columns" title="aliasing"/></li>
<li><reference id="nested-selects" title="nested selects"/></li>
<li><reference id="arithmetic-expressions" title="arithmetic expressions"/></li>
<li><reference id="cast-expressions" title="casting"/></li>
</ul>
<p>
You'll probably find other examples. If verbosity scares you off, don't worry. The verbose use-cases for jOOQ are rather rare, and when they come up, you do have an option. Just write SQL the way you're used to!
</p>
<p>
jOOQ allows you to embed SQL as a String into any supported <reference id="sql-statements" title="statement"/> in these contexts:
</p>
<ul>
<li>Plain SQL as a <reference id="conditional-expressions" title="conditional expression"/></li>
<li>Plain SQL as a <reference id="column-expressions" title="column expression"/></li>
<li>Plain SQL as a <reference id="column-expressions" title="function"/></li>
<li>Plain SQL as a <reference id="table-expressions" title="table expression"/></li>
<li>Plain SQL as a <reference id="query-vs-resultquery" title="query"/></li>
</ul>
<h3>The DSL plain SQL API</h3>
<p>
Plain SQL API methods are usually overloaded in three ways. Let's look at the <code>condition</code> query part constructor:
</p>
</html><java><![CDATA[// Construct a condition without bind values
// Example: condition("a = b")
Condition condition(String sql);
// Construct a condition with bind values
// Example: condition("a = ?", 1);
Condition condition(String sql, Object... bindings);
// Construct a condition taking other jOOQ object arguments
// Example: condition("a = {0}", val(1));
Condition condition(String sql, QueryPart... parts);]]></java><html>
<p>
Please refer to the <reference class="org.jooq.impl.DSL"/> Javadoc for more details. The following is a more complete listing of plain SQL construction methods from the DSL:
</p>
</html><java><![CDATA[// A condition
Condition condition(String sql);
Condition condition(String sql, Object... bindings);
Condition condition(String sql, QueryPart... parts);
// A field with an unknown data type
Field<Object> field(String sql);
Field<Object> field(String sql, Object... bindings);
Field<Object> field(String sql, QueryPart... parts);
// A field with a known data type
<T> Field<T> field(String sql, Class<T> type);
<T> Field<T> field(String sql, Class<T> type, Object... bindings);
<T> Field<T> field(String sql, Class<T> type, QueryPart... parts);
<T> Field<T> field(String sql, DataType<T> type);
<T> Field<T> field(String sql, DataType<T> type, Object... bindings);
<T> Field<T> field(String sql, DataType<T> type, QueryPart... parts);
// A field with a known name (properly escaped)
Field<Object> fieldByName(String... fieldName);
<T> Field<T> fieldByName(Class<T> type, String... fieldName);
<T> Field<T> fieldByName(DataType<T> type, String... fieldName)
// A function
<T> Field<T> function(String name, Class<T> type, Field<?>... arguments);
<T> Field<T> function(String name, DataType<T> type, Field<?>... arguments);
// A table
Table<?> table(String sql);
Table<?> table(String sql, Object... bindings);
Table<?> table(String sql, QueryPart... parts);
// A table with a known name (properly escaped)
Table<Record> tableByName(String... fieldName);
// A query without results (update, insert, etc)
Query query(String sql);
Query query(String sql, Object... bindings);
Query query(String sql, QueryPart... parts);
// A query with results
ResultQuery<Record> resultQuery(String sql);
ResultQuery<Record> resultQuery(String sql, Object... bindings);
ResultQuery<Record> resultQuery(String sql, QueryPart... parts);
// A query with results. This is the same as resultQuery(...).fetch();
Result<Record> fetch(String sql);
Result<Record> fetch(String sql, Object... bindings);
Result<Record> fetch(String sql, QueryPart... parts);]]></java><html>
<p>
Apart from the general factory methods, plain SQL is also available in various other contexts. For instance, when adding a <code>.where("a = b")</code> clause to a query. Hence, there exist several convenience methods where plain SQL can be inserted usefully. This is an example displaying all various use-cases in one single query:
</p>
</html><java><![CDATA[// You can use your table aliases in plain SQL fields
// As long as that will produce syntactically correct SQL
Field<?> LAST_NAME = create.field("a.LAST_NAME");
// You can alias your plain SQL fields
Field<?> COUNT1 = create.field("count(*) x");
// If you know a reasonable Java type for your field, you
// can also provide jOOQ with that type
Field<Integer> COUNT2 = create.field("count(*) y", Integer.class);
// Use plain SQL as select fields
create.select(LAST_NAME, COUNT1, COUNT2)
// Use plain SQL as aliased tables (be aware of syntax!)
.from("author a")
.join("book b")
// Use plain SQL for conditions both in JOIN and WHERE clauses
.on("a.id = b.author_id")
// Bind a variable in plain SQL
.where("b.title != ?", "Brida")
// Use plain SQL again as fields in GROUP BY and ORDER BY clauses
.groupBy(LAST_NAME)
.orderBy(LAST_NAME)
.fetch();]]></java><html>
<h3>Important things to note about plain SQL!</h3>
<p>
There are some important things to keep in mind when using plain SQL:
</p>
<ul>
<li>jOOQ doesn't know what you're doing. You're on your own again!</li>
<li>You have to provide something that will be syntactically correct. If it's not, then jOOQ won't know. Only your JDBC driver or your RDBMS will detect the syntax error.</li>
<li>You have to provide consistency when you use variable binding. The number of ? must match the number of variables</li>
<li>Your SQL is inserted into jOOQ queries without further checks. Hence, jOOQ can't prevent SQL injection. </li>
</ul>
</html></content>
</section>
<section id="names">
<title>Names and identifiers</title>
<content><html>
<p>
Various SQL objects <reference id="column-expressions" title="columns"/> or <reference id="table-expressions" title="tables"/> can be referenced using names (often also called identifiers). SQL dialects differ in the way they understand names, syntactically. The differences include:
</p>
<ul>
<li>The permitted characters to be used in "unquoted" names</li>
<li>The permitted characters to be used in "quoted" names</li>
<li>The name quoting characters</li>
<li>The standard case for case-insensitive ("unquoted") names</li>
</ul>
<p>
For the above reasons, jOOQ by default quotes all names in generated SQL to be sure they match what is really contained in your database. This means that the following names will be rendered
</p>
</html><sql><![CDATA[-- Unquoted name
AUTHOR.TITLE
-- MariaDB, MySQL
`AUTHOR`.`TITLE`
-- MS Access, SQL Server, Sybase ASE, Sybase SQL Anywhere
[AUTHOR].[TITLE]
-- All the others, including the SQL standard
"AUTHOR"."TITLE"]]></sql><html>
<p>
Note that you can influence jOOQ's name rendering behaviour through <reference id="custom-settings" title="custom settings"/>, if you prefer another name style to be applied.
</p>
<h3>Creating custom names</h3>
<p>
Custom, qualified or unqualified names can be created very easily using the <reference class="org.jooq.impl.DSL" title="DSL.name()" anchor="#name-java.lang.String...-"/> constructor:
</p>
</html><java><![CDATA[// Unqualified name
Name name = name("TITLE");
// Qualified name
Name name = name("AUTHOR", "TITLE");]]></java><html>
<p>
Such names can be used as standalone <reference id="queryparts" title="QueryParts"/>, or as DSL entry point for SQL expressions, like
</p>
<ul>
<li>Common table expressions to be used with <reference id="with-clause" title="the WITH clause"/></li>
<li>Window specifications to be used with <reference id="window-clause" title="the WINDOW clause"/></li>
</ul>
<p>
More details about how to use names / identifiers to construct such expressions can be found in the relevant sections of the manual.
</p>
</html></content>
</section>
<section id="bind-values">
<title>Bind values and parameters</title>
<content><html>
<p>
Bind values are used in SQL / JDBC for various reasons. Among the most obvious ones are:
</p>
<ul>
<li>
Protection against SQL injection. Instead of inlining values possibly originating from user input, you bind those values to your prepared statement and let the JDBC driver / database take care of handling security aspects.
</li>
<li>
Increased speed. Advanced databases such as Oracle can keep execution plans of similar queries in a dedicated cache to prevent hard-parsing your query again and again. In many cases, the actual value of a bind variable does not influence the execution plan, hence it can be reused. Preparing a statement will thus be faster
</li>
<li>
On a JDBC level, you can also reuse the SQL string and prepared statement object instead of constructing it again, as you can bind new values to the prepared statement. jOOQ currently does not cache prepared statements, internally.
</li>
</ul>
<p>
The following sections explain how you can introduce bind values in jOOQ, and how you can control the way they are rendered and bound to SQL.
</p>
</html></content>
<sections>
<section id="indexed-parameters">
<title>Indexed parameters</title>
<content><html>
<p>
JDBC only knows indexed bind values. A typical example for using bind values with JDBC is this:
</p>
</html><java><![CDATA[
try (PreparedStatement stmt = connection.prepareStatement("SELECT * FROM BOOK WHERE ID = ? AND TITLE = ?")) {
// bind values to the above statement for appropriate indexes
stmt.setInt(1, 5);
stmt.setString(2, "Animal Farm");
stmt.executeQuery();
}]]></java><html>
<p>
With dynamic SQL, keeping track of the number of question marks and their corresponding index may turn out to be hard. jOOQ abstracts this and lets you provide the bind value right where it is needed. A trivial example is this:
</p>
</html><java><![CDATA[create.select().from(BOOK).where(BOOK.ID.equal(5)).and(BOOK.TITLE.equal("Animal Farm")).fetch();
// This notation is in fact a short form for the equivalent:
create.select().from(BOOK).where(BOOK.ID.equal(val(5))).and(BOOK.TITLE.equal(val("Animal Farm"))).fetch();]]></java><html>
<p>
Note the using of <reference class="org.jooq.impl.DSL" anchor="#val(java.lang.Object)" title="DSL.val()"/> to explicitly create an indexed bind value. You don't have to worry about that index. When the query is <reference id="sql-rendering" title="rendered"/>, each bind value will render a question mark. When the query <reference id="variable-binding" title="binds its variables"/>, each bind value will generate the appropriate bind value index.
</p>
<h3>Extract bind values from a query</h3>
<p>
Should you decide to run the above query outside of jOOQ, using your own <reference class="java.sql.PreparedStatement"/>, you can do so as follows:
</p>
</html><java><![CDATA[Select<?> select = create.select().from(BOOK).where(BOOK.ID.equal(5)).and(BOOK.TITLE.equal("Animal Farm"));
// Render the SQL statement:
String sql = select.getSQL();
assertEquals("SELECT * FROM BOOK WHERE ID = ? AND TITLE = ?", sql);
// Get the bind values:
List<Object> values = select.getBindValues();
assertEquals(2, values.size());
assertEquals(5, values.get(0));
assertEquals("Animal Farm", values.get(1));]]></java><html>
<p>
You can also extract specific bind values by index from a query, if you wish to modify their underlying value after creating a query. This can be achieved as such:
</p>
</html><java><![CDATA[Select<?> select = create.select().from(BOOK).where(BOOK.ID.equal(5)).and(BOOK.TITLE.equal("Animal Farm"));
Param<?> param = select.getParam("2");
// You could now modify the Query's underlying bind value:
if ("Animal Farm".equals(param.getValue())) {
param.setConverted("1984");
}]]></java><html>
<p>
For more details about jOOQ's internals, see the manual's section about <reference id="queryparts" title="QueryParts"/>.
</p>
</html></content>
</section>
<section id="named-parameters">
<title>Named parameters</title>
<content><html>
<p>
Some SQL access abstractions that are built on top of JDBC, or some that bypass JDBC may support named parameters. jOOQ allows you to give names to your parameters as well, although those names are not rendered to SQL strings by default. Here is an example of how to create named parameters using the <reference class="org.jooq.Param"/> type:
</p>
</html><java><![CDATA[// Create a query with a named parameter. You can then use that name for accessing the parameter again
Query query1 = create.select().from(AUTHOR).where(LAST_NAME.equal(param("lastName", "Poe")));
Param<?> param1 = query.getParam("lastName");
// Or, keep a reference to the typed parameter in order not to lose the <T> type information:
Param<String> param2 = param("lastName", "Poe");
Query query2 = create.select().from(AUTHOR).where(LAST_NAME.equal(param2));
// You can now change the bind value directly on the Param reference:
param2.setValue("Orwell");]]></java><html>
<p>
The <reference class="org.jooq.Query"/> interface also allows for setting new bind values directly, without accessing the Param type:
</p>
</html><java><![CDATA[Query query1 = create.select().from(AUTHOR).where(LAST_NAME.equal("Poe"));
query1.bind(1, "Orwell");
// Or, with named parameters
Query query2 = create.select().from(AUTHOR).where(LAST_NAME.equal(param("lastName", "Poe")));
query2.bind("lastName", "Orwell");]]></java><html>
<p>
In order to actually render named parameter names in generated SQL, use the <reference class="org.jooq.DSLContext" anchor="#renderNamedParams(org.jooq.QueryPart)" title="DSLContext.renderNamedParams()"/> method:
</p>
</html><code-pair>
<java><![CDATA[create.renderNamedParams(
create.select()
.from(AUTHOR)
.where(LAST_NAME.equal(
param("lastName", "Poe"))));]]></java>
<sql><![CDATA[-- The named bind variable can be rendered
SELECT *
FROM AUTHOR
WHERE LAST_NAME = :lastName]]></sql>
</code-pair>
</content>
</section>
<section id="inlined-parameters">
<title>Inlined parameters</title>
<content><html>
<p>
Sometimes, you may wish to avoid rendering bind variables while still using custom values in SQL. jOOQ refers to that as "inlined" bind values. When bind values are inlined, they render the actual value in SQL rather than a JDBC question mark. Bind value inlining can be achieved in two ways:
</p>
<ul>
<li>
By using the <reference id="custom-settings" title="Settings"/> and setting the <reference class="org.jooq.conf.StatementType"/> to STATIC_STATEMENT. This will inline all bind values for SQL statements rendered from such a Configuration.
</li>
<li>
By using <reference class="org.jooq.impl.DSL" anchor="#inline(java.lang.Object)" title="DSL.inline()"/> methods.
</li>
</ul>
<p>
In both cases, your inlined bind values will be properly escaped to avoid SQL syntax errors and SQL injection. Some examples:
</p>
</html><java><![CDATA[
// Use dedicated calls to inline() in order to specify
// single bind values to be rendered as inline values
// --------------------------------------------------
create.select()
.from(AUTHOR)
.where(LAST_NAME.equal(inline("Poe")))
.fetch();
// Or render the whole query with inlined values
// --------------------------------------------------
Settings settings = new Settings()
.withStatementType(StatementType.STATIC_STATEMENT);
// Add the settings to the Configuration
DSLContext create = DSL.using(connection, SQLDialect.ORACLE, settings);
// Run queries that omit rendering schema names
create.select()
.from(AUTHOR)
.where(LAST_NAME.equal("Poe"))
.fetch();]]></java>
</content>
</section>
<redirect id="sql-injection-and-plain-sql-queryparts" redirect-to="sql-injection"/>
<section id="sql-injection">
<title>SQL injection</title>
<content><html>
<h3>SQL injection is serious</h3>
<p>
SQL injection is a serious problem that needs to be taken care of thoroughly. A single vulnerability can be enough for an attacker to dump your whole database, and potentially seize your database server. <a href="http://blog.jooq.org/2013/11/05/using-sql-injection-vulnerabilities-to-dump-your-database/">We've blogged about the severity of this threat on the jOOQ blog</a>.
</p>
<p>
SQL injection happens because a programming language (SQL) is used to dynamically create arbitrary server-side statements based on user input. Programmers must take lots of care not to mix the language parts (SQL) with the user input (<reference id="bind-values" title="bind variables"/>)
</p>
<h3>SQL injection in jOOQ</h3>
<p>
With jOOQ, SQL is usually created via a type safe, non-dynamic Java abstract syntax tree, where bind variables are a part of that abstract syntax tree. It is not possible to expose SQL injection vulnerabilities this way.
</p>
<p>
However, jOOQ offers convenient ways of introducing <reference id="plain-sql" title="plain SQL strings"/> in various places of the jOOQ API (which are annotated using <reference class="org.jooq.PlainSQL"/> since jOOQ 3.6). While jOOQ's API allows you to specify bind values for use with plain SQL, you're not forced to do that. For instance, both of the following queries will lead to the same, valid result:
</p>
</html><java><![CDATA[// This query will use bind values, internally.
create.fetch("SELECT * FROM BOOK WHERE ID = ? AND TITLE = ?", 5 "Animal Farm");
// This query will not use bind values, internally.
create.fetch("SELECT * FROM BOOK WHERE ID = 5 AND TITLE = 'Animal Farm'");]]></java><html>
<p>
All methods in the jOOQ API that allow for plain (unescaped, untreated) SQL contain a warning message in their relevant Javadoc, to remind you of the risk of SQL injection in what is otherwise a SQL-injection-safe API.
</p>
</html></content>
</section>
</sections>
</section>
<section id="queryparts">
<title>QueryParts</title>
<content><html>
<p>
A <reference class="org.jooq.Query" /> and all its contained objects is a <reference class="org.jooq.QueryPart" />. QueryParts essentially provide this functionality:
</p>
<ul>
<li>they can <reference id="sql-rendering" title="render SQL"/> using the <reference class="org.jooq.QueryPartInternal" anchor="#accept-org.jooq.Context-" title="accept(Context)"/> method</li>
<li>they can <reference id="variable-binding" title="bind variables"/> using the <reference class="org.jooq.QueryPartInternal" anchor="#accept-org.jooq.Context-" title="accept(Context)"/> method</li>
</ul>
<p>
Both of these methods are contained in jOOQ's internal API's <reference class="org.jooq.QueryPartInternal"/>, which is internally implemented by every QueryPart.
</p>
<p>
The following sections explain some more details about <reference id="sql-rendering" title="SQL rendering"/> and <reference id="variable-binding" title="variable binding"/>, as well as other implementation details about QueryParts in general.
</p>
</html></content>
<sections>
<section id="sql-rendering">
<title>SQL rendering</title>
<content><html>
<p>
Every <reference class="org.jooq.QueryPart"/> must implement the <reference class="org.jooq.QueryPartInternal" anchor="#accept-org.jooq.Context-" title="accept(Context)"/> method to render its SQL string to a <reference class="org.jooq.RenderContext"/>. This RenderContext has two purposes:
</p>
<ul>
<li>It provides some information about the "state" of SQL rendering.</li>
<li>It provides a common API for constructing SQL strings on the context's internal <reference class="java.lang.StringBuilder"/></li>
</ul>
<p>
An overview of the <reference class="org.jooq.RenderContext"/> API is given here:
</p>
</html><java><![CDATA[// These methods are useful for generating unique aliases within a RenderContext (and thus within a Query)
String peekAlias();
String nextAlias();
// These methods return rendered SQL
String render();
String render(QueryPart part);
// These methods allow for fluent appending of SQL to the RenderContext's internal StringBuilder
RenderContext keyword(String keyword);
RenderContext literal(String literal);
RenderContext sql(String sql);
RenderContext sql(char sql);
RenderContext sql(int sql);
RenderContext sql(QueryPart part);
// These methods allow for controlling formatting of SQL, if the relevant Setting is active
RenderContext formatNewLine();
RenderContext formatSeparator();
RenderContext formatIndentStart();
RenderContext formatIndentStart(int indent);
RenderContext formatIndentLockStart();
RenderContext formatIndentEnd();
RenderContext formatIndentEnd(int indent);
RenderContext formatIndentLockEnd();
// These methods control the RenderContext's internal state
boolean inline();
RenderContext inline(boolean inline);
boolean qualify();
RenderContext qualify(boolean qualify);
boolean namedParams();
RenderContext namedParams(boolean renderNamedParams);
CastMode castMode();
RenderContext castMode(CastMode mode);
Boolean cast();
RenderContext castModeSome(SQLDialect... dialects);]]></java><html>
<p>
The following additional methods are inherited from a common <reference class="org.jooq.Context"/>, which is shared among <reference class="org.jooq.RenderContext"/> and <reference class="org.jooq.BindContext"/>:
</p>
</html><java><![CDATA[// These methods indicate whether fields or tables are being declared (MY_TABLE AS MY_ALIAS) or referenced (MY_ALIAS)
boolean declareFields();
Context declareFields(boolean declareFields);
boolean declareTables();
Context declareTables(boolean declareTables);
// These methods indicate whether a top-level query is being rendered, or a subquery
boolean subquery();
Context subquery(boolean subquery);
// These methods provide the bind value indices within the scope of the whole Context (and thus of the whole Query)
int nextIndex();
int peekIndex();]]></java><html>
<h3>An example of rendering SQL</h3>
<p>
A simple example can be provided by checking out jOOQ's internal representation of a (simplified) <reference id="comparison-predicate" title="CompareCondition"/>. It is used for any <reference class="org.jooq.Condition"/> comparing two fields as for example the <code>AUTHOR.ID = BOOK.AUTHOR_ID</code> condition here:
</p>
</html><sql>-- [...]
FROM AUTHOR
JOIN BOOK ON AUTHOR.ID = BOOK.AUTHOR_ID
-- [...]</sql><html>
<p>
This is how jOOQ renders such a condition (simplified example):
</p>
</html><java><![CDATA[@Override
public final void accept(Context<?> context) {
// The CompareCondition delegates rendering of the Fields to the Fields
// themselves and connects them using the Condition's comparator operator:
context.visit(field1)
.sql(" ")
.keyword(comparator.toSQL())
.sql(" ")
.visit(field2);
}]]></java><html>
<p>
See the manual's sections about <reference id="custom-queryparts" title="custom QueryParts"/> and <reference id="plain-sql-queryparts" title="plain SQL QueryParts"/> to learn about how to write your own query parts in order to extend jOOQ.
</p>
</html></content>
</section>
<section id="pretty-printing">
<title>Pretty printing SQL</title>
<content><html>
<p>
As mentioned in the previous chapter about <reference id="sql-rendering" title="SQL rendering"/>, there are some elements in the <reference class="org.jooq.RenderContext"/> that are used for formatting / pretty-printing rendered SQL. In order to obtain pretty-printed SQL, just use the following <reference id="custom-settings" title="custom settings"/>:
</p>
</html><java><![CDATA[// Create a DSLContext that will render "formatted" SQL
DSLContext pretty = DSL.using(dialect, new Settings().withRenderFormatted(true));]]></java><html>
<p>
And then, use the above DSLContext to render pretty-printed SQL:
</p>
</html><code-pair>
<java><![CDATA[String sql = pretty.select(
AUTHOR.LAST_NAME, count().as("c"))
.from(BOOK)
.join(AUTHOR)
.on(BOOK.AUTHOR_ID.equal(AUTHOR.ID))
.where(BOOK.TITLE.notEqual("1984"))
.groupBy(AUTHOR.LAST_NAME)
.having(count().equal(2))
.getSQL();]]></java>
<sql><![CDATA[select
"TEST"."AUTHOR"."LAST_NAME",
count(*) "c"
from "TEST"."BOOK"
join "TEST"."AUTHOR"
on "TEST"."BOOK"."AUTHOR_ID" = "TEST"."AUTHOR"."ID"
where "TEST"."BOOK"."TITLE" <> '1984'
group by "TEST"."AUTHOR"."LAST_NAME"
having count(*) = 2]]></sql>
</code-pair><html>
<p>
The section about <reference id="execute-listeners" title="ExecuteListeners"/> shows an example of how such pretty printing can be used to log readable SQL to the stdout.
</p>
</html></content>
</section>
<section id="variable-binding">
<title>Variable binding</title>
<content><html>
<p>
Every <reference class="org.jooq.QueryPart"/> must implement the <reference class="org.jooq.QueryPartInternal" anchor="#accept-org.jooq.Context-" title="accept(Context&lt;?&gt;)"/> method. This Context has two purposes (among many others):
</p>
<ul>
<li>It provides some information about the "state" of the variable binding in process.</li>
<li>It provides a common API for binding values to the context's internal <reference class="java.sql.PreparedStatement"/></li>
</ul>
<p>
An overview of the <reference class="org.jooq.BindContext"/> API is given here:
</p>
</html><java><![CDATA[// This method provides access to the PreparedStatement to which bind values are bound
PreparedStatement statement();
// These methods provide convenience to delegate variable binding
BindContext bind(QueryPart part) throws DataAccessException;
BindContext bind(Collection<? extends QueryPart> parts) throws DataAccessException;
BindContext bind(QueryPart[] parts) throws DataAccessException;
// These methods perform the actual variable binding
BindContext bindValue(Object value, Class<?> type) throws DataAccessException;
BindContext bindValues(Object... values) throws DataAccessException;]]></java><html>
<p>
Some additional methods are inherited from a common <reference class="org.jooq.Context"/>, which is shared among <reference class="org.jooq.RenderContext"/> and <reference class="org.jooq.BindContext"/>. Details are documented in the previous chapter about <reference id="sql-rendering" title="SQL rendering"/>
</p>
<h3>An example of binding values to SQL</h3>
<p>
A simple example can be provided by checking out jOOQ's internal representation of a (simplified) <reference id="comparison-predicate" title="CompareCondition"/>. It is used for any <reference class="org.jooq.Condition"/> comparing two fields as for example the <code>AUTHOR.ID = BOOK.AUTHOR_ID</code> condition here:
</p>
</html><sql>-- [...]
WHERE AUTHOR.ID = ?
-- [...]</sql><html>
<p>
This is how jOOQ binds values on such a condition:
</p>
</html><java><![CDATA[@Override
public final void bind(BindContext context) throws DataAccessException {
// The CompareCondition itself does not bind any variables.
// But the two fields involved in the condition might do so...
context.bind(field1).bind(field2);
}]]></java><html>
<p>
See the manual's sections about <reference id="custom-queryparts" title="custom QueryParts"/> and <reference id="plain-sql-queryparts" title="plain SQL QueryParts"/> to learn about how to write your own query parts in order to extend jOOQ.
</p>
</html></content>
</section>
<section id="custom-bindings">
<title>Custom data type bindings</title>
<content><html>
<p>
jOOQ supports all the standard SQL data types out of the box, i.e. the types contained in <reference class="java.sql.Types"/>. But your domain model might be more specific, or you might be using a vendor-specific data type, such as JSON, HSTORE, or some other data structure. If this is the case, this section will be right for you, we'll see how you can create <reference class="org.jooq.Converter"/> types and <reference class="org.jooq.Binding"/> types.
</p>
<h3>
Converters
</h3>
<p>
The simplest use-case of injecting custom data types is by using <reference class="org.jooq.Converter"/>. A <code>Converter</code> can convert from a database type <code>&lt;T></code> to a user-defined type <code>&lt;U></code> and vice versa. You'll be implementing this SPI:
</p>
</html><java><![CDATA[public interface Converter<T, U> {
// Your conversion logic goes into these two methods, that can convert
// between the database type T and the user type U:
U from(T databaseObject);
T to(U userObject);
// You need to provide Class instances for each type, too:
Class<T> fromType();
Class<U> toType();
}]]></java><html>
<p>
If, for instance, you want to use Java 8's <reference class="java.time.LocalDate"/> for SQL <code>DATE</code> and <reference class="java.time.LocalDateTime"/> for SQL <code>TIMESTAMP</code>, you write a converter like this:
</p>
</html><java><![CDATA[import java.sql.Date;
import java.time.LocalDate;
import org.jooq.Converter;
public class LocalDateConverter implements Converter<Date, LocalDate> {
@Override
public LocalDate from(Date t) {
return t == null ? null : LocalDate.parse(t.toString());
}
@Override
public Date to(LocalDate u) {
return u == null ? null : Date.valueOf(u.toString());
}
@Override
public Class<Date> fromType() {
return Date.class;
}
@Override
public Class<LocalDate> toType() {
return LocalDate.class;
}
}]]></java><html>
<p>
This converter can now be used in a variety of jOOQ API, most importanly to create a new data type:
</p>
</html><java><![CDATA[DataType<LocalDate> type = SQLDataType.DATE.asConvertedDataType(new LocalDateConverter());]]></java><html>
<p>
And data types, in turn, can be used with any <reference class="org.jooq.Field"/>, i.e. with any <reference id="column-expressions" title="column expression"/>, including <reference id="plain-sql" title="plain SQL"/> or <reference id="names" title="name"/> based ones:
</p>
</html><java><![CDATA[DataType<LocalDate> type = SQLDataType.DATE.asConvertedDataType(new LocalDateConverter());
// Plain SQL based
Field<LocalDate> date1 = DSL.field("my_table.my_column", type);
// Name based
Field<LocalDate> date2 = DSL.field(name("my_table", "my_column"), type);]]></java><html>
<h3>
Bindings
</h3>
<p>
While converters are very useful for simple use-cases, <reference class="org.jooq.Binding"/> is useful when you need to customise data type interactions at a JDBC level, e.g. when you want to bind a PostgreSQL JSON data type. Custom bindings implement the following SPI:
</p>
</html><java><![CDATA[public interface Binding<T, U> extends Serializable {
// A converter that does the conversion between the database type T
// and the user type U (see previous examples)
Converter<T, U> converter();
// A callback that generates the SQL string for bind values of this
// binding type. Typically, just ?, but also ?::json, etc.
void sql(BindingSQLContext<U> ctx) throws SQLException;
// Callbacks that implement all interaction with JDBC types, such as
// PreparedStatement, CallableStatement, SQLOutput, SQLinput, ResultSet
void register(BindingRegisterContext<U> ctx) throws SQLException;
void set(BindingSetStatementContext<U> ctx) throws SQLException;
void set(BindingSetSQLOutputContext<U> ctx) throws SQLException;
void get(BindingGetResultSetContext<U> ctx) throws SQLException;
void get(BindingGetStatementContext<U> ctx) throws SQLException;
void get(BindingGetSQLInputContext<U> ctx) throws SQLException;
}]]></java><html>
<p>
Below is full fledged example implementation that uses Google Gson to model JSON documents in Java
</p>
</html><java><![CDATA[import static org.jooq.tools.Convert.convert;
import java.sql.*;
import org.jooq.*;
import org.jooq.impl.DSL;
import com.google.gson.*;
// We're binding <T> = Object (unknown database type), and <U> = JsonElement (user type)
public class PostgresJSONGsonBinding implements Binding<Object, JsonElement> {
// The converter does all the work
@Override
public Converter<Object, JsonElement> converter() {
return new Converter<Object, JsonElement>() {
@Override
public JsonElement from(Object t) {
return t == null ? JsonNull.INSTANCE : new Gson().fromJson("" + t, JsonElement.class);
}
@Override
public Object to(JsonElement u) {
return u == null || u == JsonNull.INSTANCE ? null : new Gson().toJson(u);
}
@Override
public Class<Object> fromType() {
return Object.class;
}
@Override
public Class<JsonElement> toType() {
return JsonElement.class;
}
};
}
// Rending a bind variable for the binding context's value and casting it to the json type
@Override
public void sql(BindingSQLContext<JsonElement> ctx) throws SQLException {
ctx.render().visit(DSL.val(ctx.convert(converter()).value())).sql("::json");
}
// Registering VARCHAR types for JDBC CallableStatement OUT parameters
@Override
public void register(BindingRegisterContext<JsonElement> ctx) throws SQLException {
ctx.statement().registerOutParameter(ctx.index(), Types.VARCHAR);
}
// Converting the JsonElement to a String value and setting that on a JDBC PreparedStatement
@Override
public void set(BindingSetStatementContext<JsonElement> ctx) throws SQLException {
ctx.statement().setString(ctx.index(), Objects.toString(ctx.convert(converter()).value(), null));
}
// Getting a String value from a JDBC ResultSet and converting that to a JsonElement
@Override
public void get(BindingGetResultSetContext<JsonElement> ctx) throws SQLException {
ctx.convert(converter()).value(ctx.resultSet().getString(ctx.index()));
}
// Getting a String value from a JDBC CallableStatement and converting that to a JsonElement
@Override
public void get(BindingGetStatementContext<JsonElement> ctx) throws SQLException {
ctx.convert(converter()).value(ctx.statement().getString(ctx.index()));
}
// Setting a value on a JDBC SQLOutput (useful for Oracle OBJECT types)
@Override
public void set(BindingSetSQLOutputContext<JsonElement> ctx) throws SQLException {
throw new SQLFeatureNotSupportedException();
}
// Getting a value from a JDBC SQLInput (useful for Oracle OBJECT types)
@Override
public void get(BindingGetSQLInputContext<JsonElement> ctx) throws SQLException {
throw new SQLFeatureNotSupportedException();
}
}]]></java><html>
<h3>
Code generation
</h3>
<p>
There is a special section in the manual explaining how to automatically tie your <code>Converters</code> and <code>Bindings</code> to your generated code. The relevant sections are:
</p>
<ul>
<li><reference id="custom-data-types" title="Custom data types for org.jooq.Converter"/></li>
<li><reference id="custom-bindings" title="Custom data type binding for org.jooq.Binding"/></li>
</ul>
</html></content>
</section>
<section id="custom-queryparts">
<title>Custom syntax elements</title>
<content><html>
<p>
If a SQL clause is too complex to express with jOOQ, you can extend either one of the following types for use directly in a jOOQ query:
</p>
</html><java><![CDATA[public abstract class CustomField<T> extends AbstractField<T> {}
public abstract class CustomCondition extends AbstractCondition {}
public abstract class CustomTable<R extends TableRecord<R>> extends TableImpl<R> {}
public abstract class CustomRecord<R extends TableRecord<R>> extends TableRecordImpl<R> {}]]></java><html>
<p>
These classes are declared public and covered by jOOQ's integration tests. When you extend these classes, you will have to provide your own implementations for the <reference id="queryparts" title="QueryParts'"/> <reference id="sql-rendering" title="accept()"/> method, as discussed before:
</p>
</html><java><![CDATA[// This method must produce valid SQL. If your QueryPart contains other QueryParts, you may delegate SQL generation to them
// in the correct order, passing the render context.
//
// If context.inline() is true, you must inline all bind variables
// If context.inline() is false, you must generate ? for your bind variables
public void toSQL(RenderContext context);
// This method must bind all bind variables to a PreparedStatement. If your QueryPart contains other QueryParts, $
// you may delegate variable binding to them in the correct order, passing the bind context.
//
// Every QueryPart must ensure, that it starts binding its variables at context.nextIndex().
public void bind(BindContext context) throws DataAccessException;]]></java><html>
<h3>
An example for implementing multiplication.
</h3>
<p>
The above contract may be a bit tricky to understand at first. The best thing is to check out jOOQ source code and have a look at a couple of QueryParts, to see how it's done. Here's an example <reference class="org.jooq.impl.CustomField"/> showing how to create a field multiplying another field by 2
</p>
</html><java><![CDATA[// Create an anonymous CustomField, initialised with BOOK.ID arguments
final Field<Integer> IDx2 = new CustomField<Integer>(BOOK.ID.getName(), BOOK.ID.getDataType()) {
@Override
public void toSQL(RenderContext context) {
// In inline mode, render the multiplication directly
if (context.inline()) {
context.sql(BOOK.ID).sql(" * 2");
}
// In non-inline mode, render a bind value
else {
context.sql(BOOK.ID).sql(" * ?");
}
}
@Override
public void bind(BindContext context) {
try {
// Manually bind the value 2
context.statement().setInt(context.nextIndex(), 2);
// Alternatively, you could also write:
// context.bind(DSL.val(2));
}
catch (SQLException e) {
throw translate(getSQL(), e);
}
}
};
// Use the above field in a SQL statement:
create.select(IDx2).from(BOOK);]]></java><html>
<h3>
An example for implementing vendor-specific functions.
</h3>
<p>
Many vendor-specific functions are not officially supported by jOOQ, but you can implement such support yourself using <code>CustomField</code>, for instance. Here's an example showing how to implement Oracle's <code>TO_CHAR()</code> function, emulating it in SQL Server using <code>CONVERT()</code>:
</p>
</html><java><![CDATA[// Create a CustomField implementation taking two arguments in its constructor
class ToChar extends CustomField<String> {
final Field<?> arg0;
final Field<?> arg1;
ToChar(Field<?> arg0, Field<?> arg1) {
super("to_char", SQLDataType.VARCHAR);
this.arg0 = arg0;
this.arg1 = arg1;
}
@Override
public void accept(RenderContext context) {
context.visit(delegate(context.configuration()));
}
private QueryPart delegate(Configuration configuration) {
switch (configuration.dialect().family()) {
case ORACLE:
return DSL.field("TO_CHAR({0}, {1})", String.class, arg0, arg1);
case SQLSERVER:
return DSL.field("CONVERT(VARCHAR(8), {0}, {1})", String.class, arg0, arg1);
default:
throw new UnsupportedOperationException("Dialect not supported");
}
}
}
]]></java><html>
<p>
The above <code>CustomField</code> implementation can be exposed from your own custom DSL class:
</p>
</html><java><![CDATA[public class MyDSL {
public static Field<String> toChar(Field<?> field, String format) {
return new ToChar(field, DSL.inline(format));
}
}]]></java>
</content>
</section>
<section id="plain-sql-queryparts">
<title>Plain SQL QueryParts</title>
<content><html>
<p>
If you don't need the integration of rather complex QueryParts into jOOQ, then you might be safer using simple <reference id="plain-sql" title="Plain SQL"/> functionality, where you can provide jOOQ with a simple String representation of your embedded SQL. Plain SQL methods in jOOQ's API come in two flavours.
</p>
<ul>
<li><strong>method(String, Object...)</strong>: This is a method that accepts a SQL string and a list of bind values that are to be bound to the variables contained in the SQL string</li>
<li><strong>method(String, QueryPart...)</strong>: This is a method that accepts a SQL string and a list of QueryParts that are "injected" at the position of their respective placeholders in the SQL string</li>
</ul>
<p>
The above distinction is best explained using an example:
</p>
</html><java><![CDATA[// Plain SQL using bind values. The value 5 is bound to the first variable, "Animal Farm" to the second variable:
create.selectFrom(BOOK).where("BOOK.ID = ? AND TITLE = ?", 5, "Animal Farm").fetch();
// Plain SQL using placeholders (counting from zero).
// The QueryPart "id" is substituted for the placeholder {0}, the QueryPart "title" for {1}
Field<Integer> id = val(5);
Field<String> title = val("Animal Farm");
create.selectFrom(BOOK).where("BOOK.ID = {0} AND TITLE = {1}", id, title).fetch();]]></java><html>
<p>
The above technique allows for creating rather complex SQL clauses that are currently not supported by jOOQ, without extending any of the <reference id="custom-queryparts" title="custom QueryParts"/> as indicated in the previous chapter.
</p>
</html></content>
</section>
<section id="serializability">
<title>Serializability</title>
<content><html>
<p>
The only transient, non-serializable element in any jOOQ object is the <reference id="dsl-context" title="Configuration's"/> underlying <reference class="java.sql.Connection"/>. When you want to execute queries after de-serialisation, or when you want to store/refresh/delete <reference id="crud-with-updatablerecords" title="Updatable Records"/>, you may have to "re-attach" them to a Configuration
</p>
</html><java><![CDATA[// Deserialise a SELECT statement
ObjectInputStream in = new ObjectInputStream(...);
Select<?> select = (Select<?>) in.readObject();
// This will throw a DetachedException:
select.execute();
// In order to execute the above select, attach it first
DSLContext create = DSL.using(connection, SQLDialect.ORACLE);
create.attach(select);]]></java><html>
<h3>Automatically attaching QueryParts</h3>
<p>
Another way of attaching QueryParts automatically, or rather providing them with a new <reference class="java.sql.Connection"/> at will, is to hook into the <reference id="execute-listeners" title="Execute Listener support"/>. More details about this can be found in the manual's chapter about <reference id="execute-listeners" title="ExecuteListeners"/>
</p>
</html></content>
</section>
<section id="custom-sql-transformation">
<title>Custom SQL transformation</title>
<content><html>
<p>
With jOOQ 3.2's <reference class="org.jooq.VisitListener"/> SPI, it is possible to perform custom SQL transformation to implement things like shared-schema multi-tenancy, or a security layer centrally preventing access to certain data. This SPI is extremely powerful, as you can make ad-hoc decisions at runtime regarding local or global transformation of your SQL statement. The following sections show a couple of simple, yet real-world use-cases.
</p>
</html></content>
<sections>
<section id="transformation-bind-value-abbreviation">
<title>Logging abbreviated bind values</title>
<content><html>
<p>
When implementing a logger, one needs to carefully assess how much information should really be disclosed on what logger level. In log4j and similar frameworks, we distinguish between <code>FATAL</code>, <code>ERROR</code>, <code>WARN</code>, <code>INFO</code>, <code>DEBUG</code>, and <code>TRACE</code>. In <code>DEBUG</code> level, jOOQ's <reference id="logging" title="internal default logger"/> logs all executed statements including inlined bind values as such:
</p>
</html><text><![CDATA[Executing query : select * from "BOOK" where "BOOK"."TITLE" like ?
-> with bind values : select * from "BOOK" where "BOOK"."TITLE" like 'How I stopped worrying%']]></text><html>
<p>
But textual or binary bind values can get quite long, quickly filling your log files with irrelevant information. It would be good to be able to abbreviate such long values (and possibly add a remark to the logged statement). Instead of patching jOOQ's internals, we can just transform the SQL statements in the logger implementation, cleanly separating concerns. This can be done with the following <code>VisitListener</code>:
</p>
</html><java><![CDATA[// This listener is inserted into a Configuration through a VisitListenerProvider that creates a
// new listener instance for every rendering lifecycle
public class BindValueAbbreviator extends DefaultVisitListener {
private boolean anyAbbreviations = false;
@Override
public void visitStart(VisitContext context) {
// Transform only when rendering values
if (context.renderContext() != null) {
QueryPart part = context.queryPart();
// Consider only bind variables, leave other QueryParts untouched
if (part instanceof Param<?>) {
Param<?> param = (Param<?>) part;
Object value = param.getValue();
// If the bind value is a String (or Clob) of a given length, abbreviate it
// e.g. using commons-lang's StringUtils.abbreviate()
if (value instanceof String && ((String) value).length() > maxLength) {
anyAbbreviations = true;
// ... and replace it in the current rendering context (not in the Query)
context.queryPart(val(abbreviate((String) value, maxLength)));
}
// If the bind value is a byte[] (or Blob) of a given length, abbreviate it
// e.g. by removing bytes from the array
else if (value instanceof byte[] && ((byte[]) value).length > maxLength) {
anyAbbreviations = true;
// ... and replace it in the current rendering context (not in the Query)
context.queryPart(val(Arrays.copyOf((byte[]) value, maxLength)));
}
}
}
}
@Override
public void visitEnd(VisitContext context) {
// If any abbreviations were performed before...
if (anyAbbreviations) {
// ... and if this is the top-level QueryPart, then append a SQL comment to indicate the abbreviation
if (context.queryPartsLength() == 1) {
context.renderContext().sql(" -- Bind values may have been abbreviated");
}
}
}
}]]></java><html>
<p>
If maxLength were set to 5, the above listener would produce the following log output:
</p>
</html><text><![CDATA[Executing query : select * from "BOOK" where "BOOK"."TITLE" like ?
-> with bind values : select * from "BOOK" where "BOOK"."TITLE" like 'Ho...' -- Bind values may have been abbreviated]]></text><html>
<p>
The above <code>VisitListener</code> is in place since jOOQ 3.3 in the <reference class="org.jooq.tools.LoggerListener"/>.
</p>
</html></content>
</section>
</sections>
</section>
</sections>
</section>
<section id="scala-sql-building">
<title>SQL building in Scala</title>
<content><html>
<p>
jOOQ-Scala is a maven module used for leveraging some advanced Scala features for those users that wish to use jOOQ with Scala.
</p>
<h3>Using Scala's implicit defs to allow for operator overloading</h3>
<p>
The most obvious Scala feature to use in jOOQ are implicit defs for implicit conversions in order to enhance the <reference class="org.jooq.Field"/> type with SQL-esque operators.
</p>
<p>
The following depicts a trait which wraps all fields:
</p>
</html><scala><![CDATA[/**
* A Scala-esque representation of {@link org.jooq.Field}, adding overloaded
* operators for common jOOQ operations to arbitrary fields
*/
trait SAnyField[T] extends Field[T] {
// String operations
// -----------------
def ||(value : String) : Field[String]
def ||(value : Field[_]) : Field[String]
// Comparison predicates
// ---------------------
def ===(value : T) : Condition
def ===(value : Field[T]) : Condition
def !==(value : T) : Condition
def !==(value : Field[T]) : Condition
def <>(value : T) : Condition
def <>(value : Field[T]) : Condition
def >(value : T) : Condition
def >(value : Field[T]) : Condition
def >=(value : T) : Condition
def >=(value : Field[T]) : Condition
def <(value : T) : Condition
def <(value : Field[T]) : Condition
def <=(value : T) : Condition
def <=(value : Field[T]) : Condition
def <=>(value : T) : Condition
def <=>(value : Field[T]) : Condition
}]]></scala><html>
<p>
The following depicts a trait which wraps numeric fields:
</p>
</html><scala><![CDATA[/**
* A Scala-esque representation of {@link org.jooq.Field}, adding overloaded
* operators for common jOOQ operations to numeric fields
*/
trait SNumberField[T <: Number] extends SAnyField[T] {
// Arithmetic operations
// ---------------------
def unary_- : Field[T]
def +(value : Number) : Field[T]
def +(value : Field[_ <: Number]) : Field[T]
def -(value : Number) : Field[T]
def -(value : Field[_ <: Number]) : Field[T]
def *(value : Number) : Field[T]
def *(value : Field[_ <: Number]) : Field[T]
def /(value : Number) : Field[T]
def /(value : Field[_ <: Number]) : Field[T]
def %(value : Number) : Field[T]
def %(value : Field[_ <: Number]) : Field[T]
// Bitwise operations
// ------------------
def unary_~ : Field[T]
def &(value : T) : Field[T]
def &(value : Field[T]) : Field[T]
def |(value : T) : Field[T]
def |(value : Field[T]) : Field[T]
def ^(value : T) : Field[T]
def ^(value : Field[T]) : Field[T]
def <<(value : T) : Field[T]
def <<(value : Field[T]) : Field[T]
def >>(value : T) : Field[T]
def >>(value : Field[T]) : Field[T]
}]]></scala><html>
<p>
An example query using such overloaded operators would then look like this:
</p>
</html><scala><![CDATA[select (
BOOK.ID * BOOK.AUTHOR_ID,
BOOK.ID + BOOK.AUTHOR_ID * 3 + 4,
BOOK.TITLE || " abc" || " xy")
from BOOK
leftOuterJoin (
select (x.ID, x.YEAR_OF_BIRTH)
from x
limit 1
asTable x.getName()
)
on BOOK.AUTHOR_ID === x.ID
where (BOOK.ID <> 2)
or (BOOK.TITLE in ("O Alquimista", "Brida"))
fetch]]></scala><html>
<h3>Scala 2.10 Macros</h3>
<p>
This feature is still being experimented with. With Scala Macros, it might be possible to inline a true SQL dialect into the Scala syntax, backed by the jOOQ API. Stay tuned!
</p>
</html></content>
</section>
</sections>
</section>
<section id="sql-execution">
<title>SQL execution</title>
<content><html>
<p>
In a previous section of the manual, we've seen how jOOQ can be used to <reference id="sql-building" title="build SQL"/> that can be executed with any API including JDBC or ... jOOQ. This section of the manual deals with various means of actually executing SQL with jOOQ.
</p>
<h3>SQL execution with JDBC</h3>
<p>
JDBC calls executable objects "<reference class="java.sql.Statement"/>". It distinguishes between three types of statements:
</p>
<ul>
<li><reference class="java.sql.Statement"/>, or "static statement": This statement type is used for any arbitrary type of SQL statement. It is particularly useful with <reference id="inlined-parameters" title="inlined parameters"/></li>
<li><reference class="java.sql.PreparedStatement"/>: This statement type is used for any arbitrary type of SQL statement. It is particularly useful with <reference id="indexed-parameters" title="indexed parameters"/> (note that JDBC does not support <reference id="named-parameters" title="named parameters"/>)</li>
<li><reference class="java.sql.CallableStatement"/>: This statement type is used for SQL statements that are "called" rather than "executed". In particular, this includes calls to <reference id="stored-procedures" title="stored procedures"/>. Callable statements can register OUT parameters</li>
</ul>
<p>
Today, the JDBC API may look weird to users being used to object-oriented design. While statements hide a lot of SQL dialect-specific implementation details quite well, they assume a lot of knowledge about the internal state of a statement. For instance, you can use the <reference class="java.sql.PreparedStatement" anchor="#addBatch()" title="PreparedStatement.addBatch()"/> method, to add a the prepared statement being created to an "internal list" of batch statements. Instead of returning a new type, this method forces user to reflect on the prepared statement's internal state or "mode".
</p>
<h3>jOOQ is wrapping JDBC</h3>
<p>
These things are abstracted away by jOOQ, which exposes such concepts in a more object-oriented way. For more details about jOOQ's batch query execution, see the manual's section about <reference id="batch-execution" title="batch execution"/>.
</p>
<p>
The following sections of this manual will show how jOOQ is wrapping JDBC for SQL execution
</p>
</html></content>
<sections>
<section id="comparison-with-jdbc">
<title>Comparison between jOOQ and JDBC</title>
<content><html>
<h3>Similarities with JDBC</h3>
<p>
Even if there are <reference id="query-vs-resultquery" title="two general types of Query"/>, there are a lot of similarities between JDBC and jOOQ. Just to name a few:
</p>
<ul>
<li>Both APIs return the number of affected records in non-result queries. JDBC: <reference class="java.sql.Statement" anchor="#executeUpdate(java.lang.String)" title="Statement.executeUpdate()"/>, jOOQ: <reference class="org.jooq.Query" anchor="#execute()" title="Query.execute()"/></li>
<li>Both APIs return a scrollable result set type from result queries. JDBC: <reference class="java.sql.ResultSet"/>, jOOQ: <reference class="org.jooq.Result"/></li>
</ul>
<h3>Differences to JDBC</h3>
<p>
Some of the most important differences between JDBC and jOOQ are listed here:
</p>
<ul>
<li><reference id="query-vs-resultquery" title="Query vs. ResultQuery"/>: JDBC does not formally distinguish between queries that can return results, and queries that cannot. The same API is used for both. This greatly reduces the possibility for <reference id="fetching" title="fetching convenience methods"/></li>
<li><reference id="exception-handling" title="Exception handling"/>: While SQL uses the checked <reference class="java.sql.SQLException"/>, jOOQ wraps all exceptions in an unchecked <reference class="org.jooq.exception.DataAccessException"/></li>
<li><reference class="org.jooq.Result"/>: Unlike its JDBC counter-part, this type implements <reference class="java.util.List"/> and is fully loaded into Java memory, freeing resources as early as possible. Just like statements, this means that users don't have to deal with a "weird" internal result set state.</li>
<li><reference class="org.jooq.Cursor"/>: If you want more fine-grained control over how many records are fetched into memory at once, you can still do that using jOOQ's <reference id="lazy-fetching" title="lazy fetching"/> feature</li>
<li><reference id="statement-type" title="Statement type"/>: jOOQ does not formally distinguish between static statements and prepared statements. By default, all statements are prepared statements in jOOQ, internally. Executing a statement as a static statement can be done simply using a <reference id="custom-settings" title="custom settings flag"/></li>
<li><reference id="reusing-statements" title="Closing Statements"/>: JDBC keeps open resources even if they are already consumed. With JDBC, there is a lot of verbosity around safely closing resources. In jOOQ, resources are closed after consumption, by default. If you want to keep them open after consumption, you have to explicitly say so.</li>
<li><reference id="jdbc-flags" title="JDBC flags"/>: JDBC execution flags and modes are not modified. They can be set fluently on a <reference id="query-vs-resultquery" title="Query"/></li>
</ul>
</html></content>
</section>
<section id="query-vs-resultquery">
<title>Query vs. ResultQuery</title>
<content><html>
<p>
Unlike JDBC, jOOQ has a lot of knowledge about a SQL query's structure and internals (see the manual's section about <reference id="sql-building" title="SQL building"/>). Hence, jOOQ distinguishes between these two fundamental types of queries. While every <reference class="org.jooq.Query"/> can be executed, only <reference class="org.jooq.ResultQuery"/> can return results (see the manual's section about <reference id="fetching" title="fetching"/> to learn more about fetching results). With plain SQL, the distinction can be made clear most easily:
</p>
</html><java><![CDATA[// Create a Query object and execute it:
Query query = create.query("DELETE FROM BOOK");
query.execute();
// Create a ResultQuery object and execute it, fetching results:
ResultQuery<Record> resultQuery = create.resultQuery("SELECT * FROM BOOK");
Result<Record> resultQuery.fetch();]]></java>
</content>
</section>
<section id="fetching">
<title>Fetching</title>
<content><html>
<p>
Fetching is something that has been completely neglegted by JDBC and also by various other database abstraction libraries. Fetching is much more than just looping or listing records or mapped objects. There are so many ways you may want to fetch data from a database, it should be considered a first-class feature of any database abstraction API. Just to name a few, here are some of jOOQ's fetching modes:
</p>
<ul>
<li><reference id="record-vs-tablerecord" title="Untyped vs. typed fetching"/>: Sometimes you care about the returned type of your records, sometimes (with arbitrary projections) you don't.</li>
<li><reference id="arrays-maps-and-lists" title="Fetching arrays, maps, or lists"/>: Instead of letting you transform your result sets into any more suitable data type, a library should do that work for you.</li>
<li><reference id="recordhandler" title="Fetching through handler callbacks"/>: This is an entirely different fetching paradigm. With Java 8's lambda expressions, this will become even more powerful.</li>
<li><reference id="recordmapper" title="Fetching through mapper callbacks"/>: This is an entirely different fetching paradigm. With Java 8's lambda expressions, this will become even more powerful.</li>
<li><reference id="pojos" title="Fetching custom POJOs"/>: This is what made Hibernate and JPA so strong. Automatic mapping of tables to custom POJOs.</li>
<li><reference id="lazy-fetching" title="Lazy vs. eager fetching"/>: It should be easy to distinguish these two fetch modes.</li>
<li><reference id="many-fetching" title="Fetching many results"/>: Some databases allow for returning many result sets from a single query. JDBC can handle this but it's very verbose. A list of results should be returned instead.</li>
<li><reference id="later-fetching" title="Fetching data asynchronously"/>: Some queries take too long to execute to wait for their results. You should be able to spawn query execution in a separate process.</li>
</ul>
<h3>Convenience and how ResultQuery, Result, and Record share API</h3>
<p>
The term "fetch" is always reused in jOOQ when you can fetch data from the database. An <reference class="org.jooq.ResultQuery"/> provides many overloaded means of fetching data:
</p>
<h3>Various modes of fetching</h3>
<p>
These modes of fetching are also documented in subsequent sections of the manual
</p>
</html><java><![CDATA[// The "standard" fetch
Result<R> fetch();
// The "standard" fetch when you know your query returns only one record
R fetchOne();
// The "standard" fetch when you only want to fetch the first record
R fetchAny();
// Create a "lazy" Cursor, that keeps an open underlying JDBC ResultSet
Cursor<R> fetchLazy();
Cursor<R> fetchLazy(int fetchSize);
// Fetch several results at once
List<Result<Record>> fetchMany();
// Fetch records into a custom callback
<H extends RecordHandler<R>> H fetchInto(H handler);
// Map records using a custom callback
<E> List<E> fetch(RecordMapper<? super R, E> mapper);
// Execute a ResultQuery with jOOQ, but return a JDBC ResultSet, not a jOOQ object
ResultSet fetchResultSet();]]></java><html>
<h3>Fetch convenience</h3>
<p>
These means of fetching are also available from <reference class="org.jooq.Result"/> and <reference class="org.jooq.Record"/> APIs
</p>
</html><java><![CDATA[// These methods are convenience for fetching only a single field,
// possibly converting results to another type
<T> List<T> fetch(Field<T> field);
<T> List<T> fetch(Field<?> field, Class<? extends T> type);
<T, U> List<U> fetch(Field<T> field, Converter<? super T, U> converter);
List<?> fetch(int fieldIndex);
<T> List<T> fetch(int fieldIndex, Class<? extends T> type);
<U> List<U> fetch(int fieldIndex, Converter<?, U> converter);
List<?> fetch(String fieldName);
<T> List<T> fetch(String fieldName, Class<? extends T> type);
<U> List<U> fetch(String fieldName, Converter<?, U> converter);
// These methods are convenience for fetching only a single field, possibly converting results to another type
// Instead of returning lists, these return arrays
<T> T[] fetchArray(Field<T> field);
<T> T[] fetchArray(Field<?> field, Class<? extends T> type);
<T, U> U[] fetchArray(Field<T> field, Converter<? super T, U> converter);
Object[] fetchArray(int fieldIndex);
<T> T[] fetchArray(int fieldIndex, Class<? extends T> type);
<U> U[] fetchArray(int fieldIndex, Converter<?, U> converter);
Object[] fetchArray(String fieldName);
<T> T[] fetchArray(String fieldName, Class<? extends T> type);
<U> U[] fetchArray(String fieldName, Converter<?, U> converter);
// These methods are convenience for fetching only a single field from a single record,
// possibly converting results to another type
<T> T fetchOne(Field<T> field);
<T> T fetchOne(Field<?> field, Class<? extends T> type);
<T, U> U fetchOne(Field<T> field, Converter<? super T, U> converter);
Object fetchOne(int fieldIndex);
<T> T fetchOne(int fieldIndex, Class<? extends T> type);
<U> U fetchOne(int fieldIndex, Converter<?, U> converter);
Object fetchOne(String fieldName);
<T> T fetchOne(String fieldName, Class<? extends T> type);
<U> U fetchOne(String fieldName, Converter<?, U> converter);]]></java><html>
<h3>Fetch transformations</h3>
<p>
These means of fetching are also available from <reference class="org.jooq.Result"/> and <reference class="org.jooq.Record"/> APIs
</p>
</html><java><![CDATA[// Transform your Records into arrays, Results into matrices
Object[][] fetchArrays();
Object[] fetchOneArray();
// Reduce your Result object into maps
<K> Map<K, R> fetchMap(Field<K> key);
<K, V> Map<K, V> fetchMap(Field<K> key, Field<V> value);
<K, E> Map<K, E> fetchMap(Field<K> key, Class<E> value);
Map<Record, R> fetchMap(Field<?>[] key);
<E> Map<Record, E> fetchMap(Field<?>[] key, Class<E> value);
// Transform your Result object into maps
List<Map<String, Object>> fetchMaps();
Map<String, Object> fetchOneMap();
// Transform your Result object into groups
<K> Map<K, Result<R>> fetchGroups(Field<K> key);
<K, V> Map<K, List<V>> fetchGroups(Field<K> key, Field<V> value);
<K, E> Map<K, List<E>> fetchGroups(Field<K> key, Class<E> value);
Map<Record, Result<R>> fetchGroups(Field<?>[] key);
<E> Map<Record, List<E>> fetchGroups(Field<?>[] key, Class<E> value);
// Transform your Records into custom POJOs
<E> List<E> fetchInto(Class<? extends E> type);
// Transform your records into another table type
<Z extends Record> Result<Z> fetchInto(Table<Z> table);]]></java><html>
<p>
Note, that apart from the <reference class="org.jooq.ResultQuery" anchor="#fetchLazy()" title="fetchLazy()"/> methods, all fetch() methods will immediately close underlying JDBC result sets.
</p>
</html></content>
<sections>
<section id="record-vs-tablerecord">
<title>Record vs. TableRecord</title>
<content><html>
<p>
jOOQ understands that SQL is much more expressive than Java, when it comes to the declarative typing of <reference id="table-expressions" title="table expressions"/>. As a declarative language, SQL allows for creating ad-hoc row value expressions (records with indexed columns, or tuples) and records (records with named columns). In Java, this is not possible to the same extent.
</p>
<p>
Yet, still, sometimes you wish to use strongly typed records, when you know that you're selecting only from a single table:
</p>
<h3>Fetching strongly or weakly typed records</h3>
<p>
When fetching data only from a single table, the <reference id="table-expressions" title="table expression's"/> type is known to jOOQ if you use jOOQ's <reference id="code-generation" title="code generator"/> to generate <reference id="codegen-records" title="TableRecords"/> for your database tables. In order to fetch such strongly typed records, you will have to use the <reference id="select-statement" title="simple select API"/>:
</p>
</html><java><![CDATA[// Use the selectFrom() method:
BookRecord book = create.selectFrom(BOOK).where(BOOK.ID.equal(1)).fetchOne();
// Typesafe field access is now possible:
System.out.println("Title : " + book.getTitle());
System.out.println("Published in: " + book.getPublishedIn());]]></java><html>
<p>
When you use the <reference class="org.jooq.DSLContext" anchor="#selectFrom(org.jooq.Table)" title="DSLContext.selectFrom()"/> method, jOOQ will return the record type supplied with the argument table. Beware though, that you will no longer be able to use any clause that modifies the type of your <reference id="table-expressions" title="table expression"/>. This includes:
</p>
<ul>
<li><reference id="select-clause" title="The SELECT clause"/></li>
<li><reference id="join-clause" title="The JOIN clause"/></li>
</ul>
<h3>
Mapping custom row types to strongly typed records
</h3>
<p>
Sometimes, you may want to explicitly select only a subset of your columns, but still use strongly typed records. Alternatively, you may want to join a one-to-one relationship and receive the two individual strongly typed records after the join.
</p>
<p>
In both of the above cases, you can map your <reference class="org.jooq.Record"/> "into" a <reference class="org.jooq.TableRecord"/> type by using <reference class="org.jooq.Record" anchor="#into-org.jooq.Table-" title="Record.into(Table)"/>.
</p>
</html><java><![CDATA[// Join two tables
Record record = create.select()
.from(BOOK)
.join(AUTHOR).on(BOOK.AUTHOR_ID.eq(AUTHOR.ID))
.where(BOOK.ID.equal(1))
.fetchOne();
// "extract" the two individual strongly typed TableRecord types from the denormalised Record:
BookRecord book = record.into(BOOK);
AuthorRecord author = record.into(AUTHOR);
// Typesafe field access is now possible:
System.out.println("Title : " + book.getTitle());
System.out.println("Published in: " + book.getPublishedIn());
System.out.println("Author : " + author.getFirstName() + " " + author.getLastName();]]></java>
</content>
</section>
<section id="record-n">
<title>Record1 to Record{max-row-degree}</title>
<content><html>
<p>
jOOQ's <reference id="row-value-expressions" title="row value expression (or tuple)"/> support has been explained earlier in this manual. It is useful for constructing row value expressions where they can be used in SQL. The same typesafety is also applied to records for degrees up to {max-row-degree}. To express this fact, <reference class="org.jooq.Record"/> is extended by <reference class="org.jooq.Record1"/> to <reference class="org.jooq.Record{max-row-degree}"/>. Apart from the fact that these extensions of the R type can be used throughout the <reference id="dsl-and-non-dsl" title="jOOQ DSL"/>, they also provide a useful API. Here is <reference class="org.jooq.Record2"/>, for instance:
</p>
</html><java><![CDATA[public interface Record2<T1, T2> extends Record {
// Access fields and values as row value expressions
Row2<T1, T2> fieldsRow();
Row2<T1, T2> valuesRow();
// Access fields by index
Field<T1> field1();
Field<T2> field2();
// Access values by index
T1 value1();
T2 value2();
}]]></java><html>
<h3>Higher-degree records</h3>
<p>
jOOQ chose to explicitly support degrees up to {max-row-degree} to match Scala's typesafe tuple, function and product support. Unlike Scala, however, jOOQ also supports higher degrees without the additional typesafety.
</p>
</html></content>
</section>
<section id="arrays-maps-and-lists">
<title>Arrays, Maps and Lists</title>
<content><html>
<p>
By default, jOOQ returns an <reference class="org.jooq.Result"/> object, which is essentially a <reference class="java.util.List"/> of <reference class="org.jooq.Record"/>. Often, you will find yourself wanting to transform this result object into a type that corresponds more to your specific needs. Or you just want to list all values of one specific column. Here are some examples to illustrate those use cases:
</p>
</html><java><![CDATA[// Fetching only book titles (the two calls are equivalent):
List<String> titles1 = create.select().from(BOOK).fetch().getValues(BOOK.TITLE);
List<String> titles2 = create.select().from(BOOK).fetch(BOOK.TITLE);
String[] titles3 = create.select().from(BOOK).fetchArray(BOOK.TITLE);
// Fetching only book IDs, converted to Long
List<Long> ids1 = create.select().from(BOOK).fetch().getValues(BOOK.ID, Long.class);
List<Long> ids2 = create.select().from(BOOK).fetch(BOOK.ID, Long.class);
Long[] ids3 = create.select().from(BOOK).fetchArray(BOOK.ID, Long.class);
// Fetching book IDs and mapping each ID to their records or titles
Map<Integer, BookRecord> map1 = create.selectFrom(BOOK).fetch().intoMap(BOOK.ID);
Map<Integer, BookRecord> map2 = create.selectFrom(BOOK).fetchMap(BOOK.ID);
Map<Integer, String> map3 = create.selectFrom(BOOK).fetch().intoMap(BOOK.ID, BOOK.TITLE);
Map<Integer, String> map4 = create.selectFrom(BOOK).fetchMap(BOOK.ID, BOOK.TITLE);
// Group by AUTHOR_ID and list all books written by any author:
Map<Integer, Result<BookRecord>> group1 = create.selectFrom(BOOK).fetch().intoGroups(BOOK.AUTHOR_ID);
Map<Integer, Result<BookRecord>> group2 = create.selectFrom(BOOK).fetchGroups(BOOK.AUTHOR_ID);
Map<Integer, List<String>> group3 = create.selectFrom(BOOK).fetch().intoGroups(BOOK.AUTHOR_ID, BOOK.TITLE);
Map<Integer, List<String>> group4 = create.selectFrom(BOOK).fetchGroups(BOOK.AUTHOR_ID, BOOK.TITLE);]]></java><html>
<p>
Note that most of these convenience methods are available both through <reference class="org.jooq.ResultQuery"/> and <reference class="org.jooq.Result"/>, some are even available through <reference class="org.jooq.Record"/> as well.
</p>
</html></content>
</section>
<section id="recordhandler">
<title>RecordHandler</title>
<content><html>
<p>
In a more functional operating mode, you might want to write callbacks that receive records from your select statement results in order to do some processing. This is a common data access pattern in Spring's JdbcTemplate, and it is also available in jOOQ. With jOOQ, you can implement your own <reference class="org.jooq.RecordHandler"/> classes and plug them into jOOQ's <reference class="org.jooq.ResultQuery"/>:
</p>
</html><java><![CDATA[// Write callbacks to receive records from select statements
create.selectFrom(BOOK)
.orderBy(BOOK.ID)
.fetch()
.into(new RecordHandler<BookRecord>() {
@Override
public void next(BookRecord book) {
Util.doThingsWithBook(book);
}
});
// Or more concisely
create.selectFrom(BOOK)
.orderBy(BOOK.ID)
.fetchInto(new RecordHandler<BookRecord>() {...});
// Or even more concisely with Java 8's lambda expressions:
create.selectFrom(BOOK)
.orderBy(BOOK.ID)
.fetchInto(book -> { Util.doThingsWithBook(book); }; );
]]></java><html>
<p>
See also the manual's section about the <reference id="recordmapper" title="RecordMapper"/>, which provides similar features
</p>
</html></content>
</section>
<section id="recordmapper">
<title>RecordMapper</title>
<content><html>
<p>
In a more functional operating mode, you might want to write callbacks that map records from your select statement results in order to do some processing. This is a common data access pattern in Spring's JdbcTemplate, and it is also available in jOOQ. With jOOQ, you can implement your own <reference class="org.jooq.RecordMapper"/> classes and plug them into jOOQ's <reference class="org.jooq.ResultQuery"/>:
</p>
</html><java><![CDATA[// Write callbacks to receive records from select statements
List<Integer> ids =
create.selectFrom(BOOK)
.orderBy(BOOK.ID)
.fetch()
.map(new RecordMapper<BookRecord, Integer>() {
@Override
public Integer map(BookRecord book) {
return book.getId();
}
});
// Or more concisely
create.selectFrom(BOOK)
.orderBy(BOOK.ID)
.fetch(new RecordMapper<BookRecord, Integer>() {...});
// Or even more concisely with Java 8's lambda expressions:
create.selectFrom(BOOK)
.orderBy(BOOK.ID)
.fetch(book -> book.getId());
]]></java><html>
<p>
Your custom <code>RecordMapper</code> types can be used automatically through jOOQ's <reference id="pojos" title="POJO mapping APIs"/>, by injecting a <reference id="pojos-with-recordmapper-provider" title="RecordMapperProvider"/> into your <reference id="dsl-context" title="Configuration"/>.
</p>
<p>
See also the manual's section about the <reference id="recordhandler" title="RecordHandler"/>, which provides similar features
</p>
</html></content>
</section>
<section id="pojos">
<title>POJOs</title>
<content><html>
<p>
Fetching data in records is fine as long as your application is not really layered, or as long as you're still writing code in the DAO layer. But if you have a more advanced application architecture, you may not want to allow for jOOQ artefacts to leak into other layers. You may choose to write POJOs (Plain Old Java Objects) as your primary DTOs (Data Transfer Objects), without any dependencies on jOOQ's <reference class="org.jooq.Record"/> types, which may even potentially hold a reference to a <reference id="dsl-context" title="Configuration"/>, and thus a JDBC <reference class="java.sql.Connection"/>. Like Hibernate/JPA, jOOQ allows you to operate with POJOs. Unlike Hibernate/JPA, jOOQ does not "attach" those POJOs or create proxies with any magic in them.
</p>
<p>
If you're using jOOQ's <reference id="code-generation" title="code generator"/>, you can configure it to <reference id="codegen-pojos" title="generate POJOs"/> for you, but you're not required to use those generated POJOs. You can use your own. See the manual's section about <reference id="pojos-with-recordmapper-provider" title="POJOs with custom RecordMappers"/> to see how to modify jOOQ's standard POJO mapping behaviour.
</p>
<h3>Using JPA-annotated POJOs</h3>
<p>
jOOQ tries to find JPA annotations on your POJO types. If it finds any, they are used as the primary source for mapping meta-information. Only the <reference class="javax.persistence.Column"/> annotation is used and understood by jOOQ. An example:
</p>
</html><java><![CDATA[// A JPA-annotated POJO class
public class MyBook {
@Column(name = "ID")
public int myId;
@Column(name = "TITLE")
public String myTitle;
}
// The various "into()" methods allow for fetching records into your custom POJOs:
MyBook myBook = create.select().from(BOOK).fetchAny().into(MyBook.class);
List<MyBook> myBooks = create.select().from(BOOK).fetch().into(MyBook.class);
List<MyBook> myBooks = create.select().from(BOOK).fetchInto(MyBook.class);]]></java><html>
<p>
Just as with any other JPA implementation, you can put the <reference class="javax.persistence.Column"/> annotation on any class member, including attributes, setters and getters. Please refer to the <reference class="org.jooq.Record" anchor="#into(java.lang.Class)" title="Record.into()"/> Javadoc for more details.
</p>
<h3>Using simple POJOs</h3>
<p>
If jOOQ does not find any JPA-annotations, columns are mapped to the "best-matching" constructor, attribute or setter. An example illustrates this:
</p>
</html><java><![CDATA[// A "mutable" POJO class
public class MyBook1 {
public int id;
public String title;
}
// The various "into()" methods allow for fetching records into your custom POJOs:
MyBook1 myBook = create.select().from(BOOK).fetchAny().into(MyBook1.class);
List<MyBook1> myBooks = create.select().from(BOOK).fetch().into(MyBook1.class);
List<MyBook1> myBooks = create.select().from(BOOK).fetchInto(MyBook1.class);]]></java><html>
<p>
Please refer to the <reference class="org.jooq.Record" anchor="#into(java.lang.Class)" title="Record.into()"/> Javadoc for more details.
</p>
<h3>Using "immutable" POJOs</h3>
<p>
If jOOQ does not find any default constructor, columns are mapped to the "best-matching" constructor. This allows for using "immutable" POJOs with jOOQ. An example illustrates this:
</p>
</html><java><![CDATA[// An "immutable" POJO class
public class MyBook2 {
public final int id;
public final String title;
public MyBook2(int id, String title) {
this.id = id;
this.title = title;
}
}
// With "immutable" POJO classes, there must be an exact match between projected fields and available constructors:
MyBook2 myBook = create.select(BOOK.ID, BOOK.TITLE).from(BOOK).fetchAny().into(MyBook2.class);
List<MyBook2> myBooks = create.select(BOOK.ID, BOOK.TITLE).from(BOOK).fetch().into(MyBook2.class);
List<MyBook2> myBooks = create.select(BOOK.ID, BOOK.TITLE).from(BOOK).fetchInto(MyBook2.class);
// An "immutable" POJO class with a java.beans.ConstructorProperties annotation
public class MyBook3 {
public final String title;
public final int id;
@ConstructorProperties({ "title", "id"})
public MyBook2(String title, int id) {
this.title = title;
this.id = id;
}
}
// With annotated "immutable" POJO classes, there doesn't need to be an exact match between fields and constructor arguments.
// In the below cases, only BOOK.ID is really set onto the POJO, BOOK.TITLE remains null and BOOK.AUTHOR_ID is ignored
MyBook3 myBook = create.select(BOOK.ID, BOOK.AUTHOR_ID).from(BOOK).fetchAny().into(MyBook3.class);
List<MyBook3> myBooks = create.select(BOOK.ID, BOOK.AUTHOR_ID).from(BOOK).fetch().into(MyBook3.class);
List<MyBook3> myBooks = create.select(BOOK.ID, BOOK.AUTHOR_ID).from(BOOK).fetchInto(MyBook3.class);
]]></java><html>
<p>
Please refer to the <reference class="org.jooq.Record" anchor="#into(java.lang.Class)" title="Record.into()"/> Javadoc for more details.
</p>
<h3>Using proxyable types</h3>
<p>
jOOQ also allows for fetching data into abstract classes or interfaces, or in other words, "proxyable" types. This means that jOOQ will return a <reference class="java.util.HashMap"/> wrapped in a <reference class="java.lang.reflect.Proxy"/> implementing your custom type. An example of this is given here:
</p>
</html><java><![CDATA[// A "proxyable" type
public interface MyBook3 {
int getId();
void setId(int id);
String getTitle();
void setTitle(String title);
}
// The various "into()" methods allow for fetching records into your custom POJOs:
MyBook3 myBook = create.select(BOOK.ID, BOOK.TITLE).from(BOOK).fetchAny().into(MyBook3.class);
List<MyBook3> myBooks = create.select(BOOK.ID, BOOK.TITLE).from(BOOK).fetch().into(MyBook3.class);
List<MyBook3> myBooks = create.select(BOOK.ID, BOOK.TITLE).from(BOOK).fetchInto(MyBook3.class);]]></java><html>
<p>
Please refer to the <reference class="org.jooq.Record" anchor="#into(java.lang.Class)" title="Record.into()"/> Javadoc for more details.
</p>
<h3>Loading POJOs back into Records to store them</h3>
<p>
The above examples show how to fetch data into your own custom POJOs / DTOs. When you have modified the data contained in POJOs, you probably want to store those modifications back to the database. An example of this is given here:
</p>
</html><java><![CDATA[// A "mutable" POJO class
public class MyBook {
public int id;
public String title;
}
// Create a new POJO instance
MyBook myBook = new MyBook();
myBook.id = 10;
myBook.title = "Animal Farm";
// Load a jOOQ-generated BookRecord from your POJO
BookRecord book = create.newRecord(BOOK, myBook);
// Insert it (implicitly)
book.store();
// Insert it (explicitly)
create.executeInsert(book);
// or update it (ID = 10)
create.executeUpdate(book);]]></java><html>
<p>
Note: Because of your manual setting of ID = 10, jOOQ's store() method will asume that you want to insert a new record. See the manual's section about <reference id="crud-with-updatablerecords" title="CRUD with UpdatableRecords"/> for more details on this.
</p>
<h3>Interaction with DAOs</h3>
<p>
If you're using jOOQ's <reference id="code-generation" title="code generator"/>, you can configure it to <reference id="codegen-daos" title="generate DAOs"/> for you. Those DAOs operate on <reference id="codegen-pojos" title="generated POJOs"/>. An example of using such a DAO is given here:
</p>
</html><java><![CDATA[// Initialise a Configuration
Configuration configuration = new DefaultConfiguration().set(connection).set(SQLDialect.ORACLE);
// Initialise the DAO with the Configuration
BookDao bookDao = new BookDao(configuration);
// Start using the DAO
Book book = bookDao.findById(5);
// Modify and update the POJO
book.setTitle("1984");
book.setPublishedIn(1948);
bookDao.update(book);
// Delete it again
bookDao.delete(book);]]></java><html>
<h3>More complex data structures</h3>
<p>
jOOQ currently doesn't support more complex data structures, the way Hibernate/JPA attempt to map relational data onto POJOs. While future developments in this direction are not excluded, jOOQ claims that generic mapping strategies lead to an enormous additional complexity that only serves very few use cases. You are likely to find a solution using any of jOOQ's various <reference id="fetching" title="fetching modes"/>, with only little boiler-plate code on the client side.
</p>
</html></content>
</section>
<section id="pojos-with-recordmapper-provider">
<title>POJOs with RecordMappers</title>
<content><html>
<p>
In the previous sections we have seen how to create <reference id="recordmapper" title="RecordMapper"/> types to map jOOQ records onto arbitrary objects. We have also seen how jOOQ provides default algorithms to map jOOQ records onto <reference id="pojos" title="POJOs"/>. Your own custom domain model might be much more complex, but you want to avoid looking up the most appropriate <code>RecordMapper</code> every time you need one. For this, you can provide jOOQ's <reference id="dsl-context" title="Configuration"/> with your own implementation of the <reference class="org.jooq.RecordMapperProvider"/> interface. An example is given here:
</p>
</html><java><![CDATA[DSL.using(new DefaultConfiguration()
.set(connection)
.set(SQLDialect.ORACLE)
.set(
new RecordMapperProvider() {
@Override
public <R extends Record, E> RecordMapper<R, E> provide(RecordType<R> recordType, Class<? extends E> type) {
// UUID mappers will always try to find the ID column
if (type == UUID.class) {
return new RecordMapper<R, E>() {
@Override
public E map(R record) {
return (E) record.getValue("ID");
}
}
}
// Books might be joined with their authors, create a 1:1 mapping
if (type == Book.class) {
return new BookMapper();
}
// Fall back to jOOQ's DefaultRecordMapper, which maps records onto
// POJOs using reflection.
return new DefaultRecordMapper(recordType, type);
}
}
))
.selectFrom(BOOK)
.orderBy(BOOK.ID)
.fetchInto(UUID.class);]]></java><html>
<p>
The above is a very simple example showing that you will have complete flexibility in how to override jOOQ's record to POJO mapping mechanisms.
</p>
<h3>Using third party libraries</h3>
<p>
A couple of useful libraries exist out there, which implement custom, more generic mapping algorithms. Some of them have been specifically made to work with jOOQ. Among them are:
</p>
<ul>
<li><a href="http://modelmapper.org">ModelMapper</a> (with an explicit jOOQ integration)</li>
<li><a href="http://arnaudroger.github.io/SimpleFlatMapper/">SimpleFlatMapper</a> (with an explicit jOOQ integration)</li>
<li><a href="http://orika-mapper.github.io/orika-docs">Orika Mapper</a> (without explicit jOOQ integration)</li>
</ul>
</html></content>
</section>
<section id="lazy-fetching">
<title>Lazy fetching</title>
<content><html>
<p>
Unlike JDBC's <reference class="java.sql.ResultSet"/>, jOOQ's <reference class="org.jooq.Result"/> does not represent an open database cursor with various fetch modes and scroll modes, that needs to be closed after usage. jOOQ's results are simple in-memory Java <reference class="java.util.List"/> objects, containing all of the result values. If your result sets are large, or if you have a lot of network latency, you may wish to fetch records one-by-one, or in small chunks. jOOQ supports a <reference class="org.jooq.Cursor"/> type for that purpose. In order to obtain such a reference, use the <reference class="org.jooq.ResultQuery" anchor="#fetchLazy()" title="ResultQuery.fetchLazy()"/> method. An example is given here:
</p>
</html><java><![CDATA[// Obtain a Cursor reference:
Cursor<BookRecord> cursor = null;
try {
cursor = create.selectFrom(BOOK).fetchLazy();
// Cursor has similar methods as Iterator<R>
while (cursor.hasNext()) {
BookRecord book = cursor.fetchOne();
Util.doThingsWithBook(book);
}
}
// Close the cursor and the cursor's underlying JDBC ResultSet
finally {
if (cursor != null) {
cursor.close();
}
}]]></java><html>
<p>
As a <reference class="org.jooq.Cursor"/> holds an internal reference to an open <reference class="java.sql.ResultSet"/>, it may need to be closed at the end of iteration. If a cursor is completely scrolled through, it will conveniently close the underlying ResultSet. However, you should not rely on that.
</p>
<h3>Cursors ship with all the other fetch features</h3>
<p>
Like <reference class="org.jooq.ResultQuery"/> or <reference class="org.jooq.Result"/>, <reference class="org.jooq.Cursor"/> gives access to all of the other fetch features that we've seen so far, i.e.
</p>
<ul>
<li><reference id="record-vs-tablerecord" title="Strongly or weakly typed records"/>: Cursors are also typed with the &lt;R&gt; type, allowing to fetch custom, generated <reference class="org.jooq.TableRecord"/> or plain <reference class="org.jooq.Record"/> types.</li>
<li><reference id="recordhandler" title="RecordHandler callbacks"/>: You can use your own <reference class="org.jooq.RecordHandler"/> callbacks to receive lazily fetched records.</li>
<li><reference id="recordmapper" title="RecordMapper callbacks"/>: You can use your own <reference class="org.jooq.RecordMapper"/> callbacks to map lazily fetched records.</li>
<li><reference id="pojos" title="POJOs"/>: You can fetch data into your own custom POJO types.</li>
</ul>
</html></content>
</section>
<section id="many-fetching">
<title>Many fetching</title>
<content><html>
<p>
Many databases support returning several result sets, or cursors, from single queries. An example for this is Sybase ASE's sp_help command:
</p>
</html><text><![CDATA[> sp_help 'author'
+--------+-----+-----------+-------------+-------------------+
|Name |Owner|Object_type|Object_status|Create_date |
+--------+-----+-----------+-------------+-------------------+
| author|dbo |user table | -- none -- |Sep 22 2011 11:20PM|
+--------+-----+-----------+-------------+-------------------+
+-------------+-------+------+----+-----+-----+
|Column_name |Type |Length|Prec|Scale|... |
+-------------+-------+------+----+-----+-----+
|id |int | 4|NULL| NULL| 0|
|first_name |varchar| 50|NULL| NULL| 1|
|last_name |varchar| 50|NULL| NULL| 0|
|date_of_birth|date | 4|NULL| NULL| 1|
|year_of_birth|int | 4|NULL| NULL| 1|
+-------------+-------+------+----+-----+-----+]]></text><html>
<p>
The correct (and verbose) way to do this with JDBC is as follows:
</p>
</html><java><![CDATA[ResultSet rs = statement.executeQuery();
// Repeat until there are no more result sets
for (;;) {
// Empty the current result set
while (rs.next()) {
// [ .. do something with it .. ]
}
// Get the next result set, if available
if (statement.getMoreResults()) {
rs = statement.getResultSet();
}
else {
break;
}
}
// Be sure that all result sets are closed
statement.getMoreResults(Statement.CLOSE_ALL_RESULTS);
statement.close();]]></java><html>
<p>
As previously discussed in the chapter about <reference id="comparison-with-jdbc" title="differences between jOOQ and JDBC"/>, jOOQ does not rely on an internal state of any JDBC object, which is "externalised" by Javadoc. Instead, it has a straight-forward API allowing you to do the above in a one-liner:
</p>
</html><java><![CDATA[// Get some information about the author table, its columns, keys, indexes, etc
List<Result<Record>> results = create.fetchMany("sp_help 'author'");]]></java><html>
<p>
Using generics, the resulting structure is immediately clear.
</p>
</html></content>
</section>
<section id="later-fetching">
<title>Later fetching</title>
<content><html>
<h3>Using Java 8 CompletableFutures</h3>
<p>
Java 8 has introduced the new <reference class="java.util.concurrent.CompletableFuture"/> type, which allows for functional composition of asynchronous execution units. When applying this to SQL and jOOQ, you might be writing code as follows:
</p>
</html><java><![CDATA[// Initiate an asynchronous call chain
CompletableFuture
// This lambda will supply an int value indicating the number of inserted rows
.supplyAsync(() ->
DSL.using(configuration)
.insertInto(AUTHOR, AUTHOR.ID, AUTHOR.LAST_NAME)
.values(3, "Hitchcock")
.execute()
)
// This will supply an AuthorRecord value for the newly inserted author
.handleAsync((rows, throwable) ->
DSL.using(configuration)
.fetchOne(AUTHOR, AUTHOR.ID.eq(3))
)
// This should supply an int value indicating the number of rows,
// but in fact it'll throw a constraint violation exception
.handleAsync((record, throwable) -> {
record.changed(true);
return record.insert();
})
// This will supply an int value indicating the number of deleted rows
.handleAsync((rows, throwable) ->
DSL.using(configuration)
.delete(AUTHOR)
.where(AUTHOR.ID.eq(3))
.execute()
)
.join();]]></java><html>
<p>
The above example will execute four actions one after the other, but asynchronously in the JDK's default or common <reference class="java.util.concurrent.ForkJoinPool"/>.
</p>
<p>
For more information, please refer to the <reference class="java.util.concurrent.CompletableFuture"/> Javadoc and official documentation.
</p>
<h3>Using deprecated API</h3>
<p>
Some queries take very long to execute, yet they are not crucial for the continuation of the main program. For instance, you could be generating a complicated report in a Swing application, and while this report is being calculated in your database, you want to display a background progress bar, allowing the user to pursue some other work. This can be achived simply with jOOQ, by creating a <reference class="org.jooq.FutureResult"/>, a type that extends <reference class="java.util.concurrent.Future"/>. An example is given here:
</p>
</html><java><![CDATA[// Spawn off this query in a separate process:
FutureResult<BookRecord> future = create.selectFrom(BOOK).where(... complex predicates ...).fetchLater();
// This example actively waits for the result to be done
while (!future.isDone()) {
progressBar.increment(1);
Thread.sleep(50);
}
// The result should be ready, now
Result<BookRecord> result = future.get();]]></java><html>
<p>
Note, that instead of letting jOOQ spawn a new thread, you can also provide jOOQ with your own <reference class="java.util.concurrent.ExecutorService"/>:
</p>
</html><java><![CDATA[// Spawn off this query in a separate process:
ExecutorService service = // [...]
FutureResult<BookRecord> future = create.selectFrom(BOOK).where(... complex predicates ...).fetchLater(service);]]></java>
</content>
</section>
<section id="resultset-fetching">
<title>ResultSet fetching</title>
<content><html>
<p>
When interacting with legacy applications, you may prefer to have jOOQ return a <reference class="java.sql.ResultSet"/>, rather than jOOQ's own <reference class="org.jooq.Result"/> types. This can be done simply, in two ways:
</p>
</html><java><![CDATA[// jOOQ's Cursor type exposes the underlying ResultSet:
ResultSet rs1 = create.selectFrom(BOOK).fetchLazy().resultSet();
// But you can also directly access that ResultSet from ResultQuery:
ResultSet rs2 = create.selectFrom(BOOK).fetchResultSet();
// Don't forget to close these, though!
rs1.close();
rs2.close();]]></java><html>
<h3>Transform jOOQ's Result into a JDBC ResultSet</h3>
<p>
Instead of operating on a JDBC ResultSet holding an open resource from your database, you can also let jOOQ's <reference class="org.jooq.Result"/> wrap itself in a <reference class="java.sql.ResultSet"/>. The advantage of this is that the so-created ResultSet has no open connection to the database. It is a completely in-memory ResultSet:
</p>
</html><java><![CDATA[// Transform a jOOQ Result into a ResultSet
Result<BookRecord> result = create.selectFrom(BOOK).fetch();
ResultSet rs = result.intoResultSet();]]></java><html>
<h3>The inverse: Fetch data from a legacy ResultSet using jOOQ</h3>
<p>
The inverse of the above is possible too. Maybe, a legacy part of your application produces JDBC <reference class="java.sql.ResultSet"/>, and you want to turn them into a <reference class="org.jooq.Result"/>:
</p>
</html><java><![CDATA[// Transform a JDBC ResultSet into a jOOQ Result
ResultSet rs = connection.createStatement().executeQuery("SELECT * FROM BOOK");
// As a Result:
Result<Record> result = create.fetch(rs);
// As a Cursor
Cursor<Record> cursor = create.fetchLazy(rs);]]></java><html>
<p>
You can also tighten the interaction with jOOQ's data type system and <reference id="data-type-conversion" title="data type conversion"/> features, by passing the record type to the above fetch methods:
</p>
</html><java><![CDATA[// Pass an array of types:
Result<Record> result = create.fetch (rs, Integer.class, String.class);
Cursor<Record> result = create.fetchLazy(rs, Integer.class, String.class);
// Pass an array of data types:
Result<Record> result = create.fetch (rs, SQLDataType.INTEGER, SQLDataType.VARCHAR);
Cursor<Record> result = create.fetchLazy(rs, SQLDataType.INTEGER, SQLDataType.VARCHAR);
// Pass an array of fields:
Result<Record> result = create.fetch (rs, BOOK.ID, BOOK.TITLE);
Cursor<Record> result = create.fetchLazy(rs, BOOK.ID, BOOK.TITLE);]]></java><html>
<p>
If supplied, the additional information is used to override the information obtained from the <reference class="java.sql.ResultSet" title="ResultSet"/>'s <reference class="java.sql.ResultSetMetaData"/> information.
</p>
</html></content>
</section>
<section id="data-type-conversion">
<title>Data type conversion</title>
<content><html>
<p>
Apart from a few extra features (<reference id="codegen-udts" title="user-defined types"/>), jOOQ only supports basic types as supported by the JDBC API. In your application, you may choose to transform these data types into your own ones, without writing too much boiler-plate code. This can be done using jOOQ's <reference class="org.jooq.Converter"/> types. A converter essentially allows for two-way conversion between two Java data types &lt;T&gt; and &lt;U&gt;. By convention, the &lt;T&gt; type corresponds to the type in your database whereas the &gt;U&gt; type corresponds to your own user type. The Converter API is given here:
</p>
</html><java><![CDATA[public interface Converter<T, U> extends Serializable {
/**
* Convert a database object to a user object
*/
U from(T databaseObject);
/**
* Convert a user object to a database object
*/
T to(U userObject);
/**
* The database type
*/
Class<T> fromType();
/**
* The user type
*/
Class<U> toType();
}]]></java><html>
<p>
Such a converter can be used in many parts of the jOOQ API. Some examples have been illustrated in the manual's section about <reference id="fetching" title="fetching"/>.
</p>
<h3>A Converter for GregorianCalendar</h3>
<p>
Here is a some more elaborate example involving a Converter for <reference class="java.util.GregorianCalendar"/>:
</p>
</html><java><![CDATA[// You may prefer Java Calendars over JDBC Timestamps
public class CalendarConverter implements Converter<Timestamp, GregorianCalendar> {
@Override
public GregorianCalendar from(Timestamp databaseObject) {
GregorianCalendar calendar = (GregorianCalendar) Calendar.getInstance();
calendar.setTimeInMillis(databaseObject.getTime());
return calendar;
}
@Override
public Timestamp to(GregorianCalendar userObject) {
return new Timestamp(userObject.getTime().getTime());
}
@Override
public Class<Timestamp> fromType() {
return Timestamp.class;
}
@Override
public Class<GregorianCalendar> toType() {
return GregorianCalendar.class;
}
}
// Now you can fetch calendar values from jOOQ's API:
List<GregorianCalendar> dates1 = create.selectFrom(BOOK).fetch().getValues(BOOK.PUBLISHING_DATE, new CalendarConverter());
List<GregorianCalendar> dates2 = create.selectFrom(BOOK).fetch(BOOK.PUBLISHING_DATE, new CalendarConverter());
]]></java><html>
<h3>Enum Converters</h3>
<p>
jOOQ ships with a built-in default <reference class="org.jooq.impl.EnumConverter"/>, that you can use to map VARCHAR values to enum literals or NUMBER values to enum ordinals (both modes are supported). Let's say, you want to map a YES / NO / MAYBE column to a custom Enum:
</p>
</html><java><![CDATA[// Define your Enum
public enum YNM {
YES, NO, MAYBE
}
// Define your converter
public class YNMConverter extends EnumConverter<String, YNM> {
public YNMConverter() {
super(String.class, YNM.class);
}
}
// And you're all set for converting records to your custom Enum:
for (BookRecord book : create.selectFrom(BOOK).fetch()) {
switch (book.getValue(BOOK.I_LIKE, new YNMConverter())) {
case YES: System.out.println("I like this book : " + book.getTitle()); break;
case NO: System.out.println("I didn't like this book : " + book.getTitle()); break;
case MAYBE: System.out.println("I'm not sure about this book : " + book.getTitle()); break;
}
}]]></java><html>
<h3>Using Converters in generated source code</h3>
<p>
jOOQ also allows for generated source code to reference your own custom converters, in order to permanently replace a <reference id="table-columns" title="table column's"/> &lt;T&gt; type by your own, custom &lt;U&gt; type. See the manual's section about <reference id="custom-data-types" title="custom data types"/> for details.
</p>
</html></content>
</section>
<section id="interning">
<title>Interning data</title>
<content><html>
<p>
SQL result tables are not optimal in terms of used memory as they are not designed to represent hierarchical data as produced by <code>JOIN</code> operations. Specifically, <code>FOREIGN KEY</code> values may repeat themselves unnecessarily:
</p>
</html><text>+----+-----------+--------------+
| ID | AUTHOR_ID | TITLE |
+----+-----------+--------------+
| 1 | 1 | 1984 |
| 2 | 1 | Animal Farm |
| 3 | 2 | O Alquimista |
| 4 | 2 | Brida |
+----+-----------+--------------+</text><html>
<p>
Now, if you have millions of records with only few distinct values for <code>AUTHOR_ID</code>, you may not want to hold references to distinct (but equal) <reference class="java.lang.Integer"/> objects. This is specifically true for IDs of type <reference class="java.util.UUID"/> or string representations thereof. jOOQ allows you to "intern" those values:
</p>
</html><java><![CDATA[// Interning data after fetching
Result<?> r1 = create.select(BOOK.ID, BOOK.AUTHOR_ID, BOOK.TITLE)
.from(BOOK)
.join(AUTHOR).on(BOOK.AUTHOR_ID.eq(AUTHOR.ID))
.fetch()
.intern(BOOK.AUTHOR_ID);
// Interning data while fetching
Result<?> r1 = create.select(BOOK.ID, BOOK.AUTHOR_ID, BOOK.TITLE)
.from(BOOK)
.join(AUTHOR).on(BOOK.AUTHOR_ID.eq(AUTHOR.ID))
.intern(BOOK.AUTHOR_ID)
.fetch();]]></java><html>
<p>
You can specify as many fields as you want for interning. The above has the following effect:
</p>
<ul>
<li>If the interned Field is of type <reference class="java.lang.String"/>, then <reference class="java.lang.String" anchor="#intern()" title="String.intern()"/> is called upon each string</li>
<li>If the interned Field is of any other type, then the call is ignored</li>
</ul>
<p>
Future versions of jOOQ will implement interning of data for non-String data types by collecting values in <reference class="java.util.Set"/>, removing duplicate instances.
</p>
<p>
Note, that jOOQ will not use interned data for identity comparisons: <code>string1 == string2</code>. Interning is used only to reduce the memory footprint of <reference class="org.jooq.Result"/> objects.
</p>
</html></content>
</section>
</sections>
</section>
<section id="statement-type">
<title>Static statements vs. Prepared Statements</title>
<content><html>
<p>
With JDBC, you have full control over your SQL statements. You can decide yourself, if you want to execute a static <reference class="java.sql.Statement"/> without bind values, or a <reference class="java.sql.PreparedStatement"/> with (or without) bind values. But you have to decide early, which way to go. And you'll have to prevent SQL injection and syntax errors manually, when inlining your bind variables.
</p>
<p>
With jOOQ, this is easier. As a matter of fact, it is plain simple. With jOOQ, you can just set a flag in your <reference id="dsl-context" title="Configuration's"/> <reference id="custom-settings" title="Settings"/>, and all queries produced by that configuration will be executed as static statements, with all bind values inlined. An example is given here:
</p>
</html><code-pair>
<sql><![CDATA[
-- These statements are rendered by the two factories:
SELECT ? FROM DUAL WHERE ? = ?
SELECT 1 FROM DUAL WHERE 1 = 1]]></sql>
<java><![CDATA[// This DSLContext executes PreparedStatements
DSLContext prepare = DSL.using(connection, SQLDialect.ORACLE);
// This DSLContext executes static Statements
DSLContext inlined = DSL.using(connection, SQLDialect.ORACLE,
new Settings().withStatementType(StatementType.STATIC_STATEMENT));
prepare.select(val(1)).where(val(1).equal(1)).fetch();
inlined.select(val(1)).where(val(1).equal(1)).fetch();]]></java>
</code-pair><html>
<h3>Reasons for choosing one or the other</h3>
<p>
Not all databases are equal. Some databases show improved performance if you use <reference class="java.sql.PreparedStatement"/>, as the database will then be able to re-use execution plans for identical SQL statements, regardless of actual bind values. This heavily improves the time it takes for soft-parsing a SQL statement. In other situations, assuming that bind values are irrelevant for SQL execution plans may be a bad idea, as you might run into "bind value peeking" issues. You may be better off spending the extra cost for a new hard-parse of your SQL statement and instead having the database fine-tune the new plan to the concrete bind values.
</p>
<p>
Whichever aproach is more optimal for you cannot be decided by jOOQ. In most cases, prepared statements are probably better. But you always have the option of forcing jOOQ to render inlined bind values.
</p>
<h3>Inlining bind values on a per-bind-value basis</h3>
<p>
Note that you don't have to inline all your bind values at once. If you know that a bind value is not really a variable and should be inlined explicitly, you can do so by using <reference class="org.jooq.impl.DSL" anchor="#inline(Object)" title="DSL.inline()"/>, as documented in the manual's section about <reference id="inlined-parameters" title="inlined parameters"/>
</p>
</html></content>
</section>
<section id="reusing-statements">
<title>Reusing a Query's PreparedStatement</title>
<content><html>
<p>
As previously discussed in the chapter about <reference id="comparison-with-jdbc" title="differences between jOOQ and JDBC"/>, reusing PreparedStatements is handled a bit differently in jOOQ from how it is handled in JDBC
</p>
<h3>Keeping open PreparedStatements with JDBC</h3>
<p>
With JDBC, you can easily reuse a <reference class="java.sql.PreparedStatement"/> by not closing it between subsequent executions. An example is given here:
</p>
</html><java><![CDATA[// Execute the statement
try (PreparedStatement stmt = connection.prepareStatement("SELECT 1 FROM DUAL")) {
// Fetch a first ResultSet
try (ResultSet rs1 = stmt.executeQuery()) { ... }
// Without closing the statement, execute it again to fetch another ResultSet
try (ResultSet rs2 = stmt.executeQuery()) { ... }
}]]></java><html>
<p>
The above technique can be quite useful when you want to reuse expensive database resources. This can be the case when your statement is executed very frequently and your database would take non-negligible time to soft-parse the prepared statement and generate a new statement / cursor resource.
</p>
<h3>Keeping open PreparedStatements with jOOQ</h3>
<p>
This is also modeled in jOOQ. However, the difference to JDBC is that closing a statement is the default action, whereas keeping it open has to be configured explicitly. This is better than JDBC, because the default action should be the one that is used most often. Keeping open statements is rarely done in average applications. Here's an example of how to keep open PreparedStatements with jOOQ:
</p>
</html><java><![CDATA[// Create a query which is configured to keep its underlying PreparedStatement open
ResultQuery<Record> query = create.selectOne().keepStatement(true);
// Execute the query twice, against the same underlying PreparedStatement:
try {
Result<Record> result1 = query.fetch(); // This will lazily create a new PreparedStatement
Result<Record> result2 = query.fetch(); // This will reuse the previous PreparedStatement
}
// ... but now, you must not forget to close the query
finally {
query.close();
}]]></java><html>
<p>
The above example shows how a query can be executed twice against the same underlying PreparedStatement. Unlike in other execution scenarios, you must not forget to close this query now
</p>
<h3>Beware of resource leaks</h3>
<p>
While jOOQ allows for explicitly keeping open <code>PreparedStatement</code> references in <code>Query</code> instances, the JDBC <code>Connection</code> may still be closed independently without jOOQ or the <code>PreparedStatement</code> noticing. It is the user's responsibility to close all resources according to the specification and behaviour of the concrete JDBC driver and the underlying database.
</p>
</html></content>
</section>
<section id="jdbc-flags">
<title>JDBC flags</title>
<content><html>
<p>
JDBC knows a couple of execution flags and modes, which can be set through the jOOQ API as well. jOOQ essentially supports these flags and execution modes:
</p>
</html><java><![CDATA[public interface Query extends QueryPart, Attachable {
// [...]
// The query execution timeout.
// -----------------------------------------------------------
Query queryTimeout(int timeout);
}]]></java>
<java><![CDATA[public interface ResultQuery<R extends Record> extends Query {
// [...]
// The query execution timeout.
// -----------------------------------------------------------
@Override
ResultQuery<R> queryTimeout(int timeout);
// Flags allowing to specify the resulting ResultSet modes
// -----------------------------------------------------------
ResultQuery<R> resultSetConcurrency(int resultSetConcurrency);
ResultQuery<R> resultSetType(int resultSetType);
ResultQuery<R> resultSetHoldability(int resultSetHoldability);
// The maximum number of rows to be fetched by JDBC
// -----------------------------------------------------------
ResultQuery<R> maxRows(int rows);
}]]></java><html>
<h3>Using ResultSet concurrency with ExecuteListeners</h3>
<p>
An example of why you might want to manually set a ResultSet's concurrency flag to something non-default is given here:
</p>
</html><java><![CDATA[
DSL.using(new DefaultConfiguration()
.set(connection)
.set(SQLDialect.ORACLE)
.set(DefaultExecuteListenerProvider.providers(
new DefaultExecuteListener() {
@Override
public void recordStart(ExecuteContext ctx) {
try {
// Change values in the cursor before reading a record
ctx.resultSet().updateString(BOOK.TITLE.getName(), "New Title");
ctx.resultSet().updateRow();
}
catch (SQLException e) {
throw new DataAccessException("Exception", e);
}
}
}
)
))
.select(BOOK.ID, BOOK.TITLE)
.from(BOOK)
.orderBy(BOOK.ID)
.resultSetType(ResultSet.TYPE_SCROLL_INSENSITIVE)
.resultSetConcurrency(ResultSet.CONCUR_UPDATABLE)
.fetch(BOOK.TITLE);]]></java><html>
<p>
In the above example, your custom <reference id="execute-listeners" title="ExecuteListener callback"/> is triggered before jOOQ loads a new <code>Record</code> from the JDBC <code>ResultSet</code>. With the concurrency being set to <code>ResultSet.CONCUR_UPDATABLE</code>, you can now modify the database cursor through the standard JDBC <code>ResultSet</code> API.
</p>
</html></content>
</section>
<section id="batch-execution">
<title>Using JDBC batch operations</title>
<content><html>
<p>
With JDBC, you can easily execute several statements at once using the addBatch() method. Essentially, there are two modes in JDBC
</p>
<ul>
<li>Execute several queries without bind values</li>
<li>Execute one query several times with bind values</li>
</ul>
<h3>Using JDBC</h3>
<p>
In code, this looks like the following snippet:
</p>
</html><java><![CDATA[// 1. several queries
// ------------------
try (Statement stmt = connection.createStatement()) {
stmt.addBatch("INSERT INTO author(id, first_name, last_name) VALUES (1, 'Erich', 'Gamma')");
stmt.addBatch("INSERT INTO author(id, first_name, last_name) VALUES (2, 'Richard', 'Helm')");
stmt.addBatch("INSERT INTO author(id, first_name, last_name) VALUES (3, 'Ralph', 'Johnson')");
stmt.addBatch("INSERT INTO author(id, first_name, last_name) VALUES (4, 'John', 'Vlissides')");
int[] result = stmt.executeBatch();
}
// 2. a single query
// -----------------
try (PreparedStatement stmt = connection.prepareStatement("INSERT INTO author(id, first_name, last_name) VALUES (?, ?, ?)")) {
stmt.setInt(1, 1);
stmt.setString(2, "Erich");
stmt.setString(3, "Gamma");
stmt.addBatch();
stmt.setInt(1, 2);
stmt.setString(2, "Richard");
stmt.setString(3, "Helm");
stmt.addBatch();
stmt.setInt(1, 3);
stmt.setString(2, "Ralph");
stmt.setString(3, "Johnson");
stmt.addBatch();
stmt.setInt(1, 4);
stmt.setString(2, "John");
stmt.setString(3, "Vlissides");
stmt.addBatch();
int[] result = stmt.executeBatch();
}]]></java><html>
<h3>Using jOOQ</h3>
<p>
jOOQ supports executing queries in batch mode as follows:
</p>
</html><java><![CDATA[// 1. several queries
// ------------------
create.batch(
create.insertInto(AUTHOR, ID, FIRST_NAME, LAST_NAME).values(1, "Erich" , "Gamma" ),
create.insertInto(AUTHOR, ID, FIRST_NAME, LAST_NAME).values(2, "Richard", "Helm" ),
create.insertInto(AUTHOR, ID, FIRST_NAME, LAST_NAME).values(3, "Ralph" , "Johnson" ),
create.insertInto(AUTHOR, ID, FIRST_NAME, LAST_NAME).values(4, "John" , "Vlissides"))
.execute();
// 2. a single query
// -----------------
create.batch(create.insertInto(AUTHOR, ID, FIRST_NAME, LAST_NAME ).values((Integer) null, null, null))
.bind( 1 , "Erich" , "Gamma" )
.bind( 2 , "Richard" , "Helm" )
.bind( 3 , "Ralph" , "Johnson" )
.bind( 4 , "John" , "Vlissides")
.execute();]]></java><html>
<p>
When creating a batch execution with a single query and multiple bind values, you will still have to provide jOOQ with dummy bind values for the original query. In the above example, these are set to <code>null</code>. For subsequent calls to <code>bind()</code>, there will be no type safety provided by jOOQ.
</p>
</html></content>
</section>
<section id="sequence-execution">
<title>Sequence execution</title>
<content><html>
<p>
Most databases support sequences of some sort, to provide you with unique values to be used for primary keys and other enumerations. If you're using jOOQ's <reference id="code-generation" title="code generator"/>, it will generate a sequence object per sequence for you. There are two ways of using such a sequence object:
</p>
<h3>Standalone calls to sequences</h3>
<p>
Instead of actually phrasing a select statement, you can also use the <reference id="dsl-context" title="DSLContext's"/> convenience methods:
</p>
</html><java><![CDATA[// Fetch the next value from a sequence
BigInteger nextID = create.nextval(S_AUTHOR_ID);
// Fetch the current value from a sequence
BigInteger currID = create.currval(S_AUTHOR_ID);]]></java><html>
<h3>Inlining sequence references in SQL</h3>
<p>
You can inline sequence references in jOOQ SQL statements. The following are examples of how to do that:
</p>
</html><java><![CDATA[// Reference the sequence in a SELECT statement:
BigInteger nextID = create.select(s).fetchOne(S_AUTHOR_ID.nextval());
// Reference the sequence in an INSERT statement:
create.insertInto(AUTHOR, AUTHOR.ID, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME)
.values(S_AUTHOR_ID.nextval(), val("William"), val("Shakespeare"))
.execute();
]]></java><html>
<p>
For more info about inlining sequence references in SQL statements, please refer to the manual's section about <reference id="sequences-and-serials" title="sequences and serials"/>.
</p>
</html></content>
</section>
<section id="stored-procedures">
<title>Stored procedures and functions</title>
<content><html>
<p>
Many RDBMS support the concept of "routines", usually calling them procedures and/or functions. These concepts have been around in programming languages for a while, also outside of databases. Famous languages distinguishing procedures from functions are:
</p>
<ul>
<li>Ada</li>
<li>BASIC</li>
<li>Pascal</li>
<li>etc...</li>
</ul>
<p>
The general distinction between (stored) procedures and (stored) functions can be summarised like this:
</p>
<h3>Procedures</h3>
<ul>
<li>Are called using JDBC CallableStatement</li>
<li>Have no return value</li>
<li>Usually support OUT parameters</li>
</ul>
<h3>Functions</h3>
<ul>
<li>Can be used in SQL statements</li>
<li>Have a return value</li>
<li>Usually don't support OUT parameters</li>
</ul>
<h3>Exceptions to these rules</h3>
<ul>
<li>DB2, H2, and HSQLDB don't allow for JDBC escape syntax when calling functions. Functions must be used in a SELECT statement</li>
<li>H2 only knows functions (without OUT parameters)</li>
<li>Oracle functions may have OUT parameters</li>
<li>Oracle knows functions that must not be used in SQL statements for transactional reasons</li>
<li>Postgres only knows functions (with all features combined). OUT parameters can also be interpreted as return values, which is quite elegant/surprising, depending on your taste</li>
<li>The Sybase jconn3 JDBC driver doesn't handle null values correctly when using the JDBC escape syntax on functions</li>
</ul>
<p>
In general, it can be said that the field of routines (procedures / functions) is far from being standardised in modern RDBMS even if the SQL:2008 standard specifies things quite well. Every database has its ways and JDBC only provides little abstraction over the great variety of procedures / functions implementations, especially when advanced data types such as cursors / UDT's / arrays are involved.
</p>
<p>
To simplify things a little bit, jOOQ handles both procedures and functions the same way, using a more general <reference class="org.jooq.Routine"/> type.
</p>
<h3>Using jOOQ for standalone calls to stored procedures and functions</h3>
<p>
If you're using jOOQ's <reference id="code-generation" title="code generator"/>, it will generate <reference class="org.jooq.Routine"/> objects for you. Let's consider the following example:
</p>
</html><sql><![CDATA[-- Check whether there is an author in AUTHOR by that name and get his ID
CREATE OR REPLACE PROCEDURE author_exists (author_name VARCHAR2, result OUT NUMBER, id OUT NUMBER);]]></sql><html>
<p>
The generated artefacts can then be used as follows:
</p>
</html><java><![CDATA[// Make an explicit call to the generated procedure object:
AuthorExists procedure = new AuthorExists();
// All IN and IN OUT parameters generate setters
procedure.setAuthorName("Paulo");
procedure.execute(configuration);
// All OUT and IN OUT parameters generate getters
assertEquals(new BigDecimal("1"), procedure.getResult());
assertEquals(new BigDecimal("2"), procedure.getId();]]></java><html>
<p>
But you can also call the procedure using a generated convenience method in a global Routines class:
</p>
</html><java><![CDATA[// The generated Routines class contains static methods for every procedure.
// Results are also returned in a generated object, holding getters for every OUT or IN OUT parameter.
AuthorExists result = Routines.authorExists(configuration, "Paulo");
// All OUT and IN OUT parameters generate getters
assertEquals(new BigDecimal("1"), procedure.getResult());
assertEquals(new BigDecimal("2"), procedure.getId();]]></java><html>
<p>
For more details about <reference id="code-generation" title="code generation"/> for procedures, see the manual's section about <reference id="codegen-procedures" title="procedures and code generation"/>.
</p>
<h3>Inlining stored function references in SQL</h3>
<p>
Unlike procedures, functions can be inlined in SQL statements to generate <reference id="column-expressions" title="column expressions"/> or <reference id="table-expressions" title="table expressions"/>, if you're using <reference id="array-and-cursor-unnesting" title="unnesting operators"/>. Assume you have a function like this:
</p>
</html><sql><![CDATA[-- Check whether there is an author in AUTHOR by that name and get his ID
CREATE OR REPLACE FUNCTION author_exists (author_name VARCHAR2) RETURN NUMBER;]]></sql><html>
<p>
The generated artefacts can then be used as follows:
</p>
</html><code-pair>
<sql><![CDATA[-- This is the rendered SQL
SELECT AUTHOR_EXISTS('Paulo') FROM DUAL]]></sql>
<java><![CDATA[// Use the static-imported method from Routines:
boolean exists =
create.select(authorExists("Paulo")).fetchOne(0, boolean.class);]]></java>
</code-pair><html>
<p>
For more info about inlining stored function references in SQL statements, please refer to the manual's section about <reference id="user-defined-functions" title="user-defined functions"/>.
</p>
</html></content>
<sections>
<section id="oracle-packages">
<title>Oracle Packages</title>
<content><html>
<p>
Oracle uses the concept of a PACKAGE to group several procedures/functions into a sort of namespace. The <a href="http://www.contrib.andrew.cmu.edu/~shadow/sql/sql1992.txt" title="SQL 92 standard">SQL 92 standard</a> talks about "modules", to represent this concept, even if this is rarely implemented as such. This is reflected in jOOQ by the use of Java sub-packages in the <reference id="code-generation" title="source code generation"/> destination package. Every Oracle package will be reflected by
</p>
<ul>
<li>A Java package holding classes for formal Java representations of the procedure/function in that package</li>
<li>A Java class holding convenience methods to facilitate calling those procedures/functions</li>
</ul>
<p>
Apart from this, the generated source code looks exactly like the one for standalone procedures/functions.
</p>
<p>
For more details about <reference id="code-generation" title="code generation"/> for procedures and packages see the manual's section about <reference id="codegen-procedures" title="procedures and code generation"/>.
</p>
</html></content>
</section>
<section id="oracle-member-procedures">
<title>Oracle member procedures</title>
<content><html>
<p>
Oracle UDTs can have object-oriented structures including member functions and procedures. With Oracle, you can do things like this:
</p>
</html><sql><![CDATA[CREATE OR REPLACE TYPE u_author_type AS OBJECT (
id NUMBER(7),
first_name VARCHAR2(50),
last_name VARCHAR2(50),
MEMBER PROCEDURE LOAD,
MEMBER FUNCTION counBOOKs RETURN NUMBER
)
-- The type body is omitted for the example]]></sql><html>
<p>
These member functions and procedures can simply be mapped to Java methods:
</p>
</html><java><![CDATA[// Create an empty, attached UDT record from the DSLContext
UAuthorType author = create.newRecord(U_AUTHOR_TYPE);
// Set the author ID and load the record using the LOAD procedure
author.setId(1);
author.load();
// The record is now updated with the LOAD implementation's content
assertNotNull(author.getFirstName());
assertNotNull(author.getLastName());]]></java><html>
<p>
For more details about <reference id="code-generation" title="code generation"/> for UDTs see the manual's section about <reference id="codegen-udts" title="user-defined types and code generation"/>.
</p>
</html></content>
</section>
</sections>
</section>
<section id="exporting">
<title>Exporting to XML, CSV, JSON, HTML, Text</title>
<content><html>
<p>
If you are using jOOQ for scripting purposes or in a slim, unlayered application server, you might be interested in using jOOQ's exporting functionality (see also the <reference id="importing" title="importing functionality"/>). You can export any Result&lt;Record&gt; into the formats discussed in the subsequent chapters of the manual
</p>
</html></content>
<sections>
<section id="exporting-xml">
<title>Exporting XML</title>
<content>
<java>// Fetch books and format them as XML
String xml = create.selectFrom(BOOK).fetch().formatXML();</java><html>
<p>
The above query will result in an XML document looking like the following one:
</p>
</html><xml><![CDATA[<result xmlns="http://www.jooq.org/xsd/jooq-export-{export-xsd-version}.xsd">
<fields>
<field name="ID" type="INTEGER"/>
<field name="AUTHOR_ID" type="INTEGER"/>
<field name="TITLE" type="VARCHAR"/>
</fields>
<records>
<record>
<value field="ID">1</value>
<value field="AUTHOR_ID">1</value>
<value field="TITLE">1984</value>
</record>
<record>
<value field="ID">2</value>
<value field="AUTHOR_ID">1</value>
<value field="TITLE">Animal Farm</value>
</record>
</records>
</result>]]></xml><html>
<p>
The same result as an <reference class="org.w3c.dom.Document"/> can be obtained using the Result.intoXML() method:
</p>
</html><java>// Fetch books and format them as XML
Document xml = create.selectFrom(BOOK).fetch().intoXML();</java><html>
<p>
See the XSD schema definition here, for a formal definition of the XML export format:<br/>
<a href="http://www.jooq.org/xsd/jooq-export-{export-xsd-version}.xsd">http://www.jooq.org/xsd/jooq-export-{export-xsd-version}.xsd</a>
</p>
</html></content>
</section>
<section id="exporting-csv">
<title>Exporting CSV</title>
<content>
<java>// Fetch books and format them as CSV
String csv = create.selectFrom(BOOK).fetch().formatCSV();</java><html>
<p>
The above query will result in a CSV document looking like the following one:
</p>
</html><text>ID,AUTHOR_ID,TITLE
1,1,1984
2,1,Animal Farm</text><html>
<p>
In addition to the standard behaviour, you can also specify a separator character, as well as a special string to represent NULL values (which cannot be represented in standard CSV):
</p>
</html><java>// Use ";" as the separator character
String csv = create.selectFrom(BOOK).fetch().formatCSV(';');
// Specify "{null}" as a representation for NULL values
String csv = create.selectFrom(BOOK).fetch().formatCSV(';', "{null}");</java>
</content>
</section>
<section id="exporting-json">
<title>Exporting JSON</title>
<content>
<java>// Fetch books and format them as JSON
String json = create.selectFrom(BOOK).fetch().formatJSON();</java><html>
<p>
The above query will result in a JSON document looking like the following one:
</p>
</html><text>{"fields":[{"name":"field-1","type":"type-1"},
{"name":"field-2","type":"type-2"},
...,
{"name":"field-n","type":"type-n"}],
"records":[[value-1-1,value-1-2,...,value-1-n],
[value-2-1,value-2-2,...,value-2-n]]}</text><html>
<p>
Note: This format has changed in jOOQ 2.6.0
</p>
</html></content>
</section>
<section id="exporting-html">
<title>Exporting HTML</title>
<content>
<java>// Fetch books and format them as HTML
String html = create.selectFrom(BOOK).fetch().formatHTML();</java><html>
<p>
The above query will result in an HTML document looking like the following one
</p>
</html><xml><![CDATA[<table>
<thead>
<tr>
<th>ID</th>
<th>AUTHOR_ID</th>
<th>TITLE</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>1</td>
<td>1984</td>
</tr>
<tr>
<td>2</td>
<td>1</td>
<td>Animal Farm</td>
</tr>
</tbody>
</table>]]></xml>
</content>
</section>
<section id="exporting-text">
<title>Exporting Text</title>
<content>
<java>// Fetch books and format them as text
String text = create.selectFrom(BOOK).fetch().format();</java><html>
<p>
The above query will result in a text document looking like the following one
</p>
</html><text>+---+---------+-----------+
| ID|AUTHOR_ID|TITLE |
+---+---------+-----------+
| 1| 1|1984 |
| 2| 1|Animal Farm|
+---+---------+-----------+</text><html>
<p>
A simple text representation can also be obtained by calling toString() on a Result object. See also the manual's section about <reference id="logging" title="DEBUG logging"/>
</p>
</html></content>
</section>
</sections>
</section>
<section id="importing">
<title>Importing data</title>
<content><html>
<p>
If you are using jOOQ for scripting purposes or in a slim, unlayered application server, you might be interested in using jOOQ's importing functionality (see also exporting functionality). You can import data directly into a table from the formats described in the subsequent sections of this manual.
</p>
</html></content>
<sections>
<section id="importing-csv">
<title>Importing CSV</title>
<content><html>
<p>
The below CSV data represents two author records that may have been exported previously, by jOOQ's <reference id="exporting" title="exporting functionality"/>, and then modified in Microsoft Excel or any other spreadsheet tool:
</p>
</html><text><![CDATA[ID,AUTHOR_ID,TITLE <-- Note the CSV header. By default, the first line is ignored
1,1,1984
2,1,Animal Farm]]></text><html>
<p>
With jOOQ, you can load this data using various parameters from the loader API. A simple load may look like this:
</p>
</html><java>DSLContext create = DSL.using(connection, dialect);
// Load data into the AUTHOR table from an input stream
// holding the CSV data.
create.loadInto(AUTHOR)
.loadCSV(inputstream, encoding)
.fields(ID, AUTHOR_ID, TITLE)
.execute();</java><html>
<p>
Here are various other examples:
</p>
</html><java>// Ignore the AUTHOR_ID column from the CSV file when inserting
create.loadInto(AUTHOR)
.loadCSV(inputstream, encoding)
.fields(ID, null, TITLE)
.execute();
// Specify behaviour for duplicate records.
create.loadInto(AUTHOR)
// choose any of these methods
.onDuplicateKeyUpdate()
.onDuplicateKeyIgnore()
.onDuplicateKeyError() // the default
.loadCSV(inputstream)
.fields(ID, null, TITLE)
.execute();
// Specify behaviour when errors occur.
create.loadInto(AUTHOR)
// choose any of these methods
.onErrorIgnore()
.onErrorAbort() // the default
.loadCSV(inputstream, encoding)
.fields(ID, null, TITLE)
.execute();
// Specify transactional behaviour where this is possible
// (e.g. not in container-managed transactions)
create.loadInto(AUTHOR)
// choose any of these methods
.commitEach()
.commitAfter(10)
.commitAll()
.commitNone() // the default
.loadCSV(inputstream, encoding)
.fields(ID, null, TITLE)
.execute();</java><html>
<p>
Any of the above configuration methods can be combined to achieve the type of load you need. Please refer to the API's Javadoc to learn about more details. Errors that occur during the load are reported by the execute method's result:
</p>
</html><java><![CDATA[Loader<Author> loader = /* .. */ .execute();
// The number of processed rows
int processed = loader.processed();
// The number of stored rows (INSERT or UPDATE)
int stored = loader.stored();
// The number of ignored rows (due to errors, or duplicate rule)
int ignored = loader.ignored();
// The errors that may have occurred during loading
List<LoaderError> errors = loader.errors();
LoaderError error = errors.get(0);
// The exception that caused the error
DataAccessException exception = error.exception();
// The row that caused the error
int rowIndex = error.rowIndex();
String[] row = error.row();
// The query that caused the error
Query query = error.query();]]></java>
</content>
</section>
<section id="importing-xml">
<title>Importing XML</title>
<content><html>
<p>This is not yet supported</p>
</html></content>
</section>
</sections>
</section>
<section id="crud-with-updatablerecords">
<title>CRUD with UpdatableRecords</title>
<content><html>
<p>
Your database application probably consists of 50% - 80% CRUD, whereas only the remaining 20% - 50% of querying is actual querying. Most often, you will operate on records of tables without using any advanced relational concepts. This is called CRUD for
</p>
<ul>
<li>Create (<reference id="insert-statement" title="INSERT"/>)</li>
<li>Read (<reference id="select-statement" title="SELECT"/>)</li>
<li>Update (<reference id="update-statement" title="UPDATE"/>)</li>
<li>Delete (<reference id="delete-statement" title="DELETE"/>)</li>
</ul>
<p>
CRUD always uses the same patterns, regardless of the nature of underlying tables. This again, leads to a lot of boilerplate code, if you have to issue your statements yourself. Like Hibernate / JPA and other ORMs, jOOQ facilitates CRUD using a specific API involving <reference class="org.jooq.UpdatableRecord"/> types.
</p>
<h3>Primary keys and updatability</h3>
<p>
In normalised databases, every table has a primary key by which a tuple/record within that table can be uniquely identified. In simple cases, this is a (possibly auto-generated) number called ID. But in many cases, primary keys include several non-numeric columns. An important feature of such keys is the fact that in most databases, they are enforced using an index that allows for very fast random access to the table. A typical way to access / modify / delete a book is this:
</p>
</html><sql><![CDATA[-- Inserting uses a previously generated key value or generates it afresh
INSERT INTO BOOK (ID, TITLE) VALUES (5, 'Animal Farm');
-- Other operations can use a previously generated key value
SELECT * FROM BOOK WHERE ID = 5;
UPDATE BOOK SET TITLE = '1984' WHERE ID = 5;
DELETE FROM BOOK WHERE ID = 5;]]></sql><html>
<p>
Normalised databases assume that a primary key is unique "forever", i.e. that a key, once inserted into a table, will never be changed or re-inserted after deletion. In order to use jOOQ's <reference id="simple-crud" title="CRUD"/> operations correctly, you should design your database accordingly.
</p>
</html></content>
<sections>
<section id="simple-crud">
<title>Simple CRUD</title>
<content><html>
<p>
If you're using jOOQ's <reference id="code-generation" title="code generator"/>, it will generate <reference class="org.jooq.UpdatableRecord"/> implementations for every table that has a primary key. When <reference id="fetching" title="fetching"/> such a record form the database, these records are "attached" to the <reference id="dsl-context" title="Configuration" /> that created them. This means that they hold an internal reference to the same database connection that was used to fetch them. This connection is used internally by any of the following methods of the UpdatableRecord:
</p>
</html><java><![CDATA[// Refresh a record from the database.
void refresh() throws DataAccessException;
// Store (insert or update) a record to the database.
int store() throws DataAccessException;
// Delete a record from the database
int delete() throws DataAccessException;]]></java><html>
<p>
See the manual's section about <reference id="serializability" title="serializability"/> for some more insight on "attached" objects.
</p>
<h3>Storing</h3>
<p>
Storing a record will perform an <reference id="insert-statement" title="INSERT statement"/> or an <reference id="update-statement" title="UPDATE statement"/>. In general, new records are always inserted, whereas records loaded from the database are always updated. This is best visualised in code:
</p>
</html><java><![CDATA[// Create a new record
BookRecord book1 = create.newRecord(BOOK);
// Insert the record: INSERT INTO BOOK (TITLE) VALUES ('1984');
book1.setTitle("1984");
book1.store();
// Update the record: UPDATE BOOK SET PUBLISHED_IN = 1984 WHERE ID = [id]
book1.setPublishedIn(1948);
book1.store();
// Get the (possibly) auto-generated ID from the record
Integer id = book1.getId();
// Get another instance of the same book
BookRecord book2 = create.fetchOne(BOOK, BOOK.ID.equal(id));
// Update the record: UPDATE BOOK SET TITLE = 'Animal Farm' WHERE ID = [id]
book2.setTitle("Animal Farm");
book2.store();]]></java><html>
<p>
Some remarks about storing:
</p>
<ul>
<li>jOOQ sets only modified values in <reference id="insert-statement" title="INSERT statements"/> or <reference id="update-statement" title="UPDATE statements"/>. This allows for default values to be applied to inserted records, as specified in CREATE TABLE DDL statements.</li>
<li>When store() performs an <reference id="insert-statement" title="INSERT statement"/>, jOOQ attempts to load any generated keys from the database back into the record. For more details, see the manual's section about <reference id="identity-values" title="IDENTITY values"/>.</li>
<li>When loading records from <reference id="pojos" title="POJOs"/>, jOOQ will assume the record is a new record. It will hence attempt to INSERT it.</li>
<li>When you activate <reference id="optimistic-locking" title="optimistic locking"/>, storing a record may fail, if the underlying database record has been changed in the mean time.</li>
</ul>
<h3>Deleting</h3>
<p>
Deleting a record will remove it from the database. Here's how you delete records:
</p>
</html><java><![CDATA[// Get a previously inserted book
BookRecord book = create.fetchOne(BOOK, BOOK.ID.equal(5));
// Delete the book
book.delete();]]></java><html>
<h3>Refreshing</h3>
<p>
Refreshing a record from the database means that jOOQ will issue a <reference id="select-statement" title="SELECT statement"/> to refresh all record values that are not the primary key. This is particularly useful when you use jOOQ's <reference id="optimistic-locking" title="optimistic locking"/> feature, in case a modified record is "stale" and cannot be stored to the database, because the underlying database record has changed in the mean time.
</p>
<p>
In order to perform a refresh, use the following Java code:
</p>
</html><java><![CDATA[// Fetch an updatable record from the database
BookRecord book = create.fetchOne(BOOK, BOOK.ID.equal(5));
// Refresh the record
book.refresh();]]></java><html>
<h3>CRUD and SELECT statements</h3>
<p>
CRUD operations can be combined with regular querying, if you select records from single database tables, as explained in the manual's section about <reference id="select-statement" title="SELECT statements"/>. For this, you will need to use the <code>selectFrom()</code> method from the <reference id="dsl-context" title="DSLContext"/>:
</p>
</html><java><![CDATA[// Loop over records returned from a SELECT statement
for (BookRecord book : create.fetch(BOOK, BOOK.PUBLISHED_IN.equal(1948))) {
// Perform actions on BookRecords depending on some conditions
if ("Orwell".equals(book.fetchParent(Keys.FK_BOOK_AUTHOR).getLastName())) {
book.delete();
}
}]]></java>
</content>
</section>
<section id="internal-flags">
<title>Records' internal flags</title>
<content><html>
<p>
All of jOOQ's <reference id="record-vs-tablerecord" title="Record types and subtypes"/> maintain an internal state for every column value. This state is composed of three elements:
</p>
<ul>
<li>The value itself</li>
<li>The "original" value, i.e. the value as it was originally fetched from the database or <code>null</code>, if the record was never in the database</li>
<li>The "changed" flag, indicating if the value was ever changed through the <code>Record</code> API.</li>
</ul>
<p>
The purpose of the above information is for jOOQ's <reference id="simple-crud" title="CRUD operations"/> to know, which values need to be stored to the database, and which values have been left untouched.
</p>
</html></content>
</section>
<section id="identity-values">
<title>IDENTITY values</title>
<content><html>
<p>
Many databases support the concept of IDENTITY values, or <reference id="sequence-execution" title="SEQUENCE-generated"/> key values. This is reflected by JDBC's <reference class="java.sql.Statement" anchor="#getGeneratedKeys()" title="getGeneratedKeys()"/> method. jOOQ abstracts using this method as many databases and JDBC drivers behave differently with respect to generated keys. Let's assume the following SQL Server BOOK table:
</p>
</html><sql><![CDATA[CREATE TABLE book (
ID INTEGER IDENTITY(1,1) NOT NULL,
-- [...]
CONSTRAINT pk_book PRIMARY KEY (id)
)]]></sql><html>
<p>
If you're using jOOQ's <reference id="code-generation" title="code generator"/>, the above table will generate a <reference class="org.jooq.UpdatableRecord"/> with an IDENTITY column. This information is used by jOOQ internally, to update IDs after calling <reference id="crud-with-updatablerecords" title="store()"/>:
</p>
</html><java><![CDATA[BookRecord book = create.newRecord(BOOK);
book.setTitle("1984");
book.store();
// The generated ID value is fetched after the above INSERT statement
System.out.println(book.getId());]]></java><html>
<h3>Database compatibility</h3>
<p>
<strong>DB2, Derby, HSQLDB, Ingres</strong>
</p>
<p>
These SQL dialects implement the standard very neatly.
</p>
</html><sql><![CDATA[id INTEGER GENERATED BY DEFAULT AS IDENTITY
id INTEGER GENERATED BY DEFAULT AS IDENTITY (START WITH 1)]]></sql><html>
<p>
<strong>H2, MySQL, Postgres, SQL Server, Sybase ASE, Sybase SQL Anywhere</strong>
</p>
<p>
These SQL dialects implement identites, but the DDL syntax doesn’t follow the standard
</p>
</html><sql><![CDATA[-- H2 mimicks MySQL's and SQL Server's syntax
ID INTEGER IDENTITY(1,1)
ID INTEGER AUTO_INCREMENT
-- MySQL and SQLite
ID INTEGER NOT NULL AUTO_INCREMENT
-- Postgres serials implicitly create a sequence
-- Postgres also allows for selecting from custom sequences
-- That way, sequences can be shared among tables
id SERIAL NOT NULL
-- SQL Server
ID INTEGER IDENTITY(1,1) NOT NULL
-- Sybase ASE
id INTEGER IDENTITY NOT NULL
-- Sybase SQL Anywhere
id INTEGER NOT NULL IDENTITY]]></sql><html>
<p>
<strong>Oracle</strong>
</p>
<p>
Oracle does not know any identity columns at all. Instead, you will have to use a trigger and update the ID column yourself, using a custom sequence. Something along these lines:
</p>
</html><sql><![CDATA[CREATE OR REPLACE TRIGGER my_trigger
BEFORE INSERT
ON my_table
REFERENCING NEW AS new
FOR EACH ROW
BEGIN
SELECT my_sequence.nextval
INTO :new.id
FROM dual;
END my_trigger;]]></sql><html>
<p>
Note, that this approach can be employed in most databases supporting sequences and triggers! It is a lot more flexible than standard identities
</p>
</html></content>
</section>
<section id="navigation-methods">
<title>Navigation methods</title>
<content><html>
<p>
<reference class="org.jooq.TableRecord"/> and <reference class="org.jooq.UpdatableRecord"/> contain foreign key navigation methods. These navigation methods allow for "navigating" inbound or outbound foreign key references by executing an appropriate query. An example is given here:
</p>
</html><code-pair>
<sql><![CDATA[CREATE TABLE book (
AUTHOR_ID NUMBER(7) NOT NULL,
-- [...]
FOREIGN KEY (AUTHOR_ID) REFERENCES author(ID)
)]]></sql>
<java><![CDATA[BookRecord book = create.fetch(BOOK, BOOK.ID.equal(5));
// Find the author of a book (static imported from Keys)
AuthorRecord author = book.fetchParent(FK_BOOK_AUTHOR);
// Find other books by that author
List<BookRecord> books = author.fetchChildren(FK_BOOK_AUTHOR);]]></java>
</code-pair><html>
<p>
Note that, unlike in Hibernate, jOOQ's navigation methods will always lazy-fetch relevant records, without caching any results. In other words, every time you run such a fetch method, a new query will be issued.
</p>
<p>
These fetch methods only work on "attached" records. See the manual's section about <reference id="serializability" title="serializability"/> for some more insight on "attached" objects.
</p>
</html></content>
</section>
<section id="non-updatable-records">
<title>Non-updatable records</title>
<content><html>
<p>
Tables without a <code>PRIMARY KEY</code> are considered non-updatable by jOOQ, as jOOQ has no way of uniquely identifying such a record within the database. If you're using jOOQ's <reference id="code-generation" title="code generator"/>, such tables will generate <reference class="org.jooq.TableRecord"/> classes, instead of <reference class="org.jooq.UpdatableRecord"/> classes. When you fetch <reference id="record-vs-tablerecord" title="typed records"/> from such a table, the returned records will not allow for calling any of the <reference id="crud-with-updatablerecords" title="store(), refresh(), delete()"/> methods.
</p>
<p>
Note, that some databases use internal rowid or object-id values to identify such records. jOOQ does not support these vendor-specific record meta-data.
</p>
</html></content>
</section>
<section id="optimistic-locking">
<title>Optimistic locking</title>
<content><html>
<p>
jOOQ allows you to perform <reference id="crud-with-updatablerecords" title="CRUD"/> operations using optimistic locking. You can immediately take advantage of this feature by activating the relevant <reference id="custom-settings" title="executeWithOptimisticLocking Setting"/>. Without any further knowledge of the underlying data semantics, this will have the following impact on store() and delete() methods:
</p>
<ul>
<li>INSERT statements are not affected by this Setting flag</li>
<li>Prior to UPDATE or DELETE statements, jOOQ will run a <reference id="for-update-clause" title="SELECT .. FOR UPDATE"/> statement, pessimistically locking the record for the subsequent UPDATE / DELETE</li>
<li>The data fetched with the previous SELECT will be compared against the data in the record being stored or deleted</li>
<li>An <reference class="org.jooq.exception.DataChangedException"/> is thrown if the record had been modified in the mean time</li>
<li>The record is successfully stored / deleted, if the record had not been modified in the mean time.</li>
</ul>
<p>
The above changes to jOOQ's behaviour are transparent to the API, the only thing you need to do for it to be activated is to set the Settings flag. Here is an example illustrating optimistic locking:
</p>
</html><java><![CDATA[// Properly configure the DSLContext
DSLContext optimistic = DSLContext.using(connection, SQLDialect.ORACLE,
new Settings().withExecuteWithOptimisticLocking(true));
// Fetch a book two times
BookRecord book1 = optimistic.fetch(BOOK, BOOK.ID.equal(5));
BookRecord book2 = optimistic.fetch(BOOK, BOOK.ID.equal(5));
// Change the title and store this book. The underlying database record has not been modified, it can be safely updated.
book1.setTitle("Animal Farm");
book1.store();
// Book2 still references the original TITLE value, but the database holds a new value from book1.store().
// This store() will thus fail:
book2.setTitle("1984");
book2.store();]]></java><html>
<h3>Optimised optimistic locking using TIMESTAMP fields</h3>
<p>
If you're using jOOQ's <reference id="code-generation" title="code generator"/>, you can take indicate TIMESTAMP or UPDATE COUNTER fields for every generated table in the <reference id="codegen-advanced" title="code generation configuration"/>. Let's say we have this table:
</p>
</html><sql><![CDATA[CREATE TABLE book (
-- This column indicates when each book record was modified for the last time
MODIFIED TIMESTAMP NOT NULL,
-- [...]
)]]></sql><html>
<p>
The MODIFIED column will contain a timestamp indicating the last modification timestamp for any book in the BOOK table. If you're using jOOQ and it's <reference id="crud-with-updatablerecords" title="store() methods on UpdatableRecords"/>, jOOQ will then generate this TIMESTAMP value for you, automatically. However, instead of running an additional <reference id="for-update-clause" title="SELECT .. FOR UPDATE"/> statement prior to an UPDATE or DELETE statement, jOOQ adds a WHERE-clause to the UPDATE or DELETE statement, checking for TIMESTAMP's integrity. This can be best illustrated with an example:
</p>
</html><java><![CDATA[// Properly configure the DSLContext
DSLContext optimistic = DSL.using(connection, SQLDialect.ORACLE,
new Settings().withExecuteWithOptimisticLocking(true));
// Fetch a book two times
BookRecord book1 = optimistic.fetch(BOOK, BOOK.ID.equal(5));
BookRecord book2 = optimistic.fetch(BOOK, BOOK.ID.equal(5));
// Change the title and store this book. The MODIFIED value has not been changed since the book was fetched.
// It can be safely updated
book1.setTitle("Animal Farm");
book1.store();
// Book2 still references the original MODIFIED value, but the database holds a new value from book1.store().
// This store() will thus fail:
book2.setTitle("1984");
book2.store();]]></java><html>
<p>
As before, without the added TIMESTAMP column, optimistic locking is transparent to the API.
</p>
<h3>Optimised optimistic locking using VERSION fields</h3>
<p>
Instead of using TIMESTAMPs, you may also use numeric VERSION fields, containing version numbers that are incremented by jOOQ upon store() calls.
</p>
<p>
Note, for explicit pessimistic locking, please consider the manual's section about the <reference id="for-update-clause" title="FOR UPDATE clause"/>. For more details about how to configure TIMESTAMP or VERSION fields, consider the manual's section about <reference id="codegen-advanced" title="advanced code generator configuration"/>.
</p>
</html></content>
</section>
<section id="batch-execution-for-crud">
<title>Batch execution</title>
<content><html>
<p>
When inserting, updating, deleting a lot of records, you may wish to profit from JDBC batch operations, which can be performed by jOOQ. These are available through jOOQ's <reference id="dsl-context" title="DSLContext"/> as shown in the following example:
</p>
</html><java><![CDATA[// Fetch a bunch of books
List<BookRecord> books = create.fetch(BOOK);
// Modify the above books, and add some new ones:
modify(books);
addMore(books);
// Batch-update and/or insert all of the above books
create.batchStore(books);]]></java><html>
<p>
Internally, jOOQ will render all the required SQL statements and execute them as a regular <reference id="batch-execution" title="JDBC batch execution"/>.
</p>
</html></content>
</section>
<section id="crud-record-listener">
<title>CRUD SPI: RecordListener</title>
<content><html>
<p>
When performing CRUD, you may want to be able to centrally register one or several listener objects that receive notification every time CRUD is performed on an <reference id="crud-with-updatablerecords" title="UpdatableRecord"/>. Example use cases of such a listener are:
</p>
<ul>
<li>Adding a central ID generation algorithm, generating UUIDs for all of your records.</li>
<li>Adding a central record initialisation mechanism, preparing the database prior to inserting a new record.</li>
</ul>
<p>
An example of such a <code>RecordListener</code> is given here:
</p>
</html><java><![CDATA[// Extending DefaultRecordListener, which provides empty implementations for all methods...
public class InsertListener extends DefaultRecordListener {
@Override
public void insertStart(RecordContext ctx) {
// Generate an ID for inserted BOOKs
if (ctx.record() instanceof BookRecord) {
BookRecord book = (BookRecord) ctx.record();
book.setId(IDTools.generate());
}
}
}]]></java><html>
<p>
Now, configure jOOQ's runtime to load your listener
</p>
</html><java><![CDATA[// Create a configuration with an appropriate listener provider:
Configuration configuration = new DefaultConfiguration().set(connection).set(dialect);
configuration.set(new DefaultRecordListenerProvider(new InsertListener()));
// Create a DSLContext from the above configuration
DSLContext create = DSL.using(configuration);]]></java><html>
<p>
For a full documentation of what <code>RecordListener</code> can do, please consider the <reference class="org.jooq.RecordListener" title="RecordListener Javadoc"/>. Note that <code>RecordListener</code> instances can be registered with a <reference id="dsl-context" title="Configuration"/> independently of <reference id="execute-listeners" title="ExecuteListeners"/>.
</p>
</html></content>
</section>
</sections>
</section>
<section id="daos">
<title>DAOs</title>
<content><html>
<p>
If you're using jOOQ's <reference id="code-generation" title="code generator"/>, you can configure it to generate <reference id="pojos" title="POJOs" /> and DAOs for you. jOOQ then generates one DAO per <reference id="crud-with-updatablerecords" title="UpdatableRecord"/>, i.e. per table with a single-column primary key. Generated DAOs implement a common jOOQ type called <reference class="org.jooq.DAO"/>. This type contains the following methods:
</p>
</html><java><![CDATA[// <R> corresponds to the DAO's related table
// <P> corresponds to the DAO's related generated POJO type
// <T> corresponds to the DAO's related table's primary key type.
// Note that multi-column primary keys are not yet supported by DAOs
public interface DAO<R extends TableRecord<R>, P, T> {
// These methods allow for inserting POJOs
void insert(P object) throws DataAccessException;
void insert(P... objects) throws DataAccessException;
void insert(Collection<P> objects) throws DataAccessException;
// These methods allow for updating POJOs based on their primary key
void update(P object) throws DataAccessException;
void update(P... objects) throws DataAccessException;
void update(Collection<P> objects) throws DataAccessException;
// These methods allow for deleting POJOs based on their primary key
void delete(P... objects) throws DataAccessException;
void delete(Collection<P> objects) throws DataAccessException;
void deleteById(T... ids) throws DataAccessException;
void deleteById(Collection<T> ids) throws DataAccessException;
// These methods allow for checking record existence
boolean exists(P object) throws DataAccessException;
boolean existsById(T id) throws DataAccessException;
long count() throws DataAccessException;
// These methods allow for retrieving POJOs by primary key or by some other field
List<P> findAll() throws DataAccessException;
P findById(T id) throws DataAccessException;
<Z> List<P> fetch(Field<Z> field, Z... values) throws DataAccessException;
<Z> P fetchOne(Field<Z> field, Z value) throws DataAccessException;
// These methods provide DAO meta-information
Table<R> getTable();
Class<P> getType();
}]]></java><html>
<p>
Besides these base methods, generated DAO classes implement various useful fetch methods. An incomplete example is given here, for the BOOK table:
</p>
</html><java><![CDATA[// An example generated BookDao class
public class BookDao extends DAOImpl<BookRecord, Book, Integer> {
// Columns with primary / unique keys produce fetchOne() methods
public Book fetchOneById(Integer value) { ... }
// Other columns produce fetch() methods, returning several records
public List<Book> fetchByAuthorId(Integer... values) { ... }
public List<Book> fetchByTitle(String... values) { ... }
}]]></java><html>
<p>
Note that you can further subtype those pre-generated DAO classes, to add more useful DAO methods to them. Using such a DAO is simple:
</p>
</html><java><![CDATA[// Initialise an Configuration
Configuration configuration = new DefaultConfiguration().set(connection).set(SQLDialect.ORACLE);
// Initialise the DAO with the Configuration
BookDao bookDao = new BookDao(configuration);
// Start using the DAO
Book book = bookDao.findById(5);
// Modify and update the POJO
book.setTitle("1984");
book.setPublishedIn(1948);
bookDao.update(book);
// Delete it again
bookDao.delete(book);]]></java>
</content>
</section>
<section id="transaction-management">
<title>Transaction management</title>
<content><html>
<p>
There are essentially four ways how you can handle transactions in Java / SQL:
</p>
<ul>
<li>You can issue vendor-specific <code>COMMIT</code>, <code>ROLLBACK</code> and other statements directly in your database.</li>
<li>You can call JDBC's <reference class="java.sql.Connection" anchor="#commit--" title="Connection.commit()"/>, <reference class="java.sql.Connection" anchor="#rollback--" title="Connection.rollback()"/> and other methods on your JDBC driver.</li>
<li>You can use third-party transaction management libraries like Spring TX. Examples shown in the <reference id="jooq-with-spring" title="jOOQ with Spring examples section"/>.</li>
<li>You can use a JTA-compliant Java EE transaction manager from your container.</li>
</ul>
<p>
While jOOQ does not aim to replace any of the above, it offers a simple API (and a corresponding SPI) to provide you with jOOQ-style programmatic fluency to express your transactions. Below are some Java examples showing how to implement (nested) transactions with jOOQ. For these examples, we're using Java 8 syntax. Java 8 is not a requirement, though.
</p>
</html><java><![CDATA[create.transaction(configuration -> {
AuthorRecord author =
DSL.using(configuration)
.insertInto(AUTHOR, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME)
.values("George", "Orwell")
.returning()
.fetchOne();
DSL.using(configuration)
.insertInto(BOOK, BOOK.AUTHOR_ID, BOOK.TITLE)
.values(author.getId(), "1984")
.values(author.getId(), "Animal Farm")
.execute();
// Implicit commit executed here
});
]]></java><html>
<p>
Note how the lambda expression receives a new, <em>derived</em> configuration that should be used within the local scope:
</p>
</html><java><![CDATA[create.transaction(configuration -> {
// Wrap configuration in a new DSLContext:
DSL.using(configuration).insertInto(...);
DSL.using(configuration).insertInto(...);
// Or, reuse the new DSLContext within the transaction scope:
DSLContext ctx = DSL.using(configuration);
ctx.insertInto(...);
ctx.insertInto(...);
// ... but avoid using the scope from outside the transaction:
create.insertInto(...);
create.insertInto(...);
});
]]></java><html>
<p>
While some <reference class="org.jooq.TransactionProvider"/> implementations (e.g. ones based on ThreadLocals, e.g. Spring or JTA) may allow you to reuse the globally scoped <reference id="dsl-context" title="DSLContext"/> reference, the jOOQ transaction API design allows for <code>TransactionProvider</code> implementations that require your transactional code to use the new, locally scoped <code>Configuration</code>, instead.
</p>
<p>
Transactional code is wrapped in jOOQ's <reference class="org.jooq.TransactionalRunnable"/> or <reference class="org.jooq.TransactionalCallable"/> types:
</p>
</html><java><![CDATA[public interface TransactionalRunnable {
void run(Configuration configuration) throws Exception;
}
public interface TransactionalCallable<T> {
T run(Configuration configuration) throws Exception;
}]]></java><html>
<p>
Such transactional code can be passed to <reference class="org.jooq.DSLContext" anchor="#transaction-org.jooq.TransactionalRunnable-" title="transaction(TransactionRunnable)"/> or <reference class="org.jooq.DSLContext" anchor="#transactionResult-org.jooq.TransactionalCallable-" title="transactionResult(TransactionCallable)"/> methods.
</p>
<h3>Rollbacks</h3>
<p>
Any uncaught checked or unchecked exception thrown from your transactional code will rollback the transaction to the beginning of the block. This behaviour will allow for nesting transactions, if your configured <reference class="org.jooq.TransactionProvider"/> supports nesting of transactions. An example can be seen here:
</p>
</html><java><![CDATA[create.transaction(outer -> {
final AuthorRecord author =
DSL.using(outer)
.insertInto(AUTHOR, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME)
.values("George", "Orwell")
.returning()
.fetchOne();
// Implicit savepoint created here
try {
DSL.using(outer)
.transaction(nested -> {
DSL.using(nested)
.insertInto(BOOK, BOOK.AUTHOR_ID, BOOK.TITLE)
.values(author.getId(), "1984")
.values(author.getId(), "Animal Farm")
.execute();
// Rolls back the nested transaction
if (oops)
throw new RuntimeException("Oops");
// Implicit savepoint is discarded, but no commit is issued yet.
});
}
catch (RuntimeException e) {
// We can decide whether an exception is "fatal enough" to roll back also the outer transaction
if (isFatal(e))
// Rolls back the outer transaction
throw e;
}
// Implicit commit executed here
});
]]></java><html>
<h3>TransactionProvider implementations</h3>
<p>
By default, jOOQ ships with the <reference class="org.jooq.impl.DefaultTransactionProvider"/>, which implements nested transactions using JDBC <reference class="java.sql.Savepoint"/>. You can, however, implement your own <reference class="org.jooq.TransactionProvider"/> and supply that to your <reference id="dsl-context" title="Configuration"/> to override jOOQ's default behaviour. A simple example implementation using Spring's <code>DataSourceTransactionManager</code> can be seen here:
</p>
</html><java><![CDATA[import static org.springframework.transaction.TransactionDefinition.PROPAGATION_NESTED;
import org.jooq.Transaction;
import org.jooq.TransactionContext;
import org.jooq.TransactionProvider;
import org.jooq.tools.JooqLogger;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.jdbc.datasource.DataSourceTransactionManager;
import org.springframework.transaction.TransactionStatus;
import org.springframework.transaction.support.DefaultTransactionDefinition;
public class SpringTransactionProvider implements TransactionProvider {
private static final JooqLogger log = JooqLogger.getLogger(SpringTransactionProvider.class);
@Autowired
DataSourceTransactionManager txMgr;
@Override
public void begin(TransactionContext ctx) {
log.info("Begin transaction");
// This TransactionProvider behaves like jOOQ's DefaultTransactionProvider,
// which supports nested transactions using Savepoints
TransactionStatus tx = txMgr.getTransaction(new DefaultTransactionDefinition(PROPAGATION_NESTED));
ctx.transaction(new SpringTransaction(tx));
}
@Override
public void commit(TransactionContext ctx) {
log.info("commit transaction");
txMgr.commit(((SpringTransaction) ctx.transaction()).tx);
}
@Override
public void rollback(TransactionContext ctx) {
log.info("rollback transaction");
txMgr.rollback(((SpringTransaction) ctx.transaction()).tx);
}
}
class SpringTransaction implements Transaction {
final TransactionStatus tx;
SpringTransaction(TransactionStatus tx) {
this.tx = tx;
}
}
]]></java><html>
<p>
More information about how to use jOOQ with Spring can be found in the <reference id="jooq-with-spring" title="tutorials about jOOQ and Spring"/>
</p>
</html></content>
</section>
<section id="exception-handling">
<title>Exception handling</title>
<content><html>
<h3>Checked vs. unchecked exceptions</h3>
<p>
This is an eternal and religious debate. Pros and cons have been discussed time and again, and it still is a matter of taste, today. In this case, jOOQ clearly takes a side. jOOQ's exception strategy is simple:
</p>
<ul>
<li>All "system exceptions" are unchecked. If in the middle of a transaction involving business logic, there is no way that you can recover sensibly from a lost database connection, or a constraint violation that indicates a bug in your understanding of your database model.</li>
<li>All "business exceptions" are checked. Business exceptions are true exceptions that you should handle (e.g. not enough funds to complete a transaction).</li>
</ul>
<p>
With jOOQ, it's simple. All of jOOQ's exceptions are "system exceptions", hence they are all unchecked.
</p>
<h3>jOOQ's DataAccessException</h3>
<p>
jOOQ uses its own <reference class="org.jooq.exception.DataAccessException"/> to wrap any underlying <reference class="java.sql.SQLException"/> that might have occurred. Note that all methods in jOOQ that may cause such a DataAccessException document this both in the Javadoc as well as in their method signature.
</p>
<p>
DataAccessException is subtyped several times as follows:
</p>
<ul>
<li><strong>DataAccessException</strong>: General exception usually originating from a <reference class="java.sql.SQLException"/></li>
<li><strong>DataChangedException</strong>: An exception indicating that the database's underlying record has been changed in the mean time (see <reference id="optimistic-locking" title="optimistic locking"/>)</li>
<li><strong>DataTypeException</strong>: Something went wrong during type conversion</li>
<li><strong>DetachedException</strong>: A SQL statement was executed on a "detached" <reference id="crud-with-updatablerecords" title="UpdatableRecord"/> or a "detached" <reference id="sql-statements" title="SQL statement"/>.</li>
<li><strong>InvalidResultException</strong>: An operation was performed expecting only one result, but several results were returned.</li>
<li><strong>MappingException</strong>: Something went wrong when loading a record from a <reference id="pojos" title="POJO"/> or when mapping a record into a POJO</li>
</ul>
<h3>Override jOOQ's exception handling</h3>
<p>
The following section about <reference id="execute-listeners" title="execute listeners"/> documents means of overriding jOOQ's exception handling, if you wish to deal separately with some types of constraint violations, or if you raise business errors from your database, etc.
</p>
</html></content>
</section>
<section id="execute-listeners">
<title>ExecuteListeners</title>
<content><html>
<p>
The <reference id="dsl-context" title="Configuration"/> lets you specify a list of <reference class="org.jooq.ExecuteListener"/> instances. The ExecuteListener is essentially an event listener for Query, Routine, or ResultSet render, prepare, bind, execute, fetch steps. It is a base type for loggers, debuggers, profilers, data collectors, triggers, etc. Advanced ExecuteListeners can also provide custom implementations of Connection, PreparedStatement and ResultSet to jOOQ in apropriate methods.
</p>
<p>
For convenience and better backwards-compatibility, consider extending <reference class="org.jooq.impl.DefaultExecuteListener"/> instead of implementing this interface.
</p>
<h3>Example: Query statistics ExecuteListener</h3>
<p>
Here is a sample implementation of an ExecuteListener, that is simply counting the number of queries per type that are being executed using jOOQ:
</p>
</html><java><![CDATA[package com.example;
// Extending DefaultExecuteListener, which provides empty implementations for all methods...
public class StatisticsListener extends DefaultExecuteListener {
public static Map<ExecuteType, Integer> STATISTICS = new HashMap<ExecuteType, Integer>();
// Count "start" events for every type of query executed by jOOQ
@Override
public void start(ExecuteContext ctx) {
synchronized (STATISTICS) {
Integer count = STATISTICS.get(ctx.type());
if (count == null) {
count = 0;
}
STATISTICS.put(ctx.type(), count + 1);
}
}
}]]></java><html>
<p>
Now, configure jOOQ's runtime to load your listener
</p>
</html><java><![CDATA[// Create a configuration with an appropriate listener provider:
Configuration configuration = new DefaultConfiguration().set(connection).set(dialect);
configuration.set(new DefaultExecuteListenerProvider(new StatisticsListener()));
// Create a DSLContext from the above configuration
DSLContext create = DSL.using(configuration);]]></java><html>
<p>
And log results any time with a snippet like this:
</p>
</html><java><![CDATA[log.info("STATISTICS");
log.info("----------");
for (ExecuteType type : ExecuteType.values()) {
log.info(type.name(), StatisticsListener.STATISTICS.get(type) + " executions");
}]]></java><html>
<p>
This may result in the following log output:
</p>
</html><config>15:16:52,982 INFO - TEST STATISTICS
15:16:52,982 INFO - ---------------
15:16:52,983 INFO - READ : 919 executions
15:16:52,983 INFO - WRITE : 117 executions
15:16:52,983 INFO - DDL : 2 executions
15:16:52,983 INFO - BATCH : 4 executions
15:16:52,983 INFO - ROUTINE : 21 executions
15:16:52,983 INFO - OTHER : 30 executions</config><html>
<p>
Please read the <reference class="org.jooq.ExecuteListener" title="ExecuteListener Javadoc"/> for more details
</p>
<h3>Example: Custom Logging ExecuteListener</h3>
<p>
The following depicts an example of a custom ExecuteListener, which pretty-prints all queries being executed by jOOQ to stdout:
</p>
</html><java><![CDATA[import org.jooq.DSLContext;
import org.jooq.ExecuteContext;
import org.jooq.conf.Settings;
import org.jooq.impl.DefaultExecuteListener;
import org.jooq.tools.StringUtils;
public class PrettyPrinter extends DefaultExecuteListener {
/**
* Hook into the query execution lifecycle before executing queries
*/
@Override
public void executeStart(ExecuteContext ctx) {
// Create a new DSLContext for logging rendering purposes
// This DSLContext doesn't need a connection, only the SQLDialect...
DSLContext create = DSL.using(ctx.dialect(),
// ... and the flag for pretty-printing
new Settings().withRenderFormatted(true));
// If we're executing a query
if (ctx.query() != null) {
System.out.println(create.renderInlined(ctx.query()));
}
// If we're executing a routine
else if (ctx.routine() != null) {
System.out.println(create.renderInlined(ctx.routine()));
}
// If we're executing anything else (e.g. plain SQL)
else if (!StringUtils.isBlank(ctx.sql())) {
System.out.println(ctx.sql());
}
}
}]]></java><html>
<p>
See also the manual's sections about <reference id="logging" title="logging"/> for more sample implementations of actual ExecuteListeners.
</p>
<h3>Example: Bad query execution ExecuteListener</h3>
<p>
You can also use ExecuteListeners to interact with your SQL statements, for instance when you want to check if executed <code><reference id="update-statement" title="UPDATE"/></code> or <code><reference id="delete-statement" title="DELETE"/></code> statements contain a <code>WHERE</code> clause. This can be achieved trivially with the following sample ExecuteListener:
</p>
</html><java><![CDATA[public class DeleteOrUpdateWithoutWhereListener extends DefaultExecuteListener {
@Override
public void renderEnd(ExecuteContext ctx) {
if (ctx.sql().matches("^(?i:(UPDATE|DELETE)(?!.* WHERE ).*)$")) {
throw new DeleteOrUpdateWithoutWhereException();
}
}
}
public class DeleteOrUpdateWithoutWhereException extends RuntimeException {}
]]></java><html>
<p>
You might want to replace the above implementation with a more efficient and more reliable one, of course.
</p>
</html></content>
</section>
<section id="meta-data">
<title>Database meta data</title>
<content><html>
<p>
Since jOOQ 3.0, a simple wrapping API has been added to wrap JDBC's rather awkward <reference class="java.sql.DatabaseMetaData"/>. This API is still experimental, as the calls to the underlying JDBC type are not always available for all SQL dialects.
</p>
</html></content>
</section>
<section id="logging">
<title>Logging</title>
<content><html>
<p>
jOOQ logs all SQL queries and fetched result sets to its internal DEBUG logger, which is implemented as an <reference id="execute-listeners" title="execute listener"/>. By default, execute logging is activated in the <reference id="custom-settings" title="jOOQ Settings"/>. In order to see any DEBUG log output, put either log4j or slf4j on jOOQ's classpath along with their respective configuration. A sample log4j configuration can be seen here:
</p>
</html><xml><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<log4j:configuration>
<appender name="stdout" class="org.apache.log4j.ConsoleAppender">
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%m%n" />
</layout>
</appender>
<root>
<priority value="debug" />
<appender-ref ref="stdout" />
</root>
</log4j:configuration>]]></xml><html>
<p>
With the above configuration, let's fetch some data with jOOQ
</p>
</html><java><![CDATA[create.select(BOOK.ID, BOOK.TITLE).from(BOOK).orderBy(BOOK.ID).limit(1, 2).fetch();]]></java><html>
<p>
The above query may result in the following log output:
</p>
</html><text><![CDATA[Executing query : select "BOOK"."ID", "BOOK"."TITLE" from "BOOK" order by "BOOK"."ID" asc limit ? offset ?
-> with bind values : select "BOOK"."ID", "BOOK"."TITLE" from "BOOK" order by "BOOK"."ID" asc limit 2 offset 1
Query executed : Total: 1.439ms
Fetched result : +----+------------+
: | ID|TITLE |
: +----+------------+
: | 2|Animal Farm |
: | 3|O Alquimista|
: +----+------------+
Finishing : Total: 4.814ms, +3.375ms
]]></text><html>
<p>
Essentially, jOOQ will log
</p>
<ul>
<li>The SQL statement as rendered to the prepared statement</li>
<li>The SQL statement with inlined bind values (for improved debugging)</li>
<li>The query execution time</li>
<li>The first 5 records of the result. This is formatted using <reference id="exporting-text" title="jOOQ's text export"/></li>
<li>The total execution + fetching time</li>
</ul>
<p>
If you wish to use your own logger (e.g. avoiding printing out sensitive data), you can deactivate jOOQ's logger using <reference id="custom-settings" title="your custom settings"/> and implement your own <reference id="execute-listeners" title="execute listener logger"/>.
</p>
</html></content>
</section>
<section id="performance-considerations">
<title>Performance considerations</title>
<content><html>
<p>
Many users may have switched from higher-level abstractions such as Hibernate to jOOQ, because of Hibernate's difficult-to-manage performance, when it comes to large database schemas and complex second-level caching strategies. However, jOOQ itself is not a lightweight database abstraction framework, and it comes with its own overhead. Please be sure to consider the following points:
</p>
<ul>
<li>It takes some time to construct jOOQ queries. If you can reuse the same queries, you might cache them. Beware of thread-safety issues, though, as jOOQ's <reference id="dsl-context" title="Configuration"/> is not necessarily threadsafe, and queries are "attached" to their creating DSLContext</li>
<li>It takes some time to render SQL strings. Internally, jOOQ reuses the same <reference class="java.lang.StringBuilder"/> for the complete query, but some rendering elements may take their time. You could, of course, cache SQL generated by jOOQ and prepare your own <reference class="java.sql.PreparedStatement"/> objects</li>
<li>It takes some time to bind values to prepared statements. jOOQ does not keep any open prepared statements, internally. Use a sophisticated connection pool, that will cache prepared statements and inject them into jOOQ through the standard JDBC API</li>
<li>It takes some time to fetch results. By default, jOOQ will always fetch the complete <reference class="java.sql.ResultSet"/> into memory. Use <reference id="lazy-fetching" title="lazy fetching"/> to prevent that, and scroll over an open underlying database cursor</li>
</ul>
<h3>Optimise wisely</h3>
<p>
Don't be put off by the above paragraphs. You should optimise wisely, i.e. only in places where you really need very high throughput to your database. jOOQ's overhead compared to plain JDBC is typically less than 1ms per query.
</p>
</html></content>
</section>
</sections>
</section>
<section id="code-generation">
<title>Code generation</title>
<content><html>
<p>
While optional, source code generation is one of jOOQ's main assets if you wish to increase developer productivity. jOOQ's code generator takes your database schema and reverse-engineers it into a set of Java classes modelling <reference id="table-expressions" title="tables"/>, <reference id="record-vs-tablerecord" title="records"/>, <reference id="sequence-execution" title="sequences"/>, <reference id="pojos" title="POJOs"/>, <reference id="daos" title="DAOs"/>, <reference id="stored-procedures" title="stored procedures"/>, user-defined types and many more.
</p>
<p>
The essential ideas behind source code generation are these:
</p>
<ul>
<li><strong>Increased IDE support</strong>: Type your Java code directly against your database schema, with all type information available</li>
<li><strong>Type-safety</strong>: When your database schema changes, your generated code will change as well. Removing columns will lead to compilation errors, which you can detect early.</li>
</ul>
<p>
The following chapters will show how to configure the code generator and how to generate various artefacts.
</p>
</html></content>
<sections>
<section id="codegen-configuration">
<title>Configuration and setup of the generator</title>
<content><html>
<p>
There are three binaries available with jOOQ, to be downloaded from <a href="http://www.jooq.org/download" title="jOOQ download">http://www.jooq.org/download</a> or from Maven central:
</p>
<ul>
<li>
<strong>jooq-{jooq-version}.jar</strong>
<br />
The main library that you will include in your application to run jOOQ
</li>
<li>
<strong>jooq-meta-{jooq-version}.jar</strong>
<br />
The utility that you will include in your build to navigate your database schema for code generation. This can be used as a schema crawler as well.
</li>
<li>
<strong>jooq-codegen-{jooq-version}.jar</strong>
<br />
The utility that you will include in your build to generate your database schema
</li>
</ul>
<h3>Configure jOOQ's code generator</h3>
<p>
You need to tell jOOQ some things about your database connection. Here's an example of how to do it for an Oracle database
</p>
</html><xml><![CDATA[<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<configuration>
<!-- Configure the database connection here -->
<jdbc>
<driver>oracle.jdbc.OracleDriver</driver>
<url>jdbc:oracle:thin:@[your jdbc connection parameters]</url>
<user>[your database user]</user>
<password>[your database password]</password>
<!-- You can also pass user/password and other JDBC properties in the optional properties tag: -->
<properties>
<property><key>user</key><value>[db-user]</value></property>
<property><key>password</key><value>[db-password]</value></property>
</properties>
</jdbc>
<generator>
<database>
<!-- The database dialect from jooq-meta. Available dialects are
named org.util.[database].[database]Database.
Natively supported values are:
org.jooq.util.ase.ASEDatabase
org.jooq.util.cubrid.CUBRIDDatabase
org.jooq.util.db2.DB2Database
org.jooq.util.derby.DerbyDatabase
org.jooq.util.firebird.FirebirdDatabase
org.jooq.util.h2.H2Database
org.jooq.util.hsqldb.HSQLDBDatabase
org.jooq.util.informix.InformixDatabase
org.jooq.util.ingres.IngresDatabase
org.jooq.util.mariadb.MariaDBDatabase
org.jooq.util.mysql.MySQLDatabase
org.jooq.util.oracle.OracleDatabase
org.jooq.util.postgres.PostgresDatabase
org.jooq.util.sqlite.SQLiteDatabaes
org.jooq.util.sqlserver.SQLServerDatabase
org.jooq.util.sybase.SybaseDatabase
This value can be used to reverse-engineer generic JDBC DatabaseMetaData (e.g. for MS Access)
org.jooq.util.jdbc.JDBCDatabase
This value can be used to reverse-engineer standard jOOQ-meta XML formats
org.jooq.util.xml.XMLDatabase
You can also provide your own org.jooq.util.Database implementation
here, if your database is currently not supported -->
<name>org.jooq.util.oracle.OracleDatabase</name>
<!-- All elements that are generated from your schema (A Java regular expression.
Use the pipe to separate several expressions) Watch out for
case-sensitivity. Depending on your database, this might be
important!
You can create case-insensitive regular expressions using this syntax: (?i:expr)
Whitespace is ignored and comments are possible.
-->
<includes>.*</includes>
<!-- All elements that are excluded from your schema (A Java regular expression.
Use the pipe to separate several expressions). Excludes match before
includes -->
<excludes>
UNUSED_TABLE # This table (unqualified name) should not be generated
| PREFIX_.* # Objects with a given prefix should not be generated
| SECRET_SCHEMA\.SECRET_TABLE # This table (qualified name) should not be generated
| SECRET_ROUTINE # This routine (unqualified name) ...
</excludes>
<!-- The schema that is used locally as a source for meta information.
This could be your development schema or the production schema, etc
This cannot be combined with the schemata element.
If left empty, jOOQ will generate all available schemata. See the
manual's next section to learn how to generate several schemata -->
<inputSchema>[your database schema / owner / name]</inputSchema>
</database>
<generate>
<!-- Generation flags: See advanced configuration properties -->
</generate>
<target>
<!-- The destination package of your generated classes (within the
destination directory)
jOOQ may append the schema name to this package if generating multiple schemas,
e.g. org.jooq.your.packagename.schema1
org.jooq.your.packagename.schema2 -->
<packageName>[org.jooq.your.packagename]</packageName>
<!-- The destination directory of your generated classes -->
<directory>[/path/to/your/dir]</directory>
</target>
</generator>
</configuration>]]></xml><html>
<p>
There are also lots of advanced configuration parameters, which will be treated in the <reference id="codegen-advanced" title="manual's section about advanced code generation features"/> Note, you can find the official XSD file for a formal specification at:<br/>
<a href="http://www.jooq.org/xsd/jooq-codegen-{codegen-xsd-version}.xsd" title="The jOOQ-codegen configuration XSD">http://www.jooq.org/xsd/jooq-codegen-{codegen-xsd-version}.xsd</a>
</p>
<h3>Run jOOQ code generation</h3>
<p>
Code generation works by calling this class with the above property file as argument.
</p>
</html><config>org.jooq.util.GenerationTool /jooq-config.xml</config><html>
<p>
Be sure that these elements are located on the classpath:
</p>
<ul>
<li>The XML configuration file</li>
<li>jooq-{jooq-version}.jar, jooq-meta-{jooq-version}.jar, jooq-codegen-{jooq-version}.jar</li>
<li>The JDBC driver you configured</li>
</ul>
<h3>A command-line example (For Windows, unix/linux/etc will be similar)</h3>
<ul>
<li>Put the property file, jooq*.jar and the JDBC driver into a directory, e.g. C:\temp\jooq</li>
<li>Go to C:\temp\jooq</li>
<li>Run java -cp jooq-{jooq-version}.jar;jooq-meta-{jooq-version}.jar;jooq-codegen-{jooq-version}.jar;[JDBC-driver].jar;. org.jooq.util.GenerationTool /[XML file] </li>
</ul>
<p>
Note that the property file must be passed as a classpath resource
</p>
<h3>Run code generation from Eclipse</h3>
<p>
Of course, you can also run code generation from your IDE. In Eclipse, set up a project like this. Note that:
</p>
<ul>
<li>this example uses jOOQ's log4j support by adding log4j.xml and log4j.jar to the project classpath.</li>
<li>the actual jooq-{jooq-version}.jar, jooq-meta-{jooq-version}.jar, jooq-codegen-{jooq-version}.jar artefacts may contain version numbers in the file names.</li>
</ul>
<div class="screenshot">
<img class="screenshot" src="&lt;?=$root?&gt;/img/eclipse-example-01.png" alt="Eclipse configuration"/>
</div>
<p>
Once the project is set up correctly with all required artefacts on the classpath, you can configure an Eclipse Run Configuration for org.jooq.util.GenerationTool.
</p>
<div class="screenshot">
<img class="screenshot" src="&lt;?=$root?&gt;/img/eclipse-example-02.png" alt="Eclipse configuration"/>
</div>
<p>
With the XML file as an argument
</p>
<div class="screenshot">
<img class="screenshot" src="&lt;?=$root?&gt;/img/eclipse-example-03.png" alt="Eclipse configuration"/>
</div>
<p>
And the classpath set up correctly
</p>
<div class="screenshot">
<img class="screenshot" src="&lt;?=$root?&gt;/img/eclipse-example-04.png" alt="Eclipse configuration"/>
</div>
<p>
Finally, run the code generation and see your generated artefacts
</p>
<div class="screenshot">
<img class="screenshot" src="&lt;?=$root?&gt;/img/eclipse-example-05.png" alt="Eclipse configuration"/>
</div>
<h3>Integrate generation with Maven</h3>
<p>
Using the official jOOQ-codegen-maven plugin, you can integrate source code generation in your Maven build process:
</p>
</html><xml><![CDATA[<plugin>
<!-- Specify the maven code generator plugin -->
<groupId>org.jooq</groupId>
<artifactId>jooq-codegen-maven</artifactId>
<version>{jooq-version}</version>
<!-- The plugin should hook into the generate goal -->
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
<!-- Manage the plugin's dependency. In this example, we'll use a PostgreSQL database -->
<dependencies>
<dependency>
<groupId>postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>8.4-702.jdbc4</version>
</dependency>
</dependencies>
<!-- Specify the plugin configuration.
The configuration format is the same as for the standalone code generator -->
<configuration>
<!-- JDBC connection parameters -->
<jdbc>
<driver>org.postgresql.Driver</driver>
<url>jdbc:postgresql:postgres</url>
<user>postgres</user>
<password>test</password>
</jdbc>
<!-- Generator parameters -->
<generator>
<name>org.jooq.util.DefaultGenerator</name>
<database>
<name>org.jooq.util.postgres.PostgresDatabase</name>
<includes>.*</includes>
<excludes></excludes>
<inputSchema>public</inputSchema>
</database>
<target>
<packageName>org.jooq.util.maven.example</packageName>
<directory>target/generated-sources/jooq</directory>
</target>
</generator>
</configuration>
</plugin>
]]></xml><html>
<p>
See a more complete example of a Maven pom.xml File in the <reference id="jooq-with-spring" title="jOOQ / Spring tutorial"/>.
</p>
<h3>Use jOOQ generated classes in your application</h3>
<p>
Be sure, both jooq-{jooq-version}.jar and your generated package (see configuration) are located on your classpath. Once this is done, you can execute SQL statements with your generated classes.
</p>
</html></content>
</section>
<section id="codegen-ant">
<title>Running the code generator with Ant</title>
<content><html>
<h3>Run generation with Ant</h3>
<p>
When running code generation with ant's &lt;java/&gt; task, you may have to set fork="true":
</p>
</html><xml><![CDATA[<!-- Run the code generation task -->
<target name="generate-test-classes">
<java fork="true" classname="org.jooq.util.GenerationTool">
[...]
</java><html>
</target>
]]></xml><html>
</html></content>
</section>
<section id="codegen-gradle">
<title>Running the code generator with Gradle</title>
<content><html>
<h3>Run generation with Gradle</h3>
<p>
While some third-party Gradle plugins exist (e.g. the one by <a href="https://github.com/etiennestuder/gradle-jooq-plugin">Etienne Studer from Gradleware</a>), we generally recommend new users to use jOOQ's standalone code generator for simplicity. The following working example build.gradle script should work out of the box:
</p>
</html><java><![CDATA[
// Configure the Java plugin and the dependencies
// ----------------------------------------------
apply plugin: 'java'
repositories {
mavenLocal()
mavenCentral()
}
dependencies {
compile 'org.jooq:jooq:{jooq-version}'
runtime 'com.h2database:h2:1.4.177'
testCompile 'junit:junit:4.11'
}
buildscript {
repositories {
mavenLocal()
mavenCentral()
}
dependencies {
classpath 'org.jooq:jooq-codegen:{jooq-version}'
classpath 'com.h2database:h2:1.4.177'
}
}
// Use your favourite XML builder to construct the code generation configuration file
// ----------------------------------------------------------------------------------
def writer = new StringWriter()
def xml = new groovy.xml.MarkupBuilder(writer)
.configuration('xmlns': 'http://www.jooq.org/xsd/jooq-codegen-{codegen-xsd-version}.xsd') {
jdbc() {
driver('org.h2.Driver')
url('jdbc:h2:~/test-gradle')
user('sa')
password('')
}
generator() {
database() {
}
generate() {
}
target() {
packageName('org.jooq.example.gradle.db')
directory('src/main/java')
}
}
}
// Run the code generator
// ----------------------
org.jooq.util.GenerationTool.generate(
javax.xml.bind.JAXB.unmarshal(new StringReader(writer.toString()), org.jooq.util.jaxb.Configuration.class)
)
]]></java><html>
<p>
This example is frequently updated on GitHub: <a href="https://github.com/jOOQ/jOOQ/tree/master/jOOQ-examples/jOOQ-codegen-gradle">https://github.com/jOOQ/jOOQ/tree/master/jOOQ-examples/jOOQ-codegen-gradle</a>
</p>
</html></content>
</section>
<section id="codegen-advanced">
<title>Advanced generator configuration</title>
<content><html>
<p>
In the <reference id="codegen-configuration" title="previous section"/> we have seen how jOOQ's source code generator is configured and run within a few steps. In this chapter we'll cover some advanced settings
</p>
<h3>jooq-meta configuration</h3>
<p>
Within the &lt;generator/&gt; element, there are other configuration elements:
</p>
</html><xml><![CDATA[<!-- These properties can be added to the database element: -->
<database>
<!-- This flag indicates whether include / exclude patterns should also match
columns within tables. -->
<includeExcludeColumns>false</includeExcludeColumns>
<!-- All table and view columns that are used as "version" fields for
optimistic locking (A Java regular expression. Use the pipe to separate several expressions).
See UpdatableRecord.store() and UpdatableRecord.delete() for details -->
<recordVersionFields>REC_VERSION</recordVersionFields>
<!-- All table and view columns that are used as "timestamp" fields for
optimistic locking (A Java regular expression. Use the pipe to separate several expressions).
See UpdatableRecord.store() and UpdatableRecord.delete() for details -->
<recordTimestampFields>REC_TIMESTAMP</recordTimestampFields>
<!-- A regular expression matching all columns that participate in "synthetic" primary keys,
which should be placed on generated UpdatableRecords, to be used with
- UpdatableRecord.store()
- UpdatableRecord.update()
- UpdatableRecord.delete()
- UpdatableRecord.refresh()
Synthetic primary keys will override existing primary keys. -->
<syntheticPrimaryKeys>SCHEMA\.TABLE\.COLUMN(1|2)</syntheticPrimaryKeys>
<!-- All (UNIQUE) key names that should be used instead of primary keys on
generated UpdatableRecords, to be used with
- UpdatableRecord.store()
- UpdatableRecord.update()
- UpdatableRecord.delete()
- UpdatableRecord.refresh()
If several keys match, a warning is emitted and the first one encountered will be used.
This flag will also replace synthetic primary keys, if it matches. -->
<overridePrimaryKeys>MY_UNIQUE_KEY_NAME</overridePrimaryKeys>
<!-- Generate java.sql.Timestamp fields for DATE columns. This is
particularly useful for Oracle databases.
With jOOQ 3.5, this flag has been deprecated. Use an org.jooq.Binding instead
Defaults to false -->
<dateAsTimestamp>false</dateAsTimestamp>
<!-- Generate jOOU data types for your unsigned data types, which are
not natively supported in Java.
Defaults to true -->
<unsignedTypes>true</unsignedTypes>
<!-- The schema that is used in generated source code. This will be the
production schema. Use this to override your local development
schema name for source code generation. If not specified, this
will be the same as the input-schema.
This will be ignored if outputSchemaToDefault is set to true -->
<outputSchema>[your database schema / owner / name]</outputSchema>
<!-- A flag to indicate that the outputSchema should be the "default" schema,
which generates schema-less, unqualified tables, procedures, etc. -->
<outputSchemaToDefault>false</outputSchemaToDefault>
<!-- A configuration element to configure several input and/or output
schemata for jooq-meta, in case you're using jooq-meta in a multi-
schema environment.
This cannot be combined with the above inputSchema / outputSchema -->
<schemata>
<schema>
<inputSchema>...</inputSchema>
<outputSchema>...</outputSchema>
<outputSchemaToDefault>...</outputSchemaToDefault>
</schema>
[ <schema>...</schema> ... ]
</schemata>
<!-- A configuration element to configure custom data types -->
<customTypes>...</customTypes>
<!-- A configuration element to configure type overrides for generated
artefacts (e.g. in combination with customTypes) -->
<forcedTypes>...</forcedTypes>
</database>]]></xml><html>
<p>
Check out the some of the manual's "advanced" sections to find out more about the advanced configuration parameters.
</p>
<ul>
<li><reference id="schema-mapping" title="Schema mapping"/></li>
<li><reference id="custom-data-types" title="Custom types"/></li>
</ul>
<h3>jooq-codegen configuration</h3>
<p>
Also, you can add some optional advanced configuration parameters for the generator:
</p>
</html><xml><![CDATA[<!-- These properties can be added to the generate element: -->
<generate>
<!-- Primary key / foreign key relations should be generated and used.
This is a prerequisite for various advanced features.
Defaults to true -->
<relations>true</relations>
<!-- Generate deprecated code for backwards compatibility
Defaults to true -->
<deprecated>true</deprecated>
<!-- Do not reuse this property. It is deprecated as of jOOQ 3.3.0 -->
<instanceFields>true</instanceFields>
<!-- Generate the javax.annotation.Generated annotation to indicate
jOOQ version used for source code.
Defaults to true -->
<generatedAnnotation>true</generatedAnnotation>
<!-- Generate jOOQ Record classes for type-safe querying. You can
turn this off, if you don't need "active records" for CRUD
Defaults to true -->
<records>true</records>
<!-- Generate POJOs in addition to Record classes for usage of the
ResultQuery.fetchInto(Class) API
Defaults to false -->
<pojos>false</pojos>
<!-- Generate immutable POJOs for usage of the ResultQuery.fetchInto(Class) API
This overrides any value set in <pojos/>
Defaults to false -->
<immutablePojos>false</immutablePojos>
<!-- Generate interfaces that will be implemented by records and/or pojos.
You can also use these interfaces in Record.into(Class<?>) and similar
methods, to let jOOQ return proxy objects for them.
Defaults to false -->
<interfaces>false</interfaces>
<!-- Generate DAOs in addition to POJO classes
Defaults to false -->
<daos>false</daos>
<!-- Annotate POJOs and Records with JPA annotations for increased
compatibility and better integration with JPA/Hibernate, etc
Defaults to false -->
<jpaAnnotations>false</jpaAnnotations>
<!-- Annotate POJOs and Records with JSR-303 validation annotations
Defaults to false -->
<validationAnnotations>false</validationAnnotations>
<!-- Allow to turn off the generation of global object references, which include
- Tables.java
- Sequences.java
- UDTs.java
Turning off the generation of the above files may be necessary for very
large schemas, which exceed the amount of allowed constants in a class's
constant pool (64k) or, whose static initialiser would exceed 64k of
byte code
Defaults to true -->
<globalObjectReferences>true</globalObjectReferences>
<!-- Generate fluent setters in
- records
- pojos
- interfaces
Fluent setters are against the JavaBeans specification, but can be quite
useful to those users who do not depend on EL, JSP, JSF, etc.
Defaults to false -->
<fluentSetters>false</fluentSetters>
</generate>]]></xml><html>
<h3>Property interdependencies</h3>
<p>
Some of the above properties depend on other properties to work correctly. For instance, when generating immutable pojos, pojos must be generated. jOOQ will enforce such properties even if you tell it otherwise. Here is a list of property interdependencies:
</p>
<ul>
<li>When <code>daos = true</code>, then jOOQ will set <code>relations = true</code></li>
<li>When <code>daos = true</code>, then jOOQ will set <code>records = true</code></li>
<li>When <code>daos = true</code>, then jOOQ will set <code>pojos = true</code></li>
<li>When <code>immutablePojos = true</code>, then jOOQ will set <code>pojos = true</code></li>
</ul>
</html></content>
</section>
<section id="codegen-programmatic">
<title>Programmatic generator configuration</title>
<content><html>
<h3>Configuring your code generator with Java, Groovy, etc.</h3>
<p>
In the previous sections, we have covered how to set up jOOQ's code generator using XML, either by running a standalone Java application, or by using Maven. However, it is also possible to use jOOQ's <code>GenerationTool</code> programmatically. The XSD file used for the configuration (<a href="http://www.jooq.org/xsd/jooq-codegen-{codegen-xsd-version}.xsd">http://www.jooq.org/xsd/jooq-codegen-{codegen-xsd-version}.xsd</a>) is processed using <a href="http://docs.oracle.com/javase/6/docs/technotes/tools/share/xjc.html">XJC</a> to produce Java artefacts. The below example uses those artefacts to produce the equivalent configuration of the previous <reference id="codegen-configuration" title="PostgreSQL / Maven example"/>:
</p>
</html><java><![CDATA[// Use the fluent-style API to construct the code generator configuration
import org.jooq.util.jaxb.*;
// [...]
Configuration configuration = new Configuration()
.withJdbc(new Jdbc()
.withDriver("org.postgresql.Driver")
.withUrl("jdbc:postgresql:postgres")
.withUser("postgres")
.withPassword("test"))
.withGenerator(new Generator()
.withName("org.jooq.util.DefaultGenerator")
.withDatabase(new Database()
.withName("org.jooq.util.postgres.PostgresDatabase")
.withIncludes(".*")
.withExcludes("")
.withInputSchema("public"))
.withTarget(new Target()
.withPackageName("org.jooq.util.maven.example")
.withDirectory("target/generated-sources/jooq")));
GenerationTool.generate(configuration);]]></java><html>
<p>
For the above example, you will need all of jooq-{jooq-version}.jar, jooq-meta-{jooq-version}.jar, and jooq-codegen-{jooq-version}.jar, on your classpath.
</p>
<h3>
Manually loading the XML file
</h3>
<p>
Alternatively, you can also load parts of the configuration from an XML file using JAXB and programmatically modify other parts using the code generation API:
</p>
</html><xml><![CDATA[<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<configuration xmlns="http://www.jooq.org/xsd/jooq-codegen-{codegen-xsd-version}.xsd">
<jdbc>
<driver>org.h2.Driver</driver>
<!-- ... -->]]></xml><html>
<p>
Load the above using standard JAXB API:
</p>
</html><java><![CDATA[import java.io.File;
import javax.xml.bind.JAXB;
import org.jooq.utils.jaxb.Configuration;
// [...]
// and then
Configuration configuration = JAXB.unmarshal(new File("jooq.xml"), Configuration.class);
configuration.getJdbc()
.withUser("username")
.withPassword("password");
GeberationTool.generate(configuration);]]></java><html>
<p>
... and then, modify parts of your configuration programmatically, for instance the JDBC user / password:
</p>
</html></content>
</section>
<section id="codegen-generatorstrategy">
<title>Custom generator strategies</title>
<content><html>
<h3>Using custom generator strategies to override naming schemes</h3>
<p>
jOOQ allows you to override default implementations of the code generator or the generator strategy. Specifically, the latter can be very useful if you want to inject custom behaviour into jOOQ's code generator with respect to naming classes, members, methods, and other Java objects.
</p>
</html><xml><![CDATA[<!-- These properties can be added directly to the generator element: -->
<generator>
<!-- The default code generator. You can override this one, to generate your own code style
Defaults to org.jooq.util.DefaultGenerator -->
<name>org.jooq.util.DefaultGenerator</name>
<!-- The naming strategy used for class and field names.
You may override this with your custom naming strategy. Some examples follow
Defaults to org.jooq.util.DefaultGeneratorStrategy -->
<strategy>
<name>org.jooq.util.DefaultGeneratorStrategy</name>
</strategy>
</generator>]]></xml><html>
<p>
The following example shows how you can override the DefaultGeneratorStrategy to render table and column names the way they are defined in the database, rather than switching them to camel case:
</p>
</html><java><![CDATA[/**
* It is recommended that you extend the DefaultGeneratorStrategy. Most of the
* GeneratorStrategy API is already declared final. You only need to override any
* of the following methods, for whatever generation behaviour you'd like to achieve
*
* Beware that most methods also receive a "Mode" object, to tell you whether a
* TableDefinition is being rendered as a Table, Record, POJO, etc. Depending on
* that information, you can add a suffix only for TableRecords, not for Tables
*/
public class AsInDatabaseStrategy extends DefaultGeneratorStrategy {
/**
* Override this to specifiy what identifiers in Java should look like.
* This will just take the identifier as defined in the database.
*/
@Override
public String getJavaIdentifier(Definition definition) {
return definition.getOutputName();
}
/**
* Override these to specify what a setter in Java should look like. Setters
* are used in TableRecords, UDTRecords, and POJOs. This example will name
* setters "set[NAME_IN_DATABASE]"
*/
@Override
public String getJavaSetterName(Definition definition, Mode mode) {
return "set" + definition.getOutputName();
}
/**
* Just like setters...
*/
@Override
public String getJavaGetterName(Definition definition, Mode mode) {
return "get" + definition.getOutputName();
}
/**
* Override this method to define what a Java method generated from a database
* Definition should look like. This is used mostly for convenience methods
* when calling stored procedures and functions. This example shows how to
* set a prefix to a CamelCase version of your procedure
*/
@Override
public String getJavaMethodName(Definition definition, Mode mode) {
return "call" + org.jooq.tools.StringUtils.toCamelCase(definition.getOutputName());
}
/**
* Override this method to define how your Java classes and Java files should
* be named. This example applies no custom setting and uses CamelCase versions
* instead
*/
@Override
public String getJavaClassName(Definition definition, Mode mode) {
return super.getJavaClassName(definition, mode);
}
/**
* Override this method to re-define the package names of your generated
* artefacts.
*/
@Override
public String getJavaPackageName(Definition definition, Mode mode) {
return super.getJavaPackageName(definition, mode);
}
/**
* Override this method to define how Java members should be named. This is
* used for POJOs and method arguments
*/
@Override
public String getJavaMemberName(Definition definition, Mode mode) {
return definition.getOutputName();
}
/**
* Override this method to define the base class for those artefacts that
* allow for custom base classes
*/
@Override
public String getJavaClassExtends(Definition definition, Mode mode) {
return Object.class.getName();
}
/**
* Override this method to define the interfaces to be implemented by those
* artefacts that allow for custom interface implementation
*/
@Override
public List<String> getJavaClassImplements(Definition definition, Mode mode) {
return Arrays.asList(Serializable.class.getName(), Cloneable.class.getName());
}
/**
* Override this method to define the suffix to apply to routines when
* they are overloaded.
*
* Use this to resolve compile-time conflicts in generated source code, in
* case you make heavy use of procedure overloading
*/
@Override
public String getOverloadSuffix(Definition definition, Mode mode, String overloadIndex) {
return "_OverloadIndex_" + overloadIndex;
}
}]]></java><html>
<h3>An org.jooq.Table example:</h3>
<p>
This is an example showing which generator strategy method will be called in what place when generating tables. For improved readability, full qualification is omitted:
</p>
</html><java><![CDATA[package com.example.tables;
// 1: ^^^^^^^^^^^^^^^^^^
public class Book extends TableImpl<com.example.tables.records.BookRecord> {
// 2: ^^^^ 3: ^^^^^^^^^^
public static final Book BOOK = new Book();
// 2: ^^^^ 4: ^^^^
public final TableField<BookRecord, Integer> ID = /* ... */
// 3: ^^^^^^^^^^ 5: ^^
}
// 1: strategy.getJavaPackageName(table)
// 2: strategy.getJavaClassName(table)
// 3: strategy.getJavaClassName(table, Mode.RECORD)
// 4: strategy.getJavaIdentifier(table)
// 5: strategy.getJavaIdentifier(column)
]]></java><html>
<h3>An org.jooq.Record example:</h3>
<p>
This is an example showing which generator strategy method will be called in what place when generating records. For improved readability, full qualification is omitted:
</p>
</html><java><![CDATA[package com.example.tables.records;
// 1: ^^^^^^^^^^^^^^^^^^^^^^^^^^
public class BookRecord extends UpdatableRecordImpl<BookRecord> {
// 2: ^^^^^^^^^^ 2: ^^^^^^^^^^
public void setId(Integer value) { /* ... */ }
// 3: ^^^^^
public Integer getId() { /* ... */ }
// 4: ^^^^^
}
// 1: strategy.getJavaPackageName(table, Mode.RECORD)
// 2: strategy.getJavaClassName(table, Mode.RECORD)
// 3: strategy.getJavaSetterName(column, Mode.RECORD)
// 4: strategy.getJavaGetterName(column, Mode.RECORD)
]]></java><html>
<h3>A POJO example:</h3>
<p>
This is an example showing which generator strategy method will be called in what place when generating pojos. For improved readability, full qualification is omitted:
</p>
</html><java><![CDATA[package com.example.tables.pojos;
// 1: ^^^^^^^^^^^^^^^^^^^^^^^^
public class Book implements java.io.Serializable {
// 2: ^^^^
private Integer id;
// 3: ^^
public void setId(Integer value) { /* ... */ }
// 4: ^^^^^
public Integer getId() { /* ... */ }
// 5: ^^^^^
}
// 1: strategy.getJavaPackageName(table, Mode.POJO)
// 2: strategy.getJavaClassName(table, Mode.POJO)
// 3: strategy.getJavaMemberName(column, Mode.POJO)
// 4: strategy.getJavaSetterName(column, Mode.POJO)
// 5: strategy.getJavaGetterName(column, Mode.POJO)
]]></java><html>
<p>
More examples can be found here:
</p>
<ul>
<li><a href="https://github.com/jOOQ/jOOQ/blob/master/jOOQ-codegen/src/main/java/org/jooq/util/example/JPrefixGeneratorStrategy.java">org.jooq.util.example.JPrefixGeneratorStrategy</a></li>
<li><a href="https://github.com/jOOQ/jOOQ/blob/master/jOOQ-codegen/src/main/java/org/jooq/util/example/JVMArgsGeneratorStrategy.java">org.jooq.util.example.JVMArgsGeneratorStrategy</a></li>
</ul>
</html></content>
</section>
<section id="codegen-matcherstrategy">
<title>Matcher strategies</title>
<content><html>
<h3>Using custom matcher strategies</h3>
<p>
In the <reference id="codegen-generatorstrategy" title="previous section"/>, we have seen how to override generator strategies programmatically. In this chapter, we'll see how such strategies can be configured in the XML or Maven <reference id="codegen-configuration" title="code generator configuration"/>. Instead of specifying a strategy name, you can also specify a <code>&lt;matchers/></code> element as such:
</p>
<p>
<strong>NOTE:</strong> There had been an incompatible change between jOOQ 3.2 and jOOQ 3.3 in the configuration of these matcher strategies. See <a href="https://github.com/jOOQ/jOOQ/issues/3217">Issue #3217</a> for details.
</p>
</html><xml><![CDATA[<!-- These properties can be added directly to the generator element: -->
<generator>
<strategy>
<matchers>
<!-- Specify 0..n schema matchers in order to provide a naming strategy for objects
created from schemas. -->
<schemas>
<schema>
<!-- This schema matcher applies to all unqualified or qualified schema names
matched by this regular expression. If left empty, this matcher applies to all schemas. -->
<expression>MY_SCHEMA</expression>
<!-- These elements influence the naming of a generated org.jooq.Schema object. -->
<schemaClass> --> MatcherRule </schemaClass>
<schemaIdentifier> --> MatcherRule </schemaIdentifier>
<schemaImplements>com.example.MyOptionalCustomInterface</schemaImplements>
</schema>
</schemas>
<!-- Specify 0..n table matchers in order to provide a naming strategy for objects
created from database tables. -->
<tables>
<table>
<!-- The table matcher regular expression. -->
<expression>MY_TABLE</expression>
<!-- These elements influence the naming of a generated org.jooq.Table object. -->
<tableClass> --> MatcherRule </tableClass>
<tableIdentifier> --> MatcherRule </tableIdentifier>
<tableImplements>com.example.MyOptionalCustomInterface</tableImplements>
<!-- These elements influence the naming of a generated org.jooq.Record object. -->
<recordClass> --> MatcherRule </recordClass>
<recordImplements>com.example.MyOptionalCustomInterface</recordImplements>
<!-- These elements influence the naming of a generated interface, implemented by
generated org.jooq.Record objects and by generated POJOs. -->
<interfaceClass> --> MatcherRule </interfaceClass>
<interfaceImplements>com.example.MyOptionalCustomInterface</interfaceImplements>
<!-- These elements influence the naming of a generated org.jooq.DAO object. -->
<daoClass> --> MatcherRule </daoClass>
<daoImplements>com.example.MyOptionalCustomInterface</daoImplements>
<!-- These elements influence the naming of a generated POJO object. -->
<pojoClass> --> MatcherRule </pojoClass>
<pojoExtends>com.example.MyOptionalCustomBaseClass</pojoExtends>
<pojoImplements>com.example.MyOptionalCustomInterface</pojoImplements>
</table>
</tables>
<!-- Specify 0..n field matchers in order to provide a naming strategy for objects
created from table fields. -->
<fields>
<field>
<!-- The field matcher regular expression. -->
<expression>MY_FIELD</expression>
<!-- These elements influence the naming of a generated org.jooq.Field object. -->
<fieldIdentifier> --> MatcherRule </fieldIdentifier>
<fieldMember> --> MatcherRule </fieldMember>
<fieldSetter> --> MatcherRule </fieldSetter>
<fieldGetter> --> MatcherRule </fieldGetter>
</field>
</fields>
<!-- Specify 0..n routine matchers in order to provide a naming strategy for objects
created from routines. -->
<routines>
<routine>
<!-- The routine matcher regular expression. -->
<expression>MY_ROUTINE</expression>
<!-- These elements influence the naming of a generated org.jooq.Routine object. -->
<routineClass> --> MatcherRule </routineClass>
<routineMethod> --> MatcherRule </routineMethod>
<routineImplements>com.example.MyOptionalCustomInterface</routineImplements>
</routine>
</routines>
<!-- Specify 0..n sequence matchers in order to provide a naming strategy for objects
created from sequences. -->
<sequences>
<sequence>
<!-- The sequence matcher regular expression. -->
<expression>MY_SEQUENCE</expression>
<!-- These elements influence the naming of the generated Sequences class. -->
<sequenceIdentifier> --> MatcherRule </sequenceIdentifier>
</sequence>
</sequences>
</matchers>
</strategy>
</generator>]]></xml><html>
<p>
The above example used references to "MatcherRule", which is an XSD type that looks like this:
</p>
</html><xml><![CDATA[<schemaClass>
<!-- The optional transform element lets you apply a name transformation algorithm
to transform the actual database name into a more convenient form. Possible values are:
- AS_IS : Leave the database name as it is : MY_name => MY_name
- LOWER : Transform the database name into lower case : MY_name => my_name
- UPPER : Transform the database name into upper case : MY_name => MY_NAME
- CAMEL : Transform the database name into camel case : MY_name => myName
- PASCAL : Transform the database name into pascal case : MY_name => MyName -->
<transform>CAMEL</transform>
<!-- The mandatory expression element lets you specify a replacement expression to be used when
replacing the matcher's regular expression. You can use indexed variables $0, $1, $2. -->
<expression>PREFIX_$0_SUFFIX</expression>
</schemaClass>]]></xml><html>
<h3>Some examples</h3>
<p>
The following example shows a matcher strategy that adds a <code>"T_"</code> prefix to all table classes and to table identifiers:
</p>
</html><xml><![CDATA[<generator>
<strategy>
<matchers>
<tables>
<table>
<!-- Expression is omitted. This will make this rule apply to all tables -->
<tableIdentifier>
<transform>UPPER</transform>
<expression>T_$0</expression>
</tableIdentifier>
<tableClass>
<transform>PASCAL</transform>
<expression>T_$0</expression>
</tableClass>
</table>
</tables>
</matchers>
</strategy>
</generator>]]></xml><html>
<p>
The following example shows a matcher strategy that renames BOOK table identifiers (or table identifiers containing BOOK) into BROCHURE (or tables containing BROCHURE):
</p>
</html><xml><![CDATA[<generator>
<strategy>
<matchers>
<tables>
<table>
<expression>^(.*?)_BOOK_(.*)$</expression>
<tableIdentifier>
<transform>UPPER</transform>
<expression>$1_BROCHURE_$2</expression>
</tableIdentifier>
</table>
</tables>
</matchers>
</strategy>
</generator>]]></xml><html>
<p>
For more information about each XML tag, please refer to the <a href="http://www.jooq.org/xsd/jooq-codegen-{codegen-xsd-version}.xsd">http://www.jooq.org/xsd/jooq-codegen-{codegen-xsd-version}.xsd</a> XSD file.
</p>
</html></content>
</section>
<section id="codegen-custom-code">
<title>Custom code sections</title>
<content><html>
<p>Power users might choose to re-implement large parts of the <code>org.jooq.util.JavaGenerator</code> class. If you only want to add some custom code sections, however, you can extend the <code>JavaGenerator</code> and override only parts of it.</p>
<h3>An example for generating custom class footers</h3>
</html><java><![CDATA[public class MyGenerator1 extends JavaGenerator {
@Override
protected void generateRecordClassFooter(TableDefinition table, JavaWriter out) {
out.println();
out.tab(1).println("public String toString() {");
out.tab(2).println("return \"MyRecord[\" + valuesRow() + \"]\"");
out.tab(1).println("}");
}
}
]]></java><html>
<p>
The above example simply adds a class footer to <reference id="codegen-records" title="generated records"/>, in this case, overriding the default <code>toString()</code> implementation.
</p>
<h3>An example for generating custom class Javadoc</h3>
</html><java><![CDATA[public class MyGenerator2 extends JavaGenerator {
@Override
protected void generateRecordClassJavadoc(TableDefinition table, JavaWriter out) {
out.println("/**");
out.println(" * This record belongs to table " + table.getOutputName() + ".");
if (table.getComment() != null && !"".equals(table.getComment())) {
out.println(" * <p>");
out.println(" * Table comment: " + table.getComment());
}
out.println(" */");
}
}
]]></java><html>
<p>
Any of the below methods can be overridden:
</p>
</html><java><![CDATA[generateArray(SchemaDefinition, ArrayDefinition) // Generates an Oracle array class
generateArrayClassFooter(ArrayDefinition, JavaWriter) // Callback for an Oracle array class footer
generateArrayClassJavadoc(ArrayDefinition, JavaWriter) // Callback for an Oracle array class Javadoc
generateDao(TableDefinition) // Generates a DAO class
generateDaoClassFooter(TableDefinition, JavaWriter) // Callback for a DAO class footer
generateDaoClassJavadoc(TableDefinition, JavaWriter) // Callback for a DAO class Javadoc
generateEnum(EnumDefinition) // Generates an enum
generateEnumClassFooter(EnumDefinition, JavaWriter) // Callback for an enum footer
generateEnumClassJavadoc(EnumDefinition, JavaWriter) // Callback for an enum Javadoc
generateInterface(TableDefinition) // Generates an interface
generateInterfaceClassFooter(TableDefinition, JavaWriter) // Callback for an interface footer
generateInterfaceClassJavadoc(TableDefinition, JavaWriter) // Callback for an interface Javadoc
generatePackage(SchemaDefinition, PackageDefinition) // Generates an Oracle package class
generatePackageClassFooter(PackageDefinition, JavaWriter) // Callback for an Oracle package class footer
generatePackageClassJavadoc(PackageDefinition, JavaWriter) // Callback for an Oracle package class Javadoc
generatePojo(TableDefinition) // Generates a POJO class
generatePojoClassFooter(TableDefinition, JavaWriter) // Callback for a POJO class footer
generatePojoClassJavadoc(TableDefinition, JavaWriter) // Callback for a POJO class Javadoc
generateRecord(TableDefinition) // Generates a Record class
generateRecordClassFooter(TableDefinition, JavaWriter) // Callback for a Record class footer
generateRecordClassJavadoc(TableDefinition, JavaWriter) // Callback for a Record class Javadoc
generateRoutine(SchemaDefinition, RoutineDefinition) // Generates a Routine class
generateRoutineClassFooter(RoutineDefinition, JavaWriter) // Callback for a Routine class footer
generateRoutineClassJavadoc(RoutineDefinition, JavaWriter) // Callback for a Routine class Javadoc
generateSchema(SchemaDefinition) // Generates a Schema class
generateSchemaClassFooter(SchemaDefinition, JavaWriter) // Callback for a Schema class footer
generateSchemaClassJavadoc(SchemaDefinition, JavaWriter) // Callback for a Schema class Javadoc
generateTable(SchemaDefinition, TableDefinition) // Generates a Table class
generateTableClassFooter(TableDefinition, JavaWriter) // Callback for a Table class footer
generateTableClassJavadoc(TableDefinition, JavaWriter) // Callback for a Table class Javadoc
generateUDT(SchemaDefinition, UDTDefinition) // Generates a UDT class
generateUDTClassFooter(UDTDefinition, JavaWriter) // Callback for a UDT class footer
generateUDTClassJavadoc(UDTDefinition, JavaWriter) // Callback for a UDT class Javadoc
generateUDTRecord(UDTDefinition) // Generates a UDT Record class
generateUDTRecordClassFooter(UDTDefinition, JavaWriter) // Callback for a UDT Record class footer
generateUDTRecordClassJavadoc(UDTDefinition, JavaWriter) // Callback for a UDT Record class Javadoc]]></java><html>
<p>
When you override any of the above, do note that according to <reference id="semantic-versioning" title="jOOQ's understanding of semantic versioning"/>, incompatible changes may be introduced between minor releases, even if this should be the exception.
</p>
</html></content>
</section>
<section id="codegen-globals">
<title>Generated global artefacts</title>
<content><html>
<p>
For increased convenience at the use-site, jOOQ generates "global" artefacts at the code generation root location, referencing tables, routines, sequences, etc. In detail, these global artefacts include the following:
</p>
<ul>
<li><strong>Keys.java</strong>: This file contains all of the required primary key, unique key, foreign key and identity references in the form of static members of type <reference class="org.jooq.Key"/>.</li>
<li><strong>Routines.java</strong>: This file contains all standalone routines (not in packages) in the form of static factory methods for <reference class="org.jooq.Routine"/> types.</li>
<li><strong>Sequences.java</strong>: This file contains all sequence objects in the form of static members of type <reference class="org.jooq.Sequence"/>.</li>
<li><strong>Tables.java</strong>: This file contains all table objects in the form of static member references to the actual singleton <reference class="org.jooq.Table"/> object</li>
<li><strong>UDTs.java</strong>: This file contains all UDT objects in the form of static member references to the actual singleton <reference class="org.jooq.UDT"/> object</li>
</ul>
<h3>Referencing global artefacts</h3>
<p>
When referencing global artefacts from your client application, you would typically static import them as such:
</p>
</html><java><![CDATA[// Static imports for all global artefacts (if they exist)
import static com.example.generated.Keys.*;
import static com.example.generated.Routines.*;
import static com.example.generated.Sequences.*;
import static com.example.generated.Tables.*;
// You could then reference your artefacts as follows:
create.insertInto(MY_TABLE)
.values(MY_SEQUENCE.nextval(), myFunction())
// as a more concise form of this:
create.insertInto(com.example.generated.Tables.MY_TABLE)
.values(com.example.generated.Sequences.MY_SEQUENCE.nextval(), com.example.generated.Routines.myFunction())]]></java>
</content>
</section>
<section id="codegen-tables">
<title>Generated tables</title>
<content><html>
<p>
Every table in your database will generate a <reference class="org.jooq.Table"/> implementation that looks like this:
</p>
</html><java><![CDATA[public class Book extends TableImpl<BookRecord> {
// The singleton instance
public static final Book BOOK = new Book();
// Generated columns
public final TableField<BookRecord, Integer> ID = createField("ID", SQLDataType.INTEGER, this);
public final TableField<BookRecord, Integer> AUTHOR_ID = createField("AUTHOR_ID", SQLDataType.INTEGER, this);
public final TableField<BookRecord, String> ITLE = createField("TITLE", SQLDataType.VARCHAR, this);
// Covariant aliasing method, returning a table of the same type as BOOK
@Override
public Book as(java.lang.String alias) {
return new Book(alias);
}
// [...]
}]]></java><html>
<h3>Flags influencing generated tables</h3>
<p>
These flags from the <reference id="codegen-advanced" title="code generation configuration"/> influence generated tables:
</p>
<ul>
<li><strong>recordVersionFields</strong>: Relevant methods from super classes are overridden to return the VERSION field</li>
<li><strong>recordTimestampFields</strong>: Relevant methods from super classes are overridden to return the TIMESTAMP field</li>
<li><strong>syntheticPrimaryKeys</strong>: This overrides existing primary key information to allow for "custom" primary key column sets</li>
<li><strong>overridePrimaryKeys</strong>: This overrides existing primary key information to allow for unique key to primary key promotion</li>
<li><strong>dateAsTimestamp</strong>: This influences all relevant columns</li>
<li><strong>unsignedTypes</strong>: This influences all relevant columns</li>
<li><strong>relations</strong>: Relevant methods from super classes are overridden to provide primary key, unique key, foreign key and identity information</li>
<li><strong>instanceFields</strong>: This flag controls the "static" keyword on table columns, as well as aliasing convenience</li>
<li><strong>records</strong>: The generated record type is referenced from tables allowing for type-safe single-table record fetching</li>
</ul>
<h3>Flags controlling table generation</h3>
<p>
Table generation cannot be deactivated
</p>
</html></content>
</section>
<section id="codegen-records">
<title>Generated records</title>
<content><html>
<p>
Every table in your database will generate an <reference class="org.jooq.Record"/> implementation that looks like this:
</p>
</html><java><![CDATA[// JPA annotations can be generated, optionally
@Entity
@Table(name = "BOOK", schema = "TEST")
public class BookRecord extends UpdatableRecordImpl<BookRecord>
// An interface common to records and pojos can be generated, optionally
implements IBook {
// Every column generates a setter and a getter
@Override
public void setId(Integer value) {
setValue(BOOK.ID, value);
}
@Id
@Column(name = "ID", unique = true, nullable = false, precision = 7)
@Override
public Integer getId() {
return getValue(BOOK.ID);
}
// More setters and getters
public void setAuthorId(Integer value) {...}
public Integer getAuthorId() {...}
// Convenience methods for foreign key methods
public void setAuthorId(AuthorRecord value) {
if (value == null) {
setValue(BOOK.AUTHOR_ID, null);
}
else {
setValue(BOOK.AUTHOR_ID, value.getValue(AUTHOR.ID));
}
}
// Navigation methods
public AuthorRecord fetchAuthor() {
return create().selectFrom(AUTHOR).where(AUTHOR.ID.equal(getValue(BOOK.AUTHOR_ID))).fetchOne();
}
// [...]
}]]></java><html>
<h3>Flags influencing generated records</h3>
<p>
These flags from the <reference id="codegen-advanced" title="code generation configuration"/> influence generated records:
</p>
<ul>
<li><strong>syntheticPrimaryKeys</strong>: This overrides existing primary key information to allow for "custom" primary key column sets, possibly promoting a TableRecord to an UpdatableRecord</li>
<li><strong>overridePrimaryKeys</strong>: This overrides existing primary key information to allow for unique key to primary key promotion, possibly promoting a TableRecord to an UpdatableRecord</li>
<li><strong>dateAsTimestamp</strong>: This influences all relevant getters and setters</li>
<li><strong>unsignedTypes</strong>: This influences all relevant getters and setters</li>
<li><strong>relations</strong>: This is needed as a prerequisite for navigation methods</li>
<li><strong>daos</strong>: Records are a pre-requisite for DAOs. If DAOs are generated, records are generated as well</li>
<li><strong>interfaces</strong>: If interfaces are generated, records will implement them</li>
<li><strong>jpaAnnotations</strong>: JPA annotations are used on generated records</li>
</ul>
<h3>Flags controlling record generation</h3>
<p>
Record generation can be deactivated using the <strong>records</strong> flag
</p>
</html></content>
</section>
<section id="codegen-pojos">
<title>Generated POJOs</title>
<content><html>
<p>
Every table in your database will generate a POJO implementation that looks like this:
</p>
</html><java><![CDATA[// JPA annotations can be generated, optionally
@javax.persistence.Entity
@javax.persistence.Table(name = "BOOK", schema = "TEST")
public class Book implements java.io.Serializable
// An interface common to records and pojos can be generated, optionally
, IBook {
// JSR-303 annotations can be generated, optionally
@NotNull
private Integer id;
@NotNull
private Integer authorId;
@NotNull
@Size(max = 400)
private String title;
// Every column generates a getter and a setter
@Id
@Column(name = "ID", unique = true, nullable = false, precision = 7)
@Override
public Integer getId() {
return this.id;
}
@Override
public void setId(Integer id) {
this.id = id;
}
// [...]
}]]></java><html>
<h3>Flags influencing generated POJOs</h3>
<p>
These flags from the <reference id="codegen-advanced" title="code generation configuration"/> influence generated POJOs:
</p>
<ul>
<li><strong>dateAsTimestamp</strong>: This influences all relevant getters and setters</li>
<li><strong>unsignedTypes</strong>: This influences all relevant getters and setters</li>
<li><strong>interfaces</strong>: If interfaces are generated, POJOs will implement them</li>
<li><strong>immutablePojos</strong>: Immutable POJOs have final members and no setters. All members must be passed to the constructor</li>
<li><strong>daos</strong>: POJOs are a pre-requisite for DAOs. If DAOs are generated, POJOs are generated as well</li>
<li><strong>jpaAnnotations</strong>: JPA annotations are used on generated records</li>
<li><strong>validationAnnotations</strong>: JSR-303 validation annotations are used on generated records</li>
</ul>
<h3>Flags controlling POJO generation</h3>
<p>
POJO generation can be activated using the <strong>pojos</strong> flag
</p>
</html></content>
</section>
<section id="codegen-interfaces">
<title>Generated Interfaces</title>
<content><html>
<p>
Every table in your database will generate an interface that looks like this:
</p>
</html><java><![CDATA[public interface IBook extends java.io.Serializable {
// Every column generates a getter and a setter
public void setId(Integer value);
public Integer getId();
// [...]
}]]></java><html>
<h3>Flags influencing generated interfaces</h3>
<p>
These flags from the <reference id="codegen-advanced" title="code generation configuration"/> influence generated interfaces:
</p>
<ul>
<li><strong>dateAsTimestamp</strong>: This influences all relevant getters and setters</li>
<li><strong>unsignedTypes</strong>: This influences all relevant getters and setters</li>
</ul>
<h3>Flags controlling POJO generation</h3>
<p>
POJO generation can be activated using the <strong>interfaces</strong> flag
</p>
</html></content>
</section>
<section id="codegen-daos">
<title>Generated DAOs</title>
<content><html>
<h3>Generated DAOs</h3>
<p>
Every table in your database will generate a <reference class="org.jooq.DAO"/> implementation that looks like this:
</p>
</html><java><![CDATA[public class BookDao extends DAOImpl<BookRecord, Book, Integer> {
// Generated constructors
public BookDao() {
super(BOOK, Book.class);
}
public BookDao(Configuration configuration) {
super(BOOK, Book.class, configuration);
}
// Every column generates at least one fetch method
public List<Book> fetchById(Integer... values) {
return fetch(BOOK.ID, values);
}
public Book fetchOneById(Integer value) {
return fetchOne(BOOK.ID, value);
}
public List<Book> fetchByAuthorId(Integer... values) {
return fetch(BOOK.AUTHOR_ID, values);
}
// [...]
}]]></java><html>
<h3>Flags controlling DAO generation</h3>
<p>
DAO generation can be activated using the <strong>daos</strong> flag
</p>
</html></content>
</section>
<section id="codegen-sequences">
<title>Generated sequences</title>
<content><html>
<p>
Every sequence in your database will generate a <reference class="org.jooq.Sequence"/> implementation that looks like this:
</p>
</html><java><![CDATA[public final class Sequences {
// Every sequence generates a member
public static final Sequence<Integer> S_AUTHOR_ID = new SequenceImpl<Integer>("S_AUTHOR_ID", TEST, SQLDataType.INTEGER);
}]]></java><html>
<h3>Flags controlling sequence generation</h3>
<p>
Sequence generation cannot be deactivated
</p>
</html></content>
</section>
<section id="codegen-procedures">
<title>Generated procedures</title>
<content><html>
<p>
Every procedure or function (routine) in your database will generate a <reference class="org.jooq.Routine"/> implementation that looks like this:
</p>
</html><java><![CDATA[public class AuthorExists extends AbstractRoutine<java.lang.Void> {
// All IN, IN OUT, OUT parameters and function return values generate a static member
public static final Parameter<String> AUTHOR_NAME = createParameter("AUTHOR_NAME", SQLDataType.VARCHAR);
public static final Parameter<BigDecimal> RESULT = createParameter("RESULT", SQLDataType.NUMERIC);
// A constructor for a new "empty" procedure call
public AuthorExists() {
super("AUTHOR_EXISTS", TEST);
addInParameter(AUTHOR_NAME);
addOutParameter(RESULT);
}
// Every IN and IN OUT parameter generates a setter
public void setAuthorName(String value) {
setValue(AUTHOR_NAME, value);
}
// Every IN OUT, OUT and RETURN_VALUE generates a getter
public BigDecimal getResult() {
return getValue(RESULT);
}
// [...]
}]]></java><html>
<h3>Package and member procedures or functions</h3>
<p>
Procedures or functions contained in packages or UDTs are generated in a sub-package that corresponds to the package or UDT name.
</p>
<h3>Flags controlling routine generation</h3>
<p>
Routine generation cannot be deactivated
</p>
</html></content>
</section>
<section id="codegen-udts">
<title>Generated UDTs</title>
<content><html>
<p>
Every UDT in your database will generate a <reference class="org.jooq.UDT"/> implementation that looks like this:
</p>
</html><java><![CDATA[public class AddressType extends UDTImpl<AddressTypeRecord> {
// The singleton UDT instance
public static final UAddressType U_ADDRESS_TYPE = new UAddressType();
// Every UDT attribute generates a static member
public static final UDTField<AddressTypeRecord, String> ZIP =
createField("ZIP", SQLDataType.VARCHAR, U_ADDRESS_TYPE);
public static final UDTField<AddressTypeRecord, String> CITY =
createField("CITY", SQLDataType.VARCHAR, U_ADDRESS_TYPE);
public static final UDTField<AddressTypeRecord, String> COUNTRY =
createField("COUNTRY", SQLDataType.VARCHAR, U_ADDRESS_TYPE);
// [...]
}]]></java><html>
<p>
Besides the <reference class="org.jooq.UDT"/> implementation, a <reference class="org.jooq.UDTRecord"/> implementation is also generated
</p>
</html><java><![CDATA[public class AddressTypeRecord extends UDTRecordImpl<AddressTypeRecord> {
// Every attribute generates a getter and a setter
public void setZip(String value) {...}
public String getZip() {...}
public void setCity(String value) {...}
public String getCity() {...}
public void setCountry(String value) {...}
public String getCountry() {...}
// [...]
}]]></java><html>
<h3>Flags controlling UDT generation</h3>
<p>
UDT generation cannot be deactivated
</p>
</html></content>
</section>
<section id="data-type-rewrites">
<title>Data type rewrites</title>
<content><html>
<p>
Sometimes, the actual database data type does not match the SQL data type that you would like to use in Java. This is often the case for ill-supported SQL data types, such as <code>BOOLEAN</code> or <code>UUID</code>. jOOQ's code generator allows you to apply simple data type rewriting. The following configuration will rewrite <code>IS_VALID</code> columns in all tables to be of type <code>BOOLEAN</code>.
</p>
</html><xml><![CDATA[<database>
<!-- Associate data type rewrites with database columns -->
<forcedTypes>
<forcedType>
<!-- Specify any data type from org.jooq.impl.SQLDataType -->
<name>BOOLEAN</name>
<!-- Add a Java regular expression matching fully-qualified columns. Use the pipe to separate several expressions.
If provided, both "expressions" and "types" must match. -->
<expression>.*\.IS_VALID</expression>
<!-- Add a Java regular expression matching data types to be forced to have this type.
Data types may be reported by your database as:
- NUMBER
- NUMBER(5)
- NUMBER(5, 2)
- any other form.
It is thus recommended to use defensive regexes for types.
If provided, both "expressions" and "types" must match. -->
<types>.*</types>
</forcedType>
</forcedTypes>
</database>]]></xml><html>
<p>
You must provide at least either an <code>&lt;expressions/></code> or a <code>&lt;types/></code> element, or both.
</p>
<p>
See the section about <reference id="custom-data-types" title="Custom data types"/> for rewriting columns to your own custom data types.
</p>
</html></content>
</section>
<section id="custom-data-types">
<title>Custom data types and type conversion</title>
<content><html>
<p>
When using a custom type in jOOQ, you need to let jOOQ know about its associated <reference class="org.jooq.Converter"/>. Ad-hoc usages of such converters has been discussed in the chapter about <reference id="data-type-conversion" title="data type conversion"/>. However, when mapping a custom type onto a standard JDBC type, a more common use-case is to let jOOQ know about custom types at code generation time (if you're using non-standard JDBC types, like for example JSON or HSTORE, see the <reference id="custom-data-type-bindings" title="manual's section about custom data type bindings"/>). Use the following configuration elements to specify, that you'd like to use GregorianCalendar for all database fields that start with DATE_OF_
</p>
</html><xml><![CDATA[<database>
<!-- First, register your custom types here -->
<customTypes>
<customType>
<!-- Specify the name of your custom type. Avoid using names from org.jooq.impl.SQLDataType -->
<name>GregorianCalendar</name>
<!-- Specify the Java type of your custom type. This corresponds to the Converter's <U> type. -->
<type>java.util.GregorianCalendar</type>
<!-- Associate that custom type with your converter. -->
<converter>com.example.CalendarConverter</converter>
</customType>
</customTypes>
<!-- Then, associate custom types with database columns -->
<forcedTypes>
<forcedType>
<!-- Specify the name of your custom type -->
<name>GregorianCalendar</name>
<!-- Add a Java regular expression matching fully-qualified columns. Use the pipe to separate several expressions.
If provided, both "expressions" and "types" must match. -->
<expression>.*\.DATE_OF_.*</expression>
<!-- Add a Java regular expression matching data types to be forced to
have this type.
Data types may be reported by your database as:
- NUMBER
- NUMBER(5)
- NUMBER(5, 2)
- any other form
It is thus recommended to use defensive regexes for types.
If provided, both "expressions" and "types" must match. -->
<types>.*</types>
</forcedType>
</forcedTypes>
</database>]]></xml><html>
<p>
See also the section about <reference id="data-type-rewrites" title="data type rewrites"/> to learn about an alternative use of &lt;forcedTypes/&gt;.
</p>
<p>
The above configuration will lead to AUTHOR.DATE_OF_BIRTH being generated like this:
</p>
</html><java><![CDATA[public class TAuthor extends TableImpl<TAuthorRecord> {
// [...]
public final TableField<TAuthorRecord, GregorianCalendar> DATE_OF_BIRTH = // [...]
// [...]
}]]></java><html>
<p>
This means that the bound type of &lt;T&gt; will be GregorianCalendar, wherever you reference DATE_OF_BIRTH. jOOQ will use your custom converter when binding variables and when fetching data from <reference class="java.util.ResultSet"/>:
</p>
</html><java><![CDATA[// Get all date of births of authors born after 1980
List<GregorianCalendar> result =
create.selectFrom(AUTHOR)
.where(AUTHOR.DATE_OF_BIRTH.greaterThan(new GregorianCalendar(1980, 0, 1)))
.fetch(AUTHOR.DATE_OF_BIRTH);]]></java>
</content>
</section>
<section id="custom-data-type-bindings">
<title>Custom data type binding</title>
<content><html>
<p>
The previous section discussed the case where your custom data type is mapped onto a standard JDBC type as contained in <reference class="org.jooq.impl.SQLDataType"/>. In some cases, however, you want to map your own type onto a type that is not explicitly supported by JDBC, such as for instance, PostgreSQL's various advanced data types like JSON or HSTORE, or PostGIS types. For this, you can register an <reference class="org.jooq.Binding"/> for relevant columns in your code generator. Consider the following trivial implementation of a binding for PostgreSQL's JSON data type, which binds the JSON string in PostgreSQL to a Google GSON object:
</p>
</html><java><![CDATA[import static org.jooq.tools.Convert.convert;
import java.sql.*;
import org.jooq.*;
import org.jooq.impl.DSL;
import com.google.gson.*;
// We're binding <T> = Object (unknown JDBC type), and <U> = JsonElement (user type)
public class PostgresJSONGsonBinding implements Binding<Object, JsonElement> {
// The converter does all the work
@Override
public Converter<Object, JsonElement> converter() {
return new Converter<Object, JsonElement>() {
@Override
public JsonElement from(Object t) {
return t == null ? JsonNull.INSTANCE : new Gson().fromJson("" + t, JsonElement.class);
}
@Override
public Object to(JsonElement u) {
return u == null || u == JsonNull.INSTANCE ? null : new Gson().toJson(u);
}
@Override
public Class<Object> fromType() {
return Object.class;
}
@Override
public Class<JsonElement> toType() {
return JsonElement.class;
}
};
}
// Rending a bind variable for the binding context's value and casting it to the json type
@Override
public void sql(BindingSQLContext<JsonElement> ctx) throws SQLException {
ctx.render().visit(DSL.val(ctx.convert(converter()).value())).sql("::json");
}
// Registering VARCHAR types for JDBC CallableStatement OUT parameters
@Override
public void register(BindingRegisterContext<JsonElement> ctx) throws SQLException {
ctx.statement().registerOutParameter(ctx.index(), Types.VARCHAR);
}
// Converting the JsonElement to a String value and setting that on a JDBC PreparedStatement
@Override
public void set(BindingSetStatementContext<JsonElement> ctx) throws SQLException {
ctx.statement().setString(ctx.index(), Objects.toString(ctx.convert(converter()).value(), null));
}
// Getting a String value from a JDBC ResultSet and converting that to a JsonElement
@Override
public void get(BindingGetResultSetContext<JsonElement> ctx) throws SQLException {
ctx.convert(converter()).value(ctx.resultSet().getString(ctx.index()));
}
// Getting a String value from a JDBC CallableStatement and converting that to a JsonElement
@Override
public void get(BindingGetStatementContext<JsonElement> ctx) throws SQLException {
ctx.convert(converter()).value(ctx.statement().getString(ctx.index()));
}
// Setting a value on a JDBC SQLOutput (useful for Oracle OBJECT types)
@Override
public void set(BindingSetSQLOutputContext<JsonElement> ctx) throws SQLException {
throw new SQLFeatureNotSupportedException();
}
// Getting a value from a JDBC SQLInput (useful for Oracle OBJECT types)
@Override
public void get(BindingGetSQLInputContext<JsonElement> ctx) throws SQLException {
throw new SQLFeatureNotSupportedException();
}
}]]></java><html>
<h3>Registering bindings to the code generator</h3>
<p>
The above <reference class="org.jooq.Binding"/> implementation intercepts all the interaction on a JDBC level, such that jOOQ will never need to know how to crrectly serialise / deserialise your custom data type. Similar to what we've seen in the previous section about <reference id="custom-data-types" title="how to register Converters to the code generator"/>, we can now register such a binding to the code generator. Note that you will reuse the same types of XML elements (<code>&lt;customType/></code> and <code>&lt;forcedType/></code>):
</p>
</html><xml><![CDATA[<database>
<!-- First, register your custom types here -->
<customTypes>
<customType>
<!-- Specify the name of your custom type. Avoid using names from org.jooq.impl.SQLDataType -->
<name>JsonElement</name>
<!-- Specify the Java type of your custom type. This corresponds to the Binding's <U> type. -->
<type>com.google.gson.JsonElement</type>
<!-- Associate that custom type with your binding. -->
<binding>com.example.PostgresJSONGsonBinding</binding>
</customType>
</customTypes>
<!-- Then, associate custom types with database columns -->
<forcedTypes>
<forcedType>
<!-- Specify the name of your custom type -->
<name>JsonElement</name>
<!-- Add a Java regular expression matching fully-qualified columns. Use the pipe to separate several expressions.
If provided, both "expressions" and "types" must match. -->
<expression>.*JSON.*</expression>
<!-- Add a Java regular expression matching data types to be forced to
have this type.
Data types may be reported by your database as:
- NUMBER
- NUMBER(5)
- NUMBER(5, 2)
- any other form
It is thus recommended to use defensive regexes for types.
If provided, both "expressions" and "types" must match. -->
<types>.*</types>
</forcedType>
</forcedTypes>
</database>]]></xml><html>
<p>
See also the section about <reference id="data-type-rewrites" title="data type rewrites"/> to learn about an alternative use of &lt;forcedTypes/&gt;.
</p>
<p>
The above configuration will lead to AUTHOR.CUSTOM_DATA_JSON being generated like this:
</p>
</html><java><![CDATA[public class TAuthor extends TableImpl<TAuthorRecord> {
// [...]
public final TableField<TAuthorRecord, JsonElement> CUSTOM_DATA_JSON = // [...]
// [...]
}]]></java><html>
</html></content>
</section>
<section id="schema-mapping">
<title>Mapping generated schemata and tables</title>
<content><html>
<p>
We've seen previously in the chapter about <reference id="runtime-schema-mapping" title="runtime schema mapping"/>, that schemata and tables can be mapped at runtime to other names. But you can also hard-wire schema mapping in generated artefacts at code generation time, e.g. when you have 5 developers with their own dedicated developer databases, and a common integration database. In the code generation configuration, you would then write.
</p>
</html><xml><![CDATA[<schemata>
<schema>
<!-- Use this as the developer's schema: -->
<inputSchema>LUKAS_DEV_SCHEMA</inputSchema>
<!-- Use this as the integration / production database: -->
<outputSchema>PROD</outputSchema>
</schema>
</schemata>]]></xml>
</content>
</section>
<section id="codegen-large-schemas">
<title>Code generation for large schemas</title>
<content><html>
<p>
Databases can become very large in real-world applications. This is not a problem for jOOQ's code generator, but it can be for the Java compiler. jOOQ generates some classes for <reference id="codegen-globals" title="global access"/>. These classes can hit two sorts of limits of the compiler / JVM:
</p>
<ul>
<li>Methods (including static / instance initialisers) are allowed to contain only 64kb of bytecode.</li>
<li>Classes are allowed to contain at most 64k of constant literals</li>
</ul>
<p>
While there exist workarounds for the above two limitations (delegating initialisations to nested classes, inheriting constant literals from implemented interfaces), the preferred approach is either one of these:
</p>
<ul>
<li>Distribute your database objects in several schemas. That is probably a good idea anyway for such large databases</li>
<li><reference id="codegen-configuration" title="Configure jOOQ's code generator"/> to exclude excess database objects</li>
<li><reference id="codegen-configuration" title="Configure jOOQ's code generator"/> to avoid generating <reference id="codegen-globals" title="global objects"/> using <code>&lt;globalObjectReferences/&gt;</code></li>
<li>Remove uncompilable classes after code generation</li>
</ul>
</html></content>
</section>
<section id="codegen-version-control">
<title>Code generation and version control</title>
<content><html>
<p>
When using jOOQ's code generation capabilities, you will need to make a strategic decision about whether you consider your generated code as
</p>
<ul>
<li>Part of your code base</li>
<li>Derived artefacts</li>
</ul>
<p>
In this section we'll see that both approaches have their merits and that none of them is clearly better.
</p>
<h3>Part of your code base</h3>
<p>
When you consider generated code as part of your code base, you will want to:
</p>
<ul>
<li>Check in generated sources in your version control system</li>
<li>Use manual source code generation</li>
<li>Possibly use even partial source code generation</li>
</ul>
<p>
This approach is particularly useful when your Java developers are not in full control of or do not have full access to your database schema, or if you have many developers that work simultaneously on the same database schema, which changes all the time. It is also useful to be able to track side-effects of database changes, as your checked-in database schema can be considered when you want to analyse the history of your schema.
</p>
<p>
With this approach, you can also keep track of the change of behaviour in the jOOQ code generator, e.g. when upgrading jOOQ, or when modifying the code generation configuration.
</p>
<p>
The drawback of this approach is that it is more error-prone as the actual schema may go out of sync with the generated schema.
</p>
<h3>Derived artefacts</h3>
<p>
When you consider generated code to be derived artefacts, you will want to:
</p>
<ul>
<li>Check in only the actual DDL (e.g. controlled via <reference id="jooq-with-flyway" title="Flyway"/>)</li>
<li>Regenerate jOOQ code every time the schema changes</li>
<li>Regenerate jOOQ code on every machine - including continuous integration</li>
</ul>
<p>
This approach is particularly useful when you have a smaller database schema that is under full control by your Java developers, who want to profit from the increased quality of being able to regenerate all derived artefacts in every step of your build.
</p>
<p>
The drawback of this approach is that the build may break in perfectly acceptable situations, when parts of your database are temporarily unavailable.
</p>
<h3>Pragmatic combination</h3>
<p>
In some situations, you may want to choose a pragmatic combination, where you put only some parts of the generated code under version control. For instance, jOOQ-meta's generated sources are put under version control as few contributors will be able to run the jOOQ-meta code generator against all supported databases.
</p>
</html></content>
</section>
</sections>
</section>
<section id="tools">
<title>Tools</title>
<content><html>
<p>
These chapters hold some information about tools to be used with jOOQ
</p>
</html></content>
<sections>
<section id="jdbc-mocking">
<title>JDBC mocking for unit testing</title>
<content><html>
<p>
When writing unit tests for your data access layer, you have probably used some generic mocking tool offered by popular providers like <a href="http://code.google.com/p/mockito/">Mockito</a>, <a href="http://jmock.org/">jmock</a>, <a href="http://mockrunner.sourceforge.net/">mockrunner</a>, or even <a href="http://www.dbunit.org/">DBUnit</a>. With jOOQ, you can take advantage of the built-in JDBC mock API that allows you to simulate a database on the JDBC level for precisely those SQL/JDBC use cases supported by jOOQ.
</p>
<h3>Mocking the JDBC API</h3>
<p>
JDBC is a very complex API. It takes a lot of time to write a useful and correct mock implementation, implementing at least these interfaces:
</p>
<ul>
<li><reference class="java.sql.Connection"/></li>
<li><reference class="java.sql.Statement"/></li>
<li><reference class="java.sql.PreparedStatement"/></li>
<li><reference class="java.sql.CallableStatement"/></li>
<li><reference class="java.sql.ResultSet"/></li>
<li><reference class="java.sql.ResultSetMetaData"/></li>
</ul>
<p>
Optionally, you may even want to implement interfaces, such as <reference class="java.sql.Array"/>, <reference class="java.sql.Blob"/>, <reference class="java.sql.Clob"/>, and many others. In addition to the above, you might need to find a way to simultaneously support incompatible JDBC minor versions, such as 4.0, 4.1
</p>
<h3>Using jOOQ's own mock API</h3>
<p>
This work is greatly simplified, when using jOOQ's own mock API. The <code>org.jooq.tools.jdbc</code> package contains all the essential implementations for both JDBC 4.0 and 4.1, which are needed to mock JDBC for jOOQ. In order to write mock tests, provide the jOOQ <reference id="dsl-context" title="Configuration"/> with a <reference class="org.jooq.tools.jdbc.MockConnection" title="MockConnection"/>, and implement the <reference class="org.jooq.tools.jdbc.MockDataProvider" title="MockDataProvider"/>:
</p>
</html><java><![CDATA[// Initialise your data provider (implementation further down):
MockDataProvider provider = new MyProvider();
MockConnection connection = new MockConnection(provider);
// Pass the mock connection to a jOOQ DSLContext:
DSLContext create = DSL.using(connection, SQLDialect.ORACLE);
// Execute queries transparently, with the above DSLContext:
Result<BookRecord> result = create.selectFrom(BOOK).where(BOOK.ID.equal(5)).fetch();]]></java><html>
<p>
As you can see, the configuration setup is simple. Now, the <code>MockDataProvider</code> acts as your single point of contact with JDBC / jOOQ. It unifies any of these execution modes, transparently:
</p>
<ul>
<li>Statements without results</li>
<li>Statements without results but with generated keys</li>
<li>Statements with results</li>
<li>Statements with several results</li>
<li>Batch statements with single queries and multiple bind value sets</li>
<li>Batch statements with multiple queries and no bind values</li>
</ul>
<p>
The above are the execution modes supported by jOOQ. Whether you're using any of jOOQ's various fetching modes (e.g. <reference id="pojos" title="pojo fetching"/>, <reference id="lazy-fetching" title="lazy fetching"/>, <reference id="many-fetching" title="many fetching"/>, <reference id="later-fetching" title="later fetching"/>) is irrelevant, as those modes are all built on top of the standard JDBC API.
</p>
<h3>Implementing MockDataProvider</h3>
<p>
Now, here's how to implement <code>MockDataProvider</code>:
</p>
</html><java><![CDATA[public class MyProvider implements MockDataProvider {
@Override
public MockResult[] execute(MockExecuteContext ctx) throws SQLException {
// You might need a DSLContext to create org.jooq.Result and org.jooq.Record objects
DSLContext create = DSL.using(SQLDialect.ORACLE);
MockResult[] mock = new MockResult[1];
// The execute context contains SQL string(s), bind values, and other meta-data
String sql = ctx.sql();
// Exceptions are propagated through the JDBC and jOOQ APIs
if (sql.toUpperCase().startsWith("DROP")) {
throw new SQLException("Statement not supported: " + sql);
}
// You decide, whether any given statement returns results, and how many
else if (sql.toUpperCase().startsWith("SELECT")) {
// Always return one author record
Result<AuthorRecord> result = create.newResult(AUTHOR);
result.add(create.newRecord(AUTHOR));
result.get(0).setValue(AUTHOR.ID, 1);
result.get(0).setValue(AUTHOR.LAST_NAME, "Orwell");
mock[0] = new MockResult(1, result);
}
// You can detect batch statements easily
else if (ctx.batch()) {
// [...]
}
return mock;
}
}]]></java><html>
<p>
Essentially, the <reference class="org.jooq.tools.jdbc.MockExecuteContext" title="MockExecuteContext"/> contains all the necessary information for you to decide, what kind of data you should return. The <reference class="org.jooq.tools.jdbc.MockResult" title="MockResult"/> wraps up two pieces of information:
</p>
<ul>
<li> <reference class="java.sql.Statement" anchor="#getUpdateCount" title="Statement.getUpdateCount()"/>: The number of affected rows</li>
<li> <reference class="java.sql.Statement" anchor="#getResultSet()" title="Statement.getResultSet()"/>: The result set</li>
</ul>
<p>
You should return as many <code>MockResult</code> objects as there were query executions (in <reference id="batch-execution" title="batch mode"/>) or results (in <reference id="many-fetching" title="fetch-many mode"/>). Instead of an awkward JDBC <code>ResultSet</code>, however, you can construct a "friendlier" <reference class="org.jooq.Result"/> with your own record types. The jOOQ mock API will use meta data provided with this <code>Result</code> in order to create the necessary JDBC <reference class="java.sql.ResultSetMetaData"/>
</p>
<p>
See the <reference class="org.jooq.tools.jdbc.MockDataProvider" title="MockDataProvider Javadoc"/> for a list of rules that you should follow.
</p>
</html></content>
</section>
<section id="sql2jooq">
<title>SQL 2 jOOQ Parser</title>
<content><html>
<p>
Together with <a href="http://www.dpriver.com/">Gudu Software</a>, we have created an Open Source SQL 2 jOOQ parser that takes native SQL statements as input and generates jOOQ code as output.
</p>
<p>
Gudu Software Ltd has been selling enterprise quality SQL software to hundreds of customers to help them migrate from one database to another using the <a href="http://www.sqlparser.com/">General SQL Parser</a>. Now you can take advantage of their knowledge to parse your SQL statements and transform them directly into jOOQ statements using a free trial version of SQL 2 jOOQ!
</p>
<h3>It's as simple as this!</h3>
<ul>
<li>Create a JDBC connection</li>
<li>Create a new SQL2jOOQ converter object</li>
<li>Convert your SQL code</li>
<li>Get the result</li>
</ul>
<p>
See it in action:
</p>
</html><java><![CDATA[package gudusoft.sql2jooq.readme;
import gudusoft.gsqlparser.EDbVendor;
import gudusoft.gsqlparser.sql2jooq.SQL2jOOQ;
import gudusoft.gsqlparser.sql2jooq.db.DatabaseMetaData;
import gudusoft.gsqlparser.sql2jooq.tool.DatabaseMetaUtil;
import java.sql.Connection;
import java.sql.DriverManager;
public class Test {
public static void main(String[] args) throws Exception {
// 1. Create a JDBC connection
// ---------------------------
String userName = "root";
String password = "";
String url = "jdbc:mysql://localhost:3306/guestbook";
Class.forName("com.mysql.jdbc.Driver");
Connection conn = DriverManager.getConnection(url, userName, password);
// 2. Create a new SQL2jOOQ converter object
// -----------------------------------------
DatabaseMetaData metaData = DatabaseMetaUtil
.getDataBaseMetaData(conn, "guestbook");
SQL2jOOQ convert = new SQL2jOOQ(metaData,
EDbVendor.dbvmysql,
"select first_name, last_name from actor where actor_id = 1;");
// 3. Convert your SQL code
// ------------------------
convert.convert();
if (convert.getErrorMessage() != null) {
System.err.println(convert.getErrorMessage());
System.exit(-1);
}
// 4. Get the result
// -----------------
System.out.println(convert.getConvertResult());
}
}
]]></java><html>
<p>
If all goes well, the above program yields:
</p>
</html><java><![CDATA[DSLContext create = DSL.using(conn, SQLDialect.MYSQL);
Result<Record2<String, String>> result = create.select( Actor.ACTOR.FIRST_NAME, Actor.ACTOR.LAST_NAME )
.from( Actor.ACTOR )
.where( Actor.ACTOR.ACTOR_ID.equal( DSL.inline( UShort.valueOf( 1 ) ) ) ).fetch( );]]></java><html>
<p>
SQL 2 jOOQ is a joint venture by Gudu Software Limited and Data Geekery GmbH. We will ship, test and maintain this awesome new addition with our own deliverables. So far, SQL 2 jOOQ supports the MySQL and PostgreSQL dialects and it is in an alpha stadium. Please, community, provide as much feedback as possible to make this great tool rock even more!
</p>
<p>
Please take note of the fact that the sql2jooq library is Open Source, but it depends on the commercial gsp.jar parser, whose trial licensing terms can be seen here:
</p>
<p>
<a href="https://github.com/sqlparser/sql2jooq/blob/master/sql2jooq/LICENSE-GSQLPARSER.txt">https://github.com/sqlparser/sql2jooq/blob/master/sql2jooq/LICENSE-GSQLPARSER.txt</a>
</p>
<p>
For more information about the General SQL Parser, <a href="http://www.dpriver.com/blog/list-of-demos-illustrate-how-to-use-general-sql-parser/">please refer to the product blog</a>.
</p>
<p>
Please report any issues, ideas, wishes to the <a href="https://groups.google.com/forum/#!forum/jooq-user">jOOQ user group</a> or the <a href="https://github.com/sqlparser/sql2jooq">sql2jooq GitHub project</a>.
</p>
</html></content>
</section>
<section id="jooq-console">
<title>jOOQ Console</title>
<content><html>
<p>
The jOOQ Console is no longer supported or shipped with jOOQ 3.2+. You may still use the jOOQ 3.1 Console with new versions of jOOQ, at your own risk.
</p>
</html></content>
</section>
</sections>
</section>
<section id="reference">
<title>Reference</title>
<content><html>
<p>
These chapters hold some general jOOQ reference information
</p>
</html></content>
<sections>
<section id="supported-rdbms">
<title>Supported RDBMS</title>
<content><html>
<h3>A list of supported databases</h3>
<p>
Every RDMBS out there has its own little specialties. jOOQ considers those specialties as much as possible, while trying to standardise the behaviour in jOOQ. In order to increase the quality of jOOQ, some 70 unit tests are run for syntax and variable binding verification, as well as some 180 integration tests with an overall of around 1200 queries for any of these databases:
</p>
<ul>
<li>Access 2013</li>
<li>CUBRID 8.4.1 and 9.0.0</li>
<li>DB2 9.7</li>
<li>Derby 10.8</li>
<li>Firebird 2.5.1</li>
<li>H2 1.3.161</li>
<li>HSQLDB 2.2.5</li>
<li>Ingres 10.1.0</li>
<li>MariaDB 5.2</li>
<li>MySQL 5.1.41 and 5.5.8</li>
<li>Oracle XE 10.2.0.1.0 and 11g</li>
<li>PostgreSQL 9.0</li>
<li>SQLite with inofficial JDBC driver v056</li>
<li>SQL Server 2008 R8 and 2012</li>
<li>Sybase Adaptive Server Enterprise 15.5</li>
<li>Sybase SQL Anywhere 12</li>
</ul>
<p>
These platforms have been observed to work as well, but are not integration-tested
</p>
<ul>
<li>Google Cloud SQL (MySQL)</li>
</ul>
<h3>Databases planned for support</h3>
<p>
Any of the following databases might be available in the future
</p>
<ul>
<li>Informix</li>
<li>Interbase</li>
<li>MS Excel</li>
<li>SQL Azure</li>
<li>Sybase SQL Anywhere OnDemand</li>
<li>Teradata</li>
</ul>
<h3>Databases being watched</h3>
<p>
Any of the following databases are being observed for a potential integration
</p>
<ul>
<li>Mondrian</li>
<li>Netezza</li>
<li>SQLFire</li>
<li>Vectorwise</li>
<li>Vertica</li>
<li>VoltDB</li>
</ul>
<h3>Feature matrix</h3>
<p>
This section will soon contain a feature matrix, documenting what feature is available for which database.
</p>
</html></content>
</section>
<section id="reference-data-types">
<title>Data types</title>
<content><html>
<p>
There is always a small mismatch between SQL data types and Java data types. This is for two reasons:
</p>
<ul>
<li>SQL data types are insufficiently covered by the JDBC API.</li>
<li>Java data types are often less expressive than SQL data types</li>
</ul>
<p>
This chapter should document the most important notes about SQL, JDBC and jOOQ data types.
</p>
</html></content>
<sections>
<section id="data-types-lobs">
<title>BLOBs and CLOBs</title>
<content><html>
<p>
jOOQ currently doesn't explicitly support JDBC BLOB and CLOB data types. If you use any of these data types in your database, jOOQ will map them to byte[] and String instead. In simple cases (small data), this simplification is sufficient. In more sophisticated cases, you may have to bypass jOOQ, in order to deal with these data types and their respective resources. True support for LOBs is on the roadmap, though.
</p>
</html></content>
</section>
<section id="data-types-unsigned">
<title>Unsigned integer types</title>
<content><html>
<p>
Some databases explicitly support unsigned integer data types. In most normal JDBC-based applications, they would just be mapped to their signed counterparts letting bit-wise shifting and tweaking to the user. jOOQ ships with a set of unsigned <reference class="java.lang.Number"/> implementations modelling the following types:
</p>
<ul>
<li><reference class="org.jooq.types.UByte"/>: Unsigned byte, an 8-bit unsigned integer</li>
<li><reference class="org.jooq.types.UShort"/>: Unsigned short, a 16-bit unsigned integer</li>
<li><reference class="org.jooq.types.UInteger"/>: Unsigned int, a 32-bit unsigned integer</li>
<li><reference class="org.jooq.types.ULong"/>: Unsigned long, a 64-bit unsigned integer</li>
</ul>
<p>
Each of these wrapper types extends <reference class="java.lang.Number"/>, wrapping a higher-level integer type, internally:
</p>
<ul>
<li>UByte wraps <reference class="java.lang.Short"/></li>
<li>UShort wraps <reference class="java.lang.Integer"/></li>
<li>UInteger wraps <reference class="java.lang.Long"/></li>
<li>ULong wraps <reference class="java.math.BigInteger"/></li>
</ul>
</html></content>
</section>
<section id="data-types-intervals">
<title>INTERVAL data types</title>
<content><html>
<p>
jOOQ fills a gap opened by JDBC, which neglects an important SQL data type as defined by the SQL standards: INTERVAL types. SQL knows two different types of intervals:
</p>
<ul>
<li><strong>YEAR TO MONTH</strong>: This interval type models a number of months and years</li>
<li><strong>DAY TO SECOND</strong>: This interval type models a number of days, hours, minutes, seconds and milliseconds</li>
</ul>
<p>
Both interval types ship with a variant of subtypes, such as DAY TO HOUR, HOUR TO SECOND, etc. jOOQ models these types as Java objects extending <reference class="java.lang.Number"/>: <reference class="org.jooq.types.YearToMonth"/> (where Number.intValue() corresponds to the absolute number of months) and <reference class="org.jooq.types.DayToSecond"/> (where Number.intValue() corresponds to the absolute number of milliseconds)
</p>
<h3>Interval arithmetic</h3>
<p>
In addition to the <reference id="arithmetic-expressions" title="arithmetic expressions"/> documented previously, interval arithmetic is also supported by jOOQ. Essentially, the following operations are supported:
</p>
<ul>
<li>DATETIME - DATETIME => INTERVAL</li>
<li>DATETIME + or - INTERVAL => DATETIME</li>
<li>INTERVAL + DATETIME => DATETIME</li>
<li>INTERVAL + - INTERVAL => INTERVAL</li>
<li>INTERVAL * or / NUMERIC => INTERVAL</li>
<li>NUMERIC * INTERVAL => INTERVAL</li>
</ul>
</html></content>
</section>
<section id="data-types-xml">
<title>XML data types</title>
<content><html>
<p>
XML data types are currently not supported
</p>
</html></content>
</section>
<section id="data-types-geospacial">
<title>Geospacial data types</title>
<content><html>
<h3>Geospacial data types</h3>
<p>
Geospacial data types are currently not supported
</p>
</html></content>
</section>
<section id="data-types-cursors">
<title>CURSOR data types</title>
<content><html>
<p>
Some databases support cursors returned from stored procedures. They are mapped to the following jOOQ data type:
</p>
</html><java><![CDATA[Field<Result<Record>> cursor;]]></java><html>
<p>
In fact, such a cursor will be fetched immediately by jOOQ and wrapped in an <reference class="org.jooq.Result"/> object.
</p>
</html></content>
</section>
<section id="data-types-arrays">
<title>ARRAY and TABLE data types</title>
<content><html>
<p>
The SQL standard specifies ARRAY data types, that can be mapped to Java arrays as such:
</p>
</html><java><![CDATA[Field<Integer[]> intArray;]]></java><html>
<p>
The above array type is supported by these SQL dialects:
</p>
<ul>
<li>H2</li>
<li>HSQLDB</li>
<li>Postgres</li>
</ul>
<h3>Oracle typed arrays</h3>
<p>
Oracle has strongly-typed arrays and table types (as opposed to the previously seen anonymously typed arrays). These arrays are wrapped by <reference class="org.jooq.ArrayRecord"/> types.
</p>
</html></content>
</section>
<section id="data-types-oracle-date">
<title>Oracle DATE data type</title>
<content><html>
<p>
Oracle's <code>DATE</code> data type does not conform to the SQL standard. It is really a <code>TIMESTAMP(0)</code>, i.e. a <code>TIMESTAMP</code> with a fractional second precision of zero. The most appropriate JDBC type for Oracle <code>DATE</code> types is <reference class="java.sql.Timestamp"/>.
</p>
<h3>Performance implications</h3>
<p>
When binding <code>TIMESTAMP</code> variables to SQL statements, instead of truncating such variables to <code>DATE</code>, the cost based optimiser may choose to widen the database column from <code>DATE</code> to <code>TIMESTAMP</code> using an Oracle <code>INTERNAL_FUNCTION()</code>, which prevents index usage. <a href="http://stackoverflow.com/q/6612679/521799">Details about this behaviour can be seen in this Stack Overflow question</a>.
</p>
<p>
In order to prevent this behaviour, you should register <reference class="org.jooq.impl.DateAsTimestampBinding"/> as a <reference id="custom-data-type-bindings" title="custom data type binding"/> to all your <code>DATE</code> columns:
</p>
</html><xml><![CDATA[<database>
<customTypes>
<customType>
<name>org.jooq.impl.DateAsTimestampBinding</name>
<type>java.sql.Timestamp</type>
<binding>org.jooq.impl.DateAsTimestampBinding</binding>
</customType>
</customTypes>
<forcedTypes>
<forcedType>
<name>org.jooq.impl.DateAsTimestampBinding</name>
<types>DATE</types>
</forcedType>
</forcedTypes>
</database>]]></xml><html>
<p>
For more information, please refer to <reference id="custom-data-type-bindings" title="the manual's section about custom data type bindings"/>.
</p>
</html></content>
</section>
</sections>
</section>
<section id="dsl-mapping-rules">
<title>SQL to DSL mapping rules</title>
<content><html>
<p>
jOOQ takes SQL as an external domain-specific language and maps it onto Java, creating an internal domain-specific language. Internal DSLs cannot 100% implement their external language counter parts, as they have to adhere to the syntax rules of their host or target language (i.e. Java). This section explains the various problems and workarounds encountered and implemented in jOOQ.
</p>
<h3>SQL allows for "keywordless" syntax</h3>
<p>
SQL syntax does not always need keywords to form expressions. The <code><reference id="update-statement" title="UPDATE .. SET"/></code> clause takes various argument assignments:
</p>
</html><code-pair>
<sql>UPDATE t SET a = 1, b = 2</sql>
<java>update(t).set(a, 1).set(b, 2)</java>
</code-pair><html>
<p>
The above example also shows missing operator overloading capabilities, where <code>"="</code> is replaced by <code>","</code> in jOOQ. Another example are <reference id="row-value-expressions" title="row value expressions"/>, which can be formed with parentheses only in SQL:
</p>
</html><code-pair>
<sql>(a, b) IN ((1, 2), (3, 4))</sql>
<java>row(a, b).in(row(1, 2), row(3, 4))</java>
</code-pair><html>
<p>
In this case, <code>ROW</code> is an actual (optional) SQL keyword, implemented by at least PostgreSQL.
</p>
<h3>SQL contains "composed" keywords</h3>
<p>
As most languages, SQL does not attribute any meaning to whitespace. However, whitespace is important when forming "composed" keywords, i.e. SQL clauses composed of several keywords. jOOQ follows standard Java method naming conventions to map SQL keywords (case-insensitive) to Java methods (case-sensitive, camel-cased). Some examples:
</p>
</html><code-pair>
<sql>GROUP BY
ORDER BY
WHEN MATCHED THEN UPDATE</sql>
<java>groupBy()
orderBy()
whenMatchedThenUpdate()</java>
</code-pair><html>
<p>
Future versions of jOOQ may use all-uppercased method names in addition to the camel-cased ones (to prevent collisions with Java keywords):
</p>
</html><code-pair>
<sql>GROUP BY
ORDER BY
WHEN MATCHED THEN UPDATE</sql>
<java>GROUP_BY()
ORDER_BY()
WHEN_MATCHED_THEN_UPDATE()</java>
</code-pair><html>
<h3>SQL contains "superfluous" keywords</h3>
<p>
Some SQL keywords aren't really necessary. They are just part of a keyword-rich language, the way Java developers aren't used to anymore. These keywords date from times when languages such as ADA, BASIC, COBOL, FORTRAN, PASCAL were more verbose:
</p>
<ul>
<li><code>BEGIN .. END</code></li>
<li><code>REPEAT .. UNTIL</code></li>
<li><code>IF .. THEN .. ELSE .. END IF</code></li>
</ul>
<p>
jOOQ omits some of those keywords when it is too tedious to write them in Java.
</p>
</html><code-pair>
<sql>CASE WHEN .. THEN .. END</sql>
<java>decode().when(.., ..)</java>
</code-pair><html>
<p>
The above example omits <code>THEN</code> and <code>END</code> keywords in Java. Future versions of jOOQ may comprise a more complete DSL, including such keywords again though, to provide a more 1:1 match for the SQL language.
</p>
<h3>SQL contains "superfluous" syntactic elements</h3>
<p>
Some SQL constructs are hard to map to Java, but they are also not really necessary. SQL often expects syntactic parentheses where they wouldn't really be needed, or where they feel slightly inconsistent with the rest of the SQL language.
</p>
</html><code-pair>
<sql>LISTAGG(a, b) WITHIN GROUP (ORDER BY c)
OVER (PARTITION BY d)</sql>
<java>listagg(a, b).withinGroupOrderBy(c)
.over().partitionBy(d)</java>
</code-pair><html>
<p>
The parentheses used for the <code>WITHIN GROUP (..)</code> and <code>OVER (..)</code> clauses are required in SQL but do not seem to add any immediate value. In some cases, jOOQ omits them, although the above might be optionally re-phrased in the future to form a more SQLesque experience:
</p>
</html><code-pair>
<sql>LISTAGG(a, b) WITHIN GROUP (ORDER BY c)
OVER (PARTITION BY d)</sql>
<java>listagg(a, b).withinGroup(orderBy(c))
.over(partitionBy(d))</java>
</code-pair><html>
<h3>SQL uses some of Java's reserved words</h3>
<p>
Some SQL keywords map onto <a href="http://download.oracle.com/javase/tutorial/java/nutsandbolts/_keywords.html">Java Language Keywords</a> if they're mapped using camel-casing. These keywords currently include:
</p>
<ul>
<li><code>CASE</code></li>
<li><code>ELSE</code></li>
<li><code>FOR</code></li>
</ul>
<p>
jOOQ replaces those keywords by "synonyms":
</p>
</html><code-pair>
<sql>CASE .. ELSE
PIVOT .. FOR .. IN ..</sql>
<java>decode() .. otherwise()
pivot(..).on(..).in(..)</java>
</code-pair><html>
<p>
There is more future collision potential with:
</p>
<ul>
<li><code>BOOLEAN</code></li>
<li><code>CHAR</code></li>
<li><code>DEFAULT</code></li>
<li><code>DOUBLE</code></li>
<li><code>ENUM</code></li>
<li><code>FLOAT</code></li>
<li><code>IF</code></li>
<li><code>INT</code></li>
<li><code>LONG</code></li>
<li><code>PACKAGE</code></li>
</ul>
<h3>SQL operators cannot be overloaded in Java</h3>
<p>
Most SQL operators have to be mapped to descriptive method names in Java, as Java does not allow operator overloading:
</p>
</html><code-pair>
<sql><![CDATA[=
<>, !=
||
SET a = b]]></sql>
<java>equal(), eq()
notEqual(), ne()
concat()
set(a, b)</java>
</code-pair><html>
<p>
For those users using <reference id="scala-sql-building" title="jOOQ with Scala or Groovy"/>, operator overloading and implicit conversion can be leveraged to enhance jOOQ:
</p>
</html><code-pair>
<sql><![CDATA[=
<>, !=
||]]></sql>
<java><![CDATA[===
<>, !==
||]]></java>
</code-pair><html>
<h3>SQL's reference before declaration capability</h3>
<p>
This is less of a syntactic SQL feature than a semantic one. In SQL, objects can be referenced before (i.e. "lexicographically before") they are declared. This is particularly true for <reference id="aliased-tables" title="aliasing"/>
</p>
</html><code-pair>
<sql><![CDATA[SELECT t.a
FROM my_table t]]></sql>
<java><![CDATA[MyTable t = MY_TABLE.as("t");
select(t.a).from(t)]]></java>
</code-pair><html>
<p>
A more sophisticated example are common table expressions (CTE), which are currently not supported by jOOQ:
</p>
</html><sql>WITH t(a, b) AS (
SELECT 1, 2 FROM DUAL
)
SELECT t.a, t.b
FROM t</sql><html>
<p>
Common table expressions define a "derived column list", just like <reference id="aliased-tables" title="table aliases"/> can do. The formal record type thus created cannot be typesafely verified by the Java compiler, i.e. it is not possible to formally dereference <code>t.a</code> from <code>t</code>.
</p>
</html></content>
</section>
<section id="reference-bnf-notation">
<title>jOOQ's BNF pseudo-notation</title>
<content><html>
<p>
This chapter will soon contain an overview over jOOQ's API using a pseudo BNF notation.
</p>
</html></content>
</section>
<section id="quality-assurance">
<title>Quality Assurance</title>
<content><html>
<p>
jOOQ is running some of your most mission-critical logic: the interface layer between your Java / Scala application and the database. You have probably chosen jOOQ for any of the following reasons:
</p>
<ul>
<li>To evade JDBC's verbosity and error-proneness due to string concatenation and index-based variable binding</li>
<li>To add lots of type-safety to your inline SQL</li>
<li>To increase productivity when writing inline SQL using your favourite IDE's autocompletion capabilities</li>
</ul>
<p>
With jOOQ being in the core of your application, you want to be sure that you can trust jOOQ. That is why jOOQ is heavily unit and integration tested with a strong focus on integration tests:
</p>
<h3>Unit tests</h3>
<p>
Unit tests are performed against dummy JDBC interfaces using <a href="http://jmock.org/" title="jmock">http://jmock.org/</a>. These tests verify that various <reference class="org.jooq.QueryPart"/> implementations render correct SQL and bind variables correctly.
</p>
<h3>Integration tests</h3>
<p>
This is the most important part of the jOOQ test suites. Some 1500 queries are currently run against a standard integration test database. Both the test database and the queries are translated into every one of the 14 supported SQL dialects to ensure that regressions are unlikely to be introduced into the code base.
</p>
<p>
For libraries like jOOQ, integration tests are much more expressive than unit tests, as there are so many subtle differences in SQL dialects. Simple mocks just don't give as much feedback as an actual database instance.
</p>
<p>
jOOQ integration tests run the weirdest and most unrealistic queries. As a side-effect of these extensive integration test suites, many corner-case bugs for JDBC drivers and/or open source databases have been discovered, feature requests submitted through jOOQ and reported mainly to CUBRID, Derby, H2, HSQLDB.
</p>
<h3>Code generation tests</h3>
<p>
For every one of the 14 supported integration test databases, source code is generated and the tiniest differences in generated source code can be discovered. In case of compilation errors in generated source code, new test tables/views/columns are added to avoid regressions in this field.
</p>
<h3>API Usability tests and proofs of concept</h3>
<p>
jOOQ is used in jOOQ-meta as a proof of concept. This includes complex queries such as the following Postgres query
</p>
</html><java><![CDATA[Routines r1 = ROUTINES.as("r1");
Routines r2 = ROUTINES.as("r2");
for (Record record : create().select(
r1.ROUTINE_SCHEMA,
r1.ROUTINE_NAME,
r1.SPECIFIC_NAME,
// Ignore the data type when there is at least one out parameter
DSL.when(exists(
selectOne()
.from(PARAMETERS)
.where(PARAMETERS.SPECIFIC_SCHEMA.equal(r1.SPECIFIC_SCHEMA))
.and(PARAMETERS.SPECIFIC_NAME.equal(r1.SPECIFIC_NAME))
.and(upper(PARAMETERS.PARAMETER_MODE).notEqual("IN"))),
val("void"))
.otherwise(r1.DATA_TYPE).as("data_type"),
r1.CHARACTER_MAXIMUM_LENGTH,
r1.NUMERIC_PRECISION,
r1.NUMERIC_SCALE,
r1.TYPE_UDT_NAME,
// Calculate overload index if applicable
DSL.when(
exists(
selectOne()
.from(r2)
.where(r2.ROUTINE_SCHEMA.in(getInputSchemata()))
.and(r2.ROUTINE_SCHEMA.equal(r1.ROUTINE_SCHEMA))
.and(r2.ROUTINE_NAME.equal(r1.ROUTINE_NAME))
.and(r2.SPECIFIC_NAME.notEqual(r1.SPECIFIC_NAME))),
select(count())
.from(r2)
.where(r2.ROUTINE_SCHEMA.in(getInputSchemata()))
.and(r2.ROUTINE_SCHEMA.equal(r1.ROUTINE_SCHEMA))
.and(r2.ROUTINE_NAME.equal(r1.ROUTINE_NAME))
.and(r2.SPECIFIC_NAME.lessOrEqual(r1.SPECIFIC_NAME)).asField())
.as("overload"))
.from(r1)
.where(r1.ROUTINE_SCHEMA.in(getInputSchemata()))
.orderBy(
r1.ROUTINE_SCHEMA.asc(),
r1.ROUTINE_NAME.asc())
.fetch()) {
result.add(new PostgresRoutineDefinition(this, record));
}]]></java><html>
<p>
These rather complex queries show that the jOOQ API is fit for advanced SQL use-cases, compared to the rather simple, often unrealistic queries in the integration test suite.
</p>
<h3>Clean API and implementation. Code is kept DRY</h3>
<p>
As a general rule of thumb throughout the jOOQ code, everything is kept <a href="http://en.wikipedia.org/wiki/DRY">DRY</a>. Some examples:
</p>
<ul>
<li>There is only one place in the entire code base, which consumes values from a JDBC ResultSet</li>
<li>There is only one place in the entire code base, which transforms jOOQ Records into custom POJOs</li>
</ul>
<p>
Keeping things DRY leads to longer stack traces, but in turn, also increases the relevance of highly reusable code-blocks. Chances that some parts of the jOOQ code base slips by integration test coverage decrease significantly.
</p>
</html></content>
</section>
<section id="migrating-to-3.0">
<title>Migrating to jOOQ 3.0</title>
<content><html>
<p>
This section is for all users of jOOQ 2.x who wish to upgrade to the next major release. In the next sub-sections, the most important changes are explained. Some code hints are also added to help you fix compilation errors.
</p>
<h3>Type-safe row value expressions</h3>
<p>
Support for <reference id="row-value-expressions" title="row value expressions"/> has been added in jOOQ 2.6. In jOOQ 3.0, many API parts were thoroughly (but often incompatibly) changed, in order to provide you with even more type-safety.
</p>
<p>
Here are some affected API parts:
</p>
<ul>
<li>[N] in Row[N] has been raised from 8 to 22. This means that existing row value expressions with degree >= 9 are now type-safe</li>
<li>Subqueries returned from <code>DSL.select(...)</code> now implement <code>Select&lt;Record[N]>, not Select&lt;Record></code></li>
<li><code>IN</code> predicates and comparison predicates taking subselects changed incompatibly</li>
<li><code>INSERT</code> and <code>MERGE</code> statements now take typesafe <code>VALUES()</code> clauses</li>
</ul>
<p>
Some hints related to row value expressions:
</p>
</html><java><![CDATA[// SELECT statements are now more typesafe:
Record2<String, Integer> record = create.select(BOOK.TITLE, BOOK.ID).from(BOOK).where(ID.eq(1)).fetchOne();
Result<Record2<String, Integer>> result = create.select(BOOK.TITLE, BOOK.ID).from(BOOK).fetch();
// But Record2 extends Record. You don't have to use the additional typesafety:
Record record = create.select(BOOK.TITLE, BOOK.ID).from(BOOK).where(ID.eq(1)).fetchOne();
Result<?> result = create.select(BOOK.TITLE, BOOK.ID).from(BOOK).fetch();]]></java><html>
<h3>SelectQuery and SelectXXXStep are now generic</h3>
<p>
In order to support type-safe row value expressions and type-safe Record[N] types, SelectQuery is now generic: SelectQuery&lt;R>
</p>
<h3>SimpleSelectQuery and SimpleSelectXXXStep API were removed</h3>
<p>
The duplication of the SELECT API is no longer useful, now that SelectQuery and SelectXXXStep are generic.
</p>
<h3>Factory was split into DSL (query building) and DSLContext (query execution)</h3>
<p>
The pre-existing Factory class has been split into two parts:
</p>
<ol>
<li><strong>The DSL</strong>: This class contains only static factory methods. All QueryParts constructed from this class are "unattached", i.e. queries that are constructed through DSL cannot be executed immediately. This is useful for subqueries.<br/>The DSL class corresponds to the static part of the jOOQ 2.x Factory type</li>
<li><strong>The DSLContext</strong>: This type holds a reference to a Configuration and can construct executable ("attached") QueryParts.<br/>The DSLContext type corresponds to the non-static part of the jOOQ 2.x Factory / FactoryOperations type.</li>
</ol>
<p>
The FactoryOperations interface has been renamed to DSLContext. An example:
</p>
</html><java><![CDATA[// jOOQ 2.6, check if there are any books
Factory create = new Factory(connection, dialect);
create.selectOne()
.whereExists(
create.selectFrom(BOOK) // Reuse the factory to create subselects
).fetch(); // Execute the "attached" query
// jOOQ 3.0
DSLContext create = DSL.using(connection, dialect);
create.selectOne()
.whereExists(
selectFrom(BOOK) // Create a static subselect from the DSL
).fetch(); // Execute the "attached" query]]></java><html>
<h3>Quantified comparison predicates</h3>
<p>
Field.equalAny(...) and similar methods have been removed in favour of Field.equal(any(...)). This greatly simplified the Field API. An example:
</p>
</html><java><![CDATA[// jOOQ 2.6
Condition condition = BOOK.ID.equalAny(create.select(BOOK.ID).from(BOOK));
// jOOQ 3.0 adds some typesafety to comparison predicates involving quantified selects
QuantifiedSelect<Record1<Integer>> subselect = any(select(BOOK.ID).from(BOOK));
Condition condition = BOOK.ID.equal(subselect);]]></java><html>
<h3>FieldProvider</h3>
<p>
The FieldProvider marker interface was removed. Its methods still exist on FieldProvider subtypes. Note, they have changed names from <code>getField()</code> to <code>field()</code> and from <code>getIndex()</code> to <code>indexOf()</code>
</p>
<h3>GroupField</h3>
<p>
GroupField has been introduced as a DSL marker interface to denote fields that can be passed to <code>GROUP BY</code> clauses. This includes all org.jooq.Field types. However, fields obtained from <code>ROLLUP()</code>, <code>CUBE()</code>, and <code>GROUPING SETS()</code> functions no longer implement Field. Instead, they only implement GroupField. An example:
</p>
</html><java><![CDATA[// jOOQ 2.6
Field<?> field1a = Factory.rollup(...); // OK
Field<?> field2a = Factory.one(); // OK
// jOOQ 3.0
GroupField field1b = DSL.rollup(...); // OK
Field<?> field1c = DSL.rollup(...); // Compilation error
GroupField field2b = DSL.one(); // OK
Field<?> field2c = DSL.one(); // OK]]></java><html>
<h3>NULL predicate</h3>
<p>
Beware! Previously, Field.equal(null) was translated internally to an IS NULL predicate. This is no longer the case. Binding Java "null" to a comparison predicate will result in a regular comparison predicate (which never returns true). This was changed for several reasons:
</p>
<ul>
<li>To most users, this was a surprising "feature".</li>
<li>Other predicates didn't behave in such a way, e.g. the IN predicate, the BETWEEN predicate, or the LIKE predicate.</li>
<li>Variable binding behaved unpredictably, as IS NULL predicates don't bind any variables.</li>
<li>The generated SQL depended on the possible combinations of bind values, which creates unnecessary hard-parses every time a new unique SQL statement is rendered.</li>
</ul>
<p>
Here is an example how to check if a field has a given value, without applying SQL's ternary NULL logic:
</p>
</html><java><![CDATA[String possiblyNull = null; // Or else...
// jOOQ 2.6
Condition condition1 = BOOK.TITLE.equal(possiblyNull);
// jOOQ 3.0
Condition condition2 = BOOK.TITLE.equal(possiblyNull).or(BOOK.TITLE.isNull().and(val(possiblyNull).isNull()));
Condition condition3 = BOOK.TITLE.isNotDistinctFrom(possiblyNull);]]></java><html>
<h3>Configuration</h3>
<p>
<code>DSLContext</code>, <code>ExecuteContext</code>, <code>RenderContext</code>, <code>BindContext</code> no longer extend <code>Configuration</code> for "convenience". From jOOQ 3.0 onwards, composition is chosen over inheritance as these objects are not really configurations. Most importantly
</p>
<ul>
<li><code>DSLContext</code> is only a DSL entry point for constructing "attached" QueryParts</li>
<li><code>ExecuteContext</code> has a well-defined lifecycle, tied to that of a single query execution</li>
<li><code>RenderContext</code> has a well-defined lifecycle, tied to that of a single rendering operation</li>
<li><code>BindContext</code> has a well-defined lifecycle, tied to that of a single variable binding operation</li>
</ul>
<p>
In order to resolve confusion that used to arise because of different lifecycle durations, these types are now no longer formally connected through inheritance.
</p>
<h3>ConnectionProvider</h3>
<p>
In order to allow for simpler connection / data source management, jOOQ externalised connection handling in a new ConnectionProvider type. The previous two connection modes are maintained backwards-compatibly (JDBC standalone connection mode, pooled DataSource mode). Other connection modes can be injected using:
</p>
</html><java><![CDATA[public interface ConnectionProvider {
// Provide jOOQ with a connection
Connection acquire() throws DataAccessException;
// Get a connection back from jOOQ
void release(Connection connection) throws DataAccessException;
}]]></java><html>
<p>
These are some side-effects of the above change
</p>
<ul>
<li>Connection-related JDBC wrapper utility methods (commit, rollback, etc) have been moved to the new DefaultConnectionProvider. They're no longer available from the DSLContext. This had been confusing to some users who called upon these methods while operating in pool DataSource mode.</li>
</ul>
<h3>ExecuteListeners</h3>
<p>
ExecuteListeners can no longer be configured via Settings. Instead they have to be injected into the Configuration. This resolves many class loader issues that were encountered before. It also helps listener implementations control their lifecycles themselves.
</p>
<h3>Data type API</h3>
<p>
The data type API has been changed drastically in order to enable some new DataType-related features. These changes include:
</p>
<ul>
<li>[SQLDialect]DataType and SQLDataType no longer implement DataType. They're mere constant containers</li>
<li>Various minor API changes have been done.</li>
</ul>
<h3>Object renames</h3>
<p>
These objects have been moved / renamed:
</p>
<ul>
<li>jOOU: a library used to represent unsigned integer types was moved from <code>org.jooq.util.unsigned</code> to <code>org.jooq.util.types</code> (which already contained INTERVAL data types)</li>
</ul>
<h3>Feature removals</h3>
<p>
Here are some minor features that have been removed in jOOQ 3.0
</p>
<ul>
<li>The ant task for code generation was removed, as it was not up to date at all. Code generation through ant can be performed easily by calling jOOQ's GenerationTool through a &lt;java> target.</li>
<li>The navigation methods and "foreign key setters" are no longer generated in Record classes, as they are useful only to few users and the generated code is very collision-prone.</li>
<li>The code generation configuration no longer accepts comma-separated regular expressions. Use the regex pipe | instead.</li>
<li>The code generation configuration can no longer be loaded from .properties files. Only XML configurations are supported.</li>
<li>The master data type feature is no longer supported. This feature was unlikely to behave exactly as users expected. It is better if users write their own code generators to generate master enum data types from their database tables. jOOQ's enum mapping and converter features sufficiently cover interacting with such user-defined types.</li>
<li>The DSL subtypes are no longer instanciable. As DSL now only contains static methods, subclassing is no longer useful. There are still dialect-specific DSL types providing static methods for dialect-specific functions. But the code-generator no longer generates a schema-specific DSL</li>
<li>The concept of a "main key" is no longer supported. The code generator produces UpdatableRecords only if the underlying table has a PRIMARY KEY. The reason for this removal is the fact that "main keys" are not reliable enough. They were chosen arbitrarily among UNIQUE KEYs.</li>
<li>The UpdatableTable type has been removed. While adding significant complexity to the type hierarchy, this type adds not much value over a simple <code>Table.getPrimaryKey() != null</code> check.</li>
<li>The <code>USE</code> statement support has been removed from jOOQ. Its behaviour was ill-defined, while it didn't work the same way (or didn't work at all) in some databases.</li>
</ul>
</html></content>
</section>
<!--
<section id="reference-glossary">
Analytical function -> window function
Arity -> Degree
AST
Batch
BNF
Catalog
Clause
Code generation
Column -> Field
Column expression
Common table expression
Condition -> Predicate
Configuration
Connection
CRUD -> OLTP
DAO
Database
DataSource
Degree
Dialect
Domain Specific language (internal / external)
DSL
DSLContext
Execute
Execute listener
Execution lifecycle
Export
Expression
Fetch
Field
Function
Generic R-type
Generic T-type
JDBC
JPQL
Hibernate
Hierarchical query
HQL
Identifier
Import
Keyword
LINQ
Literal
Locking (optimistic / pessimistic)
Name -> Identifier
OLAP
OLTP
Pivot
POJO
Predicate
PreparedStatement
Procedure
Projection
Query
Schema
Settings
SLICK
SQL
SQL building
SQL execution
SQL standard
Statement
Table
Table expression
Record
Row
Row value expression
Result
ResultQuery
UDT
View
Window function
</section>
-->
<section id="reference-credits">
<title>Credits</title>
<content><html>
<p>
jOOQ lives in a very challenging ecosystem. The Java to SQL interface is still one of the most important system interfaces. Yet there are still a lot of open questions, best practices and no "true" standard has been established. This situation gave way to a lot of tools, APIs, utilities which essentially tackle the same problem domain as jOOQ. jOOQ has gotten great inspiration from pre-existing tools and this section should give them some credit. Here is a list of inspirational tools in alphabetical order:
</p>
<ul>
<li><a href="http://www.hibernate.org">Hibernate</a>: The de-facto standard (JPA) with its useful table-to-POJO mapping features have influenced jOOQ's <reference class="org.jooq.ResultQuery" anchor="#fetchInto(java.lang.Class)"/> facilities</li>
<li><a href="http://www.h2database.com/html/jaqu.html">JaQu</a>: H2's own fluent API for querying databases</li>
<li><a href="http://www.oracle.com/technetwork/java/javaee/tech/persistence-jsp-140049.html">JPA</a>: The de-facto standard in the javax.persistence packages, supplied by Oracle. Its annotations are useful to jOOQ as well.</li>
<li><a href="http://onewebsql.com">OneWebSQL</a>: A commercial SQL abstraction API with support for DAO source code generation, which was integrated also in jOOQ</li>
<li><a href="http://www.querydsl.com">QueryDSL</a>: A "LINQ-port" to Java. It has a similar fluent API, a similar code-generation facility, yet quite a different purpose. While jOOQ is all about SQL, QueryDSL (like LINQ) is mostly about querying.</li>
<li><a href="http://slick.typesafe.com">SLICK</a>: A "LINQ-like" database abstraction layer for Scala. Unlike LINQ, its API doesn't really remind of SQL. Instead, it makes SQL look like Scala.</li>
<li><a href="http://www.springsource.org/features/data-access">Spring Data</a>: Spring's JdbcTemplate knows RowMappers, which are reflected by jOOQ's <reference id="recordhandler"/> or <reference id="recordmapper"/></li>
</ul>
</html></content>
</section>
</sections>
</section>
</sections>
</section>
</manual>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment