From 3c4e81e439776ad8a2bd3ff75afc0da1ef2fcac4 Mon Sep 17 00:00:00 2001 From: Lukas Eder Date: Wed, 13 Feb 2013 21:03:13 +0100 Subject: [PATCH] [#1897] Add a section to the manual about the migration to jOOQ 3.0 --- .../src/main/resources/manual-3.0.xml | 207 +++++++++++++++--- 1 file changed, 179 insertions(+), 28 deletions(-) diff --git a/jOOQ-website/src/main/resources/manual-3.0.xml b/jOOQ-website/src/main/resources/manual-3.0.xml index 62f4b7ca65..5c4f34c94e 100644 --- a/jOOQ-website/src/main/resources/manual-3.0.xml +++ b/jOOQ-website/src/main/resources/manual-3.0.xml @@ -236,6 +236,11 @@ BOOK.TITLE, AUTHOR.LAST_NAME // correspond to com.example.generated.Tables.BOOK. // Whenever you see "create" being used in Java code, assume that this is an instance of org.jooq.impl.Factory: Factory create = new Factory(connection, SQLDialect.ORACLE);]]> +

Arity / Degree

+

+ jOOQ records (and many other API elements) have a degree N between 1 and {max-row-degree}. The variable degree of an API element is denoted as [N], e.g. Row[N] or Record[N] +

+

Settings

jOOQ allows to override runtime behaviour using . If nothing is specified, the default runtime settings are assumed. @@ -2992,7 +2997,7 @@ new Factory(SQLDialect.SYBASE ).selectOne().getSQL();]]> Column expressions

- Column expressions can be used in various SQL clauses in order to refer to one or several columns. This chapter explains how to form various types of column expressions with jOOQ. A particular type of column expression is given in the section about , where an expression may have a degree of more than one. + Column expressions can be used in various SQL clauses in order to refer to one or several columns. This chapter explains how to form various types of column expressions with jOOQ. A particular type of column expression is given in the section about , where an expression may have a degree of more than one.

Using column expressions in jOOQ

@@ -9172,46 +9177,192 @@ for (Record record : create().select( 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 sub-sections, the most important changes are explained + This section is for all users of jOOQ 2.x who wish to upgrade to the next major release. In the next sub-sections, the most important changes are explained. Some code hints are also added to help you fix compilation errors.

-

Type-safe Record1 through Record22

+

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

+

+ Some hints related to row value expressions: +

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

-

Separation of query building and query execution, removed FactoryOperations

-

No sub-factories anymore (no deprecation yet)

-

Quantified comparison predicates (no deprecation yet)

-

Master data types have been removed

-

GroupField

-

? extends T has been relaxed, e.g. for casting, Field.getType(), etc.

-

Ant task removed

-

#2001 eq/equal(null) and ne/notEqual(null) now work as in SQL

-

ConnectionProvider

- -

ExecuteListeners are configured as instances in Configuration, no longer in Settings

+

+ The duplication of the SELECT API is no longer useful, now that SelectQuery and SelectXXXStep are generic. +

-

The data type API has been changed heavily

+

Query building vs. query execution

+

+ The pre-existing Factory class has been split into two parts: +

+ +
    +
  1. The Factory: This class contains only static factory methods. All QueryParts constructed from this class are "unattached", i.e. queries that are constructed through a Factory cannot be executed immediately. This is useful for subqueries.
    2. +
  2. The Executor: This class holds a reference to a Configuration and can construct executable ("attached") QueryParts.
    3. +
+ +

+ The FactoryOperations interface has been removed entirely. An example: +

+ + + +

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

+ +> subselect = any(select(BOOK.ID).from(BOOK)); +Condition condition = BOOK.ID.equal(subselect);]]> + +

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

+ + field1a = Factory.rollup(...); // OK +Field field2a = Factory.one(); // OK + +// jOOQ 3.0 +GroupField field1b = Factory.rollup(...); // OK +Field field1c = Factory.rollup(...); // Compilation error +GroupField field2b = Factory.one(); // OK +Field field2c = Factory.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: +

+ + + +

+ Here is an example how to check if a field has a given value, without applying SQL's ternary NULL logic: +

+ + + +

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

+ + + +

+ These are some side-effects of the above change +

+ + + +

ExecuteListeners

+

+ ExecuteListeners can no longer be configured via Settings. Instead they have to be injected into the Configuration (e.g. the Executor). 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: +

+ - -

No more navigation methods and "foreign key setters"

-

No more comma-separated regular expressions

-

No more .properties files for code generation

- +

Object renames

+

+ These objects have been moved / renamed: +

+ + +

Feature removals

+

+ Here are some minor features that have been removed in jOOQ 3.0 +

+ + + + +

No sub-factories anymore

+

+ As Factory is no longer +