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