Flash5/flash-extensions/flash-ext-data-jdbc/docs/README.md

flash-ext-data-jdbc

JDBC backend for flash-ext-data-core.

Purpose

This module implements TxManager on top of a DataSource and provides a raw-SQL repository base class.

How to use it

1. Create the manager

DataSource dataSource = ...;
JdbcTxManager txManager = new JdbcTxManager(dataSource);
DataExtension extension = new DataExtension(txManager);

2. Install the extension in Flash

As with Hibernate, DataExtension registers Tx in the FlashContext and enables @Transactional on class-based handlers.

3. Define a repository

public final class UserRepository extends JdbcRepository<User, Long> {
    public UserRepository(Tx tx) {
        super(tx, "users", "id");
    }

    @Override
    protected User mapRow(ResultSet rs) throws SQLException {
        return new User(rs.getLong("id"), rs.getString("name"));
    }
}

Here too you can expose reusable Specs and compose queries from the service layer:

public final class UserRepository extends JdbcRepository<User, Long> {
    public static final SpecBuilder.FieldSpec<User, String> EMAIL = SpecBuilder.field("email");

    public UserRepository(Tx tx) {
        super(tx, "users", "id");
    }
}

Saving and updating need an explicit binding:

@Override
protected String insertSql() {
    return "insert into users(name) values(?)";
}

@Override
protected void bindInsert(PreparedStatement ps, User entity) throws SQLException {
    ps.setString(1, entity.name());
}

How it works underneath

• The current transaction exposes a Connection.
• Tx.resource(Connection.class) retrieves the connection bound to the thread.
• REQUIRES_NEW suspends the active connection and opens a new one.
• NOT_SUPPORTED suspends the context and continues without a transaction.

Repository base class

JdbcRepository provides:

• select queries through queryOne, queryMany
• mutations through mutate
• persistence through doSave, doUpdate
• paging through doFindPage
• bulk deleteAll(Spec<T>)
• raw helpers queryOne(...), queryMany(...), mutate(...)

Concrete repositories only have to translate between ResultSet and the domain.

Transactional semantics

• 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.

Notes

• The Connection 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 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.