/*
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.jdbi.v3.sqlobject.transaction;

import org.jdbi.v3.core.transaction.TransactionException;
import org.jdbi.v3.core.transaction.TransactionIsolationLevel;
import org.jdbi.v3.sqlobject.SqlObject;

A mixin interface to expose transaction methods on the sql object.
 Use caution with on-demand Transactional instances. Handle throws TransactionException if closed while a transaction is open. Since on-demand extensions open and close a handle around each method invocation, calling begin() on an on-demand Transactional will always leave a transaction open, and thus always throw this exception.
 Users of on-demand Transactional instances should use the inTransaction and useTransaction methods to execute transactions. It is safe to call other Transactional methods from inside these callbacks. 
Type parameters:
<This> – must match the interface that is extending this one./**
 * A mixin interface to expose transaction methods on the sql object.
 * <p>
 * Use caution with {@link org.jdbi.v3.core.Jdbi#onDemand(Class) on-demand} {@code Transactional} instances.
 * {@link org.jdbi.v3.core.Handle} throws {@link TransactionException} if closed while a
 * transaction is open. Since on-demand extensions open and close a handle around each method invocation, calling
 * {@link #begin()} on an on-demand {@code Transactional} will always leave a transaction open, and thus
 * <em>always</em> throw this exception.
 * <p>
 * Users of on-demand {@code Transactional} instances should use the {@code inTransaction} and {@code useTransaction}
 * methods to execute transactions. It is safe to call other {@code Transactional} methods from inside these callbacks.
 *
 * @param <This> must match the interface that is extending this one.
 */
public interface Transactional<This extends Transactional<This>> extends SqlObject {
    
Begins a transaction.
Throws:
TransactionException – if called on an on-demand Transactional instance./**
     * Begins a transaction.
     *
     * @throws TransactionException if called on an on-demand Transactional instance.
     */
    default void begin() {
        getHandle().begin();
    }

    
Commits the open transaction.
/**
     * Commits the open transaction.
     */
    default void commit() {
        getHandle().commit();
    }

    
Rolls back the open transaction.
/**
     * Rolls back the open transaction.
     */
    default void rollback() {
        getHandle().rollback();
    }

    
Creates a savepoint with the given name on the transaction.
Params:
savepointName – the savepoint name./**
     * Creates a savepoint with the given name on the transaction.
     *
     * @param savepointName the savepoint name.
     */
    default void savepoint(String savepointName) {
        getHandle().savepoint(savepointName);
    }

    
Rolls back to the given savepoint.
Params:
savepointName – the savepoint name./**
     * Rolls back to the given savepoint.
     *
     * @param savepointName the savepoint name.
     */
    default void rollbackToSavepoint(String savepointName) {
        getHandle().rollbackToSavepoint(savepointName);
    }

    
Releases the given savepoint.
Params:
savepointName – the savepoint name./**
     * Releases the given savepoint.
     *
     * @param savepointName the savepoint name.
     */
    default void releaseSavepoint(String savepointName) {
        getHandle().release(savepointName);
    }

    
Executes the given callback within a transaction, returning the value returned by the callback.
Params:
callback – the callback to execute
Type parameters:
<R> –      method return type
<X> –      exception optionally thrown by the callback.
Throws:
X – any exception thrown by the callback.
Returns:
the value returned by the callback./**
     * Executes the given callback within a transaction, returning the value returned by the callback.
     *
     * @param callback the callback to execute
     * @param <R>      method return type
     * @param <X>      exception optionally thrown by the callback.
     * @return the value returned by the callback.
     * @throws X any exception thrown by the callback.
     */
    @SuppressWarnings("unchecked")
    default <R, X extends Exception> R inTransaction(TransactionalCallback<R, This, X> callback) throws X {
        return withHandle(h -> h.inTransaction(txn -> callback.inTransaction((This) this)));
    }

    
Executes the given callback within a transaction, returning the value returned by the callback.
Params:
isolation – the transaction isolation level.
callback –  the callback to execute
Type parameters:
<R> –       method return type
<X> –       exception optionally thrown by the callback.
Throws:
X – any exception thrown by the callback.
Returns:
the value returned by the callback./**
     * Executes the given callback within a transaction, returning the value returned by the callback.
     *
     * @param isolation the transaction isolation level.
     * @param callback  the callback to execute
     * @param <R>       method return type
     * @param <X>       exception optionally thrown by the callback.
     * @return the value returned by the callback.
     * @throws X any exception thrown by the callback.
     */
    @SuppressWarnings("unchecked")
    default <R, X extends Exception> R inTransaction(
            TransactionIsolationLevel isolation, TransactionalCallback<R, This, X> callback) throws X {
        return withHandle(h -> h.inTransaction(isolation, txn -> callback.inTransaction((This) this)));
    }

    
Executes the given callback within a transaction.
Params:
callback – the callback to execute
Type parameters:
<X> –      exception optionally thrown by the callback.
Throws:
X – any exception thrown by the callback./**
     * Executes the given callback within a transaction.
     *
     * @param callback the callback to execute
     * @param <X>      exception optionally thrown by the callback.
     * @throws X any exception thrown by the callback.
     */
    default <X extends Exception> void useTransaction(TransactionalConsumer<This, X> callback) throws X {
        inTransaction(callback.asCallback());
    }

    
Executes the given callback within a transaction.
Params:
isolation – the transaction isolation level.
callback –  the callback to execute
Type parameters:
<X> –       exception optionally thrown by the callback.
Throws:
X – any exception thrown by the callback./**
     * Executes the given callback within a transaction.
     *
     * @param isolation the transaction isolation level.
     * @param callback  the callback to execute
     * @param <X>       exception optionally thrown by the callback.
     * @throws X any exception thrown by the callback.
     */
    default <X extends Exception> void useTransaction(TransactionIsolationLevel isolation,
                                                      TransactionalConsumer<This, X> callback) throws X {
        inTransaction(isolation, callback.asCallback());
    }
}