diff --git a/jOOQ-website/src/main/resources/manual-2.5.xml b/jOOQ-website/src/main/resources/manual-2.5.xml index 08543a86b9..690f35a212 100644 --- a/jOOQ-website/src/main/resources/manual-2.5.xml +++ b/jOOQ-website/src/main/resources/manual-2.5.xml @@ -4331,17 +4331,12 @@ create.select(LAST_NAME, COUNT1, COUNT2) -
- Query vs. ResultQuery +
+ Comparison between jOOQ and JDBC -

Query vs. ResultQuery

-

- Unlike JDBC, jOOQ has a lot of knowledge about a SQL query's structure and internals (see the manual's section about ). Hence, jOOQ distinguishes between these two fundamental types of queries. While every can be executed, only can return results (see the manual's section about to learn more about fetching results). -

-

Similarities with JDBC

- Even if there are two general types of Query, there are a lot of similarities between JDBC and jOOQ. Just to name a few: + Even if there are , there are a lot of similarities between JDBC and jOOQ. Just to name a few:

  • Both APIs return the number of affected records in non-result queries. JDBC: , jOOQ:
    • @@ -4353,6 +4348,7 @@ create.select(LAST_NAME, COUNT1, COUNT2) Some of the most important differences between JDBC and jOOQ are listed here:

      +
    • : JDBC does not formally distinguish between queries that can return results, and queries that cannot. The same API is used for both. This greatly reduces the possibility for
    • : While SQL uses the checked , jOOQ wraps all exceptions in an unchecked
    • : Unlike its JDBC counter-part, this type implements and is fully loaded into Java memory, freeing resources as early as possible. Just like statements, this means that users don't have to deal with a "weird" internal result set state.
    • : If you want more fine-grained control over how many records are fetched into memory at once, you can still do that using jOOQ's feature
      • @@ -4360,6 +4356,24 @@ create.select(LAST_NAME, COUNT1, COUNT2)
+ +
+ Query vs. ResultQuery + +

Query vs. ResultQuery

+

+ Unlike JDBC, jOOQ has a lot of knowledge about a SQL query's structure and internals (see the manual's section about ). Hence, jOOQ distinguishes between these two fundamental types of queries. While every can be executed, only can return results (see the manual's section about to learn more about fetching results). With plain SQL, the distinction can be made clear most easily: +

+ + resultQuery = create.resultQuery("SELECT * FROM BOOK"); +Result resultQuery.fetch();]]> + +
Fetching @@ -4799,12 +4813,113 @@ bookDao.delete(book);]]>
Lazy fetching - + +

Keeping underlying cursors open to reduce traffic

+

+ Unlike JDBC's , jOOQ's does not represent an open database cursor with various fetch modes and scroll modes, that needs to be closed after usage. jOOQ's results are simple in-memory Java objects, containing all of the result values. If your result sets are large, or if you have a lot of network latency, you may wish to fetch records one-by-one, or in small chunks. jOOQ supports a type for that purpose. In order to obtain such a reference, use the method. An example is given here: +

+ + cursor = null; + +try { + cursor = create.selectFrom(BOOK).fetchLazy(); + + // Cursor has similar methods as Iterator + while (cursor.hasNext()) { + BookRecord book = cursor.fetchOne(); + + Util.doThingsWithBook(book); + } +} + +// Close the cursor and the cursor's underlying JDBC ResultSet +finally { + if (cursor != null) { + cursor.close(); + } +}]]> + +

+ As a holds an internal reference to an open , it may need to be closed at the end of iteration. If a cursor is completely scrolled through, it will conveniently close the underlying ResultSet. However, you should not rely on that. +

+ +

Cursors ship with all the other fetch features

+

+ Like or , gives access to all of the other fetch features that we've seen so far, i.e. +

+
    +
  • : Cursors are also typed with the <R> type, allowing to fetch custom, generated or plain types.
    • +
  • : You can use your own callbacks to receive lazily fetched records.
    • +
  • : You can fetch data into your own custom POJO types.
    • +
+
Many fetching - + +

Fetching several result sets from a single query

+

+ Many databases support returning several result sets, or cursors, from single queries. An example for this is Sybase ASE's sp_help command: +

+ sp_help 'author' + ++--------+-----+-----------+-------------+-------------------+ +|Name |Owner|Object_type|Object_status|Create_date | ++--------+-----+-----------+-------------+-------------------+ +| author|dbo |user table | -- none -- |Sep 22 2011 11:20PM| ++--------+-----+-----------+-------------+-------------------+ + ++-------------+-------+------+----+-----+-----+ +|Column_name |Type |Length|Prec|Scale|... | ++-------------+-------+------+----+-----+-----+ +|id |int | 4|NULL| NULL| 0| +|first_name |varchar| 50|NULL| NULL| 1| +|last_name |varchar| 50|NULL| NULL| 0| +|date_of_birth|date | 4|NULL| NULL| 1| +|year_of_birth|int | 4|NULL| NULL| 1| ++-------------+-------+------+----+-----+-----+]]> + + +

+ The correct (and verbose) way to do this with JDBC is as follows: +

+ + + +

+ As previously discussed in the chapter about , jOOQ does not rely on an internal state of any JDBC object, which is "externalised" by Javadoc. Instead, it has a straight-forward API allowing you to do the above in a one-liner: +

+ +> results = create.fetchMany("sp_help 'author'");]]> + +

+ Using generics, the resulting structure is immediately clear. +

+