Misc. improvements to Result sets

Author: mrotteveel

src/docs/asciidoc/chapters/resultsets/resultsets.adoc

@@ -1,7 +1,7 @@
 [[resultsets]]
 == Working with result sets
 
-When a `SELECT` statement is executed, the results of the query are returned through the implementation of the `java.sql.ResultSet` interface.
+When a `SELECT` statement is executed, the results of the query are returned through an implementation of the `java.sql.ResultSet` interface.
 
 === ResultSet properties
 
@@ -10,44 +10,62 @@ When a `SELECT` statement is executed, the results of the query are returned thr
 
 The JDBC specification defines three types of result sets
 
-* `TYPE_FORWARD_ONLY` -- the result set is not scrollable, the cursor can only move forward.
-When the `TRANSACTION_READ_COMMITTED` isolation level is used, the result set will return all rows that are satisfying the search condition at the moment of fetch (which -- simplified -- will be every _fetch size_ calls to `ResultSet.next()`).
-In other cases, the result set will return only rows that were visible at the moment of the transaction start.
+`TYPE_FORWARD_ONLY`::
+The result set is not scrollable, the cursor can only move forward.
++
+For isolation level `TRANSACTION_READ_COMMITTED`, the result set will return all rows that satisfy the search condition at the moment of -- Firebird 4.0 and higher -- query execution, or -- Firebird 3.0 and earlier -- fetch (which -- simplified -- will be every _fetch size_ calls to `ResultSet.next()`).
+For other isolation levels, the result set will return rows that were visible at query execution.
 +
 This is the default result set type.
-* `TYPE_SCROLL_INSENSITIVE` -- the result set is scrollable, the cursor can move back and forth, can be positioned on the specified row.
-Only rows satisfying the condition at the time of query execution are visible.
-* `TYPE_SCROLL_SENSITIVE`, is not supported by Firebird and Jaybird.
-Jaybird allows an application to ask for this type of result set, however in compliance with the JDBC specification, the type is "downgraded" to the `TYPE_SCROLL_INSENSITIVE` and a corresponding warning is added to the connection object.
 
-Due to missing support for scrollable cursors in Firebird 4.0 and earlier, support for scrollable results set (`TYPE_SCROLL_INSENSITIVE` result set type) is implemented by fetching the complete result set to the client.
+`TYPE_SCROLL_INSENSITIVE`::
+The result set is scrollable.
++
+The cursor can move back and forth, can be positioned on the specified row.
+Only rows that satisfy the condition at the time of query execution are visible.
+
+`TYPE_SCROLL_SENSITIVE`::
+This type is not supported by Firebird and Jaybird.
++
+Jaybird allows an application to ask for this type of result set, however in compliance with the JDBC specification, the type is "`downgraded`" to `TYPE_SCROLL_INSENSITIVE` and a corresponding warning is added to the connection object.
+
+Due to missing support for scrollable cursors in Firebird 4.0 and earlier, support for scrollable results sets (`TYPE_SCROLL_INSENSITIVE`) is implemented by fetching the complete result set to the client.
 Scrolling happens in memory on the client.
 This can have adverse effect on the system memory usage and performance when the result set is large.
 
 since:[Jaybird 5] +
 since:[Firebird 5.0]
 
-Starting with Firebird 5.0, server-side scrollable cursors are supported.
+Starting with Firebird 5.0, server-side scrollable cursors are supported, but not enabled by default.
 Jaybird 5 introduced support for scrollable non-holdable result set when the connection property `scrollableCursor` is set to value `SERVER`, and the connection is a pure Java connection (not native or embedded).
 A future version may enable this behaviour by default.
 
 [[resultsets-concurrency]]
 ==== ResultSet Concurrency
 
-Result set concurrency specifies whether the result set object can be updated directly or a separate SQL request should be used to update the row.
+Result set concurrency specifies if a row in the result set object can be updated directly through the result set.
 Result sets that allow direct modification using the `ResultSet.updateXXX` methods are usually used in GUI applications which allow in-place editing of the underlying result set.
 
 The result set concurrency is specified during statement creation and cannot be changed later.
 JDBC defines two types of result set concurrency, which are both supported by Jaybird:
 
-* `CONCUR_READ_ONLY` is available for all types of result sets.
-It tells the driver that direct update of the result set is not possible and all `ResultSet.updateXXX` methods should throw an exception.
-* `CONCUR_UPDATABLE` is supported only under certain conditions that are needed for the driver to correctly construct a DML request that will modify exactly one row.
+`CONCUR_READ_ONLY`::
+Read-only result set.
+This type is always supported.
+It tells the driver that direct update of the result set is not possible.
+All `ResultSet.updateXXX` methods throw an exception.
+
+`CONCUR_UPDATABLE`::
+Updatable result set.
+This is supported only under certain conditions that are needed for the driver to correctly construct a DML request that will modify exactly one row.
 These conditions are:
-** the SELECT statement references only one table;
-** all columns that are not referenced by the SELECT statement allow `NULL` values, otherwise it won't be possible to insert new rows;
-** the SELECT statement does not contain the `DISTINCT` predicate, aggregate functions, joined tables, or stored procedures;
-** the SELECT statement references all columns of the tables primary key definition or the `RDB$DB_KEY` column.
++
+--
+* the `SELECT` statement references only one table;
+* all columns that are not referenced by the `SELECT` statement allow `NULL` values, otherwise it won't be possible to insert new rows;
+* the `SELECT` statement does not contain the `DISTINCT` predicate, aggregate functions, joined tables, or stored procedures;
+* the `SELECT` statement references all columns of the tables primary key definition or the `RDB$DB_KEY` column.
+--
 
 [[resultsets-holdability]]
 ==== ResultSet Holdability
@@ -56,19 +74,19 @@ Result set holdability informs the driver whether result sets should be kept ope
 `ResultSet.HOLD_CURSORS_OVER_COMMIT` tells the driver to keep the result set object open, while `ResultSet.CLOSE_CURSORS_AT_COMMIT` tells driver to close them on commit.
 
 When an application calls `Connection.commit()`, the Firebird server closes all open result sets.
-It is not possible to tell the server to keep a result set open over commit unless "commit retaining" mode is used.
+It is not possible to tell the server to keep a result set open over commit unless "`commit retaining`" mode is used.
 This mode is global for the complete connection and is not suitable for holdability control on a statement level.
-Use of "commit retaining" mode als has an undesirable side effect for read-write transactions as it inhibits garbage collection.
-Because of these reasons "commit retaining" is not used in Jaybird during normal execution.
-Applications can commit the transaction keeping the result sets open by executing a "`COMMIT RETAIN`" SQL statement.
+Use of "`commit retaining`" mode also has an undesirable side effect for read-write transactions as it inhibits garbage collection.
+Because of these reasons "`commit retaining`" is not used in Jaybird during normal execution.
+If really needed, applications can commit the transaction keeping the result sets open by executing a `COMMIT RETAIN` SQL statement.
 
 To support holdable result sets, Jaybird will cache all rows locally. +
 until:[Jaybird 6] In Jaybird 5 and earlier, for `TYPE_FORWARD_ONLY`, this is achieved by upgrading to `TYPE_SCROLL_INSENSITIVE`. See also <<resultsets-types>>. +
 since:[Jaybird 6] Since Jaybird 6, the result set type is no longer upgraded to `TYPE_SCROLL_INSENSITIVE`, but all rows are still cached locally.
 
 [NOTE]
 ====
-When connecting to Firebird 5.0 with Jaybird 5 or higher and connection property `scrollableCursor=SERVER`, a holdable result set will not use server-side scrollable cursor, but instead emulate by caching.
+When connecting to Firebird 5.0 with Jaybird 5 or higher and connection property `scrollableCursor=SERVER`, a holdable result set will not use a server-side scrollable cursor, but instead emulate by caching.
 Server-side scrollable cursors do not support the holdable behaviour.
 ====
 
@@ -79,9 +97,9 @@ Server-side scrollable cursors do not support the holdable behaviour.
 
 [NOTE]
 ====
-until:[Jaybird 5.0.5] The implementation in Jaybird 5.0.4 and older does not allow calls to the `getResultSet()` method after using an `executeQuery` or the `getResultSet()` method of the `Statement` class.
+until:[Jaybird 5.0.5] The implementation in Jaybird 5.0.4 and older does not allow calls to the `getResultSet()` method if the result set was already returned by `executeQuery` or a previous call to `getResultSet()`.
 
-since:[Jaybird 5.0.5] Starting with Jaybird 5.0.5, calls to `getResultSet()` will return the current result set, even if the result set was returned before by an `executeQuery` or the `getResultSet()` method.
+since:[Jaybird 5.0.5] Starting with Jaybird 5.0.5, calls to `getResultSet()` will return the current result set, even if the result set was already returned before by an `executeQuery` or the `getResultSet()` method.
 ====
 
 [source,java]
@@ -108,11 +126,11 @@ try (Statement stmt = connection.createStatement()) {
 
 ==== Accessing the values in the result set
 
-Depending on the type of the result set, it is possible to move the cursor either forward only (link:#using-forward-only[next example]) or using absolute and relative positioning (link:#using-scrollable-updatable[second example below]).
+Depending on the type of the result set, it is possible to move the cursor either forward only (link:#using-forward-only[next example]), or using absolute and relative positioning (link:#using-scrollable-updatable[second example below]).
 
 Values of the result set are obtained by calling the corresponding getter method depending on the type of column.
 For example, the `ResultSet.getInt(1)` method returns the value of the first column as an `int` value.
-If the value of the column is not integer, Jaybird tries to convert it according to the conversions specified in <<datatypeconversion>>.
+If the value of the column is not `INTEGER`, Jaybird tries to convert it according to the conversions specified in <<datatypeconversion>>.
 If conversion is not possible, an exception is thrown.
 
 There are two possibilities to obtain data from result set columns: by column label or by column position.
@@ -147,7 +165,7 @@ try (Statement forwardStatement = connection.createStatement();
 
 ==== Updating records in the result set
 
-Scrollable cursors are especially useful when result of some query is displayed by the application which also allows the user to directly edit the data and post the changes to the database.
+Updatable result sets are especially useful when the result of some query is displayed by the application which also allows the user to directly edit the data and post the changes to the database.
 
 [[using-scrollable-updatable]]
 [source,java]
@@ -208,12 +226,12 @@ try (Statement selectStmt = connection.createStatement();
 }
 ----
 
-// TODO: Verify if above example works, shouldn't myColumn be included in the select?
+// TODO: Verify if above example works, shouldn't myColumn be included in the select, and the column list in FOR UPDATE is ignored
 
 ==== Closing the result set
 
 A result set is closed by calling the `ResultSet.close()` method.
-This releases the associated server resources and makes the `ResultSet` object available for garbage collection.
+This releases the associated server resources, and clears data held in the `ResultSet` object, making it available for garbage collection.
 It is strongly recommended to explicitly close result sets in auto-commit mode or `ResultSet.TYPE_SCROLL_INSENSITIVE` result sets, because this releases memory used for the cached data.
 Whenever possible, use try-with-resources.