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}