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}