Misc. copy-editing

Author: mrotteveel

src/docs/asciidoc/appendices/characterencoding/characterencoding.adoc

@@ -90,15 +90,18 @@ The reason for this is that Java internally stores all strings in Unicode format
 When the `NONE` character set is used, Jaybird does not know how to interpret the received data.
 The only choice that is left to Jaybird is to construct a string using the default character set of the JVM, which usually matches the regional settings of the operating system and can be accessed from within the JVM through the `file.encoding` system property.
 
-With connection character set `NONE`, Jaybird uses the explicit character set of `CHAR`, `VARCHAR` and `BLOB SUB_TYPE TEXT` columns for the conversion.
+With connection character set `NONE`, Jaybirdfootnote:[Since Jaybird 3] uses the explicit character set of `CHAR`, `VARCHAR` and `BLOB SUB_TYPE TEXT` columns for the conversion.
 This addresses most of the problems described in this section, except for columns without an explicit character set (i.e. their character set is `NONE`).
 
-It is clear that a conversion using default character set that happens inside the JVM can lead to errors when the same content is accessed from two or more different Java Virtual Machines that have different configuration.
-One application running on the computer with, for example, Russian regional settings saves the Russian text (the default character set of the JVM is Cp1251) and another application running on computer with German regional settings (default character set is Cp1252) will read in such case some special or accented characters.
-However, when all client applications run on the same OS with the same regional settings, in most cases this will not have any severe consequences, except probably wrong sorting order or uppercasing on the server side.
+A conversion using the default character set of the JVM can lead to errors when the same content is accessed from two or more Java Virtual Machines that have different configuration.
+One application running on a computer with, for example, Russian regional settings saves Russian text (default character set of the JVM is Cp1251), and another application running on a computer with German regional settings (default character set is Cp1252) will read in such case some special or accented characters.
+However, when all client applications run on the same OS with the same regional settings, in most cases this will not have any severe consequences, except maybe wrong sorting order or uppercasing on the server side.
 
 On Linux and other Unix platforms, it might have more severe consequences as it is very common that regional settings are not configured and that the default "C" locale is used and the non-ASCII characters will be replaced with question marks ("?").
 
+Since Java 18 (https://openjdk.org/jeps/400[JEP 400^]), this is less of a concern as the default is now always UTF-8.
+On the other hand, this can cause unexpected behaviour when upgrading from older Java versions.
+
 Therefore, an application should only use `NONE` character encoding as an encoding for a database and a connection when at least one of the following is met:
 
 * The database will contain only ASCII characters,
@@ -116,7 +119,7 @@ When `encoding` property is not set or set to `NONE` and `charSet` property is n
 With Jaybird 3 and higher, this option has limitations when `encoding=NONE`: the conversion using `charSet` will only be applied for columns that don't have an explicit character set, otherwise that explicit character set is used for the conversion.
 
 The last case is most powerful, but also is the most dangerous in use.
-When used properly, it can solve the problems with the legacy databases;
+When used properly, it can solve problems with legacy databases;
 when used incorrectly, one can easily trash the content of the database.
 
 === Available Encodings

src/docs/asciidoc/appendices/connectionproperties/connectionproperties.adoc

@@ -6,6 +6,9 @@ Jaybird has a number of connection properties that can be used to configure a co
 
 This appendix provides a list of most connection properties and a short explanation to each of them.
 The properties listed below are usable as JDBC connection properties.
+Some properties have one or more aliases.
+The first name is the primary and preferred property name;
+it's usually also the name of the property in the data source classes.
 
 The properties marked as _boolean property_ can be included in the JDBC URL with values `true`, `false` (since:[Jaybird 5]), but also without a value, or with an empty value (which will both signify `true`).
 For readability, we suggest that you only specify these properties explicitly when you want to enable or disable them, and if you do, to use explicit values like `true` or `false`.
@@ -256,7 +259,7 @@ a|`useStandarUdf` +
 `use_standard_udf`
 |Jaybird specific property (until:[Jaybird 5]).
 Boolean property. 
-Tells the JDBC driver to assume that standard UDF library is registered in the database when converting escaped function calls. 
+Tells the JDBC driver to assume that the standard UDF library is registered in the database when converting escaped function calls.
 With recent versions of Firebird, it is advisable to not specify this property and rely on the built-in functions instead.
 See <<jdbcescape>> for more information.
 
@@ -268,7 +271,7 @@ Changes how `getTime`/`getTimestamp` methods accepting a `java.util.Calendar` ap
 a|`num_buffers` +
 `isc_dpb_num_buffers`
 |Number of database pages that will be cached.
-Overrides server or database default for this specific connection.
+Overrides server or database default for this specific connection if the server mode is Classic or SuperClassic.
 Use with care to avoid using an excessive amount of memory.
 
 a|`set_db_readonly` +
@@ -279,6 +282,7 @@ Set the database into read-only state.
 a|`set_db_sql_dialect` +
  `isc_dpb_set_db_sql_dialect`
 |Set the SQL dialect of the database.
+Use with care to avoid database issues.
 
 a|`set_db_charset` +
 `isc_dpb_set_db_charset`

src/docs/asciidoc/appendices/datatypeconversion/datatypeconversion.adoc

@@ -97,7 +97,8 @@ a|`VARCHAR CHARACTER SET OCTETS` +
 |`BOOLEAN` (since:[Firebird 3.0])
 |`Boolean`
 
-|``JaybirdTypeCodes.DECFLOAT``footnote:[JDBC does not yet define a `java.sql.Types` code for `DECFLOAT`]
+a|`DECFLOAT` (since:[JDBC 4.5/Java 26]) +
+``JaybirdTypeCodes.DECFLOAT``footnote:[JDBC 4.4 and earlier do not yet define a `java.sql.Types` code for `DECFLOAT`]
 |`DECFLOAT` (since:[Firebird 4.0])
 |`java.math.BigDecimal`
 |===

src/docs/asciidoc/appendices/jdbcescape/jdbcescape.adoc

@@ -2,7 +2,7 @@
 [appendix]
 == Supported JDBC Scalar Functions
 
-The JDBC API has an escaped syntax for numeric, string, time, date, system and conversion functions.
+The JDBC API has an escape syntax for numeric, string, time, date, system and conversion functions.
 Jaybird will try to provide an equivalent of the JDBC function using the built-in capabilities of the Firebird database.
 When no equivalent is available, Jaybird will pass the function call "as is" to the database assuming that it contains the necessary UDF, UDR or stored function declaration.
 

src/docs/asciidoc/appendices/systemproperties/systemproperties.adoc

@@ -36,6 +36,8 @@ This information can be specified in connection properties, or globally using th
 Process name to send to Firebird
 `org.firebirdsql.jdbc.pid`::
 PID to send to Firebird (must be a valid integer)
++
+Ignored for native and embedded connections
 
 The property values are read for each connect, so the value can be changed at any time.
 

src/docs/asciidoc/chapters/connection/connection.adoc

@@ -116,7 +116,7 @@ On Unix platforms the path must include the root, as the path is otherwise inter
 Having to include the root has the effect that a database in `/var/firebird/employee.fdb` needs to use a double `//` after the host name (and port) in the connection string: `jdbc:firebird://localhost//var/firebird/employee.fdb`.
 
 It is possible to specify a relative path, but as this depends on the server configuration, this may be confusing or easily lead to errors.
-We suggest not to use relative paths, and instead use an alias.
+We recommend to not use a relative path, and instead use an alias.
 
 [[connection-drivermanager-props]]
 ==== Specifying extended properties
@@ -149,7 +149,7 @@ public class HelloServerWithEncoding {
 ----
 
 The `user` and `password` properties are defined in JDBC.
-All other property names -- like `encoding` here -- are driver-specific.
+Nearly all other property names -- like `encoding` here -- are driver-specific.
 
 Additional properties, for example the SQL role for the connection can be added to the `props` object.
 The list of properties available in Jaybird can be found in <<connectionproperties>>.
@@ -194,7 +194,7 @@ This can be used to include otherwise unsupported characters in a connection pro
 * `{plus}` escaped as `%2B`
 +
 A {plus} in the query part means _space_ (0x20), so occurrences of `{plus}` (_plus_) need to be escaped;
-make sure to do this for _base64_ encoded values of `dbCryptConfig`, or better yet use the _base64url_ encoding instead.
+make sure to do this for _base64_ encoded values of <<ref-dbcrypt,`dbCryptConfig`>>, or better yet use _base64url_ encoding instead.
 * `%` escaped as `%25`.
 +
 A `%` in the query part introduces an escape, so occurrences of `%` (_percent_) need to be escaped.
@@ -322,10 +322,10 @@ In fact, use of JNDI is extremely uncommon these days.
 === Driver types
 
 As mentioned in the section <<Jaybird Architecture>>, Jaybird supports multiple implementations of the GDS API.
-The default Jaybird distribution contains two main categories of the implementations: the pure Java implementation of the Firebird wire protocol, and a JNA proxy that can use a Firebird `fbclient` library.
+The default Jaybird distribution contains two main categories of the implementations: the pure Java implementation of the Firebird wire protocol, and a https://github.com/java-native-access/jna[JNA (Java Native Access)^] proxy that can use a Firebird `fbclient` library.
 
 The next sections provide a description of these types and their configuration with the corresponding JDBC URLs that should be used to obtain the connection of desired type.
-The type of the JDBC driver for the `javax.sql.DataSource` is configured via a corresponding property.
+The type of the JDBC driver for the `javax.sql.DataSource` is configured via the property `type` (`setType(String)`).
 
 [[driver-pure-java]]
 ==== PURE_JAVA type
@@ -472,7 +472,7 @@ jdbc:firebird:native:employee
 ===== Maven dependency for native client
 
 When using Jaybird 3 and later, you can use a library to provide the Firebird client library for the `native` and `local` protocol.
-For Windows, Linux, and macOS, you can add the `org.firebirdsql.jdbc:fbclient` dependency on your classpath.
+For Windows, Linux, and macOS, you can add the https://github.com/mrotteveel/jaybird-fbclient[`org.firebirdsql.jdbc:fbclient`^] dependency on your classpath.
 This dependency does not support the `embedded` protocol.
 
 .Native libraries for all supported OS and architectures
@@ -551,7 +551,7 @@ For example, when using the Type 2 JDBC driver with a web or application server,
 since:[Jaybird 6] Embedded connections require the `jaybird-native` artifact on the classpath.
 
 The Embedded server JDBC driver is a Type 2 JDBC driver that, rather than using the Firebird client library, loads the Firebird embedded server library instead.
-This is the highest performance type of JDBC driver for accessing local databases, as the Java code accesses the database file directly.
+This is the highest performance type of JDBC driver for accessing local databases, as the Java application accesses the database file directly.
 
 The following JDBC URL syntax is supported:
 

src/docs/asciidoc/chapters/events/events.adoc

@@ -3,14 +3,14 @@
 
 Firebird supports events.
 Events are a feature that provides asynchronous notification to the connected applications about events triggered by the database or other applications.
-Instead of requiring applications to reread the database tables to check for the changes, events make it possible to avoid that: triggers in the database can post an event in case of a change.
+Instead of requiring applications to reread the database tables to check for changes, events make it possible to avoid that: triggers in the database can post an event in case of a change.
 And even more, the event can be so specific that an application would need to reread only a limited set of records, possibly only one.
 
 This chapter describes the event mechanism in Firebird and the common usage scenarios.
 
 === Database events
 
-An _event_ is a message generated in a trigger, stored procedure or execute block that is delivered to subscribed applications.
+An _event_ is a message generated in PSQL code that is delivered to subscribed applications.
 The event is characterized only by a name which is used when the event is posted, therefore two different events must have two different names.
 The applications that subscribe for events are required to specify the event names of interest, no wildcards are allowed;
 and applications either provide a callback function that will be invoked in case of event or are required to poll for the posted events periodically.
@@ -21,7 +21,7 @@ The database engine will continue operating even if no application subscribes to
 
 It can also happen that multiple transactions will be committed before the events are delivered to the client system.
 But even in such case the callback function will be invoked only once, and only the event name and the count of the events will be passed as parameters.
-The same applies to periodical polling, the application will receive event names and counts of the events since last polling.
+The same applies to periodical polling, the application will receive event names and counts of the events since last poll.
 
 Internally, Firebird can be thought to store the subscription information in a table where columns contain event names, rows correspond to the subscribed applications and the cells contain the count of the particular event for a particular application.
 When an event is posted in trigger or stored procedure, Firebird checks the subscription information and increases the event count for the subscribed applications.
@@ -36,8 +36,8 @@ For such cases, applications should maintain a change tracking table where the I
 
 === Posting events
 
-Events are posted from PSQL code (trigger, stored procedure, execute block, function) using the `POST_EVENT` command.
-It is possible to create a stored procedure with the sole purpose of posting events:
+Events are posted from PSQL code (trigger, stored procedure, execute block, function) using the https://firebirdsql.org/file/documentation/chunk/en/refdocs/fblangref50/fblangref50-psql-coding.html#fblangref50-psql-postevent[`POST_EVENT`^] statement.
+It is possible to create a stored procedure with the sole purpose of posting events (e.g. to notify events from an application):
 
 [source,sql]
 .Example of posting events from PSQL code
@@ -48,16 +48,14 @@ AS BEGIN
 END
 ----
 
-The `EXECUTE BLOCK` statement can be used to execute PSQL statements within DSQL code:
+The https://firebirdsql.org/file/documentation/chunk/en/refdocs/fblangref50/fblangref50-dml-execblock.html#fblangref50-dml-execblock[`EXECUTE BLOCK`^] statement can be used to execute PSQL statements within DSQL code:
 
 [source,sql]
 .Using EXECUTE BLOCK to post events
 ----
 try (Statement stmt = connection.createStatement()) {
   stmt.execute(
       "EXECUTE BLOCK AS BEGIN POST_EVENT 'some_evt'; END");
-} finally {
-  stmt.close();
 }
 ----
 
@@ -88,7 +86,7 @@ a|`port` +
 |Path to the database.
 The path is specified for the remote host but must be absolute. __Required__.
 
-3+a|NOTE: since:[Jaybird 5] `serverName`, `portNumber` and `databaseName` are replacements for `host`, `port` and `databaseName`, which have been deprecated for removal in Jaybird 6.
+3+a|NOTE: since:[Jaybird 5] `serverName`, `portNumber` and `databaseName` are replacements for `host`, `port` and `database`, which have been deprecated for removal in Jaybird 6.
 
 |user
 |String

src/docs/asciidoc/chapters/introduction/introduction.adoc

@@ -159,18 +159,18 @@ For the JDBC specification, see https://jcp.org/en/jsr/detail?id=221[JSR 221: JD
 
 General information about the Firebird database is available from the Firebird website (https://firebirdsql.org/[^]).
 
-For information about using SQL in Firebird, see the https://firebirdsql.org/file/documentation/html/en/refdocs/fblangref50/firebird-50-language-reference.html[Firebird 5.0 Language Reference^] and other documents available from the https://firebirdsql.org/en/reference-manuals/[Reference Manuals^] section of the Firebird website.
+For information about using SQL in Firebird, see the https://firebirdsql.org/file/documentation/html/en/refdocs/fblangref50/firebird-50-language-reference.html[Firebird 5.0 Language Reference^] and other documentation available from the https://firebirdsql.org/en/reference-manuals/[Reference Manuals^] section of the Firebird website.
 
 ==== Jaybird Support
 
 Support for Jaybird is available through the following channels:
 
 * The https://groups.google.com/g/firebird-java[firebird-java Google Group^] and corresponding mailing list firebird-java@googlegroups.com
 +
-You can subscribe to the mailing list by sending an email to firebird-java+subscribe@googlegroups.com (this does not require a Google account).
+You can subscribe to the mailing list by sending an email to firebird-java+subscribe@googlegroups.com (this does not require a Google account *if* you confirm by email reply).
 Alternatively, you can join the group at the https://groups.google.com/g/firebird-java[firebird-java Google Group^] (this requires a Google account).
-* On https://firebirdsql.org/docs/drivers/java/faq.html[Jaybird Frequently Asked Questions^].
-* On https://github.com/FirebirdSQL/jaybird/wiki/[Jaybird wiki^].
+* On https://firebirdsql.org/docs/drivers/java/faq.html[Jaybird Frequently Asked Questions^]
+* On https://github.com/FirebirdSQL/jaybird/wiki/[Jaybird wiki^]
 
 === Contributing