io.micronaut.transaction.support.TransactionSynchronization Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of micronaut-data-tx Show documentation
Data Repository Support for Micronaut
There is a newer version: 4.9.3
/*
 * Copyright 2017-2020 original authors
 *
 * 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
 *
 * https://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 io.micronaut.transaction.support;

import io.micronaut.core.annotation.NonNull;
import io.micronaut.core.order.Ordered;

/**
 * Interface for transaction synchronization callbacks.
 *
 * TransactionSynchronization implementations can implement the Ordered interface
 * to influence their execution order. A synchronization that does not implement the
 * Ordered interface is appended to the end of the synchronization chain.
 *
 * @author Juergen Hoeller
 * @since 02.06.2003
 * @see io.micronaut.transaction.TransactionStatus#registerSynchronization(TransactionSynchronization)
 */
public interface TransactionSynchronization extends Ordered {

    /**
     * Transaction synchronization status.
     */
    enum Status {
        /** Completion status in case of proper commit. */
        COMMITTED,
        /** Completion status in case of proper rollback. */
        ROLLED_BACK,
        /** Completion status in case of heuristic mixed completion or system errors. */
        UNKNOWN
    }

    /**
     * Invoked before transaction commit (before "beforeCompletion").
     * Can e.g. flush transactional O/R Mapping sessions to the database.
     * 
This callback does not mean that the transaction will actually be committed.
     * A rollback decision can still occur after this method has been called. This callback
     * is rather meant to perform work that's only relevant if a commit still has a chance
     * to happen, such as flushing SQL statements to the database.
     * 
Note that exceptions will get propagated to the commit caller and cause a
     * rollback of the transaction.
     * @param readOnly whether the transaction is defined as read-only transaction
     * @throws RuntimeException in case of errors; will be propagated to the caller
     * (note: do not throw TransactionException subclasses here!)
     * @see #beforeCompletion
     */
    default void beforeCommit(boolean readOnly) {
    }

    /**
     * Invoked before transaction commit/rollback.
     * Can perform resource cleanup before transaction completion.
     * 
This method will be invoked after {@code beforeCommit}, even when
     * {@code beforeCommit} threw an exception. This callback allows for
     * closing resources before transaction completion, for any outcome.
     * @throws RuntimeException in case of errors; will be logged but not propagated
     * (note: do not throw TransactionException subclasses here!)
     * @see #beforeCommit
     * @see #afterCompletion
     */
    default void beforeCompletion() {
    }

    /**
     * Invoked after transaction commit. Can perform further operations right
     * after the main transaction has successfully committed.
     * 
Can e.g. commit further operations that are supposed to follow on a successful
     * commit of the main transaction, like confirmation messages or emails.
     * 
NOTE: The transaction will have been committed already, but the
     * transactional resources might still be active and accessible. As a consequence,
     * any data access code triggered at this point will still "participate" in the
     * original transaction, allowing to perform some cleanup (with no commit following
     * anymore!), unless it explicitly declares that it needs to run in a separate
     * transaction. Hence: Use {@code PROPAGATION_REQUIRES_NEW} for any
     * transactional operation that is called from here.
     * @throws RuntimeException in case of errors; will be propagated to the caller
     * (note: do not throw TransactionException subclasses here!)
     */
    default void afterCommit() {
    }

    /**
     * Invoked after transaction commit/rollback.
     * Can perform resource cleanup after transaction completion.
     * NOTE: The transaction will have been committed or rolled back already,
     * but the transactional resources might still be active and accessible. As a
     * consequence, any data access code triggered at this point will still "participate"
     * in the original transaction, allowing to perform some cleanup (with no commit
     * following anymore!), unless it explicitly declares that it needs to run in a
     * separate transaction. Hence: Use {@code PROPAGATION_REQUIRES_NEW}
     * for any transactional operation that is called from here.
     * @param status completion status according to the {@code STATUS_*} constants
     * @throws RuntimeException in case of errors; will be logged but not propagated
     * (note: do not throw TransactionException subclasses here!)
     * @see Status#COMMITTED
     * @see Status#ROLLED_BACK
     * @see Status#UNKNOWN
     * @see #beforeCompletion
     */
    default void afterCompletion(@NonNull Status status) {
    }

}