docs(data): write the data-layer docs in English
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
co-authored by
Claude Opus 5
Claude Opus 5
parent
0194470c1f
commit
c5179146c0
@@ -1,14 +1,15 @@
|
||||
# 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
|
||||
SessionFactory sessionFactory = ...;
|
||||
@@ -16,12 +17,12 @@ HibernateTxManager txManager = new HibernateTxManager(sessionFactory);
|
||||
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`.
|
||||
Le handler class-based annotate con `@Transactional` vengono wrappate automaticamente.
|
||||
The extension registers `Tx` and `TxManager` in the `FlashContext`. Class-based handlers annotated
|
||||
with `@Transactional` are wrapped automatically.
|
||||
|
||||
### 3. Definire una repository
|
||||
### 3. Define a repository
|
||||
|
||||
```java
|
||||
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
|
||||
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
|
||||
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`.
|
||||
- La risorsa esposta al core è una `Session`.
|
||||
- `Tx.resource(Session.class)` recupera la `Session` dal contesto corrente.
|
||||
- `REQUIRES_NEW` sospende lo status attivo e apre una nuova `Session`.
|
||||
- `NOT_SUPPORTED` sospende la tx attiva e continua senza sessione bindata.
|
||||
- The current transaction is represented by `HibernateTxStatus`.
|
||||
- The resource exposed to the core is a `Session`.
|
||||
- `Tx.resource(Session.class)` retrieves the `Session` from the current context.
|
||||
- `REQUIRES_NEW` suspends the active status and opens a new `Session`.
|
||||
- `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`
|
||||
- `save`, `update`, `delete`, `saveAll`
|
||||
- bulk `deleteAll(Spec<T>)` e `updateAll(Spec<T>, T)`
|
||||
- helper HQL: `hql(...)`, `hqlMutate(...)`
|
||||
- bulk `deleteAll(Spec<T>)` and `updateAll(Spec<T>, T)`
|
||||
- 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.
|
||||
- `REQUIRES_NEW`: sospensione del contesto corrente.
|
||||
- `SUPPORTS`: join se c’è tx, altrimenti no-op.
|
||||
- `NOT_SUPPORTED`: sospende e prosegue senza tx.
|
||||
- `MANDATORY`: fallisce se non c’è tx.
|
||||
- `REQUIRED`: join, or open a new transaction.
|
||||
- `REQUIRES_NEW`: suspend the current context.
|
||||
- `SUPPORTS`: join if a transaction exists, otherwise no-op.
|
||||
- `NOT_SUPPORTED`: suspend and continue without a transaction.
|
||||
- `MANDATORY`: fail if there is no transaction.
|
||||
|
||||
## Note
|
||||
## Notes
|
||||
|
||||
- `Session` viene chiusa a fine tx nuova.
|
||||
- Le synchronizations vengono eseguite al commit/rollback.
|
||||
- Il backend è pensato per essere usato tramite la base class, non direttamente.
|
||||
- The `Session` is closed when a new transaction ends.
|
||||
- Synchronizations registered in a transaction fire when *that* transaction completes:
|
||||
`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.
|
||||
|
||||
Reference in New Issue
Block a user