Write operation listeners
A write operation listener is your own code that the database layer calls after each successful write, inside the same transaction as that write. Any writes the listener makes through the transaction object it receives commit or roll back together with the write that triggered it.
Use a listener when an extra write must be atomic with every write, for example to maintain a derived table. Don't use one just to react to changes: a listener runs on every write in the process, so anything slow in it slows down every write. To react to changes, subscribe to the data instead.
The three listener interfaces
There is one listener interface for each style of API, all in the global.genesis.db.bustxn package. Each has a default no-op implementation. To replace it, provide your own implementation as a @Module.
A listener is only bound if its package is registered as a core extension package, which is scanned at start-up together with the platform's database layer. To register it, add an empty classpath resource file named after the listener's package, under META-INF/global/genesis/bootstrap/extensions/. For a listener in the package com.example.listeners, in your app module:
src/main/resources/META-INF/global/genesis/bootstrap/extensions/com.example.listeners
Listing the listener's package in a process's <package> section in processes.xml is not enough to make the platform use it; register it with the extensions file. Because <package> scanning also installs any @Module it finds, don't list the listener's package, or a parent of it, in a process's <package> section as well: the listener is then installed twice and the process fails at start-up with a Guice BindingAlreadySet error.
The file must end up in the deployed app jar, on the classpath of every process that writes and should notify the listener. There is no property or flag that enables listener support.
A listener is bound in every process whose <classpath> includes the jar holding its extensions file, so a listener in a jar that every process loads is bound in all of them. A write listener runs inside the transaction of the process that makes the write, so it is always in-process: it sees only the writes made by the process it is bound in. To react to writes made by another process, subscribe to the update queue instead, which is asynchronous and crosses process boundaries. To give different processes different listeners, put each listener, with its extensions file, in a module or jar that only that process's <classpath> includes. See Processes for the <classpath> element.
When a process starts, it logs one of two lines from RxDb. Database WriteOperationListener support not enabled means no custom WriteOperationListener was bound in that process. Enabling database WriteOperationListener support means one was bound. Both lines are about WriteOperationListener only: they say nothing about SyncWriteOperationListener or AsyncWriteOperationListener, and the "not enabled" line is logged whether or not you have bound one of those. Check those two by their effect, for example by a side effect or log line in the listener itself after a write. A process whose only listener is a WriteOperationListener also logs INFO ... No SyncWriteOperationListener bound; bridging WriteOperationListener onto the sync write path. This is expected: the WriteOperationListener is being used for sync writes. If you expected a WriteOperationListener and see the "not enabled" line, check that the extensions file exists, is named exactly after the listener's package, and is in the process's classpath.
| Interface | Signature | tx |
|---|---|---|
AsyncWriteOperationListener | suspend fun onWriteResult(tx: AsyncDb, writeResults: List<WriteResult>) | an AsyncDb bound to the write's transaction |
SyncWriteOperationListener | fun onWriteResult(tx: SyncDb, writeResults: List<WriteResult>) | a SyncDb bound to the write's transaction |
WriteOperationListener | fun onWriteResult(tx: RxRecordWriteSupport<*, *, *>, writeResults: List<WriteResult>) | an RxJava record API bound to the write's transaction |
RawSQLWriteOperationListener has been removed in 10.0. Implement WriteOperationListener instead; onTransactionWriteResult becomes onWriteResult(tx, writeResults). A WriteOperationListener is also the one that sees RxDb writes, and when it is the only listener bound it is notified by sync and async writes too (see Which listener is called).
Choose SyncWriteOperationListener or AsyncWriteOperationListener instead when you want tx to be a SyncDb or an AsyncDb. Prefer SyncWriteOperationListener for blocking code that uses SyncDb. Prefer AsyncWriteOperationListener when the listener needs to call suspend functions. Neither is notified by RxDb writes.
Each WriteResult holds the records the write saved and removed. To tell which operation a WriteResult describes, look at which of its two lists is empty, as the database does itself:
savedRecordsis empty: a delete. The deleted records are inremovedRecords.removedRecordsis empty: an insert. The new records are insavedRecords.- Both have records: a modify. The two lists are the same size and are paired by position, so
removedRecords[i]is the previous version ofsavedRecords[i].
This listener keeps a TRADE_SUMMARY row in step with every TRADE that is saved, building the row as a DbRecord:
import global.genesis.commons.annotation.Module
import global.genesis.db.DbRecord
import global.genesis.db.ModifyDetails
import global.genesis.db.SyncDb
import global.genesis.db.bustxn.SyncWriteOperationListener
import global.genesis.db.engine.WriteResult
@Module
class TradeSummaryListener : SyncWriteOperationListener {
override fun onWriteResult(tx: SyncDb, writeResults: List<WriteResult>) {
writeResults
.flatMap { it.savedRecords }
.filter { it.tableName == "TRADE" }
.forEach { trade ->
val summary = DbRecord("TRADE_SUMMARY").apply {
setString("TRADE_ID", trade.getString("TRADE_ID"))
setString("TRADE_STATUS", trade.getString("TRADE_STATUS"))
}
tx.upsert(ModifyDetails(summary, "TRADE_SUMMARY_BY_TRADE_ID"))
}
}
}
The table, index and field names in this example are placeholders for your own data model.
For what ModifyDetails is, see Modify details.
Index names come from your data model. By default, the platform names an index <TABLE_NAME>_BY_<FIELD_1>(_<FIELD_N>), as described in primaryKey, so a TRADE_SUMMARY table keyed on TRADE_ID gets TRADE_SUMMARY_BY_TRADE_ID. You can override the name with .name().
A WriteOperationListener receives an RxRecordWriteSupport as tx. The write methods are bound to the write's transaction. They are insert, modify, upsert, delete, recover and their All variants, and each returns an RxJava Single. The read methods are declared on RxRecordWriteSupport too, but tx is typed RxRecordWriteSupport<*, *, *>, and through that star-projected type only getAll and getAllAsList can be called. get, getBulk, getRange, count and the other reads do not compile through it. Block on each call on the thread that called you, as described below. Do not cast it to RxDb: anything done through RxDb runs outside the write's transaction. This listener records a TRADE_EVENT row for every TRADE that is saved:
import global.genesis.commons.annotation.Module
import global.genesis.db.DbRecord
import global.genesis.db.bustxn.WriteOperationListener
import global.genesis.db.engine.WriteResult
import global.genesis.db.rx.engine.RxRecordWriteSupport
@Module
class TradeEventListener : WriteOperationListener {
override fun onWriteResult(tx: RxRecordWriteSupport<*, *, *>, writeResults: List<WriteResult>) {
writeResults
.flatMap { it.savedRecords }
.filter { it.tableName == "TRADE" }
.forEach { trade ->
val event = DbRecord("TRADE_EVENT").apply {
setString("TRADE_ID", trade.getString("TRADE_ID"))
setString("TRADE_STATUS", trade.getString("TRADE_STATUS"))
}
tx.insert(event).blockingGet()
}
}
}
The table and field names in this example are placeholders for your own data model.
Which listener is called
Bind only one write listener in each process: one of WriteOperationListener, SyncWriteOperationListener or AsyncWriteOperationListener. If you bind more than one, the behaviour is undefined, and the process logs a warning at start-up that begins Only one write listener per service is supported. To run several pieces of logic in one process, write one listener that dispatches to your own classes. Writes from GPAL Event Handlers reach your listener like any other write. Each of the three receives a different tx: an AsyncWriteOperationListener gets an AsyncDb, a SyncWriteOperationListener gets a SyncDb, and a WriteOperationListener gets an RxRecordWriteSupport.
Which writes notify your listener also depends on its type. An AsyncWriteOperationListener is notified only by async (suspend) writes: AsyncDb and AsyncEntityDb suspend writes, and single RxEntityDb writes. It is not notified by SyncDb or SyncEntityDb writes, or by blocking views such as AsyncEntityDb.sync(). A SyncWriteOperationListener is notified by SyncDb, SyncEntityDb and .sync() view writes, and also by AsyncDb, AsyncEntityDb and single RxEntityDb writes when no AsyncWriteOperationListener is bound. A WriteOperationListener is notified by RxDb writes, including writes through rxDb.entityDb(). When it is the only listener bound, it is also notified by SyncDb, SyncEntityDb, AsyncDb and AsyncEntityDb writes, which are bridged onto the sync path as in 8.x; see WriteOperationListener on the SQL write path for what that means for tx. Single RxEntityDb writes are async writes, not RxDb writes, because an injected RxEntityDb wraps AsyncEntityDb. RxDb writes notify only a WriteOperationListener, so if you switch from it to a SyncWriteOperationListener or an AsyncWriteOperationListener, your listener no longer sees RxDb writes. Writes made inside RxEntityDb.writeTransaction are the same: they notify only a WriteOperationListener, and a SyncWriteOperationListener or AsyncWriteOperationListener is not notified by them.
To switch to a different listener type, replace the old listener with the new one: move the old listener's logic into the new one and delete the old listener class. If the new listener is in a different package, register that package with its own extensions file (see The three listener interfaces), and delete the old package's file if nothing else in that package needs binding.
How a listener is called
- The listener is called after the write, inside the write's transaction, and before the write is published to the update queue.
- It is called once per write call. A batch write such as
insertAll,upsertAllormodifyAllcalls it once for the whole batch. Depending on the operation and the API,writeResultsholds oneWriteResultper record (as forupsertAll) or a singleWriteResultwith all the batch's records (as forinsertAll), so read every record in everyWriteResult. An audited write is two writes (the record and its audit record), so it calls the listener twice. txis bound to the same transaction. Writes you make through it commit or roll back with the triggering write, are published to the update queue after it, and don't call the listener again.- If the listener throws an exception, or one of its own writes fails, the triggering write rolls back and nothing is published.
- Only an exception thrown before
onWriteResultreturns rolls the triggering write back. Work you hand to another thread is outside the transaction. - Stay on the thread that called you (for
AsyncWriteOperationListener, the coroutine). Handing work ontxto another thread or dispatcher breaks the transaction or deadlocks it. Since 10.0.0,SyncWriteOperationListenerandAsyncWriteOperationListenercatch some of this and throw anIllegalStateException:- In a
SyncWriteOperationListener, usingtxon any thread other than the one that callsonWriteResultthrows anIllegalStateExceptionthat names the listener and the thread. It tells you to make eachtxcall on that thread, and not to handtxto another thread, executor or coroutine dispatcher. - In an
AsyncWriteOperationListener, usingtxafteronWriteResultreturns throws anIllegalStateException. It tells you to finish everytxcall before returning: await or join any coroutine that usestx, and don't launch one into another scope. This check is scope-based, not a thread check. It does not catchtxused on another dispatcher beforeonWriteResultreturns.
- In a
WriteOperationListener on the SQL write path
When a WriteOperationListener is called for a write that didn't go through RxDb, its tx is backed by the write's own transaction. Block on every call you make through it, for example with blockingGet(), on the thread that called onWriteResult. A call through tx from any other thread fails with an error that explains this.
This requirement is new in 10.0. In 8.x, the write waited for onWriteResult to return, but reactive work the listener started on tx without blocking was neither enforced nor awaited. Because 8.x committed as soon as onWriteResult returned, that work raced the commit: it could be written in the same transaction, written after it, or fail without an error reaching the caller. If your 8.x listener did this, check the records it wrote. In 8.x, a WriteOperationListener was already called for AsyncEntityDb and SyncEntityDb writes as well, so which writes your listener sees has not changed; only the blocking requirement on tx is new.
Whether you need to change your listener depends on how it uses tx:
- A listener that already blocks on every
txcall (for example withblockingGet()), or that callstxonly on the thread runningonWriteResultwith nosubscribeOnorobserveOn, needs no change. - A listener that uses
txfrom another thread, or afteronWriteResultreturns, now gets anIllegalStateExceptionon that thread. IfonWriteResultwaits for that work (for example withblockingGet()), the exception reaches it and the triggering write rolls back; if it doesn't wait, the triggering write and anything the listener wrote before the switch stay committed. If you have 8.x listener code that callssubscribe()on atxcall without blocking, change it to block.