KaumeiTxManager.java

/*
 * SPDX-FileCopyrightText: 2026 kaumei.io
 * SPDX-License-Identifier: Apache-2.0
 */
package io.kaumei.jdbc.tx;

import io.kaumei.jdbc.core.JdbcConnectionProvider;
import io.kaumei.jdbc.tx.internal.KaumeiTxManagerImpl;
import org.jspecify.annotations.Nullable;

public interface KaumeiTxManager extends JdbcConnectionProvider {

    static KaumeiTxManager getInstance(JdbcConnectionProvider provider) {
        return new KaumeiTxManagerImpl(provider);
    }

    @FunctionalInterface
    interface Callback {

        void execute(KaumeiTxContext context) throws Exception;
    }

    @FunctionalInterface
    interface CallbackWithNullableResult<T> {

        @Nullable T execute(KaumeiTxContext context) throws Exception;
    }

    @FunctionalInterface
    interface CallbackWithResult<T> {

        T execute(KaumeiTxContext context) throws Exception;
    }

    // ------------------------------------------------------------------------

    void setRollbackOnly();

    boolean isRollbackOnly();

    boolean isTransactionActive();

    void registerSynchronization(KaumeiTxSynchronization synchronization);

    /**
     * Complete the current physical transaction and retain its context and connection for the
     * next physical transaction.
     */
    void commitAndContinue();

    // ------------------------------------------------------------------------

    void required(KaumeiTxDefinition definition, Callback callback) throws Exception;

    <T> T required(KaumeiTxDefinition definition, CallbackWithResult<T> callback) throws Exception;

    <T> @Nullable T requiredOpt(KaumeiTxDefinition definition, CallbackWithNullableResult<T> callback) throws Exception;

    // ------------------------------------------------------------------------

    void requiresNew(KaumeiTxDefinition definition, Callback callback) throws Exception;

    <T> T requiresNew(KaumeiTxDefinition definition, CallbackWithResult<T> callback) throws Exception;

    <T> @Nullable T requiresNewOpt(KaumeiTxDefinition definition, CallbackWithNullableResult<T> callback) throws Exception;

    // ------------------------------------------------------------------------

    void mandatory(KaumeiTxDefinition definition, Callback callback) throws Exception;

    <T> T mandatory(KaumeiTxDefinition definition, CallbackWithResult<T> callback) throws Exception;

    <T> @Nullable T mandatoryOpt(KaumeiTxDefinition definition, CallbackWithNullableResult<T> callback) throws Exception;

    // ------------------------------------------------------------------------

    void supports(KaumeiTxDefinition definition, Callback callback) throws Exception;

    <T> T supports(KaumeiTxDefinition definition, CallbackWithResult<T> callback) throws Exception;

    <T> @Nullable T supportsOpt(KaumeiTxDefinition definition, CallbackWithNullableResult<T> callback) throws Exception;

    // ------------------------------------------------------------------------

    void notSupported(KaumeiTxDefinition definition, Callback callback) throws Exception;

    <T> T notSupported(KaumeiTxDefinition definition, CallbackWithResult<T> callback) throws Exception;

    <T> @Nullable T notSupportedOpt(KaumeiTxDefinition definition, CallbackWithNullableResult<T> callback) throws Exception;

    // ------------------------------------------------------------------------

    void never(KaumeiTxDefinition definition, Callback callback) throws Exception;

    <T> T never(KaumeiTxDefinition definition, CallbackWithResult<T> callback) throws Exception;

    <T> @Nullable T neverOpt(KaumeiTxDefinition definition, CallbackWithNullableResult<T> callback) throws Exception;

    // ------------------------------------------------------------------------

}