diff --git a/jOOQ-website/src/main/resources/manual-2.5.xml b/jOOQ-website/src/main/resources/manual-2.5.xml index 867c00f2e5..742c1bebb2 100644 --- a/jOOQ-website/src/main/resources/manual-2.5.xml +++ b/jOOQ-website/src/main/resources/manual-2.5.xml @@ -4302,17 +4302,186 @@ create.select(LAST_NAME, COUNT1, COUNT2)
SQL execution - + +

SQL execution with jOOQ

+

+ In a previous section of the manual, we've seen how jOOQ can be used to that can be executed with any API including JDBC or ... jOOQ. This section of the manual deals with various means of actually executing SQL with jOOQ. +

+ +

SQL execution with JDBC

+

+ JDBC calls executable objects "". It distinguishes between three types of statements: +

+ +

+ Today, the JDBC API may look weird to users being used to object-oriented design. While statements hide a lot of SQL dialect-specific implementation details quite well, they assume a lot of knowledge about the internal state of a statement. For instance, you can use the method, to add a the prepared statement being created to an "internal list" of batch statements. Instead of returning a new type, this method forces user to reflect on the prepared statement's internal state or "mode". +

+ +

jOOQ is wrapping JDBC

+

+ These things are abstracted away by jOOQ, which exposes such concepts in a more object-oriented way. For more details about jOOQ's batch query execution, see the manual's section about . +

+

+ The following sections of this manual will show how jOOQ is wrapping JDBC for SQL execution +

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

+ +

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

+
    +
  • Both APIs return the number of affected records in non-result queries. JDBC: , jOOQ:
    • +
  • Both APIs return a scrollable result set type from result queries. JDBC: , jOOQ:
    • +
+ +

Differences to JDBC

+

+ Some of the most important differences between JDBC and jOOQ are listed here: +

+
    +
  • : 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
    • +
  • : jOOQ does not formally distinguish between static statements and prepared statements. By default, all statements are prepared statements in jOOQ, internally. Executing a statement as a static statement can be done simply using a
    • +
+
Fetching - + +

The power of fetching data with jOOQ

+

+ Fetching is something that has been completely neglegted by JDBC and also by various other database abstraction libraries. Fetching is much more than just looping or listing records or mapped objects. There are so many ways you may want to fetch data from a database, it should be considered a first-class feature of any database abstraction API. Just to name a few, here are some of jOOQ's fetching modes: +

+
    +
  • : Sometimes you care about the returned type of your records, sometimes (with arbitrary projections) you don't.
    • +
  • : Instead of letting you transform your result sets into any more suitable data type, a library should do that work for you.
    • +
  • : This is an entirely different fetching paradigm. With Java 8's lambda expressions, this will become even more powerful.
    • +
  • : This is what made Hibernate and JPA so strong. Automatic mapping of tables to custom POJOs.
    • +
  • : It should be easy to distinguish these two fetch modes.
    • +
  • : Some databases allow for returning many result sets from a single query. JDBC can handle this but it's very verbose. A list of results should be returned instead.
    • +
  • : Some queries take too long to execute to wait for their results. You should be able to spawn query execution in a separate process.
    • +
+ +

Convenience and how ResultQuery, Result, and Record share API

+

+ The term "fetch" is always reused in jOOQ when you can fetch data from the database. An provides many overloaded means of fetching data: +

+ +

Various modes of fetching

+

+ These modes of fetching are also documented in subsequent sections of the manual +

+ + fetch(); + +// The "standard" fetch when you know your query returns only one record +R fetchOne(); + +// The "standard" fetch when you only want to fetch the first record +R fetchAny(); + +// Create a "lazy" Cursor, that keeps an open underlying JDBC ResultSet +Cursor fetchLazy(); +Cursor fetchLazy(int fetchSize); + +// Create a java.util.concurrent.Future, to handle asynchronous execution of the ResultQuery +FutureResult fetchLater(); +FutureResult fetchLater(ExecutorService executor); + +// Fetch several results at once +List> fetchMany(); + +// Fetch records into a custom callback +> H fetchInto(H handler); + +// Execute a ResultQuery with jOOQ, but return a JDBC ResultSet, not a jOOQ object +ResultSet fetchResultSet();]]> + +

Fetch convenience

+

+ These means of fetching are also available from and APIs +

+ + List fetch(Field field); + List fetch(Field field, Class type); + List fetch(Field field, Converter converter); + List fetch(int fieldIndex); + List fetch(int fieldIndex, Class type); + List fetch(int fieldIndex, Converter converter); + List fetch(String fieldName); + List fetch(String fieldName, Class type); + List fetch(String fieldName, Converter converter); + +// These methods are convenience for fetching only a single field, possibly converting results to another type +// Instead of returning lists, these return arrays + T[] fetchArray(Field field); + T[] fetchArray(Field field, Class type); + U[] fetchArray(Field field, Converter converter); + Object[] fetchArray(int fieldIndex); + T[] fetchArray(int fieldIndex, Class type); + U[] fetchArray(int fieldIndex, Converter converter); + Object[] fetchArray(String fieldName); + T[] fetchArray(String fieldName, Class type); + U[] fetchArray(String fieldName, Converter converter); + +// These methods are convenience for fetching only a single field from a single record, possibly converting results to another type + T fetchOne(Field field); + T fetchOne(Field field, Class type); + U fetchOne(Field field, Converter converter); + Object fetchOne(int fieldIndex); + T fetchOne(int fieldIndex, Class type); + U fetchOne(int fieldIndex, Converter converter); + Object fetchOne(String fieldName); + T fetchOne(String fieldName, Class type); + U fetchOne(String fieldName, Converter converter);]]> + +

Fetch transformations

+

+ These means of fetching are also available from and APIs +

+ + Map fetchMap(Field key); + Map fetchMap(Field key, Field value); + List> fetchMaps(); + Map fetchOneMap(); + +// Transform your Result object into groups + Map> fetchGroups(Field key); + Map> fetchGroups(Field key, Field value); + +// Transform your Records into custom POJOs + List fetchInto(Class type), MappingException; + +// Transform your records into another table type + Result fetchInto(Table table);]]> + +

+ Note, that apart from the methods, all fetch() methods will immediately close underlying JDBC result sets. +

+
@@ -4345,6 +4514,11 @@ create.select(LAST_NAME, COUNT1, COUNT2)
+
+ Later fetching + +
+
ResultSet fetching @@ -4356,6 +4530,12 @@ create.select(LAST_NAME, COUNT1, COUNT2)
+ +
+ Static statements vs. Prepared Statements + + +
Using JDBC batch operations