001/*
002 * Copyright 2002-2020 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
019import org.springframework.lang.Nullable;
020
021/**
022 * This is the central interface in Spring's imperative transaction infrastructure.
023 * Applications can use this directly, but it is not primarily meant as an API:
024 * Typically, applications will work with either TransactionTemplate or
025 * declarative transaction demarcation through AOP.
026 *
027 * <p>For implementors, it is recommended to derive from the provided
028 * {@link org.springframework.transaction.support.AbstractPlatformTransactionManager}
029 * class, which pre-implements the defined propagation behavior and takes care
030 * of transaction synchronization handling. Subclasses have to implement
031 * template methods for specific states of the underlying transaction,
032 * for example: begin, suspend, resume, commit.
033 *
034 * <p>The default implementations of this strategy interface are
035 * {@link org.springframework.transaction.jta.JtaTransactionManager} and
036 * {@link org.springframework.jdbc.datasource.DataSourceTransactionManager},
037 * which can serve as an implementation guide for other transaction strategies.
038 *
039 * @author Rod Johnson
040 * @author Juergen Hoeller
041 * @since 16.05.2003
042 * @see org.springframework.transaction.support.TransactionTemplate
043 * @see org.springframework.transaction.interceptor.TransactionInterceptor
044 * @see org.springframework.transaction.ReactiveTransactionManager
045 */
046public interface PlatformTransactionManager extends TransactionManager {
047
048        /**
049         * Return a currently active transaction or create a new one, according to
050         * the specified propagation behavior.
051         * <p>Note that parameters like isolation level or timeout will only be applied
052         * to new transactions, and thus be ignored when participating in active ones.
053         * <p>Furthermore, not all transaction definition settings will be supported
054         * by every transaction manager: A proper transaction manager implementation
055         * should throw an exception when unsupported settings are encountered.
056         * <p>An exception to the above rule is the read-only flag, which should be
057         * ignored if no explicit read-only mode is supported. Essentially, the
058         * read-only flag is just a hint for potential optimization.
059         * @param definition the TransactionDefinition instance (can be {@code null} for defaults),
060         * describing propagation behavior, isolation level, timeout etc.
061         * @return transaction status object representing the new or current transaction
062         * @throws TransactionException in case of lookup, creation, or system errors
063         * @throws IllegalTransactionStateException if the given transaction definition
064         * cannot be executed (for example, if a currently active transaction is in
065         * conflict with the specified propagation behavior)
066         * @see TransactionDefinition#getPropagationBehavior
067         * @see TransactionDefinition#getIsolationLevel
068         * @see TransactionDefinition#getTimeout
069         * @see TransactionDefinition#isReadOnly
070         */
071        TransactionStatus getTransaction(@Nullable TransactionDefinition definition)
072                        throws TransactionException;
073
074        /**
075         * Commit the given transaction, with regard to its status. If the transaction
076         * has been marked rollback-only programmatically, perform a rollback.
077         * <p>If the transaction wasn't a new one, omit the commit for proper
078         * participation in the surrounding transaction. If a previous transaction
079         * has been suspended to be able to create a new one, resume the previous
080         * transaction after committing the new one.
081         * <p>Note that when the commit call completes, no matter if normally or
082         * throwing an exception, the transaction must be fully completed and
083         * cleaned up. No rollback call should be expected in such a case.
084         * <p>If this method throws an exception other than a TransactionException,
085         * then some before-commit error caused the commit attempt to fail. For
086         * example, an O/R Mapping tool might have tried to flush changes to the
087         * database right before commit, with the resulting DataAccessException
088         * causing the transaction to fail. The original exception will be
089         * propagated to the caller of this commit method in such a case.
090         * @param status object returned by the {@code getTransaction} method
091         * @throws UnexpectedRollbackException in case of an unexpected rollback
092         * that the transaction coordinator initiated
093         * @throws HeuristicCompletionException in case of a transaction failure
094         * caused by a heuristic decision on the side of the transaction coordinator
095         * @throws TransactionSystemException in case of commit or system errors
096         * (typically caused by fundamental resource failures)
097         * @throws IllegalTransactionStateException if the given transaction
098         * is already completed (that is, committed or rolled back)
099         * @see TransactionStatus#setRollbackOnly
100         */
101        void commit(TransactionStatus status) throws TransactionException;
102
103        /**
104         * Perform a rollback of the given transaction.
105         * <p>If the transaction wasn't a new one, just set it rollback-only for proper
106         * participation in the surrounding transaction. If a previous transaction
107         * has been suspended to be able to create a new one, resume the previous
108         * transaction after rolling back the new one.
109         * <p><b>Do not call rollback on a transaction if commit threw an exception.</b>
110         * The transaction will already have been completed and cleaned up when commit
111         * returns, even in case of a commit exception. Consequently, a rollback call
112         * after commit failure will lead to an IllegalTransactionStateException.
113         * @param status object returned by the {@code getTransaction} method
114         * @throws TransactionSystemException in case of rollback or system errors
115         * (typically caused by fundamental resource failures)
116         * @throws IllegalTransactionStateException if the given transaction
117         * is already completed (that is, committed or rolled back)
118         */
119        void rollback(TransactionStatus status) throws TransactionException;
120
121}