com.yahoo.transaction.Transaction Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of vespajlib Show documentation

Library for use in Java components of Vespa. Shared code which do not fit anywhere else.

There is a newer version: 8.441.21

// Copyright Vespa.ai. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package com.yahoo.transaction;

import java.util.List;

/**
 * A transaction against a single system, which may include several operations against the system, 
 * to be committed as one.
 * Implementations are required to atomically apply changes
 * in the commit step or throw an exception if it fails.
 * Operations are performed in the order they are added.
 *
 * @author Ulf Lilleengen
 * @author bratseth
 */
public interface Transaction extends AutoCloseable {

    /**
     * Adds an operation to this transaction. Return self for chaining.
     *
     * @param operation {@link Operation} to append
     * @return self, for chaining
     */
    Transaction add(Operation operation);

    /**
     * Adds multiple operations to this transaction. Return self for chaining.
     *
     * @param operation {@link Operation} to append
     * @return self, for chaining
     */
    Transaction add(List operation);

    /**
     * Returns the operations of this.
     * Ownership of the returned list is transferred to the caller. The ist may be ready only.
     */
    List operations();

    /**
     * Checks whether or not the transaction is able to commit in its current state and do any transient preparatory
     * work to commit.
     *
     * @throws IllegalStateException if the transaction cannot be committed
     */
    void prepare();

    /**
     * Commit this transaction. If this method returns, all operations in this transaction was committed
     * successfully. Implementations of this must be exception safe or log a message of type severe if they partially
     * alter state.
     *
     * @throws IllegalStateException if transaction failed.
     */
    void commit();

    /**
     * This is called if the transaction should be rolled back after commit. If a rollback is not possible or
     * supported. This must log a message of type severe with detailed information about the resulting state.
     */
    void rollbackOrLog();

    /**
     * Closes and frees any resources allocated by this transaction. The transaction instance cannot be reused once
     * closed.
     */
    void close();

    /**
     * Operations that a transaction supports should implement this interface.
     * It does not define any methods because the interface to use is a contract between the
     * specific transaction and operation type used.
     */
    interface Operation { }

}