/*
 * Copyright 2002-2014 the original author or authors.
 *
 * Licensed 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.springframework.transaction;

Interface that specifies an API to programmatically manage transaction
savepoints in a generic fashion. Extended by TransactionStatus to
expose savepoint management functionality for a specific transaction.
Note that savepoints can only work within an active transaction.
Just use this programmatic savepoint handling for advanced needs;
else, a subtransaction with PROPAGATION_NESTED is preferable.
This interface is inspired by JDBC 3.0's Savepoint mechanism
but is independent from any specific persistence technology.
Author:
Juergen Hoeller
See Also:
TransactionStatus
TransactionDefinition.PROPAGATION_NESTED
Savepoint
Since:
1.1/**
 * Interface that specifies an API to programmatically manage transaction
 * savepoints in a generic fashion. Extended by TransactionStatus to
 * expose savepoint management functionality for a specific transaction.
 *
 * <p>Note that savepoints can only work within an active transaction.
 * Just use this programmatic savepoint handling for advanced needs;
 * else, a subtransaction with PROPAGATION_NESTED is preferable.
 *
 * <p>This interface is inspired by JDBC 3.0's Savepoint mechanism
 * but is independent from any specific persistence technology.
 *
 * @author Juergen Hoeller
 * @since 1.1
 * @see TransactionStatus
 * @see TransactionDefinition#PROPAGATION_NESTED
 * @see java.sql.Savepoint
 */
public interface SavepointManager {

	
Create a new savepoint. You can roll back to a specific savepoint via rollbackToSavepoint, and explicitly release a savepoint that you don't need anymore via releaseSavepoint. 
Note that most transaction managers will automatically release
savepoints at transaction completion.
Throws:
NestedTransactionNotSupportedException – if the underlying
transaction does not support savepoints
TransactionException – if the savepoint could not be created,
for example because the transaction is not in an appropriate state
See Also:
Connection.setSavepoint
Returns:
a savepoint object, to be passed into rollbackToSavepoint or releaseSavepoint/**
	 * Create a new savepoint. You can roll back to a specific savepoint
	 * via {@code rollbackToSavepoint}, and explicitly release a savepoint
	 * that you don't need anymore via {@code releaseSavepoint}.
	 * <p>Note that most transaction managers will automatically release
	 * savepoints at transaction completion.
	 * @return a savepoint object, to be passed into
	 * {@link #rollbackToSavepoint} or {@link #releaseSavepoint}
	 * @throws NestedTransactionNotSupportedException if the underlying
	 * transaction does not support savepoints
	 * @throws TransactionException if the savepoint could not be created,
	 * for example because the transaction is not in an appropriate state
	 * @see java.sql.Connection#setSavepoint
	 */
	Object createSavepoint() throws TransactionException;

	
Roll back to the given savepoint.
The savepoint will not be automatically released afterwards. You may explicitly call releaseSavepoint(Object) or rely on automatic release on transaction completion. 
Params:
savepoint – the savepoint to roll back to
Throws:
NestedTransactionNotSupportedException – if the underlying
transaction does not support savepoints
TransactionException – if the rollback failed
See Also:
Connection.rollback(Savepoint)/**
	 * Roll back to the given savepoint.
	 * <p>The savepoint will <i>not</i> be automatically released afterwards.
	 * You may explicitly call {@link #releaseSavepoint(Object)} or rely on
	 * automatic release on transaction completion.
	 * @param savepoint the savepoint to roll back to
	 * @throws NestedTransactionNotSupportedException if the underlying
	 * transaction does not support savepoints
	 * @throws TransactionException if the rollback failed
	 * @see java.sql.Connection#rollback(java.sql.Savepoint)
	 */
	void rollbackToSavepoint(Object savepoint) throws TransactionException;

	
Explicitly release the given savepoint.
Note that most transaction managers will automatically release
savepoints on transaction completion.
Implementations should fail as silently as possible if proper
resource cleanup will eventually happen at transaction completion.
Params:
savepoint – the savepoint to release
Throws:
NestedTransactionNotSupportedException – if the underlying
transaction does not support savepoints
TransactionException – if the release failed
See Also:
Connection.releaseSavepoint/**
	 * Explicitly release the given savepoint.
	 * <p>Note that most transaction managers will automatically release
	 * savepoints on transaction completion.
	 * <p>Implementations should fail as silently as possible if proper
	 * resource cleanup will eventually happen at transaction completion.
	 * @param savepoint the savepoint to release
	 * @throws NestedTransactionNotSupportedException if the underlying
	 * transaction does not support savepoints
	 * @throws TransactionException if the release failed
	 * @see java.sql.Connection#releaseSavepoint
	 */
	void releaseSavepoint(Object savepoint) throws TransactionException;

}