You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<h2 id="events"><a class="anchor" href="#events"></a>8. Working with Events</h2>
6470
6470
<div class="sectionbody">
6471
6471
<div class="paragraph">
6472
-
<p>Firebird supports events.
6473
-
Events are a feature that provides asynchronous notification to the connected applications about events triggered by the database or other applications.
6472
+
<p>Events are a Firebird feature that provides asynchronous notification to connected applications about events triggered by the database or other applications.
6474
6473
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.
6475
6474
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.</p>
6476
6475
</div>
@@ -6480,38 +6479,38 @@ <h2 id="events"><a class="anchor" href="#events"></a>8. Working with Events</h2>
<p>An <em>event</em> is a message generated in PSQL code that is delivered to subscribed applications.
6484
-
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.
6485
-
The applications that subscribe for events are required to specify the event names of interest, no wildcards are allowed;
6486
-
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.</p>
6482
+
<p>An <em>event</em> is a message generated in PSQL code using <a href="https://firebirdsql.org/file/documentation/chunk/en/refdocs/fblangref50/fblangref50-psql-coding.html#fblangref50-psql-postevent"><code>POST_EVENT</code></a> that is delivered to subscribed applications.
6483
+
An event is characterized only by its name, so two different events must use different names.
6484
+
Applications subscribing for events specify the event names of interest, no wildcards are allowed;
6485
+
an applications either provides a callback function that will be invoked asynchronously for the event, or it polls for the posted events periodically.</p>
6487
6486
</div>
6488
6487
<div class="paragraph">
6489
6488
<p>Events are delivered to the application only on (after) commit of the transaction that generated the event.
6490
6489
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.
6491
6490
The database engine will continue operating even if no application subscribes to events or when the subscribed application crashed in the meantime.</p>
6492
6491
</div>
6493
6492
<div class="paragraph">
6494
-
<p>It can also happen that multiple transactions will be committed before the events are delivered to the client system.
6495
-
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.
6496
-
The same applies to periodical polling, the application will receive event names and counts of the events since last poll.</p>
6493
+
<p>It’s possible that multiple transactions have been committed before the events are delivered to subscribed applications.
6494
+
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.
6495
+
The same applies to periodical polling, the application will receive event names and counts of the events since the last poll.</p>
6497
6496
</div>
6498
6497
<div class="paragraph">
6499
6498
<p>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.
6500
-
When an event is posted in trigger or stored procedure, Firebird checks the subscription information and increases the event count for the subscribed applications.
6501
-
Another thread checks the table periodically and notifies the application about all new events relevant to the particular application.
6499
+
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.
6500
+
Another thread checks the table periodically and notifies subscribed applications about all new events relevant to the particular application.
6502
6501
Such mechanism allows Firebird to keep the event notification table very small<sup class="footnote">[<a id="_footnoteref_19" class="footnote" href="#_footnotedef_19" title="View footnote.">19</a>]</sup>
6503
6502
and to reduce the number of messages sent to the application.</p>
6504
6503
</div>
6505
6504
<div class="paragraph">
6506
6505
<p>It is not possible to pass parameters with the event, e.g. an ID of the modified records.
6507
-
It is also not possible to encode such information in the event names, wildcards are not supported.
6506
+
It is also not possible to encode such information in the event names, as wildcards are not supported.
6508
6507
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.</p>
<p>Events are posted from PSQL code (trigger, stored procedure, execute block, function) using the <a href="https://firebirdsql.org/file/documentation/chunk/en/refdocs/fblangref50/fblangref50-psql-coding.html#fblangref50-psql-postevent" target="_blank" rel="noopener"><code>POST_EVENT</code></a> statement.
6513
+
<p>Events are posted from PSQL code (trigger, stored procedure, execute block, function) using the <a href="https://firebirdsql.org/file/documentation/chunk/en/refdocs/fblangref50/fblangref50-psql-coding.html#fblangref50-psql-postevent"><code>POST_EVENT</code></a> statement.
6515
6514
It is possible to create a stored procedure with the sole purpose of posting events (e.g. to notify events from an application):</p>
6516
6515
</div>
6517
6516
<div class="listingblock">
@@ -6529,7 +6528,7 @@ <h3 id="_posting_events"><a class="anchor" href="#_posting_events"></a>8.2. Post
6529
6528
<div class="listingblock">
6530
6529
<div class="title">Using EXECUTE BLOCK to post events</div>
"EXECUTE BLOCK AS BEGIN POST_EVENT 'some_evt'; END");
6535
6534
}</code></pre>
@@ -6540,10 +6539,10 @@ <h3 id="_posting_events"><a class="anchor" href="#_posting_events"></a>8.2. Post
6540
6539
<h3 id="_subscribing_to_events"><a class="anchor" href="#_subscribing_to_events"></a>8.3. Subscribing to events</h3>
6541
6540
<div class="paragraph">
6542
6541
<p>The design of the classes and interfaces in the <code>org.firebirdsql.event</code> package is similar to the Services API support;
6543
-
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.</p>
6542
+
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.</p>
6544
6543
</div>
6545
6544
<div class="paragraph">
6546
-
<p>Applications have to configure the following properties before starting use of the implementation <code>EventManager</code> interface:</p>
6545
+
<p>Applications have to configure the following properties before starting use of the implementation of the <code>EventManager</code> interface:</p>
<td class="tableblock halign-left valign-top"><p class="tableblock">Name or the IP address of the host to which we subscribe for events. <em>Required</em>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the user on behalf of which we connect to the database. <em>Required</em>.</p></td>
<p>The authentication plugin (and provider) interfaces should be considered unstable;
6981
-
they may change with point-releases (although we will try to avoid that)</p>
6992
+
they may change with point-releases (though we will try to avoid that)</p>
6982
6993
</li>
6983
6994
<li>
6984
6995
<p>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</p>
<p>This functionality is experimental, and will remain so unless Firebird changes how its auto-commit mode works.
7236
-
<strong>Do not use this unless you really know what you’re doing.</strong></p>
7246
+
<p><strong>Do not use this unless you really know what you’re doing.</strong></p>
7247
+
</div>
7248
+
<div class="paragraph">
7249
+
<p>This functionality is experimental, and will remain so unless Firebird changes how its auto-commit mode works.</p>
7237
7250
</div>
7238
7251
<div class="paragraph">
7239
7252
<p>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.
<p>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%.</p>
7271
7284
</div>
7272
7285
<div class="paragraph">
7273
-
<p>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.
7274
-
Internally <code>isc_tpb_autocommit</code> uses <code>commit_retaining</code>, which means that using this feature may increase the transaction gap with associated sweep and garbage collection impact.</p>
7286
+
<p>Support for this option is experimental, and should only be enabled if you</p>
7287
+
</div>
7288
+
<div class="olist arabic">
7289
+
<ol class="arabic">
7290
+
<li>
7291
+
<p>know what you’re doing, and</p>
7292
+
</li>
7293
+
<li>
7294
+
<p>really need this feature.</p>
7295
+
</li>
7296
+
</ol>
7297
+
</div>
7298
+
<div class="paragraph">
7299
+
<p>Internally <code>isc_tpb_autocommit</code> uses <code>commit_retaining</code>, which means that using this feature may increase the transaction gap with associated sweep and garbage collection impact.</p>
7275
7300
</div>
7276
7301
</div>
7277
7302
<div class="sect2">
@@ -7421,7 +7446,7 @@ <h3 id="ref-datatypebind"><a class="anchor" href="#ref-datatypebind"></a>9.8. Da
7421
7446
<div class="listingblock">
7422
7447
<div class="title">Properties object with dataTypeBind</div>
7423
7448
<div class="content">
7424
-
<pre class="prettyprint highlight"><code data-lang="java">Properties props = new Properties();
7449
+
<pre class="prettyprint highlight"><code data-lang="java">var props = new Properties();
7425
7450
props.setProperty("dataTypeBind",
7426
7451
"decfloat to varchar;timestamp with time zone to legacy"</code></pre>
<p>The <code>useCatalogAsPackage</code> connection property does not result in any other behaviour.</p>
7616
7641
</div>
7617
7642
<div class="paragraph">
7618
-
<p>Keep in mind, that this is non-standard behaviour, and standard JDBC tools or libraries may not work correctly when this property is enabled.
7643
+
<p>Keep in mind that this is non-standard behaviour, and standard JDBC tools or libraries may not work correctly when this property is enabled.
7619
7644
This feature may be discontinued and removed in the future if Jaybird needs to implement “real” catalogs (e.g. because Firebird started supporting catalogs).</p>
<h4 id="ref-client-info-jb5"><a class="anchor" href="#ref-client-info-jb5"></a>9.11.1. Support in Jaybird 5 and earlier</h4>
7632
7657
<div class="paragraph">
7633
7658
<p>Support for client info properties was introduced in Jaybird 2.2, storing properties in the <code>USER_SESSION</code> context of <a href="https://firebirdsql.org/file/documentation/chunk/en/refdocs/fblangref50/fblangref50-functions.html#fblangref50-functions-workcontext"><code>RDB$GET/SET_CONTEXT</code></a>.
7634
-
Support is quite limited, allowing you to:</p>
7659
+
Support in Jaybird 5 and earlier is quite limited, allowing you to:</p>
0 commit comments