The jOOQ™ User Manual

The jOOQ™ User Manual

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!

The jOOQ User Manual

Overview

This manual is divided into six main sections:

-

Getting started with jOOQ

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

-

SQL building

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

-

Code generation

This section explains how to configure and use the built-in source code generator

-

SQL execution

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

-

Tools

This section is dedicated to tools that ship with jOOQ, such as the jOOQ's JDBC mocking feature

-

Reference

This section is a reference for elements in this manual

© 2009 - 2014 by Data Geekery™ GmbH. All rights reserved.

Page 2 / 245


Table of contents

1. Preface.................................................................................................................................................................................................................. 8

2. Copyright, License, and Trademarks.......................................................................................................................................................... 10

3. Getting started with jOOQ............................................................................................................................................................................ 14

3.1. How to read this manual........................................................................................................................................................................... 14

3.2. The sample database used in this manual........................................................................................................................................... 15

3.3. Different use cases for jOOQ................................................................................................................................................................... 16

3.3.1. jOOQ as a SQL builder........................................................................................................................................................................... 17

3.3.2. jOOQ as a SQL builder with code generation.................................................................................................................................. 18

3.3.3. jOOQ as a SQL executor........................................................................................................................................................................ 18

3.3.4. jOOQ for CRUD......................................................................................................................................................................................... 19

3.3.5. jOOQ for PROs.......................................................................................................................................................................................... 20

3.4. Tutorials........................................................................................................................................................................................................... 20

3.4.1. jOOQ in 7 easy steps.............................................................................................................................................................................. 20

3.4.1.1. Step 1: Preparation............................................................................................................................................................................... 20

3.4.1.2. Step 2: Your database.......................................................................................................................................................................... 21

3.4.1.3. Step 3: Code generation..................................................................................................................................................................... 21

3.4.1.4. Step 4: Connect to your database................................................................................................................................................... 23

3.4.1.5. Step 5: Querying.................................................................................................................................................................................... 24

3.4.1.6. Step 6: Iterating..................................................................................................................................................................................... 24

3.4.1.7. Step 7: Explore!...................................................................................................................................................................................... 25

3.4.2. Using jOOQ in modern IDEs................................................................................................................................................................. 25

3.4.3. Using jOOQ with Spring and Apache DBCP...................................................................................................................................... 25

3.4.4. Using jOOQ with Flyway.......................................................................................................................................................................... 29

3.4.5. Using jOOQ with ERD tools................................................................................................................................................................... 35

3.4.6. Using jOOQ with JAX-RS.......................................................................................................................................................................... 37

3.4.7. A simple web application with jOOQ.................................................................................................................................................. 43

3.5. jOOQ and Java 8.......................................................................................................................................................................................... 43

3.6. jOOQ and JavaFX.......................................................................................................................................................................................... 44

3.7. jOOQ and Nashorn...................................................................................................................................................................................... 48

3.8. jOOQ and Scala............................................................................................................................................................................................ 48

3.9. jOOQ and Groovy......................................................................................................................................................................................... 49

3.10. jOOQ and NoSQL...................................................................................................................................................................................... 50

3.11. Dependencies............................................................................................................................................................................................. 50

3.12. Build your own........................................................................................................................................................................................... 50

3.13. jOOQ and backwards-compatibility...................................................................................................................................................... 51

4. SQL building...................................................................................................................................................................................................... 53

4.1. The query DSL type..................................................................................................................................................................................... 53

4.1.1. DSL subclasses.......................................................................................................................................................................................... 54

4.2. The DSLContext class.................................................................................................................................................................................. 54

4.2.1. SQL Dialect................................................................................................................................................................................................. 55

4.2.2. SQL Dialect Family.................................................................................................................................................................................... 56

4.2.3. Connection vs. DataSource.................................................................................................................................................................... 57

4.2.4. Custom data............................................................................................................................................................................................... 58

4.2.5. Custom ExecuteListeners....................................................................................................................................................................... 58

4.2.6. Custom Settings........................................................................................................................................................................................ 59

4.2.7. Runtime schema and table mapping.................................................................................................................................................. 61

4.3. SQL Statements (DML)............................................................................................................................................................................... 63

4.3.1. jOOQ's DSL and model API.................................................................................................................................................................... 63

4.3.2. The WITH clause....................................................................................................................................................................................... 65

4.3.3. The SELECT statement............................................................................................................................................................................ 66


Page 3 / 245


4.3.3.1. The SELECT clause................................................................................................................................................................................ 67

4.3.3.2. The FROM clause.................................................................................................................................................................................. 68

4.3.3.3. The JOIN clause...................................................................................................................................................................................... 69

4.3.3.4. The WHERE clause................................................................................................................................................................................ 71

4.3.3.5. The CONNECT BY clause..................................................................................................................................................................... 72

4.3.3.6. The GROUP BY clause......................................................................................................................................................................... 73

4.3.3.7. The HAVING clause............................................................................................................................................................................... 74

4.3.3.8. The WINDOW clause............................................................................................................................................................................ 74

4.3.3.9. The ORDER BY clause.......................................................................................................................................................................... 75

4.3.3.10. The LIMIT .. OFFSET clause............................................................................................................................................................... 77

4.3.3.11. The SEEK clause.................................................................................................................................................................................. 78

4.3.3.12. The FOR UPDATE clause................................................................................................................................................................... 79

4.3.3.13. UNION, INTERSECTION and EXCEPT.............................................................................................................................................. 81

4.3.3.14. Oracle-style hints................................................................................................................................................................................. 82

4.3.3.15. Lexical and logical SELECT clause order....................................................................................................................................... 83

4.3.4. The INSERT statement............................................................................................................................................................................. 84

4.3.4.1. INSERT .. VALUES................................................................................................................................................................................... 84

4.3.4.2. INSERT .. DEFAULT VALUES................................................................................................................................................................. 85

4.3.4.3. INSERT .. SET........................................................................................................................................................................................... 86

4.3.4.4. INSERT .. SELECT.................................................................................................................................................................................... 86

4.3.4.5. INSERT .. ON DUPLICATE KEY............................................................................................................................................................. 86

4.3.4.6. INSERT .. RETURNING........................................................................................................................................................................... 87

4.3.5. The UPDATE statement........................................................................................................................................................................... 87

4.3.6. The DELETE statement............................................................................................................................................................................ 89

4.3.7. The MERGE statement............................................................................................................................................................................ 89

4.4. SQL Statements (DDL)................................................................................................................................................................................ 90

4.4.1. The ALTER statement.............................................................................................................................................................................. 90

4.4.2. The CREATE statement............................................................................................................................................................................ 91

4.4.3. The DROP statement............................................................................................................................................................................... 91

4.4.4. The TRUNCATE statement...................................................................................................................................................................... 92

4.5. Table expressions......................................................................................................................................................................................... 92

4.5.1. Generated Tables...................................................................................................................................................................................... 93

4.5.2. Aliased Tables............................................................................................................................................................................................ 93

4.5.3. Joined tables............................................................................................................................................................................................... 94

4.5.4. The VALUES() table constructor............................................................................................................................................................ 95

4.5.5. Nested SELECTs......................................................................................................................................................................................... 96

4.5.6. The Oracle 11g PIVOT clause................................................................................................................................................................ 97

4.5.7. jOOQ's relational division syntax.......................................................................................................................................................... 97

4.5.8. Array and cursor unnesting................................................................................................................................................................... 98

4.5.9. Table-valued functions............................................................................................................................................................................. 98

4.5.10. The DUAL table....................................................................................................................................................................................... 99

4.6. Column expressions.................................................................................................................................................................................. 100

4.6.1. Table columns......................................................................................................................................................................................... 100

4.6.2. Aliased columns...................................................................................................................................................................................... 101

4.6.3. Cast expressions..................................................................................................................................................................................... 101

4.6.4. Datatype coercions................................................................................................................................................................................ 102

4.6.5. Arithmetic expressions.......................................................................................................................................................................... 102

4.6.6. String concatenation.............................................................................................................................................................................. 103

4.6.7. General functions................................................................................................................................................................................... 103

4.6.8. Numeric functions.................................................................................................................................................................................. 104

4.6.9. Bitwise functions..................................................................................................................................................................................... 104

4.6.10. String functions..................................................................................................................................................................................... 105

4.6.11. Date and time functions.................................................................................................................................................................... 106

4.6.12. System functions.................................................................................................................................................................................. 106


Page 4 / 245


4.6.13. Aggregate functions............................................................................................................................................................................. 106

4.6.14. Window functions................................................................................................................................................................................ 108

4.6.15. Grouping functions.............................................................................................................................................................................. 110

4.6.16. User-defined functions....................................................................................................................................................................... 112

4.6.17. User-defined aggregate functions................................................................................................................................................... 112

4.6.18. The CASE expression.......................................................................................................................................................................... 114

4.6.19. Sequences and serials........................................................................................................................................................................ 114

4.6.20. Tuples or row value expressions..................................................................................................................................................... 115

4.7. Conditional expressions........................................................................................................................................................................... 116

4.7.1. Condition building.................................................................................................................................................................................. 117

4.7.2. AND, OR, NOT boolean operators..................................................................................................................................................... 117

4.7.3. Comparison predicate........................................................................................................................................................................... 118

4.7.4. Boolean operator precedence............................................................................................................................................................ 119

4.7.5. Comparison predicate (degree > 1).................................................................................................................................................. 119

4.7.6. Quantified comparison predicate...................................................................................................................................................... 120

4.7.7. NULL predicate....................................................................................................................................................................................... 121

4.7.8. NULL predicate (degree > 1)............................................................................................................................................................... 121

4.7.9. DISTINCT predicate................................................................................................................................................................................ 121

4.7.10. BETWEEN predicate............................................................................................................................................................................. 122

4.7.11. BETWEEN predicate (degree > 1).................................................................................................................................................... 123

4.7.12. LIKE predicate....................................................................................................................................................................................... 123

4.7.13. IN predicate........................................................................................................................................................................................... 124

4.7.14. IN predicate (degree > 1)................................................................................................................................................................... 125

4.7.15. EXISTS predicate................................................................................................................................................................................... 125

4.7.16. OVERLAPS predicate........................................................................................................................................................................... 126

4.8. Plain SQL...................................................................................................................................................................................................... 126

4.9. Names and identifiers.............................................................................................................................................................................. 129

4.10. Bind values and parameters................................................................................................................................................................ 130

4.10.1. Indexed parameters............................................................................................................................................................................ 130

4.10.2. Named parameters............................................................................................................................................................................. 131

4.10.3. Inlined parameters.............................................................................................................................................................................. 132

4.10.4. SQL injection......................................................................................................................................................................................... 132

4.11. QueryParts................................................................................................................................................................................................. 133

4.11.1. SQL rendering....................................................................................................................................................................................... 133

4.11.2. Pretty printing SQL.............................................................................................................................................................................. 135

4.11.3. Variable binding.................................................................................................................................................................................... 135

4.11.4. Custom data type bindings............................................................................................................................................................... 136

4.11.5. Custom syntax elements................................................................................................................................................................... 139

4.11.6. Plain SQL QueryParts.......................................................................................................................................................................... 140

4.11.7. Serializability.......................................................................................................................................................................................... 141

4.11.8. Custom SQL transformation............................................................................................................................................................. 141

4.11.8.1. Logging abbreviated bind values.................................................................................................................................................. 141

4.12. SQL building in Scala.............................................................................................................................................................................. 142

5. SQL execution................................................................................................................................................................................................ 145

5.1. Comparison between jOOQ and JDBC................................................................................................................................................ 146

5.2. Query vs. ResultQuery.............................................................................................................................................................................. 146

5.3. Fetching........................................................................................................................................................................................................ 147

5.3.1. Record vs. TableRecord......................................................................................................................................................................... 149

5.3.2. Record1 to Record22............................................................................................................................................................................ 150

5.3.3. Arrays, Maps and Lists.......................................................................................................................................................................... 150

5.3.4. RecordHandler........................................................................................................................................................................................ 151

5.3.5. RecordMapper......................................................................................................................................................................................... 151

5.3.6. POJOs......................................................................................................................................................................................................... 152

5.3.7. POJOs with RecordMappers................................................................................................................................................................ 155


Page 5 / 245


5.3.8. Lazy fetching............................................................................................................................................................................................ 156

5.3.9. Many fetching.......................................................................................................................................................................................... 156

5.3.10. Later fetching........................................................................................................................................................................................ 157

5.3.11. ResultSet fetching................................................................................................................................................................................ 159

5.3.12. Data type conversion.......................................................................................................................................................................... 160

5.3.13. Interning data........................................................................................................................................................................................ 161

5.4. Static statements vs. Prepared Statements........................................................................................................................................ 162

5.5. Reusing a Query's PreparedStatement................................................................................................................................................ 163

5.6. JDBC flags..................................................................................................................................................................................................... 164

5.7. Using JDBC batch operations................................................................................................................................................................. 165

5.8. Sequence execution.................................................................................................................................................................................. 166

5.9. Stored procedures and functions......................................................................................................................................................... 166

5.9.1. Oracle Packages...................................................................................................................................................................................... 168

5.9.2. Oracle member procedures................................................................................................................................................................ 169

5.10. Exporting to XML, CSV, JSON, HTML, Text......................................................................................................................................... 169

5.10.1. Exporting XML....................................................................................................................................................................................... 169

5.10.2. Exporting CSV........................................................................................................................................................................................ 170

5.10.3. Exporting JSON..................................................................................................................................................................................... 170

5.10.4. Exporting HTML.................................................................................................................................................................................... 171

5.10.5. Exporting Text....................................................................................................................................................................................... 171

5.11. Importing data.......................................................................................................................................................................................... 172

5.11.1. Importing CSV....................................................................................................................................................................................... 172

5.11.2. Importing XML...................................................................................................................................................................................... 173

5.12. CRUD with UpdatableRecords............................................................................................................................................................. 174

5.12.1. Simple CRUD......................................................................................................................................................................................... 174

5.12.2. Records' internal flags........................................................................................................................................................................ 176

5.12.3. IDENTITY values.................................................................................................................................................................................... 176

5.12.4. Navigation methods............................................................................................................................................................................ 177

5.12.5. Non-updatable records...................................................................................................................................................................... 178

5.12.6. Optimistic locking................................................................................................................................................................................. 178

5.12.7. Batch execution.................................................................................................................................................................................... 180

5.12.8. CRUD SPI: RecordListener................................................................................................................................................................. 180

5.13. DAOs........................................................................................................................................................................................................... 181

5.14. Transaction management...................................................................................................................................................................... 182

5.15. Exception handling.................................................................................................................................................................................. 185

5.16. ExecuteListeners...................................................................................................................................................................................... 186

5.17. Database meta data............................................................................................................................................................................... 188

5.18. Logging....................................................................................................................................................................................................... 189

5.19. Performance considerations................................................................................................................................................................ 189

5.20. Alternative execution models............................................................................................................................................................... 190

5.20.1. Using jOOQ with JPA........................................................................................................................................................................... 190

5.20.1.1. Using jOOQ with JPA Native Query.............................................................................................................................................. 191

5.20.1.2. Using jOOQ with JPA entities......................................................................................................................................................... 192

5.20.1.3. Using jOOQ with JPA EntityResult................................................................................................................................................ 192

6. Code generation............................................................................................................................................................................................ 195

6.1. Configuration and setup of the generator......................................................................................................................................... 195

6.2. Running the code generator with Ant................................................................................................................................................. 201

6.3. Running the code generator with Gradle........................................................................................................................................... 202

6.4. Advanced generator configuration....................................................................................................................................................... 203

6.5. Programmatic generator configuration................................................................................................................................................ 207

6.6. Custom generator strategies.................................................................................................................................................................. 208

6.7. Matcher strategies..................................................................................................................................................................................... 211

6.8. Custom code sections.............................................................................................................................................................................. 213

6.9. Generated global artefacts..................................................................................................................................................................... 215


Page 6 / 245


6.10. Generated tables..................................................................................................................................................................................... 216

6.11. Generated records.................................................................................................................................................................................. 217

6.12. Generated POJOs.................................................................................................................................................................................... 218

6.13. Generated Interfaces.............................................................................................................................................................................. 219

6.14. Generated DAOs...................................................................................................................................................................................... 219

6.15. Generated sequences............................................................................................................................................................................ 220

6.16. Generated procedures........................................................................................................................................................................... 220

6.17. Generated UDTs...................................................................................................................................................................................... 221

6.18. Data type rewrites................................................................................................................................................................................... 222

6.19. Custom data types and type conversion.......................................................................................................................................... 222

6.20. Custom data type binding.................................................................................................................................................................... 223

6.21. Mapping generated schemata and tables........................................................................................................................................ 225

6.22. Code generation for large schemas................................................................................................................................................... 226

6.23. Code generation and version control................................................................................................................................................ 226

7. Tools.................................................................................................................................................................................................................. 228

7.1. JDBC mocking for unit testing................................................................................................................................................................ 228

7.2. SQL 2 jOOQ Parser................................................................................................................................................................................... 230

7.3. jOOQ Console............................................................................................................................................................................................. 231

8. Reference......................................................................................................................................................................................................... 232

8.1. Supported RDBMS..................................................................................................................................................................................... 232

8.2. Data types.................................................................................................................................................................................................... 232

8.2.1. BLOBs and CLOBs.................................................................................................................................................................................. 233

8.2.2. Unsigned integer types......................................................................................................................................................................... 233

8.2.3. INTERVAL data types............................................................................................................................................................................. 233

8.2.4. XML data types....................................................................................................................................................................................... 234

8.2.5. Geospacial data types........................................................................................................................................................................... 234

8.2.6. CURSOR data types............................................................................................................................................................................... 234

8.2.7. ARRAY and TABLE data types.............................................................................................................................................................. 234

8.2.8. Oracle DATE data type.......................................................................................................................................................................... 235

8.3. SQL to DSL mapping rules...................................................................................................................................................................... 235

8.4. jOOQ's BNF pseudo-notation................................................................................................................................................................. 238

8.5. Quality Assurance...................................................................................................................................................................................... 238

8.6. Migrating to jOOQ 3.0.............................................................................................................................................................................. 240

8.7. Credits........................................................................................................................................................................................................... 245


Page 7 / 245


1. Preface

1. Preface

jOOQ's reason for being - compared to JPA

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.

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 jOOQ has come to fill this gap.

jOOQ's reason for being - compared to LINQ

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.

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.

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.

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...).

jOOQ has come to fill this gap.

jOOQ's reason for being - compared to SQL / JDBC

So why not just use SQL?

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:


Page 8 / 245

The jOOQ User Manual 1. Preface

No typesafety

No syntax safety

No bind value index safety

Verbose SQL String concatenation

Boring bind value indexing techniques

Verbose resource and exception handling in JDBC

A very "stateful", not very object-oriented JDBC API, which is hard to use

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 jOOQ has come to fill this gap.

jOOQ is different

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!


Page 9 / 245

The jOOQ User Manual 2. Copyright, License, and Trademarks

2. Copyright, License, and Trademarks

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

Apache Software License 2.0

. With jOOQ 3.2, jOOQ became dual-licensed:

Apache Software License 2.0

(for use with Open Source databases) and

commercial

(for use with commercial databases).

This manual itself (as well as the

www.jooq.org

public website) is licensed to you under the terms of the

CC BY-SA 4.0

license.

Please contact

[email protected]

, should you have any questions regarding licensing.

License for jOOQ 3.2 and later

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


Page 10 / 245


Historic license for jOOQ 1.x, 2.x, 3.0, 3.1


Copyright (c) 2009-2015, Lukas Eder, [email protected]

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.

Trademarks owned by Data Geekery™ GmbH

jOOλ™ is a trademark by Data Geekery™ GmbH

jOOQ™ is a trademark by Data Geekery™ GmbH

jOOR™ is a trademark by Data Geekery™ GmbH

jOOU™ is a trademark by Data Geekery™ GmbH

jOOX™ is a trademark by Data Geekery™ GmbH

Trademarks owned by Data Geekery™ GmbH partners

GSP and General SQL Parser are trademarks by Gudu Software Limited

SQL 2 jOOQ is a trademark by Data Geekery™ GmbH and Gudu Software Limited

Flyway is a trademark by Snow Mountain Labs UG (haftungsbeschränkt)


Page 11 / 245

The jOOQ User Manual 2. Copyright, License, and Trademarks

Trademarks owned by database vendors with no affiliation to Data

Geekery™ GmbH

Access® is a registered trademark of Microsoft® Inc.

Adaptive Server® Enterprise is a registered trademark of Sybase®, Inc.

CUBRID™ is a trademark of NHN® Corp.

DB2® is a registered trademark of IBM® Corp.

Derby is a trademark of the Apache™ Software Foundation

H2 is a trademark of the H2 Group

HANA is a trademark of SAP SE

HSQLDB is a trademark of The hsql Development Group

Ingres is a trademark of Actian™ Corp.

MariaDB is a trademark of Monty Program Ab

MySQL® is a registered trademark of Oracle® Corp.

Firebird® is a registered trademark of Firebird Foundation Inc.

Oracle® database is a registered trademark of Oracle® Corp.

PostgreSQL® is a registered trademark of The PostgreSQL Global Development Group

Postgres Plus® is a registered trademark of EnterpriseDB® software

SQL Anywhere® is a registered trademark of Sybase®, Inc.

SQL Server® is a registered trademark of Microsoft® Inc.

SQLite is a trademark of Hipp, Wyrick & Company, Inc.

Other trademarks by vendors with no affiliation to Data Geekery™ GmbH

Java® is a registered trademark by Oracle® Corp. and/or its affiliates

Scala is a trademark of EPFL

Other trademark remarks

Other names may be trademarks of their respective owners.

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

contact us

if you think that your trademark(s) are not properly attributed.

Contributions

The following are authors and contributors of jOOQ or parts of jOOQ in alphabetical order:


Page 12 / 245


Aaron Digulla

Arnaud Roger

Art O Cathain

Artur Dryomov

Ben Manes

Brent Douglas

Brett Meyer

Christopher Deckers

Ed Schaller

Espen Stromsnes

Gonzalo Ortiz Jaureguizar

Gregory Hlavac

Henrik Sjöstrand

Ivan Dugic

Javier Durante

Johannes Bühler

Joseph B Phillips

Laurent Pireyn

Lukas Eder

Michael Doberenz

Michał Kołodziejski

Peter Ertl

Robin Stocker

Sander Plas

Sean Wellington

Sergey Epik

Stanislas Nanchen

Sugiharto Lim

Sven Jacobs

Thomas Darimont

Tsukasa Kitachi

Vladimir Kulev

Vladimir Vinogradov

Zoltan Tamasi

See the following website for details about contributing to jOOQ:

http://www.jooq.org/legal/contributions



Page 13 / 245

The jOOQ User Manual 3. Getting started with jOOQ

3. Getting started with jOOQ

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.

3.1. How to read this manual

This section helps you correctly interpret this manual in the context of jOOQ.

Code blocks

The following are code blocks:

-- A SQL code block

SELECT 1 FROM DUAL

// A Java code block for (int i = 0; i < 10; i++);



<hello what="world"></hello>

# A config file code block org.jooq.property=value

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:

-- In SQL:

SELECT 1 FROM DUAL

// Using jOOQ: create.selectOne().fetch()

Code block contents

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:

-- SQL assumptions

------------------

-- If nothing else is specified, assume that the Oracle syntax is used

SELECT 1 FROM DUAL


Page 14 / 245

The jOOQ User Manual 3.2. The sample database used in this manual

// 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);

Your naming may differ, of course. For instance, you could name the "create" instance "db", instead.

Execution

When you're coding PL/SQL, T-SQL or some other procedural SQL language, SQL statements are always executed immediately at the semi-colon. This is not the case in jOOQ, because as an internal DSL, jOOQ can never be sure that your statement is complete until you call fetch() or execute(). The manual tries to apply fetch() and execute() as thoroughly as possible. If not, it is implied:

SELECT 1 FROM DUAL

UPDATE t SET v = 1 create.selectOne().fetch(); create.update(T).set(T.V, 1).execute();

Degree (arity)

jOOQ records (and many other API elements) have a degree N between 1 and 22. 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.

Settings

jOOQ allows to override runtime behaviour using

org.jooq.conf.Settings

. If nothing is specified, the default runtime settings are assumed.

Sample database

jOOQ query examples run against the sample database. See the manual's section about

the sample database used in this manual

to learn more about the sample database.

3.2. The sample database used in this manual

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


Page 15 / 245

The jOOQ User Manual 3.3. Different use cases for jOOQ

CREATE TABLE language (

id NUMBER(7) NOT NULL PRIMARY KEY,

cd CHAR(2) NOT NULL,

description VARCHAR2(50)

);

CREATE TABLE author (


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 (


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

);

More entities, types (e.g. UDT's, ARRAY types, ENUM types, etc), stored procedures and packages are introduced for specific examples

In addition to the above, you may assume the following sample data:

INSERT INTO language (id, cd, description) VALUES (1, 'en', 'English');

INSERT INTO language (id, cd, description) VALUES (2, 'de', 'Deutsch');

INSERT INTO language (id, cd, description) VALUES (3, 'fr', 'Français');

INSERT INTO language (id, cd, description) VALUES (4, 'pt', 'Português');

INSERT INTO author (id, first_name, last_name, date_of_birth , year_of_birth)

VALUES (1 , 'George' , 'Orwell' , DATE '1903-06-26', 1903 );

INSERT INTO author (id, first_name, last_name, date_of_birth , year_of_birth)

VALUES (2 , 'Paulo' , 'Coelho' , DATE '1947-08-24', 1947 );

INSERT INTO book (id, author_id, title , published_in, language_id)

VALUES (1 , 1 , '1984' , 1948 , 1 );


VALUES (2 , 1 , 'Animal Farm' , 1945 , 1 );


VALUES (3 , 2 , 'O Alquimista', 1988 , 4 );


VALUES (4 , 2 , 'Brida' , 1990 , 2 );

INSERT INTO book_store VALUES ('Orell Füssli');

INSERT INTO book_store VALUES ('Ex Libris');

INSERT INTO book_store VALUES ('Buchhandlung im Volkshaus');

INSERT INTO book_to_book_store VALUES ('Orell Füssli' , 1, 10);



INSERT INTO book_to_book_store VALUES ('Ex Libris' , 1, 1 );

INSERT INTO book_to_book_store VALUES ('Ex Libris' , 3, 2 );

INSERT INTO book_to_book_store VALUES ('Buchhandlung im Volkshaus', 3, 1 );

3.3. Different use cases for jOOQ

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:


Page 16 / 245

The jOOQ User Manual 3.3.1. jOOQ as a SQL builder

Typesafe database object referencing through generated schema, table, column, record, procedure, type, dao, pojo artefacts (see the chapter about

code generation

)

Typesafe SQL construction / SQL building through a complete querying DSL API modelling SQL as a domain specific language in Java (see the chapter about

the query DSL API

)

Convenient query execution through an improved API for result fetching (see the chapters about

the various types of data fetching

)

SQL dialect abstraction and SQL clause emulation to improve cross-database compatibility and

to enable missing features in simpler databases (see the chapter about

SQL dialects

)

SQL logging and debugging using jOOQ as an integral part of your development process (see the

chapters about

logging

)

Effectively, jOOQ was originally designed to replace any other database abstraction framework short of

the ones handling connection pooling (and more sophisticated

transaction management

)

Use jOOQ the way you prefer

... 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:

-

Using Hibernate for 70% of the queries (i.e.

CRUD

) and jOOQ for the remaining 30% where SQL

is really needed

Using jOOQ for SQL building and JDBC for SQL execution

Using jOOQ for SQL building and Spring Data for SQL execution

Using jOOQ without the

source code generator

to build the basis of a framework for dynamic

SQL execution.

The following sections explain about various use cases for using jOOQ in your application.

3.3.1. jOOQ as a SQL builder

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

jOOQ's code generator

and probably not even

jOOQ's query execution facilities

. Instead, you'll use

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:

// 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();

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.

If you wish to use jOOQ only as a SQL builder, the following sections of the manual will be of interest to you:


Page 17 / 245

The jOOQ User Manual 3.3.2. jOOQ as a SQL builder with code generation

-

SQL building

: This section contains a lot of information about creating SQL statements using the jOOQ API

-

Plain SQL

: This section contains information useful in particular to those that want to supply

table expressions

,

column expressions

, etc. as plain SQL to jOOQ, rather than through

generated artefacts

3.3.2. jOOQ as a SQL builder with code generation

In addition to using jOOQ as a

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:

// 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();

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.

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:

-

SQL building


-

Code generation

: This section contains the necessary information to run jOOQ's code generator against your developer database

3.3.3. jOOQ as a SQL executor

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:

// 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)


.where(BOOK.PUBLISHED_IN.equal(1948))

.fetch();

By having jOOQ execute your SQL, the jOOQ query DSL becomes truly embedded SQL.

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:


Page 18 / 245

The jOOQ User Manual 3.3.4. jOOQ for CRUD

// 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);

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:

-

SQL building


-

Code generation


-

SQL execution

: This section contains a lot of information about executing SQL statements using the jOOQ API

-

Fetching

: This section contains some useful information about the various ways of fetching data

with jOOQ

3.3.4. jOOQ for CRUD

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:

// 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();

}

}

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):

-

SQL building


-

Code generation


-

SQL execution

: This section contains a lot of information about executing SQL statements using the jOOQ API


Page 19 / 245

The jOOQ User Manual 3.3.5. jOOQ for PROs

3.3.5. jOOQ for PROs

jOOQ isn't just a library that helps you

build

and

execute

SQL against your

generated, compilable schema

. jOOQ ships with a lot of tools. Here are some of the most important tools shipped with jOOQ:

-

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.

-

Logging

: jOOQ has a standard DEBUG logger built-in, for logging and tracing all your executed

SQL statements and fetched result sets

-

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.

-

Batch execution

: Batch execution is important when executing a big load of SQL statements.

jOOQ simplifies these operations compared to JDBC

-

Exporting

and

Importing

: jOOQ ships with an API to easily export/import data in various formats

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.

3.4. Tutorials

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.

3.4.1. jOOQ in 7 easy steps

This manual section is intended for new users, to help them get a running application with jOOQ, quickly.

3.4.1.1. Step 1: Preparation

If you haven't already downloaded it, download jOOQ:

http://www.jooq.org/download

Alternatively, you can create a Maven dependency to download jOOQ artefacts:


Page 20 / 245

The jOOQ User Manual 3.4.1.2. Step 2: Your database

<dependency>

<groupId>org.jooq</groupId>

<artifactId>jooq</artifactId>

<version>3.6.4</version>

</dependency>

<dependency>


<artifactId>jooq-meta</artifactId>


</dependency>

<dependency>


<artifactId>jooq-codegen</artifactId>


</dependency>

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

licensing pages

.

Please refer to the manual's section about

Code generation configuration

to learn how to use jOOQ's code generator with Maven.

For this example, we'll be using MySQL. If you haven't already downloaded MySQL Connector/J, download it here:

http://dev.mysql.com/downloads/connector/j/

If you don't have a MySQL instance up and running yet, get

XAMPP

now! XAMPP is a simple installation bundle for Apache, MySQL, PHP and Perl

3.4.1.2. Step 2: Your database

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:

CREATE DATABASE `library`;

USE `library`;

CREATE TABLE àuthor` (

ìd` int NOT NULL,

`first_name` varchar(255) DEFAULT NULL,

`last_name` varchar(255) DEFAULT NULL,

PRIMARY KEY (ìd`)

);

3.4.1.3. Step 3: Code generation

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:

jOOQ manual pages about setting up the code generator

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:


Page 21 / 245

The jOOQ User Manual 3.4.1.3. Step 3: Code generation

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<configuration xmlns="http://www.jooq.org/xsd/jooq-codegen-3.6.0.xsd">



<jdbc>

<driver>com.mysql.jdbc.Driver</driver>

<url>jdbc:mysql://localhost:3306/library</url>

<user>root</user>

<password></password>

</jdbc>

<generator>



<name>org.jooq.util.JavaGenerator</name>

<database>



<name>org.jooq.util.mysql.MySQLDatabase</name>



<inputSchema>library</inputSchema>



<includes>.*</includes>



<excludes></excludes>

</database>

<target>



<packageName>test.generated</packageName>



<directory>C:/workspace/MySQLTest/src</directory>

</target>

</generator>

</configuration>

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: generator.target.package - set this to the parent package you want to create for the generated classes.

The setting of test.generated will cause the test.generated.Author and test.generated.AuthorRecord to be created generator.target.directory - the directory to output to.

Once you have the JAR files and library.xml in your temp directory, type this on a Windows machine: java -classpath jooq-3.6.4.jar;jooq-meta-3.6.4.jar;jooq-codegen-3.6.4.jar;mysql-connector-java-5.1.18-bin.jar;.

org.jooq.util.GenerationTool library.xml

... or type this on a UNIX / Linux / Mac system (colons instead of semi-colons): java -classpath jooq-3.6.4.jar:jooq-meta-3.6.4.jar:jooq-codegen-3.6.4.jar:mysql-connector-java-5.1.18-bin.jar:.

org.jooq.util.GenerationTool library.xml

Note: jOOQ will try loading the library.xml from your classpath. This is also why there is a trailing period

(.) on the classpath. If the file cannot be found on the classpath, jOOQ will look on the file system from the current working directory.

Replace the filenames with your actual filenames. In this example, jOOQ 3.6.4 is being used. If everything has worked, you should see this in your console output:


Page 22 / 245


Nov 1, 2011 7:25:06 PM org.jooq.impl.JooqLogger info

INFO: Initialising properties : /library.xml


INFO: Database parameters


INFO: ----------------------------------------------------------


INFO: dialect : MYSQL


INFO: schema : library


INFO: target dir : C:/workspace/MySQLTest/src


INFO: target package : test.generated


INFO: ----------------------------------------------------------


INFO: Emptying : C:/workspace/MySQLTest/src/test/generated


INFO: Generating classes in : C:/workspace/MySQLTest/src/test/generated


INFO: Generating schema : Library.java


INFO: Schema generated : Total: 122.18ms


INFO: Sequences fetched : 0 (0 included, 0 excluded)


INFO: Tables fetched : 5 (5 included, 0 excluded)


INFO: Generating tables : C:/workspace/MySQLTest/src/test/generated/tables


INFO: ARRAYs fetched : 0 (0 included, 0 excluded)


INFO: Enums fetched : 0 (0 included, 0 excluded)


INFO: UDTs fetched : 0 (0 included, 0 excluded)


INFO: Generating table : Author.java


INFO: Tables generated : Total: 680.464ms, +558.284ms


INFO: Generating Keys : C:/workspace/MySQLTest/src/test/generated/tables


INFO: Keys generated : Total: 718.621ms, +38.157ms


INFO: Generating records : C:/workspace/MySQLTest/src/test/generated/tables/records


INFO: Generating record : AuthorRecord.java


INFO: Table records generated : Total: 782.545ms, +63.924ms


INFO: Routines fetched : 0 (0 included, 0 excluded)


INFO: Packages fetched : 0 (0 included, 0 excluded)


INFO: GENERATION FINISHED! : Total: 791.688ms, +9.143ms

3.4.1.4. Step 4: Connect to your database

3.4.1.4. Step 4: Connect to your database

Let's just write a vanilla main class in the project containing the generated classes:

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

}

}

}


Page 23 / 245


This is pretty standard code for establishing a MySQL connection.

3.4.1.5. Step 5: Querying

3.4.1.5. Step 5: Querying

Let's add a simple query constructed with jOOQ's query DSL:

DSLContext create = DSL.using(conn, SQLDialect.MYSQL);

Result<Record> result = create.select().from(AUTHOR).fetch();

First get an instance of DSLContext so we can write a simple SELECT query. We pass an instance of the MySQL connection to DSL. Note that the DSLContext doesn't close the connection. We'll have to do that ourselves.

We then use jOOQ's query DSL to return an instance of Result. We'll be using this result in the next step.

3.4.1.6. Step 6: Iterating

After the line where we retrieve the results, let's iterate over the results and print out the data: 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);

}

The full program should now look like this:


Page 24 / 245

The jOOQ User Manual 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 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)) {


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



}

}

}

3.4.1.7. Step 7: Explore!

3.4.1.7. Step 7: Explore!

jOOQ has grown to be a comprehensive SQL library. For more information, please consider the documentation:

http://www.jooq.org/learn

... explore the Javadoc:

http://www.jooq.org/javadoc/latest/

... or join the news group:

https://groups.google.com/forum/#!forum/jooq-user

This tutorial is the courtesy of Ikai Lan. See the original source here:

http://ikaisays.com/2011/11/01/getting-started-with-jooq-a-tutorial/

3.4.2. Using jOOQ in modern IDEs

Feel free to contribute a tutorial!

3.4.3. Using jOOQ with Spring and Apache DBCP

jOOQ and Spring are easy to integrate. In this example, we shall integrate:


Page 25 / 245

The jOOQ User Manual 3.4.3. Using jOOQ with Spring and Apache DBCP

-

Apache DBCP

(but you may as well use some other connection pool, like

BoneCP

,

C3P0

,

HikariCP

, and various others).

-

Spring TX

as the transaction management library.

-

jOOQ

as the

SQL building

and

execution

library.

Before you copy the manual examples, consider also these further resources:

-

The complete example can also be downloaded from GitHub

.

-

Another example using Spring and Guice for transaction management can be downloaded from

GitHub

.

-

Another, excellent tutorial by Petri Kainulainen can be found here

.

Add the required Maven dependencies

For this example, we'll create the following Maven dependencies



<properties>

<org.springframework.version>3.2.3.RELEASE</org.springframework.version>

</properties>

<dependencies>



<dependency>



<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>


</dependency>



<dependency>

<groupId>log4j</groupId>

<artifactId>log4j</artifactId>


</dependency>

<dependency>

<groupId>org.slf4j</groupId>

<artifactId>slf4j-log4j12</artifactId>


</dependency>



<dependency>

<groupId>org.springframework</groupId>

<artifactId>spring-context</artifactId>

<version>${org.springframework.version}</version>

</dependency>

<dependency>


<artifactId>spring-jdbc</artifactId>


</dependency>



<dependency>

<groupId>junit</groupId>

<artifactId>junit</artifactId>


<type>jar</type>

<scope>test</scope>

</dependency>

<dependency>


<artifactId>spring-test</artifactId>


<scope>test</scope>

</dependency>

</dependencies>


Page 26 / 245

The jOOQ User Manual 3.4.3. Using jOOQ with Spring and Apache DBCP

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

licensing pages

.

Create a minimal Spring configuration file

The above dependencies are configured together using a Spring Beans configuration:

<?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">



<tx:annotation-driven transaction-manager="transactionManager"/>

<bean id="dataSource" class="org.apache.commons.dbcp2.BasicDataSource" destroy-method="close" >



<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>



<bean id="transactionManager"

class="org.springframework.jdbc.datasource.DataSourceTransactionManager">

<property name="dataSource" ref="dataSource" />

</bean>



<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>



<bean id="dsl" class="org.jooq.impl.DefaultDSLContext">

<constructor-arg ref="config" />

</bean>

<bean id="exceptionTranslator" class="org.jooq.example.spring.exception.ExceptionTranslator" />



<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>



<bean id="books" class="org.jooq.example.spring.impl.DefaultBookService"/>

</beans>

Run a query using the above configuration:

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:


Page 27 / 245


@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)));

}

}

3.4.3. Using jOOQ with Spring and Apache DBCP

Run a queries in an explicit transaction:

The following example shows how you can use Spring's TransactionManager to explicitly handle transactions:

@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);

}

}


Page 28 / 245

The jOOQ User Manual 3.4.4. Using jOOQ with Flyway

Run queries using declarative transactions

Spring-TX has very powerful means to handle transactions declaratively, using the

@Transactional

annotation. The BookService that we had defined in the previous Spring configuration can be seen here: 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);

}

And here is how we interact with it:

@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);

}

Run queries using jOOQ's transaction API

jOOQ has its own programmatic transaction API that can be used with Spring transactions by implementing the jOOQ

org.jooq.TransactionProvider

SPI and passing that to your jOOQ

Configuration

.

More details about this transaction API can be found in the

manual's section about transaction management

.

You can try the above example yourself by downloading it from GitHub

.

3.4.4. Using jOOQ with Flyway

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.

When


Page 29 / 245


Philosophy

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.

The general philosophy behind the following approach can be summarised as this:

1. Database increment

2. Database migration

3. Code re-generation

4. Development

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:

1. Database increment - You need a new column in your database, so you write the necessary

DDL in a Flyway script

2. Database migration - 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

3. Code re-generation - Once the database is migrated, you regenerate all jOOQ artefacts (see

code generation

), locally

4. Development - You continue developing your business logic, writing code against the udpated, generated database schema

Maven Project Configuration - Properties

The following properties are defined in our pom.xml, to be able to reuse them between plugin configurations:

<properties>

<db.url>jdbc:h2:~/flyway-test</db.url>

<db.username>sa</db.username>

</properties>

0. Maven Project Configuration - Dependencies

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

https://github.com/jOOQ/jOOQ/tree/master/jOOQ-examples/jOOQ-flyway-example

, and the full

pom.xml file here

.

These are the dependencies that we're using in our Maven configuration:


Page 30 / 245




<dependency>




</dependency>

<dependency>

<groupId>com.h2database</groupId>

<artifactId>h2</artifactId>


</dependency>



<dependency>




</dependency>

<dependency>

<groupId>org.slf4j</groupId>

<artifactId>slf4j-log4j12</artifactId>


</dependency>



<dependency>

<groupId>junit</groupId>

<artifactId>junit</artifactId>


<scope>test</scope>

</dependency>

0. Maven Project Configuration - Plugins

After the dependencies, let's simply add the Flyway and jOOQ Maven plugins like so. The Flyway plugin:

<plugin>

<groupId>org.flywaydb</groupId>

<artifactId>flyway-maven-plugin</artifactId>




<executions>

<execution>

<phase>generate-sources</phase>

<goals>

<goal>migrate</goal>

</goals>

</execution>

</executions>



<configuration>

<url>${db.url}</url>

<user>${db.username}</user>

<locations>

<location>filesystem:src/main/resources/db/migration</location>

</locations>

</configuration>

</plugin>

The above Flyway Maven plugin configuration will read and execute all database migration scripts from src/main/resources/db/migration prior to compiling Java source code. While

the official Flyway documentation

suggests that migrations be done in the compile phase, the jOOQ code generator relies on such migrations having been done to code generation.

After the Flyway plugin, we'll add the jOOQ Maven Plugin. For more details, please refer to the

manual's section about the code generation configuration

.


Page 31 / 245


<plugin>


<artifactId>jooq-codegen-maven</artifactId>

<version>${org.jooq.version}</version>



<executions>

<execution>

<phase>generate-sources</phase>

<goals>

<goal>generate</goal>

</goals>

</execution>

</executions>



<configuration>

<jdbc>

<url>${db.url}</url>

<user>${db.username}</user>

</jdbc>

<generator>

<database>


<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>

This configuration will now read the FLYWAY_TEST schema and reverse-engineer it into the target/ generated-sources/jooq-h2 directory, and within that, into the org.jooq.example.flyway.db.h2 package.

1. Database increments

Now, when we start developing our database. For that, we'll create database increment scripts, which we put into the src/main/resources/db/migration directory, as previously configured for the Flyway plugin.

We'll add these files:

V1__initialise_database.sql

V2__create_author_table.sql

V3__create_book_table_and_records.sql

These three scripts model our schema versions 1-3 (note the capital V!). Here are the scripts' contents

-- V1__initialise_database.sql

DROP SCHEMA flyway_test IF EXISTS;

CREATE SCHEMA flyway_test;

-- 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_author PRIMARY KEY (ID)

);


Page 32 / 245


-- 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_book PRIMARY KEY (id),

CONSTRAINT fk_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');

2. Database migration and 3. Code regeneration

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: mvn clean install

And then observing the log output from Flyway...

[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] Successfully applied 3 migrations to schema "PUBLIC" (execution time 00:00.073s).

... and from jOOQ on the console:

[INFO] --- jooq-codegen-maven:3.6.4:generate (default) @ jooq-flyway-example ---

[INFO] --- jooq-codegen-maven:3.6.4: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

4. Development

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.

Now, that these steps are done, you can proceed writing your database queries. Imagine the following test case


Page 33 / 245

The jOOQ User Manual 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(asList(1, 2, 3, 4), result.getValues(BOOK.ID));

}

}

}

3.4.4. Using jOOQ with Flyway

Reiterate

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:

-- V4__le_french.sql

ALTER TABLE flyway_test.book ALTER COLUMN title RENAME TO le_titre;

They check it in, you check out the new database migration script, run mvn clean install

And then observing the log output:



[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] Successfully applied 1 migration to schema "PUBLIC" (execution time 00:00.016s).

So far so good, but later on:

[ERROR] COMPILATION ERROR :

[INFO] -------------------------------------------------------------

[ERROR] C:\...\jOOQ-flyway-example\src\test\java\AfterMigrationTest.java:[24,19] error: cannot find symbol

[INFO] 1 error

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:


Page 34 / 245

The jOOQ User Manual 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(asList(1, 2, 3, 4), result.getValues(BOOK.ID));

}

}

}

3.4.5. Using jOOQ with ERD tools

Conclusion

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!

Please, visit the

Flyway website

for more information about Flyway.

3.4.5. Using jOOQ with ERD tools

Many people make use of ERD tools to design their databases. Most ERD tools support exporting of their schema meta information in one form or another, e.g. as:

DDL scripts to be executed in the database

Images to be embedded in documentation

XML formats for consumption by other software - such as jOOQ

A popular ERD SaaS is Vertabelo (

www.vertabelo.com

), which provides all this functionality online. Given the following diagram:


Page 35 / 245

The jOOQ User Manual 3.4.5. Using jOOQ with ERD tools

... and the following, Vertabelo-specific export format:


<DatabaseModel VersionId="2.2">

<ModelGid>none</ModelGid>

<ModelVersionGid>none</ModelVersionGid>

...

<Tables>

<Table Id="t1">

<Name>LANGUAGE</Name>

<Columns>

<Column Id="c1">

<Name>ID</Name>

<Type>number(7)</Type>

<Nullable>false</Nullable>

<PK>true</PK>

</Column>

<Column Id="c2">

<Name>CD</Name>

<Type>char(2)</Type>

<Nullable>false</Nullable>

<PK>false</PK>

</Column>

...

</Columns>

</Table>

</Tables>

... we can now proceed with importing such an export format directly into jOOQ's

source code generator

in two ways:

By XML transforming the export format into jOOQ's import format

By using the VertabeloXMLDatabase or VertabeloAPIDatabase from the jOOQ-meta-extensions artifact, in case you are using Vertabelo.


Page 36 / 245

The jOOQ User Manual 3.4.6. Using jOOQ with JAX-RS

Depending on your workflow setup, you can have any team member re-design your schema, re-export it to your development database, re-import it into your Java / jOOQ code base and start working on the new tables / columns.

Further reading

The Vertabelo team has set up a comprehensive set of tutorial articles, which help you get started with the jOOQ+Vertabelo integration:

-

jOOQ and Vertabelo – getting started

-

Generate jOOQ classes with Vertabelo and Maven

-

Generate jOOQ classes with Vertabelo and Gradle

-

How to create a Spark REST API with jOOQ

And we've also written up a simple tutorial about how to use XSLT to import any ERD format:

-

Stop Manually Importing Your ERD Export into jOOQ

Use the jOOQ20 discount code for 3 months x 20% off any vertabelo.com price plan!

3.4.6. Using jOOQ with JAX-RS

In some use-cases, having a lean, single-tier server-side architecture is desirable. Typically, such architectures expose a

RESTful

API implementing client code and the UI using something like

AngularJS

.

In Java, the standard API for RESTful applications is

JAX-RS

, which is part of

JEE 7

, along with a standard

JSON implementation

. 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:

-

Maven

for building and running

-

Jetty

as a lightweight Servlet implementation

-

Jersey

, the JAX-RS (

JSR 311

&

JSR 339

) reference implementation

-

jOOQ

as a data access layer

For the example, we'll use a PostgreSQL database.

Creating the license server database

We'll keep the example simple and use a LICENSE table to store all license keys and associated information, whereas a LOG_VERIFY table is used to log access to the license server. Here's the DDL:


Page 37 / 245


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)

);

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:

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;

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.

Setting up the project

We're going to be setting up the

jOOQ code generator using Maven


Page 38 / 245



<project xmlns="http://maven.apache.org/POM/4.0.0"


xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

<modelVersion>4.0.0</modelVersion>


<artifactId>jooq-webservices</artifactId>

<packaging>war</packaging>


<build>

<plugins>

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-compiler-plugin</artifactId>


<configuration>

<source>1.7</source>

<target>1.7</target>

</configuration>

</plugin>

<plugin>

<groupId>org.mortbay.jetty</groupId>

<artifactId>maven-jetty-plugin</artifactId>


<configuration>

<reload>manual</reload>

<stopKey>stop</stopKey>

<stopPort>9966</stopPort>

</configuration>

</plugin>

<plugin>






</plugin>

</plugins>

</build>

<dependencies>

<dependency>

<groupId>com.sun.jersey</groupId>

<artifactId>jersey-server</artifactId>


</dependency>

<dependency>

<groupId>com.sun.jersey</groupId>

<artifactId>jersey-json</artifactId>


</dependency>

<dependency>

<groupId>com.sun.jersey.contribs</groupId>

<artifactId>jersey-spring</artifactId>


</dependency>

<dependency>

<groupId>javax.servlet</groupId>

<artifactId>servlet-api</artifactId>


</dependency>

<dependency>




</dependency>

<dependency>

<groupId>org.postgresql</groupId>

<artifactId>postgresql</artifactId>

<version>9.2-1003-jdbc4</version>

</dependency>

<dependency>




</dependency>

</dependencies>

</project>

With the above setup, we're now pretty ready to start developing our license service as a JAX-RS service.

The license service class

Once we've run the

jOOQ code generator using Maven

, we can write the following service class:


Page 39 / 245


/**

* 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);

}

});

}

// [...]

}

The INSERT INTO LOG_VERIFY query is actually rather interesting. In plain SQL, it would look like this:


Page 40 / 245


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;

Apart from the foregoing, the LicenseService also contains a couple of simple utilities:

/**

* 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);

}



Response.status(Status.SERVICE_UNAVAILABLE);

return "Service Unavailable - Please contact [email protected] for help";

}

finally {

JDBCUtils.safeClose(c);

}

}

private interface CtxRunnable {

String run(DSLContext ctx);

}

Configuring Spring and Jetty

All we need now is to configure Spring...

<beans xmlns="http://www.springframework.org/schema/beans"


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>

... and Jetty ...


Page 41 / 245



<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"


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>

... and we're done! We can now run the server with the following command: mvn jetty:run

Or if you need a custom port: mvn jetty:run -Djetty.port=8088

3.4.6. Using jOOQ with JAX-RS

Using the license server

You can now use the license server at the following URLs http://localhost:8088/jooq-jax-rs-example/license/[email protected]

-> license-key http://localhost:8088/jooq-jax-rs-example/license/[email protected]&license=license-key&version=3.2.0

-> true http://localhost:8088/jooq-jax-rs-example/license/[email protected]&license=wrong&version=3.2.0

-> false

Let's verify what happened, in the database: select * from license_server.license

-- id | license_date | licensee | license | version

--------------------------------------------------------------------------

-- 3 | 2013-11-22 14:26:07.768 | [email protected] | license-key | .* select * from license_server.log_verify

-- id | licensee | license | request_ip | version | match

--------------------------------------------------------------------------

-- 2 | [email protected] | license-key | 0:0:0:0:0:0:0:1 | 3.2.0 | t

-- 5 | [email protected] | wrong | 0:0:0:0:0:0:0:1 | 3.2.0 | f

Downloading the complete example

The complete example can be downloaded for free and under the terms of the

Apache Software License

2.0

from here:

https://github.com/jOOQ/jOOQ/tree/master/jOOQ-examples/jOOQ-jax-rs-example


Page 42 / 245

The jOOQ User Manual 3.4.7. A simple web application with jOOQ

3.4.7. A simple web application with jOOQ

Feel free to contribute a tutorial!

3.5. jOOQ and Java 8

Java 8 has introduced a great set of enhancements, among which lambda expressions and the new

java.util.stream.Stream

. These new constructs align very well with jOOQ's fluent API as can be seen in the following examples:

jOOQ and lambda expressions

jOOQ's

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: 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);

}

The above example shows how jOOQ's

Result.map()

method can receive a lambda expression that implements

RecordMapper

to map from jOOQ

Records

to your custom types.

jOOQ and the Streams API

jOOQ's

Result

type extends

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 Result containing

INFORMATION_SCHEMA meta data to produce DDL statements:


Page 43 / 245

The jOOQ User Manual 3.6. jOOQ and JavaFX

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(");");

}

);

The above example is explained more in depth in this blog post:

http://blog.jooq.org/2014/04/11/java-8friday-no-more-need-for-orms/

. For more information about Java 8, consider these resources:

Our

Java 8 Friday blog series

A great

Java 8 resources collection by the folks at Baeldung.com

3.6. jOOQ and JavaFX

One of the major improvements of Java 8 is the introduction of JavaFX into the JavaSE. With jOOQ and

Java 8 Streams and lambdas

, it is now very easy and idiomatic to transform SQL results into JavaFX

XYChart.Series

or other, related objects:

Creating a bar chart from a jOOQ Result

As we've seen in the previous

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.

In this example, we're going to use Open Data from the

world bank

to show a comparison of countries

GDP and debts:


Page 44 / 245


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);

Once this data is set up (e.g. in an H2 or PostgreSQL database), we'll run jOOQ's

code generator

and implement the following code to display our chart:


Page 45 / 245


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(field(name("c1", COUNTRIES.CODE.getName()), String.class)))

// order countries by their average projected value

.orderBy(

field(name("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())

);

The above example uses basic SQL-92 syntax where the countries are ordered using aggregate

information from a

nested SELECT

, which is supported in all databases. If you're using a database that supports

window functions

, e.g. PostgreSQL or any commercial database, you could have also written a simpler query like this:00

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;


Page 46 / 245


When executed, we'll get nice-looking bar charts like these:

3.6. jOOQ and JavaFX

The complete example can be downloaded and run from GitHub:

https://github.com/jOOQ/jOOQ/tree/master/jOOQ-examples/jOOQ-javafx-example


Page 47 / 245

The jOOQ User Manual 3.7. jOOQ and Nashorn

3.7. jOOQ and Nashorn

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:

// 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()

);

More details about how to use jOOQ, JDBC, and SQL with Nashorn can be seen here.

3.8. jOOQ and Scala

As any other library, jOOQ can be easily used in Scala, taking advantage of the many Scala language features such as for example:

Optional "." to dereference methods from expressions

Optional "(" and ")" to delimit method argument lists

Optional ";" at the end of a Scala statement

Type inference using "var" and "val" keywords

Lambda expressions and for-comprehension syntax for record iteration and data type conversion

But jOOQ also leverages other useful Scala features, such as

implicit defs for operator overloading

Scala Macros (soon to come)

All of the above heavily improve jOOQ's querying DSL API experience for Scala developers.

A short example jOOQ application in Scala might look like this:


Page 48 / 245

The jOOQ User Manual 3.9. jOOQ and Groovy 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) //

} //

} //

}

For more details about jOOQ's Scala integration, please refer to the manual's section about

SQL building with Scala

.

3.9. jOOQ and Groovy

As any other library, jOOQ can be easily used in Groovy, taking advantage of the many Groovy language features such as for example:

Optional ";" at the end of a Groovy statement

Type inference for local variables

While this is less impressive than the features available from a

Scala integration

, it is still useful for those of you using jOOQ's querying DSL with Groovy.

A short example jOOQ application in Groovy might look like this:

Note that while Groovy supports

some means of operator overloading

, we think that these means should be avoided in a jOOQ integration. For instance, a + b in Groovy maps to a formal a.plus(b) 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.

Another caveat of Groovy operator overloading is the fact that operators such as == or >= map to a.equals(b), a.compareTo(b) == 0, a.compareTo(b) >= 0 respectively. This behaviour does not make sense in a fluent API such as jOOQ.


Page 49 / 245

The jOOQ User Manual 3.10. jOOQ and NoSQL

3.10. jOOQ and NoSQL

jOOQ users often get excited about jOOQ's intuitive API and would then wish for NoSQL support.

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

JCR-SQL2

,

CQL (Cassandra Query Language)

,

Cypher (Neo4j's Query Language)

,

SOQL (Salesforce Query Language)

and many more.

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.

jOOQ is about SQL, and about SQL alone. Read more about our visions in the

manual's preface

.

3.11. Dependencies

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.

However, the above rule has some exceptions:

-

logging APIs

are referenced as "optional dependencies". jOOQ tries to find

slf4j

or

log4j

on the classpath. If it fails, it will use the

java.util.logging.Logger

Oracle ojdbc types used for array creation are loaded using reflection. The same applies to

Postgres PG* types.

Small libraries with compatible licenses are incorporated into jOOQ. These include

jOOR

,

jOOU

, parts of

OpenCSV

,

json simple

, parts of

commons-lang

-

javax.persistence

and

javax.validation

will be needed if you activate the relevant

code generation flags

3.12. Build your own

In order to build jOOQ (Open Source Edition) yourself, please download the sources from

https:// github.com/jOOQ/jOOQ

and use Maven to build jOOQ, preferably in Eclipse. jOOQ requires Java 6+ to compile and run.

Some useful hints to build jOOQ yourself:


Page 50 / 245

The jOOQ User Manual 3.13. jOOQ and backwards-compatibility

Get the latest version of

Git

or

EGit

Get the latest version of

Maven

or

M2E

Check out the jOOQ sources from

https://github.com/jOOQ/jOOQ

Optionally, import Maven artefacts into an Eclipse workspace using the following command (see the

maven-eclipse-plugin

documentation for details):

* mvn eclipse:eclipse

Build the jooq-parent artefact by using any of these commands:

* mvn clean package create .jar files in ${project.build.directory}

* mvn clean install install the .jar files in your local repository (e.g. ~/.m2)

* mvn clean {goal} -Dmaven.test.skip=true don't run unit tests when building artefacts

3.13. jOOQ and backwards-compatibility

jOOQ follows the rules of semantic versioning according to

http://semver.org

quite strictly. Those rules impose a versioning scheme [X].[Y].[Z] that can be summarised as follows:

If a patch release includes bugfixes, performance improvements and API-irrelevant new features,

[Z] is incremented by one.

If a minor release includes backwards-compatible, API-relevant new features, [Y] is incremented by one and [Z] is reset to zero.

If a major release includes backwards-incompatible, API-relevant new features, [X] is incremented by one and [Y], [Z] are reset to zero.

jOOQ's understanding of backwards-compatibility

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

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

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:

Adding methods to the interface

Overloading methods for convenience

Changing the type hierarchy of interfaces


Page 51 / 245

The jOOQ User Manual 3.13. jOOQ and backwards-compatibility

It becomes obvious that it would be impossible to add new language elements (e.g. new

SQL functions

, new

SELECT clauses

) to the API without breaking any client code that actually implements those

interfaces. Hence, the following rule should be observed: jOOQ's DSL interfaces should not be implemented by client code! Extend only those extension points that are explicitly documented as "extendable" (e.g.

custom QueryParts

)

jOOQ-codegen and jOOQ-meta

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.


Page 52 / 245

The jOOQ User Manual 4. SQL building

4. SQL building

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

"internal domain specific language"

directly into Java.

With this philosophy in mind, SQL building is the main feature of jOOQ. All other features (such as

SQL execution

and

code generation

) are mere convenience built on top of jOOQ's SQL building capabilities.

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

SQL to DSL mapping rules

as well as

jOOQ's BNF notation

4.1. The query DSL type

jOOQ exposes a lot of interfaces and hides most implementation facts from client code. The reasons for this are:

Interface-driven design. This allows for modelling queries in a fluent API most efficiently

Reduction of complexity for client code.

API guarantee. You only depend on the exposed interfaces, not concrete (potentially dialectspecific) implementations.

The

org.jooq.impl.DSL

class is the main class from where you will create all jOOQ objects. It serves as a

static factory for

table expressions

,

column expressions

(or "fields"),

conditional expressions

and many

other

QueryParts

.

The static query DSL API

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: import static org.jooq.impl.DSL.*;

Note, that when working with Eclipse, you could also add the DSL to your favourites. This will allow to access functions even more fluently: concat(trim(FIRST_NAME), trim(LAST_NAME));

// ... which is in fact the same as:

DSL.concat(DSL.trim(FIRST_NAME), DSL.trim(LAST_NAME));


Page 53 / 245

The jOOQ User Manual 4.1.1. DSL subclasses

4.1.1. DSL subclasses

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:

The advantage of referencing a dialect-specific DSL lies in the fact that you have access to more proprietary RDMBS functionality. This may include:

MySQL's encryption functions

PL/SQL constructs, pgplsql, or any other dialect's ROUTINE-language (maybe in the future)

4.2. The DSLContext class

DSLContext references a

org.jooq.Configuration

, an object that configures jOOQ's behaviour when

executing queries (see

SQL execution

for more details). Unlike the static DSL, the DSLContext allow for creating

SQL statements

that are already "configured" and ready for execution.

Fluent creation of a DSLContext object

The DSLContext object can be created fluently from the

DSL type

:

// Create it from a pre-existing configuration

DSLContext create = DSL.using(configuration);

// Create it from ad-hoc arguments

DSLContext create = DSL.using(connection, dialect);

If you do not have a reference to a pre-existing Configuration object (e.g. created from

org.jooq.impl.DefaultConfiguration

), the various overloaded DSL.using() methods will create one for you.

Contents of a Configuration object

A Configuration can be supplied with these objects:


Page 54 / 245

The jOOQ User Manual 4.2.1. SQL Dialect

-

org.jooq.SQLDialect

: The dialect of your database. This may be any of the currently supported database types (see

SQL Dialect

for more details)

-


: An optional runtime configuration (see

Custom Settings

for more details)

-

org.jooq.ExecuteListenerProvider

: An optional reference to a provider class that can provide execute listeners to jOOQ (see

ExecuteListeners

for more details)

-

org.jooq.RecordMapperProvider

: An optional reference to a provider class that can provide

record mappers to jOOQ (see

POJOs with RecordMappers

for more details)

Any of these:

*

java.sql.Connection

: An optional JDBC Connection that will be re-used for the whole

lifecycle of your Configuration (see

Connection vs. DataSource

for more details). For

simplicity, this is the use-case referenced from this manual, most of the time.

*

java.sql.DataSource

: An optional JDBC DataSource that will be re-used for the whole lifecycle of your Configuration. If you prefer using DataSources over Connections, jOOQ will internally fetch new Connections from your DataSource, conveniently closing them again

after query execution. This is particularly useful in J2EE or Spring contexts (see


for more details)

*

org.jooq.ConnectionProvider

: A custom abstraction that is used by jOOQ to "acquire" and "release" connections. jOOQ will internally "acquire" new Connections from your

ConnectionProvider, conveniently "releasing" them again after query execution. (see


for more details)

Wrapping a Configuration object, a DSLContext can construct

statements

, for later

execution

. An example is given here:

// The DSLContext is "configured" with a Connection and a SQLDialect


// This select statement contains an internal reference to the DSLContext's Configuration:

Select<?> select = create.selectOne();

// Using the internally referenced Configuration, the select statement can now be executed:

Result<?> result = select.fetch();

Note that you do not need to keep a reference to a DSLContext. You may as well inline your local variable, and fluently execute a SQL statement as such:

// Execute a statement from a single execution chain:

Result<?> result =

DSL.using(connection, dialect)

.select()

.from(BOOK)

.where(BOOK.TITLE.like("Animal%"))

.fetch();

4.2.1. SQL Dialect

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

org.jooq.SQLDialect

enum type.

The SQL dialect is one of the main attributes of a

Configuration

. Queries created from DSLContexts will

assume dialect-specific behaviour when

rendering SQL

and

binding bind values

.

Some parts of the jOOQ API are officially supported only by a given subset of the supported SQL dialects.

For instance, the

Oracle CONNECT BY clause

, which is supported by the Oracle and CUBRID databases,

is annotated with a

org.jooq.Support

annotation, as such:


Page 55 / 245

The jOOQ User Manual 4.2.2. SQL Dialect Family

/**

* Add an Oracle-specific <code>CONNECT BY</code> clause to the query

*/

@Support({ SQLDialect.CUBRID, SQLDialect.ORACLE })

SelectConnectByConditionStep<R> connectBy(Condition condition); jOOQ API methods which are not annotated with the

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

SELECT statement

factory method:

/**

* Create a new DSL select statement.

*/

@Support

SelectSelectStep<R> select(Field<?>... fields);

jOOQ's SQL clause emulation capabilities

The aforementioned Support annotation does not only designate, which databases natively support a feature. It also indicates that a feature is emulated by jOOQ for some databases lacking this feature. An example of this is the

DISTINCT predicate

, a predicate syntax defined by SQL:1999 and implemented

only by H2, HSQLDB, and Postgres:

A IS DISTINCT FROM B

Nevertheless, the IS DISTINCT FROM predicate is supported by jOOQ in all dialects, as its semantics can be expressed with an equivalent

CASE expression

. For more details, see the manual's section about

the

DISTINCT predicate

.

jOOQ and the Oracle SQL dialect

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

The

CONNECT BY clause

, for hierarchical queries

The

PIVOT

keyword for creating PIVOT tables

-

Packages

,

object-oriented user-defined types, member procedures

as described in the section

about

stored procedures and functions

Advanced analytical functions as described in the section about

window functions

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

4.2.2. SQL Dialect Family

In jOOQ 3.1, the notion of a SQLDialect.family() was introduced, in order to group several similar

SQL dialects

into a common family. An example for this is SQL Server, which is supported by jOOQ in various versions:


Page 56 / 245

The jOOQ User Manual 4.2.3. Connection vs. DataSource

-

SQL Server

: The "version-less" SQL Server version. This always maps to the latest supported version of SQL Server

-

SQL Server 2012

: The SQL Server version 2012

-

SQL Server 2008

: The SQL Server version 2008

In the above list, SQLSERVER is both a dialect and a family of three dialects. This distinction is used internally by jOOQ to distinguish whether to use the

OFFSET .. FETCH

clause (SQL Server 2012), or

whether to emulate it using ROW_NUMBER() OVER() (SQL Server 2008).

4.2.3. Connection vs. DataSource

Interact with JDBC Connections

While you can use jOOQ for

SQL building

only, you can also run queries against a JDBC

java.sql.Connection

. Internally, jOOQ creates

java.sql.Statement

or

java.sql.PreparedStatement

objects from such a Connection, in order to execute statements. The normal operation mode is to provide a

Configuration

with a JDBC Connection, whose lifecycle you will control yourself. This means that jOOQ will not actively close connections, rollback or commit transactions.

Note, in this case, jOOQ will internally use a

org.jooq.impl.DefaultConnectionProvider

, which you can reference directly if you prefer that. The DefaultConnectionProvider exposes various transactioncontrol methods, such as commit(), rollback(), etc.

Interact with JDBC DataSources

If you're in a J2EE or Spring context, however, you may wish to use a

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

using jOOQ with Spring

.

Note, in this case, jOOQ will internally use a

org.jooq.impl.DataSourceConnectionProvider

, which you can reference directly if you prefer that.

Inject custom behaviour

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: public interface ConnectionProvider {

// Provide jOOQ with a connection

Connection acquire() throws DataAccessException;

// Get a connection back from jOOQ

void release(Connection connection) throws DataAccessException;

}

Note that acquire() should always return the same Connection until this connection is returned via release()


Page 57 / 245

The jOOQ User Manual 4.2.4. Custom data

4.2.4. Custom data

In advanced use cases of integrating your application with jOOQ, you may want to put custom data into your

Configuration

, which you can then access from your...

-

Custom ExecuteListeners

-

Custom QueryParts

Here is an example of how to use the custom data API. Let's assume that you have written an

ExecuteListener

, that prevents INSERT statements, when a given flag is set to true:

// 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");

}

}

}

}

See the manual's section about

ExecuteListeners

to learn more about how to implement an

ExecuteListener.

Now, the above listener can be added to your

Configuration

, but you will also need to pass the flag to the Configuration, in order for the listener to work:

// 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());

}

Using the data() methods, you can store and retrieve custom data in your Configurations.

4.2.5. Custom ExecuteListeners

ExecuteListeners are a useful tool to...


Page 58 / 245

The jOOQ User Manual 4.2.6. Custom Settings

implement custom logging

apply triggers written in Java

collect query execution statistics

ExecuteListeners are hooked into your

Configuration

by returning them from an

org.jooq.ExecuteListenerProvider

:

// 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())

);


ExecuteListeners

to see examples of such listener implementations.

4.2.6. Custom Settings

The jOOQ Configuration allows for some optional configuration elements to be used by advanced users.

The


class is a JAXB-annotated type, that can be provided to a Configuration in several ways:

In the DSLContext constructor (DSL.using()). This will override default settings below

in the

org.jooq.impl.DefaultConfiguration

constructor. This will override default settings below

From a location specified by a JVM parameter: -Dorg.jooq.settings

From the classpath at /jooq-settings.xml

From the settings defaults, as specified in

http://www.jooq.org/xsd/jooq-runtime-3.6.0.xsd

Example

For example, if you want to indicate to jOOQ, that it should inline all bind variables, and execute static

java.sql.Statement

instead of binding its variables to


, you can do so by creating the following DSLContext:

Settings settings = new Settings(); settings.setStatementType(StatementType.STATIC_STATEMENT);

DSLContext create = DSL.using(connection, dialect, settings);

Subsequent sections of the manual contain some more in-depth explanations about these settings and what is controlled by these settings:

-

Runtime schema and table mapping

-

Names and identifiers

-

Execute CRUD with optimistic locking enabled

-

Enabling DEBUG logging of all executed SQL


Page 59 / 245

The jOOQ User Manual 4.2.6. Custom Settings

All Settings

This section of the manual explains all the available Settings flags as available from the

XSD specification

.

<settings>



<renderSchema>false</renderSchema>



<renderMapping>...</renderMapping>



<renderNameStyle>LOWER</renderNameStyle>



<renderKeywordStyle>UPPER</renderKeywordStyle>



<renderFormatted>false</renderFormatted>



<paramType>INDEXED</paramType>



<statementType>PREPARED_STATEMENT</statementType>



<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>



<properties>

<property><key>user</key><value>[db-user]</value></property>

<property><key>password</key><value>[db-password]</value></property>

</properties>

</jdbc>

<generator>

<database>



<name>org.jooq.util.oracle.OracleDatabase</name>






<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>



<inputSchema>[your database schema / owner / name]</inputSchema>

</database>

<generate>



</generate>

<target>



<packageName>[org.jooq.your.packagename]</packageName>



<directory>[/path/to/your/dir]</directory>

</target>

</generator>

</configuration>


Page 196 / 245


There are also lots of advanced configuration parameters, which will be treated in the

manual's section about advanced code generation features

Note, you can find the official XSD file for a formal

specification at:

http://www.jooq.org/xsd/jooq-codegen-3.6.0.xsd

Run jOOQ code generation

Code generation works by calling this class with the above property file as argument.

org.jooq.util.GenerationTool /jooq-config.xml

Be sure that these elements are located on the classpath:

The XML configuration file

jooq-3.6.4.jar, jooq-meta-3.6.4.jar, jooq-codegen-3.6.4.jar

The JDBC driver you configured

A command-line example (For Windows, unix/linux/etc will be similar)

Put the property file, jooq*.jar and the JDBC driver into a directory, e.g. C:\temp\jooq

Go to C:\temp\jooq

Run java -cp jooq-3.6.4.jar;jooq-meta-3.6.4.jar;jooq-codegen-3.6.4.jar;[JDBC-driver].jar;.

org.jooq.util.GenerationTool /[XML file]

Note that the property file must be passed as a classpath resource

Run code generation from Eclipse

Of course, you can also run code generation from your IDE. In Eclipse, set up a project like this. Note that:

this example uses jOOQ's log4j support by adding log4j.xml and log4j.jar to the project classpath.

the actual jooq-3.6.4.jar, jooq-meta-3.6.4.jar, jooq-codegen-3.6.4.jar artefacts may contain version numbers in the file names.


Page 197 / 245


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.

With the XML file as an argument


Page 198 / 245


And the classpath set up correctly


Page 199 / 245


Finally, run the code generation and see your generated artefacts

Integrate generation with Maven

Using the official jOOQ-codegen-maven plugin, you can integrate source code generation in your Maven build process:


Page 200 / 245

The jOOQ User Manual 6.2. Running the code generator with Ant

<plugin>








<executions>

<execution>

<goals>

<goal>generate</goal>

</goals>

</execution>

</executions>



<dependencies>

<dependency>

<groupId>postgresql</groupId>

<artifactId>postgresql</artifactId>

<version>8.4-702.jdbc4</version>

</dependency>

</dependencies>



<configuration>



<jdbc>

<driver>org.postgresql.Driver</driver>

<url>jdbc:postgresql:postgres</url>

<user>postgres</user>

<password>test</password>

</jdbc>



<generator>

<database>

<name>org.jooq.util.postgres.PostgresDatabase</name>


<excludes></excludes>

<inputSchema>public</inputSchema>

</database>

<target>

<packageName>org.jooq.util.maven.example</packageName>

<directory>target/generated-sources/jooq</directory>

</target>

</generator>

</configuration>

</plugin>

See a more complete example of a Maven pom.xml File in the

jOOQ / Spring tutorial

.

Use jOOQ generated classes in your application

Be sure, both jooq-3.6.4.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.

6.2. Running the code generator with Ant

Run generation with Ant

When running code generation with ant's <java/> task, you may have to set fork="true":



<target name="generate-test-classes">

<java fork="true" classname="org.jooq.util.GenerationTool">

[...]

</java>

</target>


Page 201 / 245

The jOOQ User Manual 6.3. Running the code generator with Gradle

6.3. Running the code generator with Gradle

Run generation with Gradle

While some third-party Gradle plugins exist (e.g. the one by

Etienne Studer from Gradleware

), 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:

// Configure the Java plugin and the dependencies

// ---------------------------------------------apply plugin: 'java' repositories {

mavenLocal()

mavenCentral()

} dependencies {

compile 'org.jooq:jooq:3.6.4'

runtime 'com.h2database:h2:1.4.177'

testCompile 'junit:junit:4.11'

} buildscript {

repositories {

mavenLocal()

mavenCentral()

}

dependencies {

classpath 'org.jooq:jooq-codegen:3.6.4'

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-3.6.0.xsd') {

jdbc() {

driver('org.h2.Driver')

url('jdbc:h2:~/test-gradle')

user('sa')

password('')

}

generator() {

database() {

}

// Watch out for this caveat when using MarkupBuilder with "reserved names"

// - https://github.com/jOOQ/jOOQ/issues/4797

// - http://stackoverflow.com/a/11389034/521799

// - https://groups.google.com/forum/#!topic/jooq-user/wi4S9rRxk4A

generate([:]) {

pojos true

daos true

}

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)

)

This example is frequently updated on GitHub:

https://github.com/jOOQ/jOOQ/tree/master/jOOQexamples/jOOQ-codegen-gradle


Page 202 / 245

The jOOQ User Manual 6.4. Advanced generator configuration

6.4. Advanced generator configuration

In the

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

jooq-meta configuration

Within the <generator/> element, there are other configuration elements:


Page 203 / 245




<database>



<includeExcludeColumns>false</includeExcludeColumns>



<recordVersionFields>REC_VERSION</recordVersionFields>



<recordTimestampFields>REC_TIMESTAMP</recordTimestampFields>



<syntheticPrimaryKeys>SCHEMA\.TABLE\.COLUMN(1|2)</syntheticPrimaryKeys>



<overridePrimaryKeys>MY_UNIQUE_KEY_NAME</overridePrimaryKeys>



<dateAsTimestamp>false</dateAsTimestamp>



<unsignedTypes>true</unsignedTypes>



<outputSchema>[your database schema / owner / name]</outputSchema>



<outputSchemaToDefault>false</outputSchemaToDefault>



<schemata>

<schema>

<inputSchema>...</inputSchema>

<outputSchema>...</outputSchema>

<outputSchemaToDefault>...</outputSchemaToDefault>

</schema>

[ <schema>...</schema> ... ]

</schemata>



<schemaVersionProvider>SELECT :schema_name || '_' || MAX("version") FROM "schema_version"</schemaVersionProvider>



<customTypes>...</customTypes>



<forcedTypes>...</forcedTypes>

</database>


Page 204 / 245


Check out the some of the manual's "advanced" sections to find out more about the advanced configuration parameters.

-

Schema mapping

-

Custom types

jooq-codegen configuration

Also, you can add some optional advanced configuration parameters for the generator:


Page 205 / 245




<generate>



<instanceFields>true</instanceFields>



Load the above using standard JAXB API:


Page 207 / 245

The jOOQ User Manual 6.6. Custom generator strategies 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);

... and then, modify parts of your configuration programmatically, for instance the JDBC user / password:

6.6. Custom generator strategies

Using custom generator strategies to override naming schemes

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.



<generator>



<name>org.jooq.util.JavaGenerator</name>



<strategy>

<name>org.jooq.util.DefaultGeneratorStrategy</name>

</strategy>

</generator>

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:


Page 208 / 245


/**

* 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;

}

}

6.6. Custom generator strategies

Page 209 / 245

The jOOQ User Manual 6.6. Custom generator strategies

An org.jooq.Table example:

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: 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)

An org.jooq.Record example:

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: 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)

A POJO example:

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: 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)

More examples can be found here:


Page 210 / 245


-

org.jooq.util.example.JPrefixGeneratorStrategy

-

org.jooq.util.example.JVMArgsGeneratorStrategy

6.7. Matcher strategies


Using custom matcher strategies

In the

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

code generator configuration

. Instead of specifying a strategy name, you can also specify a <matchers/> element as

such:

NOTE: There had been an incompatible change between jOOQ 3.2 and jOOQ 3.3 in the configuration of these matcher strategies. See

Issue #3217

for details.


Page 211 / 245




<generator>

<strategy>

<matchers>



<schemas>

<schema>



<expression>MY_SCHEMA</expression>



<schemaClass> --> MatcherRule </schemaClass>

<schemaIdentifier> --> MatcherRule </schemaIdentifier>

<schemaImplements>com.example.MyOptionalCustomInterface</schemaImplements>

</schema>

</schemas>



<tables>

<table>



<expression>MY_TABLE</expression>



<tableClass> --> MatcherRule </tableClass>

<tableIdentifier> --> MatcherRule </tableIdentifier>

<tableImplements>com.example.MyOptionalCustomInterface</tableImplements>



<recordClass> --> MatcherRule </recordClass>

<recordImplements>com.example.MyOptionalCustomInterface</recordImplements>



<interfaceClass> --> MatcherRule </interfaceClass>

<interfaceImplements>com.example.MyOptionalCustomInterface</interfaceImplements>



<daoClass> --> MatcherRule </daoClass>

<daoImplements>com.example.MyOptionalCustomInterface</daoImplements>



<pojoClass> --> MatcherRule </pojoClass>

<pojoExtends>com.example.MyOptionalCustomBaseClass</pojoExtends>

<pojoImplements>com.example.MyOptionalCustomInterface</pojoImplements>

</table>

</tables>



<fields>

<field>



<expression>MY_FIELD</expression>



<fieldIdentifier> --> MatcherRule </fieldIdentifier>

<fieldMember> --> MatcherRule </fieldMember>

<fieldSetter> --> MatcherRule </fieldSetter>

<fieldGetter> --> MatcherRule </fieldGetter>

</field>

</fields>



<routines>

<routine>



<expression>MY_ROUTINE</expression>



<routineClass> --> MatcherRule </routineClass>

<routineMethod> --> MatcherRule </routineMethod>

<routineImplements>com.example.MyOptionalCustomInterface</routineImplements>

</routine>

</routines>



<sequences>

<sequence>



<expression>MY_SEQUENCE</expression>



<sequenceIdentifier> --> MatcherRule </sequenceIdentifier>

</sequence>

</sequences>

</matchers>

</strategy>

</generator>



Page 212 / 245

The jOOQ User Manual 6.8. Custom code sections

The above example used references to "MatcherRule", which is an XSD type that looks like this:

<schemaClass>



<transform>CAMEL</transform>



<expression>PREFIX_$0_SUFFIX</expression>

</schemaClass>

Some examples

The following example shows a matcher strategy that adds a "T_" prefix to all table classes and to table identifiers:

<generator>

<strategy>

<matchers>

<tables>

<table>



<tableIdentifier>

<transform>UPPER</transform>

<expression>T_$0</expression>

</tableIdentifier>

<tableClass>

<transform>PASCAL</transform>

<expression>T_$0</expression>

</tableClass>

</table>

</tables>

</matchers>

</strategy>

</generator>

The following example shows a matcher strategy that renames BOOK table identifiers (or table identifiers containing BOOK) into BROCHURE (or tables containing BROCHURE):

<generator>

<strategy>

<matchers>

<tables>

<table>

<expression>^(.*?)_BOOK_(.*)$</expression>

<tableIdentifier>

<transform>UPPER</transform>

<expression>$1_BROCHURE_$2</expression>

</tableIdentifier>

</table>

</tables>

</matchers>

</strategy>

</generator>

For more information about each XML tag, please refer to the

http://www.jooq.org/xsd/jooqcodegen-3.6.0.xsd

XSD file.

6.8. Custom code sections

Power users might choose to re-implement large parts of the org.jooq.util.JavaGenerator class. If you only want to add some custom code sections, however, you can extend the JavaGenerator and override only parts of it.


Page 213 / 245


An example for generating custom class footers

6.8. Custom code sections 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("}");

}

}

The above example simply adds a class footer to

generated records

, in this case, overriding the default toString() implementation.

An example for generating custom class Javadoc

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(" */");

}

}

Any of the below methods can be overridden:


Page 214 / 245

The jOOQ User Manual 6.9. Generated global artefacts 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

When you override any of the above, do note that according to

jOOQ's understanding of semantic versioning

, incompatible changes may be introduced between minor releases, even if this should be the exception.

6.9. Generated global artefacts

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:

Keys.java: This file contains all of the required primary key, unique key, foreign key and identity references in the form of static members of type

org.jooq.Key

.

Routines.java: This file contains all standalone routines (not in packages) in the form of static factory methods for

org.jooq.Routine

types.

Sequences.java: This file contains all sequence objects in the form of static members of type

org.jooq.Sequence

.

Tables.java: This file contains all table objects in the form of static member references to the actual singleton

org.jooq.Table

object

UDTs.java: This file contains all UDT objects in the form of static member references to the actual singleton

org.jooq.UDT

object


Page 215 / 245

The jOOQ User Manual 6.10. Generated tables

Referencing global artefacts

When referencing global artefacts from your client application, you would typically static import them as such:

// 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())

6.10. Generated tables

Every table in your database will generate a

org.jooq.Table

implementation that looks like this: 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);

}

// [...]

}

Flags influencing generated tables

These flags from the


influence generated tables:


Page 216 / 245

The jOOQ User Manual 6.11. Generated records

recordVersionFields: Relevant methods from super classes are overridden to return the

VERSION field

recordTimestampFields: Relevant methods from super classes are overridden to return the

TIMESTAMP field

syntheticPrimaryKeys: This overrides existing primary key information to allow for "custom" primary key column sets

overridePrimaryKeys: This overrides existing primary key information to allow for unique key to primary key promotion

dateAsTimestamp: This influences all relevant columns

unsignedTypes: This influences all relevant columns

relations: Relevant methods from super classes are overridden to provide primary key, unique key, foreign key and identity information

instanceFields: This flag controls the "static" keyword on table columns, as well as aliasing convenience

records: The generated record type is referenced from tables allowing for type-safe single-table record fetching

Flags controlling table generation

Table generation cannot be deactivated

6.11. Generated records

Every table in your database will generate an

org.jooq.Record

implementation that looks like this:

// 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();

}

// [...]

}


Page 217 / 245


Flags influencing generated records



influence generated records:

6.12. Generated POJOs

syntheticPrimaryKeys: This overrides existing primary key information to allow for "custom" primary key column sets, possibly promoting a TableRecord to an UpdatableRecord

overridePrimaryKeys: This overrides existing primary key information to allow for unique key to primary key promotion, possibly promoting a TableRecord to an UpdatableRecord

dateAsTimestamp: This influences all relevant getters and setters

unsignedTypes: This influences all relevant getters and setters

relations: This is needed as a prerequisite for navigation methods

daos: Records are a pre-requisite for DAOs. If DAOs are generated, records are generated as well

interfaces: If interfaces are generated, records will implement them

jpaAnnotations: JPA annotations are used on generated records

Flags controlling record generation

Record generation can be deactivated using the records flag

6.12. Generated POJOs

Every table in your database will generate a POJO implementation that looks like this:

// 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;

}

// [...]

}

Flags influencing generated POJOs



influence generated POJOs:


Page 218 / 245

The jOOQ User Manual 6.13. Generated Interfaces



interfaces: If interfaces are generated, POJOs will implement them

immutablePojos: Immutable POJOs have final members and no setters. All members must be passed to the constructor

daos: POJOs are a pre-requisite for DAOs. If DAOs are generated, POJOs are generated as well

jpaAnnotations: JPA annotations are used on generated records

validationAnnotations: JSR-303 validation annotations are used on generated records

Flags controlling POJO generation

POJO generation can be activated using the pojos flag

6.13. Generated Interfaces

Every table in your database will generate an interface that looks like this: public interface IBook extends java.io.Serializable {

// Every column generates a getter and a setter

public void setId(Integer value);

public Integer getId();

// [...]

}

Flags influencing generated interfaces



influence generated interfaces:



Flags controlling POJO generation

POJO generation can be activated using the interfaces flag

6.14. Generated DAOs

Generated DAOs

Every table in your database will generate a

org.jooq.DAO



Page 219 / 245

The jOOQ User Manual 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);

}

// [...]

}

6.15. Generated sequences

Flags controlling DAO generation

DAO generation can be activated using the daos flag

6.15. Generated sequences

Every sequence in your database will generate a

org.jooq.Sequence

implementation that looks like this: 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);

}

Flags controlling sequence generation

Sequence generation cannot be deactivated

6.16. Generated procedures

Every procedure or function (routine) in your database will generate a

org.jooq.Routine



Page 220 / 245

The jOOQ User Manual 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);

}

// [...]

}

6.17. Generated UDTs

Package and member procedures or functions

Procedures or functions contained in packages or UDTs are generated in a sub-package that corresponds to the package or UDT name.

Flags controlling routine generation

Routine generation cannot be deactivated

6.17. Generated UDTs

Every UDT in your database will generate a

org.jooq.UDT

implementation that looks like this: 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);

// [...]

}

Besides the

org.jooq.UDT

implementation, a

org.jooq.UDTRecord

implementation is also generated 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() {...}

// [...]

}


Page 221 / 245


Flags controlling UDT generation

UDT generation cannot be deactivated

6.18. Data type rewrites

6.18. Data type rewrites

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 BOOLEAN or UUID. jOOQ's code generator allows you to apply simple data type rewriting. The following configuration will rewrite

IS_VALID columns in all tables to be of type BOOLEAN.

<database>



<forcedTypes>

<forcedType>



<name>BOOLEAN</name>



<expression>.*\.IS_VALID</expression>



<customTypes>

<customType>



<name>GregorianCalendar</name>



<type>java.util.GregorianCalendar</type>



<converter>com.example.CalendarConverter</converter>

</customType>

</customTypes>



<forcedTypes>

<forcedType>



<name>GregorianCalendar</name>



<expression>.*\.DATE_OF_.*</expression>



<customTypes>

<customType>



<name>JsonElement</name>



<type>com.google.gson.JsonElement</type>



<binding>com.example.PostgresJSONGsonBinding</binding>

</customType>

</customTypes>



<forcedTypes>

<forcedType>



<name>JsonElement</name>



<expression>.*JSON.*</expression>



<inputSchema>LUKAS_DEV_SCHEMA</inputSchema>



<outputSchema>PROD</outputSchema>

</schema>

</schemata>


Page 225 / 245

The jOOQ User Manual 6.22. Code generation for large schemas

6.22. Code generation for large schemas

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

global access

. These

classes can hit two sorts of limits of the compiler / JVM:

Methods (including static / instance initialisers) are allowed to contain only 64kb of bytecode.

Classes are allowed to contain at most 64k of constant literals

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:

Distribute your database objects in several schemas. That is probably a good idea anyway for such large databases

-


to exclude excess database objects

-


to avoid generating

global objects

using

<globalObjectReferences/>

Remove uncompilable classes after code generation

6.23. Code generation and version control

When using jOOQ's code generation capabilities, you will need to make a strategic decision about whether you consider your generated code as

Part of your code base

Derived artefacts

In this section we'll see that both approaches have their merits and that none of them is clearly better.

Part of your code base

When you consider generated code as part of your code base, you will want to:

Check in generated sources in your version control system

Use manual source code generation

Possibly use even partial source code generation

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.

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.


Page 226 / 245

The jOOQ User Manual 6.23. Code generation and version control

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.

Derived artefacts

When you consider generated code to be derived artefacts, you will want to:

Check in only the actual DDL (e.g. controlled via

Flyway

)

Regenerate jOOQ code every time the schema changes

Regenerate jOOQ code on every machine - including continuous integration

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.

The drawback of this approach is that the build may break in perfectly acceptable situations, when parts of your database are temporarily unavailable.

Pragmatic combination

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.


Page 227 / 245

The jOOQ User Manual 7. Tools

7. Tools

These chapters hold some information about tools to be used with jOOQ

7.1. JDBC mocking for unit testing

When writing unit tests for your data access layer, you have probably used some generic mocking tool offered by popular providers like

Mockito

,

jmock

,

mockrunner

, or even

DBUnit

. With jOOQ, you can take advantage of the built-in JDBC mock API that allows you to emulate a database on the JDBC level for precisely those SQL/JDBC use cases supported by jOOQ.

Mocking the JDBC API

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:

-

java.sql.Connection

-

java.sql.Statement

-


-

java.sql.CallableStatement

-

java.sql.ResultSet

-


Optionally, you may even want to implement interfaces, such as

java.sql.Array

,

java.sql.Blob

,

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

Using jOOQ's own mock API

This work is greatly simplified, when using jOOQ's own mock API. The org.jooq.tools.jdbc 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

Configuration

with a

MockConnection

, and implement the

MockDataProvider

:

// 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();

As you can see, the configuration setup is simple. Now, the MockDataProvider acts as your single point of contact with JDBC / jOOQ. It unifies any of these execution modes, transparently:


Page 228 / 245

The jOOQ User Manual 7.1. JDBC mocking for unit testing

Statements without results

Statements without results but with generated keys

Statements with results

Statements with several results

Batch statements with single queries and multiple bind value sets

Batch statements with multiple queries and no bind values

The above are the execution modes supported by jOOQ. Whether you're using any of jOOQ's various fetching modes (e.g.

pojo fetching

,

lazy fetching

,

many fetching

,

later fetching

) is irrelevant, as those

modes are all built on top of the standard JDBC API.

Implementing MockDataProvider

Now, here's how to implement MockDataProvider: 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;

}

}

Essentially, the

MockExecuteContext

contains all the necessary information for you to decide, what kind of data you should return. The

MockResult

wraps up two pieces of information:

-

Statement.getUpdateCount()

: The number of affected rows

-

Statement.getResultSet()

: The result set

You should return as many MockResult objects as there were query executions (in

batch mode

) or

results (in

fetch-many mode

). Instead of an awkward JDBC ResultSet, however, you can construct a

"friendlier"

org.jooq.Result

with your own record types. The jOOQ mock API will use meta data provided with this Result in order to create the necessary JDBC


See the

MockDataProvider Javadoc

for a list of rules that you should follow.


Page 229 / 245

The jOOQ User Manual 7.2. SQL 2 jOOQ Parser

7.2. SQL 2 jOOQ Parser

Together with

Gudu Software

, we have created an Open Source SQL 2 jOOQ parser that takes native

SQL statements as input and generates jOOQ code as output.

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

General SQL Parser

. 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!

It's as simple as this!

Create a JDBC connection

Create a new SQL2jOOQ converter object

Convert your SQL code

Get the result

See it in action: 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 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());

}

}

If all goes well, the above program yields:


Page 230 / 245

The jOOQ User Manual 7.3. jOOQ Console


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( );

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!

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:

https://github.com/sqlparser/sql2jooq/blob/master/sql2jooq/LICENSE-GSQLPARSER.txt

For more information about the General SQL Parser,

please refer to the product blog

.

Please report any issues, ideas, wishes to the

jOOQ user group

or the

sql2jooq GitHub project

.

7.3. jOOQ Console

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.


Page 231 / 245


8. Reference

These chapters hold some general jOOQ reference information

8.1. Supported RDBMS

8. Reference

A list of supported databases

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 400 integration tests with an overall of around 4000 queries for any of these databases:

CUBRID 8.4

DB2 9.7

Derby 10.10

Firebird 2.5

H2 1.3

HANA

HSQLDB 2.2

Informix 12.10

Ingres 10.1

MariaDB 5.2

Microsoft Access 2013

MySQL 5.5

Oracle 11g

PostgreSQL 9.0

SQLite with Xerial JDBC driver

SQL Azure

SQL Server 2008 R8

Sybase Adaptive Server Enterprise 15.5

Sybase SQL Anywhere 12

For an up-to-date list of currently supported RDBMS, please refer to

http://www.jooq.org/legal/ licensing/#databases

.

8.2. Data types

There is always a small mismatch between SQL data types and Java data types. This is for two reasons:

SQL data types are insufficiently covered by the JDBC API.

Java data types are often less expressive than SQL data types

This chapter should document the most important notes about SQL, JDBC and jOOQ data types.


Page 232 / 245

The jOOQ User Manual 8.2.1. BLOBs and CLOBs

8.2.1. BLOBs and CLOBs

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.

8.2.2. Unsigned integer types

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

java.lang.Number

implementations modelling the following types:

-

org.jooq.types.UByte

: Unsigned byte, an 8-bit unsigned integer

-

org.jooq.types.UShort

: Unsigned short, a 16-bit unsigned integer

-

org.jooq.types.UInteger

: Unsigned int, a 32-bit unsigned integer

-

org.jooq.types.ULong

: Unsigned long, a 64-bit unsigned integer

Each of these wrapper types extends

java.lang.Number

, wrapping a higher-level integer type, internally:

UByte wraps

java.lang.Short

UShort wraps

java.lang.Integer

UInteger wraps

java.lang.Long

ULong wraps

java.math.BigInteger

8.2.3. INTERVAL data types

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:

YEAR TO MONTH: This interval type models a number of months and years

DAY TO SECOND: This interval type models a number of days, hours, minutes, seconds and milliseconds

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

java.lang.Number

:

org.jooq.types.YearToMonth

(where

Number.intValue() corresponds to the absolute number of months) and

org.jooq.types.DayToSecond

(where Number.intValue() corresponds to the absolute number of milliseconds)


Page 233 / 245

The jOOQ User Manual 8.2.4. XML data types

Interval arithmetic

In addition to the


documented previously, interval arithmetic is also supported

by jOOQ. Essentially, the following operations are supported:

DATETIME - DATETIME => INTERVAL

DATETIME + or - INTERVAL => DATETIME

INTERVAL + DATETIME => DATETIME

INTERVAL + - INTERVAL => INTERVAL

INTERVAL * or / NUMERIC => INTERVAL

NUMERIC * INTERVAL => INTERVAL

8.2.4. XML data types

XML data types are currently not supported

8.2.5. Geospacial data types

Geospacial data types

Geospacial data types are currently not supported

8.2.6. CURSOR data types

Some databases support cursors returned from stored procedures. They are mapped to the following jOOQ data type:

Field<Result<Record>> cursor;

In fact, such a cursor will be fetched immediately by jOOQ and wrapped in an

org.jooq.Result

object.

8.2.7. ARRAY and TABLE data types

The SQL standard specifies ARRAY data types, that can be mapped to Java arrays as such:

Field<Integer[]> intArray;

The above array type is supported by these SQL dialects:


Page 234 / 245


H2

HSQLDB

Postgres

8.2.8. Oracle DATE data type

Oracle typed arrays

Oracle has strongly-typed arrays and table types (as opposed to the previously seen anonymously typed arrays). These arrays are wrapped by

org.jooq.ArrayRecord

types.

8.2.8. Oracle DATE data type

Oracle's DATE data type does not conform to the SQL standard. It is really a TIMESTAMP(0), i.e. a

TIMESTAMP with a fractional second precision of zero. The most appropriate JDBC type for Oracle DATE types is

java.sql.Timestamp

.

Performance implications

When binding TIMESTAMP variables to SQL statements, instead of truncating such variables to DATE, the cost based optimiser may choose to widen the database column from DATE to TIMESTAMP using an

Oracle INTERNAL_FUNCTION(), which prevents index usage.

Details about this behaviour can be seen in this Stack Overflow question

.

In order to prevent this behaviour, you should register

org.jooq.impl.DateAsTimestampBinding

as a

custom data type binding

to all your DATE columns:

<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>

For more information, please refer to

the manual's section about custom data type bindings

.

8.3. SQL to DSL mapping rules

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.


Page 235 / 245

The jOOQ User Manual 8.3. SQL to DSL mapping rules

SQL allows for "keywordless" syntax

SQL syntax does not always need keywords to form expressions. The

UPDATE .. SET

clause takes various argument assignments:

UPDATE t SET a = 1, b = 2 update(t).set(a, 1).set(b, 2)

The above example also shows missing operator overloading capabilities, where "=" is replaced by "," in

jOOQ. Another example are


, which can be formed with parentheses only in SQL:

(a, b) IN ((1, 2), (3, 4)) row(a, b).in(row(1, 2), row(3, 4))

In this case, ROW is an actual (optional) SQL keyword, implemented by at least PostgreSQL.

SQL contains "composed" keywords

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:

GROUP BY

ORDER BY

WHEN MATCHED THEN UPDATE groupBy() orderBy() whenMatchedThenUpdate()

Future versions of jOOQ may use all-uppercased method names in addition to the camel-cased ones

(to prevent collisions with Java keywords):

GROUP BY

ORDER BY

WHEN MATCHED THEN UPDATE

GROUP_BY()

ORDER_BY()

WHEN_MATCHED_THEN_UPDATE()

SQL contains "superfluous" keywords

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:

BEGIN .. END

REPEAT .. UNTIL

IF .. THEN .. ELSE .. END IF jOOQ omits some of those keywords when it is too tedious to write them in Java.

CASE WHEN .. THEN .. END decode().when(.., ..)

The above example omits THEN and END 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.


Page 236 / 245

The jOOQ User Manual 8.3. SQL to DSL mapping rules

SQL contains "superfluous" syntactic elements

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.

LISTAGG(a, b) WITHIN GROUP (ORDER BY c)

OVER (PARTITION BY d) listagg(a, b).withinGroupOrderBy(c)

.over().partitionBy(d)

The parentheses used for the WITHIN GROUP (..) and OVER (..) 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:

LISTAGG(a, b) WITHIN GROUP (ORDER BY c)

OVER (PARTITION BY d) listagg(a, b).withinGroup(orderBy(c))

.over(partitionBy(d))

SQL uses some of Java's reserved words

Some SQL keywords map onto

Java Language Keywords

if they're mapped using camel-casing. These keywords currently include:

CASE

ELSE

FOR jOOQ replaces those keywords by "synonyms":

CASE .. ELSE

PIVOT .. FOR .. IN ..

There is more future collision potential with:

BOOLEAN

CHAR

DEFAULT

DOUBLE

ENUM

FLOAT

IF

INT

LONG

PACKAGE decode() .. otherwise() pivot(..).on(..).in(..)

SQL operators cannot be overloaded in Java

Most SQL operators have to be mapped to descriptive method names in Java, as Java does not allow operator overloading:


Page 237 / 245

The jOOQ User Manual 8.4. jOOQ's BNF pseudo-notation

=

<>, !=

||

SET a = b equal(), eq() notEqual(), ne() concat() set(a, b)

For those users using

jOOQ with Scala or Groovy

, operator overloading and implicit conversion can be

leveraged to enhance jOOQ:

=

<>, !=

||

===

<>, !==

||

SQL's reference before declaration capability

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

aliasing

SELECT t.a

FROM my_table t

MyTable t = MY_TABLE.as("t"); select(t.a).from(t)

A more sophisticated example are common table expressions (CTE), which are currently not supported by jOOQ:

WITH t(a, b) AS (

SELECT 1, 2 FROM DUAL

)

SELECT t.a, t.b

FROM t

Common table expressions define a "derived column list", just like

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 t.a from t.

8.4. jOOQ's BNF pseudo-notation

This chapter will soon contain an overview over jOOQ's API using a pseudo BNF notation.

8.5. Quality Assurance

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:

To evade JDBC's verbosity and error-proneness due to string concatenation and index-based variable binding

To add lots of type-safety to your inline SQL

To increase productivity when writing inline SQL using your favourite IDE's autocompletion capabilities

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:


Page 238 / 245

The jOOQ User Manual 8.5. Quality Assurance

Unit tests

Unit tests are performed against dummy JDBC interfaces using

http://jmock.org/

. These tests verify that various

org.jooq.QueryPart

implementations render correct SQL and bind variables correctly.

Integration tests

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.

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.

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.

Code generation tests

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.

API Usability tests and proofs of concept

jOOQ is used in jOOQ-meta as a proof of concept. This includes complex queries such as the following

Postgres query


Page 239 / 245

The jOOQ User Manual 8.6. Migrating to jOOQ 3.0

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)


.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)


.orderBy(

r1.ROUTINE_SCHEMA.asc(),

r1.ROUTINE_NAME.asc())

.fetch()) {

result.add(new PostgresRoutineDefinition(this, record));

}

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.

Clean API and implementation. Code is kept DRY

As a general rule of thumb throughout the jOOQ code, everything is kept

DRY

. Some examples:

There is only one place in the entire code base, which consumes values from a JDBC ResultSet

There is only one place in the entire code base, which transforms jOOQ Records into custom

POJOs

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.

8.6. Migrating to jOOQ 3.0

This section is for all users of jOOQ 2.x who wish to upgrade to the next major release. In the next subsections, the most important changes are explained. Some code hints are also added to help you fix compilation errors.


Page 240 / 245


Type-safe row value expressions

Support for


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.

Here are some affected API parts:

[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

Subqueries returned from DSL.select(...) now implement Select<Record[N]>, not Select<Record>

IN predicates and comparison predicates taking subselects changed incompatibly

INSERT and MERGE statements now take typesafe VALUES() clauses

Some hints related to row value expressions:

// 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();

SelectQuery and SelectXXXStep are now generic

In order to support type-safe row value expressions and type-safe Record[N] types, SelectQuery is now generic: SelectQuery<R>

SimpleSelectQuery and SimpleSelectXXXStep API were removed

The duplication of the SELECT API is no longer useful, now that SelectQuery and SelectXXXStep are generic.

Factory was split into DSL (query building) and DSLContext (query execution)

The pre-existing Factory class has been split into two parts: o The DSL: 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.

The DSL class corresponds to the static part of the jOOQ 2.x Factory type o The DSLContext: This type holds a reference to a Configuration and can construct executable

("attached") QueryParts.

The DSLContext type corresponds to the non-static part of the jOOQ 2.x Factory /

FactoryOperations type.

The FactoryOperations interface has been renamed to DSLContext. An example:


Page 241 / 245


// 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

8.6. Migrating to jOOQ 3.0

Quantified comparison predicates

Field.equalAny(...) and similar methods have been removed in favour of Field.equal(any(...)). This greatly simplified the Field API. An example:

// 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);

FieldProvider

The FieldProvider marker interface was removed. Its methods still exist on FieldProvider subtypes. Note, they have changed names from getField() to field() and from getIndex() to indexOf()

GroupField

GroupField has been introduced as a DSL marker interface to denote fields that can be passed to

GROUP BY clauses. This includes all org.jooq.Field types. However, fields obtained from ROLLUP(),

CUBE(), and GROUPING SETS() functions no longer implement Field. Instead, they only implement

GroupField. An example:

// 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

NULL predicate

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:


Page 242 / 245


To most users, this was a surprising "feature".

Other predicates didn't behave in such a way, e.g. the IN predicate, the BETWEEN predicate, or the LIKE predicate.

Variable binding behaved unpredictably, as IS NULL predicates don't bind any variables.

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.

Here is an example how to check if a field has a given value, without applying SQL's ternary NULL logic:

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);

Configuration

DSLContext, ExecuteContext, RenderContext, BindContext no longer extend Configuration for

"convenience". From jOOQ 3.0 onwards, composition is chosen over inheritance as these objects are not really configurations. Most importantly

DSLContext is only a DSL entry point for constructing "attached" QueryParts

ExecuteContext has a well-defined lifecycle, tied to that of a single query execution

RenderContext has a well-defined lifecycle, tied to that of a single rendering operation

BindContext has a well-defined lifecycle, tied to that of a single variable binding operation

In order to resolve confusion that used to arise because of different lifecycle durations, these types are now no longer formally connected through inheritance.

ConnectionProvider

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: public interface ConnectionProvider {

// Provide jOOQ with a connection

Connection acquire() throws DataAccessException;

// Get a connection back from jOOQ

void release(Connection connection) throws DataAccessException;

}

These are some side-effects of the above change

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.


Page 243 / 245


ExecuteListeners

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.

Data type API

The data type API has been changed drastically in order to enable some new DataType-related features.

These changes include:

[SQLDialect]DataType and SQLDataType no longer implement DataType. They're mere constant containers

Various minor API changes have been done.

Object renames

These objects have been moved / renamed:

jOOU: a library used to represent unsigned integer types was moved from org.jooq.util.unsigned

to org.jooq.util.types (which already contained INTERVAL data types)

Feature removals

Here are some minor features that have been removed in jOOQ 3.0


Page 244 / 245

The jOOQ User Manual 8.7. Credits

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 <java> target.

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.

The code generation configuration no longer accepts comma-separated regular expressions.

Use the regex pipe | instead.

The code generation configuration can no longer be loaded from .properties files. Only XML configurations are supported.

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.

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

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.

The UpdatableTable type has been removed. While adding significant complexity to the type hierarchy, this type adds not much value over a simple Table.getPrimaryKey() != null check.

The USE 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.

8.7. Credits

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:

-

Hibernate

: The de-facto standard (JPA) with its useful table-to-POJO mapping features have influenced jOOQ's


facilities

-

JaQu

: H2's own fluent API for querying databases

-

JPA

: The de-facto standard in the javax.persistence packages, supplied by Oracle. Its annotations are useful to jOOQ as well.

-

OneWebSQL

: A commercial SQL abstraction API with support for DAO source code generation, which was integrated also in jOOQ

-

QueryDSL

: 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.

-

SLICK

: 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.

-

Spring Data

: Spring's JdbcTemplate knows RowMappers, which are reflected by jOOQ's

RecordHandler

or

RecordMapper


Page 245 / 245