Sync FAQ from master

Author: mrotteveel

src/docs/asciidoc/faq.adoc

@@ -7,9 +7,9 @@
 :source-highlighter: prettify
 :toc: left
 :icons: font
-:jaybird6-full-version: 6.0.2
+:jaybird6-full-version: 6.0.3
 :jaybird6-jna-version: 5.17.0
-:jaybird5-full-version: 5.0.8
+:jaybird5-full-version: 5.0.9
 :jaybird5-template-version: {jaybird5-full-version}.<java>
 :jaybird5-example-version: {jaybird5-full-version}.java11
 :jaybird5-jna-version: 5.17.0
@@ -42,6 +42,9 @@ SPDX-License-Identifier: LicenseRef-PDL-1.0
 [#jaybird-6]
 ==== Jaybird 6
 
+Jaybird 6 requires Java 17 or higher.
+For older Java versions (Java and higher), use <<jaybird-5>>.
+
 Jaybird 6 is available on Maven Central:
 
 [horizontal.compact]
@@ -91,6 +94,8 @@ To enable the "`ChaCha64`" wire encryption support for pure Java connections, yo
 [#jaybird-5]
 ==== Jaybird 5
 
+Unless you need to use Java 8 or Java 11, we recommend upgrading to <<jaybird-6>>.
+
 Jaybird 5 is available on Maven Central:
 
 [horizontal.compact]
@@ -127,7 +132,7 @@ If you want to use Type 2 support (native or embedded), you need to explicitly i
 ==== Jaybird 4
 
 Jaybird 4 is end-of-life and will receive no further updates.
-We recommend upgrading to <<jaybird-5>>.
+We recommend upgrading to <<jaybird-6>>.
 
 ////
 // Stop showing Jaybird 4 Maven info, but keep available for now
@@ -195,7 +200,7 @@ If you want to use Type 2 support (native, local or embedded), you need to expli
 +++<a name="jaybird-3.0">++++++</a>+++
 
 Jaybird 3 is end-of-life and will receive no further updates.
-We recommend upgrading to <<jaybird-5>>.
+We recommend upgrading to <<jaybird-6>>.
 
 ////
 // Stop showing Jaybird 3 Maven info, but keep available for now
@@ -260,7 +265,7 @@ If you want to use Type 2 support (native, local or embedded), you need to  expl
 ==== Jaybird 2.2
 
 Jaybird 2.2 is end-of-life and will receive no further updates.
-We recommend upgrading to <<jaybird-5>>.
+We recommend upgrading to <<jaybird-6>>.
 
 ////
 // Stop showing Jaybird 2.2 Maven info, but keep available for now
@@ -293,15 +298,15 @@ When deploying to a JavaEE environment, exclude the `javax.resource connector-ap
 
 Jaybird can be downloaded from the Firebird website, under Downloads, https://firebirdsql.org/en/jdbc-driver/[JDBC Driver].
 
-Alternatively, you can go directly to GitHub and download Jaybird from the https://github.com/FirebirdSQL/jaybird/releases[jaybird releases].
+Alternatively, you can go directly to GitHub and download Jaybird from the https://github.com/FirebirdSQL/jaybird/releases[Jaybird releases].
 
 [#where-can-i-get-the-sourcecode]
 == Where can I get the sourcecode?
 
 All Jaybird distribution zips contain a `jaybird-<version>-sources.zip` with the sources used for that specific version.
 The Maven Central repository also has the `jaybird-<version>-sources.zip`, and your IDE will generally offer to download it for you if you navigate to any Jaybird class.
 
-The full Jaybird sources are available from GitHub in the jaybird repository, {jaybird-repo}.
+The full Jaybird sources are available from GitHub in the Jaybird repository, {jaybird-repo}.
 Each release is tagged in the repository.
 
 [#how-is-jaybird-licensed]
@@ -345,7 +350,7 @@ Jaybird 5 is the last version to support Java 8 and Java 11, support has been dr
 
 [NOTE]
 ====
-Jaybird 5 will serve as a form of long-term support for Java 8 and Java 11, with maintenance releases guaranteed at least until the release of Jaybird 7.
+Jaybird 5 serves as a "`long-term support`" version for Java 8 and Java 11, with maintenance releases at least until the release of Jaybird 7.
 
 See also https://github.com/FirebirdSQL/jaybird/blob/master/devdoc/jdp/jdp-2022-03-java-17-minimum-version.md[jdp-2022-03: Java 17 minimum version].
 ====
@@ -358,25 +363,31 @@ Jaybird 4 supports Java 7, Java 8, Java 11, Java 17 and Java 21.
 Support for Java 9 and higher is limited to Java 11, Java 17 and Java 21.
 
 Jaybird 4 is the last version to support Java 7, support was dropped with Jaybird 5.
-Jaybird 4.0.10 is the last release of Jaybird 4, and is end-of-life.
-We recommend upgrading to Jaybird 5.
+Jaybird 4.0.10 is the last release of Jaybird 4.
+
+Jaybird 4 is end-of-life.
+We recommend upgrading to Jaybird 6.
 
 [#java-jaybird-3-0]
 [discrete]
 === Jaybird 3
 
 Jaybird 3 supports Java 7 and Java 8 and has basic support for Java 9 and higher using the Java 8 version of the driver.
 Support for Java 9 and higher is limited to Java 11 and 17, but in practice Jaybird should work on all Java 9+ versions upto Java 17footnote:[versions after Java 17 have not been tested].
-Jaybird 3.0.12 is the last release of Jaybird 3, and is end-of-life.
-We recommend upgrading to Jaybird 5.
+Jaybird 3.0.12 is the last release of Jaybird 3.
+
+Jaybird 3 is end-of-life.
+We recommend upgrading to Jaybird 6.
 
 [#java-jaybird-2-2]
 [discrete]
 === Jaybird 2.2
 
 Jaybird 2.2 supports Java 6, Java 7 and Java 8.
-Jaybird 2.2.15 is that last release of Jaybird 2.2, and is end-of-life.
-We recommend upgrading to Jaybird 5.
+Jaybird 2.2.15 is the last release of Jaybird 2.2.
+
+Jaybird 2.2 is end-of-life.
+We recommend upgrading to Jaybird 6.
 
 Jaybird 2.2.4 added basic support for Java 8 (JDBC 4.2), although not all JDBC 4.2 features are supported or fully implemented.
 
@@ -411,6 +422,15 @@ To ensure a stable module name, Jaybird 5 and older, since versions 2.2.14 and 3
 
 Jaybird 6 supports Firebird 3.0, Firebird 4.0, and Firebird 5.0.
 
+.No promises on Firebird 6.0 support
+[WARNING#firebird-jaybird-6-fb6]
+====
+Firebird 6.0 is still in development, and includes changes -- like schema support -- that impact Jaybird.
+
+As a result -- at this time -- we make no promises on the support for Firebird 6.0 by Jaybird 6.
+We may delay support for Firebird 6.0 until Jaybird 7, or we may improve support during maintenance releases of Jaybird 6.
+====
+
 By default, Jaybird 6 -- using the pure Java protocol -- will not connect to Firebird 2.5 and older.
 See <<connection-rejected-by-remote-interface-335544421>> for a workaround.
 
@@ -420,6 +440,15 @@ See <<connection-rejected-by-remote-interface-335544421>> for a workaround.
 
 Jaybird 5 supports Firebird 2.5, Firebird 3.0, Firebird 4.0, and Firebird 5.0.
 
+.No promises on Firebird 6.0 support
+[WARNING#firebird-jaybird-5-fb6]
+====
+Firebird 6.0 is still in development, and includes changes -- like schema support -- that impact Jaybird.
+
+As a result -- at this time -- we make no promises on the support for Firebird 6.0 by Jaybird 5.
+We may delay support for Firebird 6.0 until Jaybird 7, or we may improve support during maintenance releases of Jaybird 5 and/or Jaybird 6.
+====
+
 Jaybird 5 is the last version to support Firebird 2.5.
 
 [#firebird-jaybird-4]
@@ -472,7 +501,7 @@ Instead, we recommend building a webservice (e.g. REST-based) to mediate between
 Apart from this FAQ, you can get additional information from:
 
 * https://firebirdsql.github.io/jaybird-manual/jaybird_manual.html[Jaybird JDBC Driver Java Programmer's Manual] (HTML, https://firebirdsql.github.io/jaybird-manual/jaybird_manual.pdf[PDF version]) (covers Jaybird 4 and higher)
-* https://www.firebirdsql.org/en/jdbc-driver/[Firebird website: Downloads, Connectivity, JDBC Driver]
+* https://firebirdsql.org/en/jdbc-driver/[Firebird website: Downloads, Connectivity, JDBC Driver]
 * https://firebirdsql.org/en/devel-jdbc-driver/[Firebird website: Development, JDBC Driver]
 * https://github.com/FirebirdSQL/jaybird/wiki/[Jaybird wiki]
 
@@ -520,7 +549,7 @@ You can report bugs in the Jaybird bug tracker, {issues}.
 When reporting bugs, please provide a minimal, but complete reproduction, including databases and sourcecode to reproduce the problem.
 Patches to fix bugs are also appreciated.
 Make sure the patch is against a recent master version of the code.
-You can also fork the {jaybird-repo}[jaybird repository] and create pull requests.
+You can also fork the {jaybird-repo}[Jaybird repository] and create pull requests.
 
 [#connecting-to-firebird]
 = Connecting to Firebird
@@ -575,7 +604,7 @@ Jaybird 4 and higher also support:
 
 [NOTE]
 ====
-This URL format is deprecated with jaybird 5 and was removed in Jaybird 6.
+This URL format is deprecated with Jaybird 5 and was removed in Jaybird 6.
 As a replacement, use the "`Firebird External`" option in LibreOffice Base.
 
 See also https://github.com/FirebirdSQL/jaybird/blob/master/devdoc/jdp/jdp-2022-04-deprecate-ooremote.md[jdp-2022-04: Deprecate OOREMOTE (OpenOffice/LibreOffice driver) for removal].
@@ -729,7 +758,7 @@ It requires support on both client and server side.
 
 Java support for "TCP Loopback Fast Path" was introduced in Java 8 update 60, it can be enabled by specifying the system property `jdk.net.useFastTcpLoopback` with value `true` (e.g. specify `-Djdk.net.useFastTcpLoopback=true` in your Java commandline).
 
-Unfortunately, Java only has an 'all-or-nothing' support for the "`TCP Loopback Fast Path`", so Jaybird cannot enable this for you: you must specify this  property on JVM startup.
+Unfortunately, Java only has an 'all-or-nothing' support for the "`TCP Loopback Fast Path`", so Jaybird cannot enable this for you: you must specify this property on JVM startup.
 On the other hand, this has the benefit that this works for all Jaybird versions, as long as you use Java 8 update 60 or higher (and Firebird 3.0.2 or higher, but before 5.0.0).
 
 [#common-connection-errors]
@@ -938,7 +967,7 @@ Jaybird itself no longer provides connection pooling.
 Earlier versions had a `DataSource` implementation with connection pooling, but this implementation had severe bugs.
 This implementation (and all other classes in `org.firebirdsql.pool`) was deprecated in Jaybird 2.2 and dropped in Jaybird 3.
 
-Jaybird provides a basic `DataSource` implementation and a `ConnectionPoolDataSource` implementation.
+Jaybird provides a basic `DataSource`, an `XADataSource`, and a `ConnectionPoolDataSource` implementation.
 Contrary to its name, the latter *does not provide a connection pool*, but is intended to be used by a connection pool (as implemented in an application server) to create connections _for_ a connection pool.
 
 If your application is built on a Java EE/Jakarta EE application server, we suggest you use the connection pooling provided by the application server using the `javax.sql.ConnectionPoolDataSource` implementation `org.firebirdsql.ds.FBConnectionPoolDataSource`, or using the `javax.sql.XADataSource` implementation `org.firebirdsql.ds.FBXADataSource`.