001/*
002 * Copyright 2002-2014 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.transaction;
018
019/**
020 * Interface that specifies an API to programmatically manage transaction
021 * savepoints in a generic fashion. Extended by TransactionStatus to
022 * expose savepoint management functionality for a specific transaction.
023 *
024 * <p>Note that savepoints can only work within an active transaction.
025 * Just use this programmatic savepoint handling for advanced needs;
026 * else, a subtransaction with PROPAGATION_NESTED is preferable.
027 *
028 * <p>This interface is inspired by JDBC 3.0's Savepoint mechanism
029 * but is independent from any specific persistence technology.
030 *
031 * @author Juergen Hoeller
032 * @since 1.1
033 * @see TransactionStatus
034 * @see TransactionDefinition#PROPAGATION_NESTED
035 * @see java.sql.Savepoint
036 */
037public interface SavepointManager {
038
039        /**
040         * Create a new savepoint. You can roll back to a specific savepoint
041         * via {@code rollbackToSavepoint}, and explicitly release a savepoint
042         * that you don't need anymore via {@code releaseSavepoint}.
043         * <p>Note that most transaction managers will automatically release
044         * savepoints at transaction completion.
045         * @return a savepoint object, to be passed into
046         * {@link #rollbackToSavepoint} or {@link #releaseSavepoint}
047         * @throws NestedTransactionNotSupportedException if the underlying
048         * transaction does not support savepoints
049         * @throws TransactionException if the savepoint could not be created,
050         * for example because the transaction is not in an appropriate state
051         * @see java.sql.Connection#setSavepoint
052         */
053        Object createSavepoint() throws TransactionException;
054
055        /**
056         * Roll back to the given savepoint.
057         * <p>The savepoint will <i>not</i> be automatically released afterwards.
058         * You may explicitly call {@link #releaseSavepoint(Object)} or rely on
059         * automatic release on transaction completion.
060         * @param savepoint the savepoint to roll back to
061         * @throws NestedTransactionNotSupportedException if the underlying
062         * transaction does not support savepoints
063         * @throws TransactionException if the rollback failed
064         * @see java.sql.Connection#rollback(java.sql.Savepoint)
065         */
066        void rollbackToSavepoint(Object savepoint) throws TransactionException;
067
068        /**
069         * Explicitly release the given savepoint.
070         * <p>Note that most transaction managers will automatically release
071         * savepoints on transaction completion.
072         * <p>Implementations should fail as silently as possible if proper
073         * resource cleanup will eventually happen at transaction completion.
074         * @param savepoint the savepoint to release
075         * @throws NestedTransactionNotSupportedException if the underlying
076         * transaction does not support savepoints
077         * @throws TransactionException if the release failed
078         * @see java.sql.Connection#releaseSavepoint
079         */
080        void releaseSavepoint(Object savepoint) throws TransactionException;
081
082}