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

docs(data): write the data-layer docs in English

Browse Source 
The three data modules' docs were in Italian, so the synchronization contract
added in the previous commit went in as Italian too, to match its file. English
is the project's language for docs, comments and READMEs alike, and a file half
in each is worse than either — so all three are translated, not just the new
section.

Content is otherwise unchanged, except the "synchronizations run on
commit/rollback" line in the two backend READMEs, which was vague before and is
now accurate about which hook sees the session/connection still bound, pointing
at flash-ext-data-core's README for the full contract.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Zakaria El Orche
2026-08-12 23:36:11 +00:00
co-authored by Claude Opus 5
parent 0194470c1f
commit c5179146c0
3 changed files with 152 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files
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.