io.evitadb.api.TransactionContract Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of evita_api Show documentation
Module contains external API of the evitaDB.
The newest version!
/*
 *
 *                         _ _        ____  ____
 *               _____   _(_) |_ __ _|  _ \| __ )
 *              / _ \ \ / / | __/ _` | | | |  _ \
 *             |  __/\ V /| | || (_| | |_| | |_) |
 *              \___| \_/ |_|\__\__,_|____/|____/
 *
 *   Copyright (c) 2023-2024
 *
 *   Licensed under the Business Source License, Version 1.1 (the "License");
 *   you may not use this file except in compliance with the License.
 *   You may obtain a copy of the License at
 *
 *   https://github.com/FgForrest/evitaDB/blob/master/LICENSE
 *
 *   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.evitadb.api;

import javax.annotation.Nonnull;
import java.util.UUID;

/**
 * Transaction represents internal object that allows to track all information necessary to keep writes in isolation
 * and finally commits them to the shared data storage or throw them away in case of rollback.
 *
 * Transaction is created by creating instance of this class (i.e. constructor), transaction is closed by calling
 * {@link #close()} method and it either commits or rollbacks the changes (when {@link #setRollbackOnly()} is called.
 *
 * This concept is pretty much known from relational databases.
 *
 * @author Jan Novotný ([email protected]), FG Forrest a.s. (c) 2021
 */
public interface TransactionContract extends AutoCloseable {

	/**
	 * Returns unique id of the transaction. This id serves only to identify the transaction among other transaction
	 * and doesn't relate to MVVC mechanism of the database.
	 */
	@Nonnull
	UUID getTransactionId();

	/**
	 * Marks this transaction for rollback only. Ie. when transaction terminates, all changes will be rolled back.
	 */
	void setRollbackOnly();

	/**
	 * Returns TRUE if {@link #setRollbackOnly()} was called anytime in this transaction.
	 */
	boolean isRollbackOnly();

	/**
	 * Closes the transaction and frees related resources.
	 * If {@link #setRollbackOnly()} the changes made in session are committed, otherwise they're rolled back.
	 */
	@Override
	void close();

	/**
	 * Returns TRUE if {@link #close()} was called anytime in this transaction.
	 */
	boolean isClosed();

	/**
	 * Enum representing the different behaviors a transaction can have when committing changes.
	 */
	enum CommitBehavior {

		/**
		 * Changes performed in the transaction are passed to evitaDB server, checked for conflicts and if no conflict
		 * is found the transaction is marked as completed and commit is finished. This behaviour is fastest, but does
		 * not guarantee that the changes are persisted on disk and durable. If the server crashes before the changes
		 * are written to disk, the changes are lost.
		 */
		WAIT_FOR_CONFLICT_RESOLUTION,

		/**
		 * Changes performed in the transaction are passed to evitaDB server, checked for conflicts and if no conflict
		 * is found, they are written to Write Ahead Log (WAL) and transaction waits until the WAL is persisted on disk
		 * (fsynced). After that the transaction is marked as completed and commit is finished. This behaviour is
		 * slower than {@link #WAIT_FOR_CONFLICT_RESOLUTION} but guarantees that the changes are persisted on disk and durable. The server
		 * may decide to fsync changes from multiple transaction at once, so the transaction may wait longer than
		 * necessary. This behaviour still does not guarantee that the changes will be visible immediately after
		 * the commit - because they still need to be propagated to indexes in order new data can be found by queries.
		 */
		WAIT_FOR_WAL_PERSISTENCE,

		/**
		 * Changes performed in the transaction are passed to evitaDB server, checked for conflicts and if no conflict
		 * is found, they are written to Write Ahead Log (WAL). Then the WAL is processed and all changes are propagated
		 * to indexes. After that the transaction is marked as completed and commit is finished. This behaviour is
		 * slowest but guarantees that the changes are persisted on disk and durable and that they are visible
		 * immediately after the commit is marked as completed.
		 *
		 * This behaviour is default.
		 */
		WAIT_FOR_INDEX_PROPAGATION;

		/**
		 * Returns default commit behaviour.
		 * @return default commit behaviour
		 */
		public static CommitBehavior defaultBehaviour() {
			return WAIT_FOR_INDEX_PROPAGATION;
		}

	}

}