github/jooq
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[#6482] Document in the manual: SQL and JDBC are one-based, jOOQ is zero-based

Browse Source
This commit is contained in:
lukaseder 2017-12-19 09:24:09 +01:00
parent 5bb2d17f9d
commit 710a452b59
11 changed files with 11 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
jOOQ-manual/src/main/resources/org/jooq/web/manual-3.1.xml
View File

@ -6964,7 +6964,7 @@ for (int i = 0; i < result.size(); i++)
<h3>All JDBC API is one-based</h3>
<p>
An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a <reference id="custom-binding" title="custom data type binding"/>, 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 <reference id="custom-bindings" title="custom data type binding"/>, you will work with JDBC API directly from within jOOQ, which is one-based.
</p>
</html></content>
</section>

2
jOOQ-manual/src/main/resources/org/jooq/web/manual-3.10.xml
View File

@ -10672,7 +10672,7 @@ for (int i = 0; i < result.size(); i++)
<h3>All JDBC API is one-based</h3>
<p>
An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a <reference id="custom-binding" title="custom data type binding"/>, 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 <reference id="custom-bindings" title="custom data type binding"/>, you will work with JDBC API directly from within jOOQ, which is one-based.
</p>
</html></content>
</section>

61
jOOQ-manual/src/main/resources/org/jooq/web/manual-3.11.xml
View File

@ -10672,66 +10672,7 @@ for (int i = 0; i < result.size(); i++)
<h3>All JDBC API is one-based</h3>
<p>
An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a <reference id="custom-binding" title="custom data type binding"/>, you will work with JDBC API directly from within jOOQ, which is one-based.
</p>
</html></content>
</section>
<section id="zero-based-vs-one-based">
<title>Zero-based vs one-based APIs</title>
<content><html>
<p>
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?
</p>
<p>
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:
</p>
<h3>All SQL API is one-based</h3>
<p>
When using SQL API, such as the index-based <reference id="order-by-clause" title="ORDER BY clause"/>, or <reference id="window-functions" title="window functions"/> such as in the example below, jOOQ will not interpret indexes but send them directly as-is to the SQL engine. For instance:
</p>
</html>
<code-pair><sql><![CDATA[SELECT nth_value(title, 3) OVER (ORDER BY id)
FROM book
ORDER BY 1]]></sql>
<java><![CDATA[create.select(nthValue(BOOK.TITLE, 3).over(orderBy(BOOK.ID)))
.from(BOOK)
.orderBy(1).fetch();]]></java>
</code-pair>
<html>
<p>
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 <code>ORDER BY</code> clause, which orders the result by the 1st column - again one-based counting. There is no column zero in SQL.
</p>
<h3>All jOOQ API is zero-based</h3>
<p>
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 <reference class="org.jooq.Result"/>, given that the result extends <reference class="java.util.List"/>, you will use zero-based index access:
</p>
</html>
<java><![CDATA[Result<?> 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));]]></java>
<html>
<p>
Unlike in JDBC, where <reference class="java.sql.ResultSet" anchor="#absolute-int-" title="java.sql.ResultSet#absolute(int)"/> 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.
</p>
<h3>All JDBC API is one-based</h3>
<p>
An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a <reference id="custom-binding" title="custom data type binding"/>, 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 <reference id="custom-bindings" title="custom data type binding"/>, you will work with JDBC API directly from within jOOQ, which is one-based.
</p>
</html></content>
</section>

2
jOOQ-manual/src/main/resources/org/jooq/web/manual-3.2.xml
View File

@ -7278,7 +7278,7 @@ for (int i = 0; i < result.size(); i++)
<h3>All JDBC API is one-based</h3>
<p>
An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a <reference id="custom-binding" title="custom data type binding"/>, 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 <reference id="custom-bindings" title="custom data type binding"/>, you will work with JDBC API directly from within jOOQ, which is one-based.
</p>
</html></content>
</section>

2
jOOQ-manual/src/main/resources/org/jooq/web/manual-3.3.xml
View File

@ -8073,7 +8073,7 @@ for (int i = 0; i < result.size(); i++)
<h3>All JDBC API is one-based</h3>
<p>
An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a <reference id="custom-binding" title="custom data type binding"/>, 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 <reference id="custom-bindings" title="custom data type binding"/>, you will work with JDBC API directly from within jOOQ, which is one-based.
</p>
</html></content>
</section>

2
jOOQ-manual/src/main/resources/org/jooq/web/manual-3.4.xml
View File

@ -9041,7 +9041,7 @@ for (int i = 0; i < result.size(); i++)
<h3>All JDBC API is one-based</h3>
<p>
An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a <reference id="custom-binding" title="custom data type binding"/>, 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 <reference id="custom-bindings" title="custom data type binding"/>, you will work with JDBC API directly from within jOOQ, which is one-based.
</p>
</html></content>
</section>

2
jOOQ-manual/src/main/resources/org/jooq/web/manual-3.5.xml
View File

@ -9438,7 +9438,7 @@ for (int i = 0; i < result.size(); i++)
<h3>All JDBC API is one-based</h3>
<p>
An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a <reference id="custom-binding" title="custom data type binding"/>, 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 <reference id="custom-bindings" title="custom data type binding"/>, you will work with JDBC API directly from within jOOQ, which is one-based.
</p>
</html></content>
</section>

2
jOOQ-manual/src/main/resources/org/jooq/web/manual-3.6.xml
View File

@ -9833,7 +9833,7 @@ for (int i = 0; i < result.size(); i++)
<h3>All JDBC API is one-based</h3>
<p>
An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a <reference id="custom-binding" title="custom data type binding"/>, 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 <reference id="custom-bindings" title="custom data type binding"/>, you will work with JDBC API directly from within jOOQ, which is one-based.
</p>
</html></content>
</section>

2
jOOQ-manual/src/main/resources/org/jooq/web/manual-3.7.xml
View File

@ -10105,7 +10105,7 @@ for (int i = 0; i < result.size(); i++)
<h3>All JDBC API is one-based</h3>
<p>
An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a <reference id="custom-binding" title="custom data type binding"/>, 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 <reference id="custom-bindings" title="custom data type binding"/>, you will work with JDBC API directly from within jOOQ, which is one-based.
</p>
</html></content>
</section>

2
jOOQ-manual/src/main/resources/org/jooq/web/manual-3.8.xml
View File

@ -10329,7 +10329,7 @@ for (int i = 0; i < result.size(); i++)
<h3>All JDBC API is one-based</h3>
<p>
An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a <reference id="custom-binding" title="custom data type binding"/>, 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 <reference id="custom-bindings" title="custom data type binding"/>, you will work with JDBC API directly from within jOOQ, which is one-based.
</p>
</html></content>
</section>

2
jOOQ-manual/src/main/resources/org/jooq/web/manual-3.9.xml
View File

@ -10493,7 +10493,7 @@ for (int i = 0; i < result.size(); i++)
<h3>All JDBC API is one-based</h3>
<p>
An exception to the above rule is, obviously, all jOOQ API that is JDBC-interfacing. E.g. when you implement a <reference id="custom-binding" title="custom data type binding"/>, 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 <reference id="custom-bindings" title="custom data type binding"/>, you will work with JDBC API directly from within jOOQ, which is one-based.
</p>
</html></content>
</section>