From 710a452b59e2e38fa9dc34d1056d79c2bd20c273 Mon Sep 17 00:00:00 2001 From: lukaseder Date: Tue, 19 Dec 2017 09:24:09 +0100 Subject: [PATCH] [#6482] Document in the manual: SQL and JDBC are one-based, jOOQ is zero-based --- .../resources/org/jooq/web/manual-3.1.xml | 2 +- .../resources/org/jooq/web/manual-3.10.xml | 2 +- .../resources/org/jooq/web/manual-3.11.xml | 61 +------------------ .../resources/org/jooq/web/manual-3.2.xml | 2 +- .../resources/org/jooq/web/manual-3.3.xml | 2 +- .../resources/org/jooq/web/manual-3.4.xml | 2 +- .../resources/org/jooq/web/manual-3.5.xml | 2 +- .../resources/org/jooq/web/manual-3.6.xml | 2 +- .../resources/org/jooq/web/manual-3.7.xml | 2 +- .../resources/org/jooq/web/manual-3.8.xml | 2 +- .../resources/org/jooq/web/manual-3.9.xml | 2 +- 11 files changed, 11 insertions(+), 70 deletions(-) diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.1.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.1.xml index 698c1990f9..13425ecc62 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.1.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.1.xml @@ -6964,7 +6964,7 @@ for (int i = 0; i < result.size(); i++)

All JDBC API is one-based

- An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based. + An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based.

diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.10.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.10.xml index 5fd982ba59..1acb0d50c4 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.10.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.10.xml @@ -10672,7 +10672,7 @@ for (int i = 0; i < result.size(); i++)

All JDBC API is one-based

- An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based. + An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based.

diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.11.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.11.xml index ad03720582..b9954d229b 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.11.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.11.xml @@ -10672,66 +10672,7 @@ for (int i = 0; i < result.size(); i++)

All JDBC API is one-based

- An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based. -

- - - -
- Zero-based vs one-based APIs - -

- Any API that bridges two languages / mind sets, such as Java / SQL will inevitably face the difficulty of finding a consistent strategy to solving the "based-ness" problem. Should arrays be one-based or zero-based? -

- -

- Clearly, Java is zero-based and SQL is one-based, and the best strategy for jOOQ is to keep things this way. The following are a set of rules that you should remember if this ever confuses you: -

- -

All SQL API is one-based

- -

- When using SQL API, such as the index-based , or such as in the example below, jOOQ will not interpret indexes but send them directly as-is to the SQL engine. For instance: -

- - - - - - - -

- In the above example, we're looking for the 3rd value of X in T ordered by Y. Clearly, this window function uses one-based indexing. The same is true for the ORDER BY clause, which orders the result by the 1st column - again one-based counting. There is no column zero in SQL. -

- -

All jOOQ API is zero-based

- -

- jOOQ is a Java API and as such, one-basedness would be quite surprising despite the fact that JDBC is one-based (see below). For instance, when you access a record by index in a jOOQ , given that the result extends , you will use zero-based index access: -

- - - result = create.select(BOOK.ID, BOOK.TITLE) - .from(BOOK) - .orderBy(1) - .fetch(); - -for (int i = 0; i < result.size(); i++) - System.out.println(result.get(i));]]> - - -

- Unlike in JDBC, where positions the underlying cursor at the one-based index, we Java developers really don't like that way of thinking. As can be seen in the above loop, we iterate over this result as we do over any other Java collection. -

- -

All JDBC API is one-based

- -

- An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based. + An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based.

diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.2.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.2.xml index 23fa48480c..344314cf3f 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.2.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.2.xml @@ -7278,7 +7278,7 @@ for (int i = 0; i < result.size(); i++)

All JDBC API is one-based

- An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based. + An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based.

diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.3.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.3.xml index cba2fd6aaf..3449bfb0e2 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.3.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.3.xml @@ -8073,7 +8073,7 @@ for (int i = 0; i < result.size(); i++)

All JDBC API is one-based

- An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based. + An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based.

diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.4.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.4.xml index 62f13381df..c3ec6b6a37 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.4.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.4.xml @@ -9041,7 +9041,7 @@ for (int i = 0; i < result.size(); i++)

All JDBC API is one-based

- An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based. + An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based.

diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.5.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.5.xml index acb8f3d476..6dd0eb6f94 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.5.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.5.xml @@ -9438,7 +9438,7 @@ for (int i = 0; i < result.size(); i++)

All JDBC API is one-based

- An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based. + An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based.

diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.6.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.6.xml index 3270078a7d..b0c2f8bbe7 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.6.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.6.xml @@ -9833,7 +9833,7 @@ for (int i = 0; i < result.size(); i++)

All JDBC API is one-based

- An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based. + An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based.

diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.7.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.7.xml index eb690a9be7..745d9a0707 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.7.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.7.xml @@ -10105,7 +10105,7 @@ for (int i = 0; i < result.size(); i++)

All JDBC API is one-based

- An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based. + An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based.

diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.8.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.8.xml index f84a6d8fbc..0527de512a 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.8.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.8.xml @@ -10329,7 +10329,7 @@ for (int i = 0; i < result.size(); i++)

All JDBC API is one-based

- An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based. + An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based.

diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.9.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.9.xml index 75c873766d..373c07eccf 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.9.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.9.xml @@ -10493,7 +10493,7 @@ for (int i = 0; i < result.size(); i++)

All JDBC API is one-based

- An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based. + An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a , you will work with JDBC API directly from within jOOQ, which is one-based.