Document FirebirdSQL/jaybird#831 and FirebirdSQL/jaybird#755

Author: mrotteveel

Diff for: src/docs/asciidoc/appendices/connectionproperties/connectionproperties.adoc

@@ -74,6 +74,13 @@ See <<ref-processinfo>> for more information.
 |Connection property (+ aliases) 
 |Explanation
 
+a|`asyncFetch`
+a|Jaybird specific property ([.since]_Jaybird 6_).
+Boolean property.
+Enables/disables async fetching for pure Java connections.
+Default is `true`.
+See <<ref-async-fetch>> for more information.
+
 a|`encoding` +
 `lc_ctype`, `isc_dpb_lc_ctype`
 a|Character encoding for the connection using the Firebird character set name.
@@ -302,6 +309,7 @@ a|`createDatabaseIfNotExist`
 a|Jaybird specific property ([.since]_Jaybird 6_).
 Boolean property.
 Attempts to create a database if it does not exist.
+Default is `false`.
 See <<ref-create-database-if-not-exist>> for more information.
 
 a|`reportSQLWarnings`

Diff for: src/docs/asciidoc/appendices/systemproperties/systemproperties.adoc

@@ -52,9 +52,20 @@ This property will have no effect if `org.firebirdsql.jdbc.defaultConnectionEnco
 
 The property values are read for each connect, so the value can be changed at any time.
 
+[#systemproperties-default-async-fetch]
+=== Default `asyncFetch` value
+
+[.since]_Jaybird 6_
+
+`org.firebirdsql.jdbc.defaultAsyncFetch`::
+Configures the default value for the `asyncFetch` connection property.
+See <<ref-async-fetch>> for more information.
+
 [#systemproperties-default-enable-protocol]
 === Default `enableProtocol` value
 
+[.since]_Jaybird 6_
+
 `org.firebirdsql.jdbc.defaultEnableProtocol`::
 Configures the default value for the `enableProtocol` connection property.
 See <<ref-enable-protocol>> for more information.
@@ -63,6 +74,8 @@ See <<ref-enable-protocol>> for more information.
 
 === Default `reportSQLWarnings` value
 
+[.since]_Jaybird 6_
+
 `org.firebirdsql.jdbc.defaultReportSQLWarnings`::
 Configures the default value for the `reportSQLWarnings` connection property.
 See <<ref-report-sql-warnings>> for more information.

Diff for: src/docs/asciidoc/reference/connection/asyncfetch.adoc

@@ -0,0 +1,38 @@
+[#ref-async-fetch]
+=== Async fetch
+
+[.since]_Jaybird 6_
+
+For pure Java connections, non-holdable forward-only result sets perform asynchronous fetches by default.
+Asynchronous fetches are implemented for protocol implementation version 11 and higher (i.e. Firebird 2.1 or higher), but are formally only supported for protocol version 13 and higher (i.e. Firebird 3.0 or higher).
+
+In normal usage of a result set, the first fetch will be a normal synchronous fetch.
+If certain conditions are met, subsequent fetches will be performed asynchronously.
+
+The conditions for using asynchronous fetch are considered an implementation detail and may change in point releases.
+In Jaybird 6.0.0, the conditions to enable asynchronous fetching are:
+
+. The result set has type `FORWARD_ONLY`.
+. The result set does not have a cursor name set.
+. Any synchronous fetch on the statement cursor retrieved at least 15 rows.
+Be aware that the server may return fewer rows than the configured fetch size (default is 400), depending on Firebird version, row size and other factors.
+
+When the asynchronous fetch is triggered is also an implementation detail and may change in point releases.
+In Jaybird 6.0.0, the conditions to perform an asynchronous fetch are:
+
+* Size of the row buffer is equal to the "`low-water mark`".
++
+This "`low-water mark`" is calculated as ~33% of the maximum number of rows returned by previous fetches, with a minimum of 10 rows.
++
+As a consequence of this condition, reducing the fetch size equal to or less than the "`low-water mark`" may cause asynchronous fetches to stop being triggered, as the buffer size may remain smaller than this "`low-water mark`" (this effect may be reduced if there is other activity on the connection after the asynchronous fetch was performed).
+In that case, a synchronous fetch is triggered when the buffer is empty.
+* Fetch size at time of async fetch is larger than 1.
+This may be the configured fetch size, or the fetch size derived taking into account the configured maximum row count.
+
+Native connections do not support this type of asynchronous fetching, but `fbclient` itself provides a different form of internal asynchronous fetching for native connections.
+
+Asynchronous fetching -- for pure Java -- can be disabled with the Boolean connection property `asyncFetch`, by setting it to `false`.
+The system property <<systemproperties-default-async-fetch,`org.firebirdsql.jdbc.defaultAsyncFetch`>> can be used to disable it globally;
+this system property is checked dynamically when the connection configuration is created.
+These properties are primarily intended for troubleshooting or workarounds if it turns out this feature has problems;
+they may be removed in a future Jaybird version once this feature has proven itself.

Diff for: src/docs/asciidoc/reference/reference.adoc

@@ -4,6 +4,8 @@
 [[ref-connection]]
 == Connection reference
 
+include::connection/asyncfetch.adoc[]
+
 include::connection/authenticationplugins.adoc[]
 
 include::connection/wirecrypt.adoc[]