Misc. textual improvements

Author: mrotteveel

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

@@ -1,42 +1,41 @@
 [[events]]
 == Working with Events
 
-Firebird supports events.
-Events are a feature that provides asynchronous notification to the connected applications about events triggered by the database or other applications.
+Events are a Firebird feature that provides asynchronous notification to connected applications about events triggered by the database or other applications.
 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 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.
+An _event_ is a message generated in PSQL code using https://firebirdsql.org/file/documentation/chunk/en/refdocs/fblangref50/fblangref50-psql-coding.html#fblangref50-psql-postevent[`POST_EVENT`] that is delivered to subscribed applications.
+An event is characterized only by its name, so two different events must use different names.
+Applications subscribing for events specify the event names of interest, no wildcards are allowed;
+an applications either provides a callback function that will be invoked asynchronously for the event, or it polls for the posted events periodically.
 
 Events are delivered to the application only on (after) commit of the transaction that generated the event.
 Firebird does not provide any guarantees about the time of event delivery, it depends on the load of the Firebird engine, application load, network delays between application and the database system.
 The database engine will continue operating even if no application subscribes to events or when the subscribed application crashed in the meantime.
 
-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 poll.
+It's possible that multiple transactions have been committed before the events are delivered to subscribed applications.
+In that case, the callback function is invoked only once, and only the event name and the count of the events are passed as parameters.
+The same applies to periodical polling, the application will receive event names and counts of the events since the 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.
-Another thread checks the table periodically and notifies the application about all new events relevant to the particular application.
+When an event is posted in a trigger or stored procedure, Firebird checks the subscription information and increases the event count for the subscribed applications.
+Another thread checks the table periodically and notifies subscribed applications about all new events relevant to the particular application.
 Such mechanism allows Firebird to keep the event notification table very smallfootnote:[
 For example, the effective size for 100 applications subscribed for 100 different events is about 40k in memory.]
 and to reduce the number of messages sent to the application.
 
 It is not possible to pass parameters with the event, e.g. an ID of the modified records.
-It is also not possible to encode such information in the event names, wildcards are not supported.
+It is also not possible to encode such information in the event names, as wildcards are not supported.
 For such cases, applications should maintain a change tracking table where the IDs of the modified records are stored and the event mechanism is used to tell the application that new records were added to the table.
 
 === 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.
+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]
@@ -50,7 +49,7 @@ END
 
 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]
+[source,java]
 .Using EXECUTE BLOCK to post events
 ----
 try (Statement stmt = connection.createStatement()) {
@@ -62,26 +61,26 @@ try (Statement stmt = connection.createStatement()) {
 === Subscribing to events
 
 The design of the classes and interfaces in the `org.firebirdsql.event` package is similar to the Services API support;
-there is a central manager-class that establishes a database connection and provides service methods to work with the events, a callback interface that applications must implement to use the asynchronous event notification and an interface representing a database event with two properties, event name and occurrence count.
+there is a central manager-class that establishes a database connection and provides service methods to work with the events, a callback interface that applications must implement to use the asynchronous event notification, and an interface representing a database event with two properties, event name and occurrence count.
 
-Applications have to configure the following properties before starting use of the implementation `EventManager` interface:
+Applications have to configure the following properties before starting use of the implementation of the `EventManager` interface:
 
-[cols="1m,2m,4",options="header",]
+[cols="1m,2m,4a",options="header",]
 |===
 |Name |Type |Description
 
-a|`host` +
-`serverName`
+a|`serverName` +
+`host` (until:[Jaybird 6])
 |String
 |Name or the IP address of the host to which we subscribe for events. __Required__.
 
-a|`port` +
-`portNumber`
+a|`portNumber` +
+`port` (until:[Jaybird 6])
 |int
 |Port to which we connect to, 3050 by default.
 
-|`database` +
-`databaseName`
+|`databaseName` +
+`database` (until:[Jaybird 6])
 |String
 |Path to the database.
 The path is specified for the remote host but must be absolute. __Required__.
@@ -102,52 +101,52 @@ The path is specified for the remote host but must be absolute. __Required__.
 
 |expectedDb
 |String
-a|since:[Jaybird 5] With Firebird 3.0 and higher, this is used to find the non-default security database to use when authenticating.
+|since:[Jaybird 5] With Firebird 3.0 and higher, this is used to find the non-default security database to use when authenticating.
 Value is a database path or alias the user can connect to. _Optional_.
 
 |authPlugins
 |String
-a|Comma-separated list of authentication plugins to use (ignored for Firebird 2.5 or earlier).
+|Comma-separated list of authentication plugins to use (ignored for Firebird 2.5 or earlier).
 Use `null` (the default) to use Jaybird defaults.
 
 |processId
 |int
-a|since:[Jaybird 5] Process id to report to the server.
+|since:[Jaybird 5] Process id to report to the server.
 
 |processName
 |String
-a|since:[Jaybird 5] Process name to report to the server.
+|since:[Jaybird 5] Process name to report to the server.
 
 |socketBufferSize
 |int
-a|since:[Jaybird 5] Socket buffer size in bytes
+|since:[Jaybird 5] Socket buffer size in bytes
 
 |soTimeout
 |int
-a|since:[Jaybird 5] Socket blocking read timeout in milliseconds (`0` is OS default timeout)
+|since:[Jaybird 5] Socket blocking read timeout in milliseconds (`0` is OS default timeout)
 
 |connectTimeout
 |int
-a|since:[Jaybird 5] Socket connect timeout in milliseconds (`0` is OS default timeout)
+|since:[Jaybird 5] Socket connect timeout in milliseconds (`0` is OS default timeout)
 
 |wireCrypt
 a|`String` or `WireCrypt`
-a|Wire encryption level (`DISABLED`, `ENABLED`, `REQUIRED`, `DEFAULT`).
+|Wire encryption level (`DISABLED`, `ENABLED`, `REQUIRED`, `DEFAULT`).
 In Jaybird 3.0.4+ and Jaybird 4, the property is type `WireCrypt`.
 In Jaybird 5, the property is type `String`.
 
 |wireCryptAsEnum
 |WireCrypt
-a|since:[Jaybird 5] Alternative to `WireCrypt` to use `WireCrypt` enum.
+|since:[Jaybird 5] Alternative to `WireCrypt` to use `WireCrypt` enum.
 
 |dbCryptConfig
 |String
-a|Database encryption config.
+|Database encryption config.
 See <<ref-dbcrypt>> for details.
 
 |wireCompression
 |boolean
-a|Enable wire compression (requires Firebird 3.0 or higher).
+|Enable wire compression (requires Firebird 3.0 or higher).
 Default is `false`.
 
 This property only affects the primary connection, not the event channel (secondary connection).
@@ -191,7 +190,7 @@ The following shows an example of using the blocking methods.
 [source,java]
 .Example of blocking waiting for event with a specified timeout
 ----
-EventManager eventManager = new FBEventManager();
+var eventManager = new FBEventManager();
 
 eventManager.setServerName("localhost");
 eventManager.setUser("SYSDBA");

src/docs/asciidoc/reference/connection/authenticationplugins.adoc

@@ -137,7 +137,7 @@ This support is experimental and comes with a number of caveats:
 
 * We haven't tested this extensively (except for loading Jaybird's own plugins internally)
 * The authentication plugin (and provider) interfaces should be considered unstable; 
-they may change with point-releases (although we will try to avoid that) 
+they may change with point-releases (though we will try to avoid that)
 * For now, it is probably necessary for the JAR containing the authentication plugin to be loaded by the same class loader -- or at least, from the same classpath -- as Jaybird itself
 
 If you implement a custom authentication plugin and run into problems, contact us on the https://groups.google.com/g/firebird-java[firebird-java Google Group^].

src/docs/asciidoc/reference/connection/catalogaspackage.adoc

@@ -31,7 +31,7 @@ When this connection property is enabled, the `DatabaseMetaData` of that connect
 
 The `useCatalogAsPackage` connection property does not result in any other behaviour.
 
-Keep in mind, that this is non-standard behaviour, and standard JDBC tools or libraries may not work correctly when this property is enabled.
+Keep in mind that this is non-standard behaviour, and standard JDBC tools or libraries may not work correctly when this property is enabled.
 This feature may be discontinued and removed in the future if Jaybird needs to implement "`real`" catalogs (e.g. because Firebird started supporting catalogs).
 
 See also https://github.com/FirebirdSQL/jaybird/blob/master/devdoc/jdp/jdp-2023-09-use-catalog-as-package.adoc[jdp-2023-08: Use Catalog as Package^]

src/docs/asciidoc/reference/connection/clientinfoproperties.adoc

@@ -7,7 +7,7 @@ Client info properties allow you to set properties on a connection for informati
 ==== Support in Jaybird 5 and earlier
 
 Support for client info properties was introduced in Jaybird 2.2, storing properties in the `USER_SESSION` context of https://firebirdsql.org/file/documentation/chunk/en/refdocs/fblangref50/fblangref50-functions.html#fblangref50-functions-workcontext[`RDB$GET/SET_CONTEXT`].
-Support is quite limited, allowing you to:
+Support in Jaybird 5 and earlier is quite limited, allowing you to:
 
 * Set properties individually or collectively using a `Properties` object (`Connection#setClientInfo(String,String)`, `Connection#setClientInfo(Properties)`)
 * Clear properties individually (setting them to `null`) (`Connection#setClientInfo(String,String)`

src/docs/asciidoc/reference/connection/datatypebind.adoc

@@ -35,7 +35,7 @@ For example:
 [source,java]
 .Properties object with dataTypeBind
 ----
-Properties props = new Properties();
+var props = new Properties();
 props.setProperty("dataTypeBind", 
     "decfloat to varchar;timestamp with time zone to legacy"
 ----

src/docs/asciidoc/reference/connection/enableprotocol.adoc

@@ -16,7 +16,7 @@ The listed versions are tried in addition to the supported protocol versions.
 Non-integer values or unknown protocol versions are silently ignored.
 +
 It is possible to use the "`masked`" protocol version (e.g. `"32780"` for protocol version 12).
-However, we recommend using the unmasked version (e.g. `"12"` for protocol version 12).
+However, we recommend using the unmasked version (e.g. `"12"`).
 * `"*"` -- enable all available protocol versions
 * `null` or empty string (`++""++`) -- default behaviour, only use supported protocols
 

src/docs/asciidoc/reference/connection/firebirdautocommit.adoc

@@ -3,9 +3,10 @@
 
 [CAUTION]
 ====
-This functionality is experimental, and will remain so unless Firebird changes how its auto-commit mode works.
 **Do not use this unless you really know what you're doing.**
 
+This functionality is experimental, and will remain so unless Firebird changes how its auto-commit mode works.
+
 Incorrect use of this functionality can result in excessive growth of the database due to increases in back-version chains of records, which can also cause performance degradation.
 Additionally, when used with an isolation level other than READ COMMITTED, the connection will only see changes committed at the time the initial transaction was started;
 the auto-commit barrier will not make new committed changes visible to the current transaction.
@@ -30,5 +31,9 @@ If you manually add `isc_tpb_autocommit` to the transaction parameter buffer, an
 
 Artificial testing with repeated inserts (using a prepared statement) against a Firebird server on localhost shows that this leads to a reduction of execution time of +/- 7%.
 
-Support for this option is experimental, and should only be enabled if you 1) know what you're doing, and 2) really need this feature. 
+Support for this option is experimental, and should only be enabled if you
+
+. know what you're doing, and
+. really need this feature.
+
 Internally `isc_tpb_autocommit` uses `commit_retaining`, which means that using this feature may increase the transaction gap with associated sweep and garbage collection impact.