src/java/org/apache/cassandra/utils/concurrent/Transactional.java

/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements.  See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership.  The ASF licenses this file
* to you 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.apache.cassandra.utils.concurrent;

import static org.apache.cassandra.utils.Throwables.maybeFail;
import static org.apache.cassandra.utils.Throwables.merge;

/**
 * An abstraction for Transactional behaviour. An object implementing this interface has a lifetime
 * of the following pattern:
 *
 * Throwable failure = null;
 * try (Transactional t1, t2 = ...)
 * {
 *     // do work with t1 and t2
 *     t1.prepareToCommit();
 *     t2.prepareToCommit();
 *     failure = t1.commit(failure);
 *     failure = t2.commit(failure);
 * }
 * logger.error(failure);
 *
 * If something goes wrong before commit() is called on any transaction, then on exiting the try block
 * the auto close method should invoke cleanup() and then abort() to reset any state.
 * If everything completes normally, then on exiting the try block the auto close method will invoke cleanup
 * to release any temporary state/resources
 *
 * All exceptions and assertions that may be thrown should be checked and ruled out during commit preparation.
 * Commit should generally never throw an exception unless there is a real correctness-affecting exception that
 * cannot be moved to prepareToCommit, in which case this operation MUST be executed before any other commit
 * methods in the object graph.
 *
 * If exceptions are generated by commit after this initial moment, it is not at all clear what the correct behaviour
 * of the system should be, and so simply logging the exception is likely best (since it may have been an issue
 * during cleanup, say), and rollback cannot now occur. As such all exceptions and assertions that may be thrown
 * should be checked and ruled out during commit preparation.
 *
 * Since Transactional implementations will abort any changes they've made if calls to prepareToCommit() and commit()
 * aren't made prior to calling close(), the semantics of its close() method differ significantly from
 * most AutoCloseable implementations.
 */
public interface Transactional extends AutoCloseable
{
    /**
     * A simple abstract implementation of Transactional behaviour.
     * In general this should be used as the base class for any transactional implementations.
     *
     * If the implementation wraps any internal Transactional objects, it must proxy every
     * commit() and abort() call onto each internal object to ensure correct behaviour
     */
    abstract class AbstractTransactional implements Transactional
    {
        public enum State
        {
            IN_PROGRESS,
            READY_TO_COMMIT,
            COMMITTED,
            ABORTED;
        }

        private boolean permitRedundantTransitions;
        private State state = State.IN_PROGRESS;

        // the methods for actually performing the necessary behaviours, that are themselves protected against
        // improper use by the external implementations provided by this class. empty default implementations
        // could be provided, but we consider it safer to force implementers to consider explicitly their presence

        protected abstract Throwable doCommit(Throwable accumulate);
        protected abstract Throwable doAbort(Throwable accumulate);

        // these only needs to perform cleanup of state unique to this instance; any internal
        // Transactional objects will perform cleanup in the commit() or abort() calls

        /**
         * perform an exception-safe pre-abort/commit cleanup;
         * this will be run after prepareToCommit (so before commit), and before abort
         */
        protected Throwable doPreCleanup(Throwable accumulate){ return accumulate; }

        /**
         * perform an exception-safe post-abort cleanup
         */
        protected Throwable doPostCleanup(Throwable accumulate){ return accumulate; }

        /**
         * Do any preparatory work prior to commit. This method should throw any exceptions that can be encountered
         * during the finalization of the behaviour.
         */
        protected abstract void doPrepare();

        /**
         * commit any effects of this transaction object graph, then cleanup; delegates first to doCommit, then to doCleanup
         */
        public final Throwable commit(Throwable accumulate)
        {
            if (permitRedundantTransitions && state == State.COMMITTED)
                return accumulate;
            if (state != State.READY_TO_COMMIT)
                throw new IllegalStateException("Cannot commit unless READY_TO_COMMIT; state is " + state);
            accumulate = doCommit(accumulate);
            accumulate = doPostCleanup(accumulate);
            state = State.COMMITTED;
            return accumulate;
        }

        /**
         * rollback any effects of this transaction object graph; delegates first to doCleanup, then to doAbort
         */
        public final Throwable abort(Throwable accumulate)
        {
            if (state == State.ABORTED)
                return accumulate;
            if (state == State.COMMITTED)
            {
                try
                {
                    throw new IllegalStateException("Attempted to abort a committed operation");
                }
                catch (Throwable t)
                {
                    accumulate = merge(accumulate, t);
                }
                return accumulate;
            }
            state = State.ABORTED;
            // we cleanup first so that, e.g., file handles can be released prior to deletion
            accumulate = doPreCleanup(accumulate);
            accumulate = doAbort(accumulate);
            accumulate = doPostCleanup(accumulate);
            return accumulate;
        }

        // if we are committed or aborted, then we are done; otherwise abort
        public final void close()
        {
            switch (state)
            {
                case COMMITTED:
                case ABORTED:
                    break;
                default:
                    abort();
            }
        }

        /**
         * The first phase of commit: delegates to doPrepare(), with valid state transition enforcement.
         * This call should be propagated onto any child objects participating in the transaction
         */
        public final void prepareToCommit()
        {
            if (permitRedundantTransitions && state == State.READY_TO_COMMIT)
                return;
            if (state != State.IN_PROGRESS)
                throw new IllegalStateException("Cannot prepare to commit unless IN_PROGRESS; state is " + state);

            doPrepare();
            maybeFail(doPreCleanup(null));
            state = State.READY_TO_COMMIT;
        }

        /**
         * convenience method to both prepareToCommit() and commit() in one operation;
         * only of use to outer-most transactional object of an object graph
         */
        public Object finish()
        {
            prepareToCommit();
            commit();
            return this;
        }

        // convenience method wrapping abort, and throwing any exception encountered
        // only of use to (and to be used by) outer-most object in a transactional graph
        public final void abort()
        {
            maybeFail(abort(null));
        }

        // convenience method wrapping commit, and throwing any exception encountered
        // only of use to (and to be used by) outer-most object in a transactional graph
        public final void commit()
        {
            maybeFail(commit(null));
        }

        public final State state()
        {
            return state;
        }

        protected void permitRedundantTransitions()
        {
            permitRedundantTransitions = true;
        }
    }

    // commit should generally never throw an exception, and preferably never generate one,
    // but if it does generate one it should accumulate it in the parameter and return the result
    // IF a commit implementation has a real correctness affecting exception that cannot be moved to
    // prepareToCommit, it MUST be executed before any other commit methods in the object graph
    Throwable commit(Throwable accumulate);

    // release any resources, then rollback all state changes (unless commit() has already been invoked)
    Throwable abort(Throwable accumulate);

    void prepareToCommit();

    // close() does not throw
    public void close();
}