Relism/Flash5
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(data): fire transaction synchronizations, and scope them to their transaction #9

Merged
Relism merged 3 commits from fix/tx-synchronizations into master 2026-08-12 23:37:36 +00:00
Conversation 0 Commits 3 Files Changed 14
+152 -143
3 changed files with 152 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit c5179146c0 - Show all commits
flash-extensions/flash-ext-data-core/docs/README.md
+79 -78
View File
@@ -1,93 +1,93 @@
# flash-ext-data-core # flash-ext-data-core
Core comune per il layer dati di Flash. Shared core for Flash's data layer.
## Scopo ## Purpose
Questo modulo definisce il contratto transazionale condiviso tra le implementazioni backend. This module defines the transactional contract shared across backend implementations. It does not
Non parla con Hibernate o JDBC direttamente: espone solo astrazioni e un runtime minimale. talk to Hibernate or JDBC directly: it exposes abstractions and a minimal runtime, nothing else.
## Componenti ## Components
- `TxDefinition`: metadata immutabile della transazione. - `TxDefinition`: immutable transaction metadata.
- `TxStatus`: stato runtime restituito dal manager. - `TxStatus`: runtime state returned by the manager.
- `TxManager`: contratto per `begin`, `commit`, `rollback`. - `TxManager`: the `begin`/`commit`/`rollback` contract.
- `Tx`: orchestration runtime e stack transazionale per thread. - `Tx`: runtime orchestration and the per-thread transaction stack.
- `ResourceRegistry`: storage thread-local di risorse e synchronizations. - `ResourceRegistry`: thread-local storage for resources and synchronizations.
- `Repository<T, ID>`: base repository auto-transazionale. - `Repository<T, ID>`: self-transactional base repository.
- `Spec<T>`: predicato componibile. - `Spec<T>`: composable predicate.
- `Query<T>`: oggetto query con spec, sort e paging. - `Query<T>`: query object carrying spec, sort and paging.
- `SpecBuilder<T>`: DSL fluente per costruire spec tipizzate. - `SpecBuilder<T>`: fluent DSL for building typed specs.
- `RepositorySupport<T, ID>`: helper interno condiviso. - `RepositorySupport<T, ID>`: shared internal helper.
- `TransactionPropagation`: semantica di propagazione. - `TransactionPropagation`: propagation semantics.
- `TransactionIsolation`: livello di isolamento. - `TransactionIsolation`: isolation level.
- `TxSynchronization`: hook lifecycle (vedi sotto). - `TxSynchronization`: lifecycle hooks (see below).
## Modello di esecuzione ## Execution model
Il flusso è: The flow is:
1. `Tx.call(definition, work)` chiama `TxManager.begin(definition)`. 1. `Tx.call(definition, work)` calls `TxManager.begin(definition)`.
2. Il `TxManager` crea un `TxStatus` backend-specific. 2. The `TxManager` creates a backend-specific `TxStatus`.
3. Lo status viene pushato nello stack thread-local. 3. The status is pushed onto the thread-local stack.
4. Il lavoro usa `Tx.resource(Class)` per ottenere la risorsa corrente. 4. The work uses `Tx.resource(Class)` to obtain the current resource.
5. A fine lavoro `Tx` decide tra `commit` e `rollback`. 5. When the work ends, `Tx` chooses between `commit` and `rollback`.
6. Lo stack viene poppato e il thread-local viene pulito se vuoto. 6. The stack is popped, and the thread-local is cleared once it is empty.
## Propagation supportata ## Supported propagation
- `REQUIRED`: usa la tx attiva oppure ne apre una nuova. - `REQUIRED`: use the active transaction, or open a new one.
- `REQUIRES_NEW`: sospende la tx corrente e apre una nuova tx. - `REQUIRES_NEW`: suspend the current transaction and open a new one.
- `SUPPORTS`: se esiste una tx attiva si aggancia, altrimenti esegue senza tx. - `SUPPORTS`: join the active transaction if there is one, otherwise run without a transaction.
- `NOT_SUPPORTED`: sospende la tx corrente ed esegue senza tx. - `NOT_SUPPORTED`: suspend the current transaction and run without one.
- `MANDATORY`: richiede una tx attiva. - `MANDATORY`: require an active transaction.
## Synchronization (`TxSynchronization`) ## Synchronizations (`TxSynchronization`)
Hook sul ciclo di vita di **una** transazione, registrati con `Data.afterCommit(...)` (o Lifecycle hooks for **one** transaction, registered through `Data.afterCommit(...)` (or directly
direttamente con `ResourceRegistry.addSynchronization(...)`). with `ResourceRegistry.addSynchronization(...)`).
Ogni callback appartiene esattamente alla transazione più interna attiva al momento della Every callback belongs to exactly the innermost transaction active at registration time, and fires
registrazione, e scatta una volta sola quando *quella* transazione completa: exactly once, when *that* transaction completes:
- una tx interna **joined** (`REQUIRED`) non è una transazione a sé, quindi i callback registrati - a **joined** inner transaction (`REQUIRED`) is not a transaction of its own, so callbacks
al suo interno aspettano il commit più esterno; registered inside one wait for the outermost commit;
- una tx `REQUIRES_NEW` lo è, quindi completarla fa scattare solo i propri callback e lascia in - a `REQUIRES_NEW` transaction is, so completing it fires only its own callbacks and leaves the
sospeso quelli della transazione esterna sospesa. suspended outer transaction's pending.
### Posizione rispetto al commit ### Which side of the commit each hook sits on
| hook | quando | risorsa | | hook | when | resource |
| --- | --- | --- | | --- | --- | --- |
| `beforeCommit(readOnly)` | subito **prima** del commit reale | sessione/connection ancora **bound**, tx ancora attiva | | `beforeCommit(readOnly)` | immediately **before** the real commit | session/connection still **bound**, transaction still active |
| `afterCommit()` / `afterRollback()` | dopo il completamento | risorsa già **sganciata** | | `afterCommit()` / `afterRollback()` | after completion | resource already **unbound** |
| `afterCompletion(outcome)` | dopo i due precedenti | risorsa già sganciata | | `afterCompletion(outcome)` | after the two above | resource already unbound |
`beforeCommit` è l'unico hook che può ancora scrivere sulla stessa risorsa e finire nella stessa `beforeCommit` is the only hook that can still write through the same resource and have the write
unità atomica: flush di un buffer, riga di audit, valore derivato. Non viene eseguito se la land in the same atomic unit: flush a buffer, stamp an audit row, materialize a derived value. It
transazione è già `rollback-only`, perché non c'è nessun commit da precedere. is skipped when the transaction is already `rollback-only`, since there is no commit to precede.
I callback post-completamento girano invece a risorsa sganciata: uno che apre una propria Post-completion callbacks run with the resource unbound instead: one that opens its own transaction
transazione ne ottiene una **nuova** invece di agganciarsi a quella appena conclusa. È questo che gets a **fresh** one rather than joining the transaction that just finished. That is what makes
li rende il posto giusto per invalidare una cache, accodare un messaggio o notificare qualcosa them the right place to refresh a cache, enqueue a message, or notify anything outside the
fuori dal database. database.
### Fallimenti ### Failure
Lanciare da `beforeCommit` **veta il commit**: la transazione va in rollback, scattano Throwing from `beforeCommit` **vetoes the commit**: the transaction is rolled back,
`afterRollback`/`afterCompletion(ROLLED_BACK)` e l'eccezione arriva al chiamante. È il motivo per `afterRollback`/`afterCompletion(ROLLED_BACK)` fire, and the exception reaches the caller. That is
cui l'hook gira prima del commit e non dopo — può ancora rifiutare. the reason the hook runs before the commit rather than after — it can still refuse.
Gli hook post-completamento non hanno questo potere: la transazione è già chiusa quando girano, The post-completion hooks have no such power: the transaction is already over by the time they run,
quindi un'eccezione si propaga ma non cambia nulla di ciò che è stato committato, e blocca i so an exception propagates but changes nothing already committed, and stops the callbacks queued
callback in coda dietro di lei. behind it.
## Uso di `Repository` ## Using `Repository`
`Repository` è la base comune per le repository concrete. `Repository` is the shared base for concrete repositories. Every public operation internally uses a
Ogni operazione pubblica usa internamente una tx `REQUIRED` o `REQUIRED` read-only. `REQUIRED` transaction, read-only where applicable.
Le sottoclassi implementano i metodi `doXxx(...)` del nuovo modello: Subclasses implement the `doXxx(...)` methods:
- `doFind(Query<T>)` - `doFind(Query<T>)`
- `doFindOne(Spec<T>)` - `doFindOne(Spec<T>)`
@@ -95,7 +95,8 @@ Le sottoclassi implementano i metodi `doXxx(...)` del nuovo modello:
- `doDeleteAll(Spec<T>)` - `doDeleteAll(Spec<T>)`
- `doUpdateAll(Spec<T>, T)` - `doUpdateAll(Spec<T>, T)`
I vecchi overload di `findAll(...)` e `findPage(...)` sono stati ridotti a una combinazione di `Query<T>` e `Spec<T>`. The old `findAll(...)` and `findPage(...)` overloads were reduced to a combination of `Query<T>` and
`Spec<T>`.
```java ```java
public abstract class Repository<T, ID> { public abstract class Repository<T, ID> {
@@ -104,21 +105,21 @@ public abstract class Repository<T, ID> {
} }
``` ```
## Composizione con Flash ## Composing with Flash
`DataExtension` registra: `DataExtension` registers:
- `Tx` nel `FlashContext` - `Tx` in the `FlashContext`
- `TxManager` nel `FlashContext` - `TxManager` in the `FlashContext`
- un annotation processor per `@Transactional` - an annotation processor for `@Transactional`
Questo rende il layer dati componibile con il sistema di extension di Flash senza stato globale. This makes the data layer composable with Flash's extension system without global state.
## Note implementative ## Implementation notes
- Lo stack transazionale è thread-local e viene ripulito quando torna vuoto. - The transaction stack is thread-local and is cleared once it becomes empty.
- Le risorse backend sono sospese e ripristinate per `REQUIRES_NEW` e `NOT_SUPPORTED`. - Backend resources are suspended and restored for `REQUIRES_NEW` and `NOT_SUPPORTED`.
- `TxSynchronization` è il punto di aggancio per hook di commit/rollback/completion. - `TxSynchronization` is the hook point for commit/rollback/completion callbacks.
- Le synchronization sono in una lista thread-local; ogni transazione nuova registra quante ne - Synchronizations live in a thread-local list; every new transaction records how many were already
esistevano già alla sua apertura e fa scattare solo la propria coda, così una `REQUIRES_NEW` registered when it opened and fires only its own tail, so a `REQUIRES_NEW` does not drag along
non trascina con sé quelle della transazione sospesa. the suspended transaction's callbacks.
flash-extensions/flash-ext-data-hibernate/docs/README.md
+35 -32
View File
@@ -1,14 +1,15 @@
# flash-ext-data-hibernate # flash-ext-data-hibernate
Backend Hibernate per `flash-ext-data-core`. Hibernate backend for `flash-ext-data-core`.
## Scopo ## Purpose
Questo modulo implementa `TxManager` sopra `SessionFactory` e fornisce una base repository Hibernate-centric. This module implements `TxManager` on top of a `SessionFactory` and provides a Hibernate-centric
repository base class.
## Come si usa ## How to use it
### 1. Creare il manager ### 1. Create the manager
```java ```java
SessionFactory sessionFactory = ...; SessionFactory sessionFactory = ...;
@@ -16,12 +17,12 @@ HibernateTxManager txManager = new HibernateTxManager(sessionFactory);
DataExtension extension = new DataExtension(txManager); DataExtension extension = new DataExtension(txManager);
``` ```
### 2. Installare l’estensione in Flash ### 2. Install the extension in Flash
L’estensione registra `Tx` e `TxManager` nel `FlashContext`. The extension registers `Tx` and `TxManager` in the `FlashContext`. Class-based handlers annotated
Le handler class-based annotate con `@Transactional` vengono wrappate automaticamente. with `@Transactional` are wrapped automatically.
### 3. Definire una repository ### 3. Define a repository
```java ```java
public final class UserRepository extends HibernateRepository<User, Long> { public final class UserRepository extends HibernateRepository<User, Long> {
@@ -31,7 +32,7 @@ public final class UserRepository extends HibernateRepository<User, Long> {
} }
``` ```
Con il nuovo modello query/spec puoi esporre campi riusabili come costanti: With the query/spec model you can expose reusable fields as constants:
```java ```java
public final class UserRepository extends HibernateRepository<User, Long> { public final class UserRepository extends HibernateRepository<User, Long> {
@@ -48,7 +49,7 @@ public final class UserRepository extends HibernateRepository<User, Long> {
} }
``` ```
Le query domain-specific possono usare gli helper della base class: Domain-specific queries can use the base class helpers:
```java ```java
public List<User> findByEmailDomain(String domain) { public List<User> findByEmailDomain(String domain) {
@@ -58,35 +59,37 @@ public List<User> findByEmailDomain(String domain) {
} }
``` ```
## Come funziona sotto ## How it works underneath
- La tx corrente è rappresentata da `HibernateTxStatus`. - The current transaction is represented by `HibernateTxStatus`.
- La risorsa esposta al core è una `Session`. - The resource exposed to the core is a `Session`.
- `Tx.resource(Session.class)` recupera la `Session` dal contesto corrente. - `Tx.resource(Session.class)` retrieves the `Session` from the current context.
- `REQUIRES_NEW` sospende lo status attivo e apre una nuova `Session`. - `REQUIRES_NEW` suspends the active status and opens a new `Session`.
- `NOT_SUPPORTED` sospende la tx attiva e continua senza sessione bindata. - `NOT_SUPPORTED` suspends the active transaction and continues with no session bound.
## Repository base ## Repository base class
`HibernateRepository` fornisce: `HibernateRepository` provides:
- `findById`, `findAll`, `findPage`, `findOne` - `findById`, `findAll`, `findPage`, `findOne`
- `save`, `update`, `delete`, `saveAll` - `save`, `update`, `delete`, `saveAll`
- bulk `deleteAll(Spec<T>)` e `updateAll(Spec<T>, T)` - bulk `deleteAll(Spec<T>)` and `updateAll(Spec<T>, T)`
- helper HQL: `hql(...)`, `hqlMutate(...)` - HQL helpers: `hql(...)`, `hqlMutate(...)`
Le classi concrete devono solo implementare query di dominio, non il plumbing transazionale. Concrete classes only have to implement domain queries, never the transactional plumbing.
## Semantica transazionale ## Transactional semantics
- `REQUIRED`: join o apertura nuova tx. - `REQUIRED`: join, or open a new transaction.
- `REQUIRES_NEW`: sospensione del contesto corrente. - `REQUIRES_NEW`: suspend the current context.
- `SUPPORTS`: join se c’è tx, altrimenti no-op. - `SUPPORTS`: join if a transaction exists, otherwise no-op.
- `NOT_SUPPORTED`: sospende e prosegue senza tx. - `NOT_SUPPORTED`: suspend and continue without a transaction.
- `MANDATORY`: fallisce se non c’è tx. - `MANDATORY`: fail if there is no transaction.
## Note ## Notes
- `Session` viene chiusa a fine tx nuova. - The `Session` is closed when a new transaction ends.
- Le synchronizations vengono eseguite al commit/rollback. - Synchronizations registered in a transaction fire when *that* transaction completes:
- Il backend è pensato per essere usato tramite la base class, non direttamente. `beforeCommit` while it is still active and the `Session` still bound, the post-completion hooks
once it is unbound. See `flash-ext-data-core/docs/README.md` for the full contract.
- This backend is meant to be used through the base class, not directly.
flash-extensions/flash-ext-data-jdbc/docs/README.md
+38 -33
View File
@@ -1,14 +1,15 @@
# flash-ext-data-jdbc # flash-ext-data-jdbc
Backend JDBC per `flash-ext-data-core`. JDBC backend for `flash-ext-data-core`.
## Scopo ## Purpose
Questo modulo implementa `TxManager` sopra `DataSource` e fornisce una base repository SQL raw. This module implements `TxManager` on top of a `DataSource` and provides a raw-SQL repository base
class.
## Come si usa ## How to use it
### 1. Creare il manager ### 1. Create the manager
```java ```java
DataSource dataSource = ...; DataSource dataSource = ...;
@@ -16,11 +17,12 @@ JdbcTxManager txManager = new JdbcTxManager(dataSource);
DataExtension extension = new DataExtension(txManager); DataExtension extension = new DataExtension(txManager);
``` ```
### 2. Installare l’estensione in Flash ### 2. Install the extension in Flash
Come per Hibernate, `DataExtension` registra `Tx` nel `FlashContext` e abilita `@Transactional` sugli handler class-based. As with Hibernate, `DataExtension` registers `Tx` in the `FlashContext` and enables
`@Transactional` on class-based handlers.
### 3. Definire una repository ### 3. Define a repository
```java ```java
public final class UserRepository extends JdbcRepository<User, Long> { public final class UserRepository extends JdbcRepository<User, Long> {
@@ -35,7 +37,7 @@ public final class UserRepository extends JdbcRepository<User, Long> {
} }
``` ```
Anche qui puoi esporre `Spec` riusabili e comporre query dal service layer: Here too you can expose reusable `Spec`s and compose queries from the service layer:
```java ```java
public final class UserRepository extends JdbcRepository<User, Long> { public final class UserRepository extends JdbcRepository<User, Long> {
@@ -47,7 +49,7 @@ public final class UserRepository extends JdbcRepository<User, Long> {
} }
``` ```
Per il salvataggio e l’update devi fornire il binding esplicito: Saving and updating need an explicit binding:
```java ```java
@Override @Override
@@ -61,36 +63,39 @@ protected void bindInsert(PreparedStatement ps, User entity) throws SQLException
} }
``` ```
## Come funziona sotto ## How it works underneath
- La tx corrente espone una `Connection`. - The current transaction exposes a `Connection`.
- `Tx.resource(Connection.class)` recupera la connessione bindata al thread. - `Tx.resource(Connection.class)` retrieves the connection bound to the thread.
- `REQUIRES_NEW` sospende la connessione attiva e ne apre una nuova. - `REQUIRES_NEW` suspends the active connection and opens a new one.
- `NOT_SUPPORTED` sospende il contesto e prosegue senza tx. - `NOT_SUPPORTED` suspends the context and continues without a transaction.
## Repository base ## Repository base class
`JdbcRepository` fornisce: `JdbcRepository` provides:
- query `select` con `queryOne`, `queryMany` - `select` queries through `queryOne`, `queryMany`
- mutation con `mutate` - mutations through `mutate`
- persistenza con `doSave`, `doUpdate` - persistence through `doSave`, `doUpdate`
- paging con `doFindPage` - paging through `doFindPage`
- bulk `deleteAll(Spec<T>)` - bulk `deleteAll(Spec<T>)`
- helper raw `queryOne(...)`, `queryMany(...)`, `mutate(...)` - raw helpers `queryOne(...)`, `queryMany(...)`, `mutate(...)`
Le repository concrete devono solo tradurre tra `ResultSet` e dominio. Concrete repositories only have to translate between `ResultSet` and the domain.
## Semantica transazionale ## Transactional semantics
- `REQUIRED`: join o apertura nuova tx. - `REQUIRED`: join, or open a new transaction.
- `REQUIRES_NEW`: sospensione del contesto corrente. - `REQUIRES_NEW`: suspend the current context.
- `SUPPORTS`: join se c’è tx, altrimenti no-op. - `SUPPORTS`: join if a transaction exists, otherwise no-op.
- `NOT_SUPPORTED`: sospende e prosegue senza tx. - `NOT_SUPPORTED`: suspend and continue without a transaction.
- `MANDATORY`: fallisce se non c’è tx. - `MANDATORY`: fail if there is no transaction.
## Note ## Notes
- La `Connection` viene chiusa a fine tx nuova. - The `Connection` is closed when a new transaction ends.
- Le synchronizations vengono eseguite al commit/rollback. - Synchronizations registered in a transaction fire when *that* transaction completes:
- Se una repository usa `doDelete(T)`, il comportamento predefinito è non supportato: usare `deleteById` o override specifico. `beforeCommit` while it is still active and the `Connection` still bound, the post-completion
hooks once it is unbound. See `flash-ext-data-core/docs/README.md` for the full contract.
- If a repository uses `doDelete(T)`, the default behaviour is unsupported: use `deleteById` or
override it.