001: /*
002: * Copyright 2002-2006 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: * http://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:
017: package 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: * AbstractPlatformTransactionManager class, which pre-implements the defined
027: * propagation behavior and completely handles transaction synchronization.
028: * Subclasses have to implement template methods for specific states of the
029: * underlying transaction, for example: begin, suspend, resume, commit.
030: *
031: * <p>The default implementations of this strategy interface are
032: * JtaTransactionManager and DataSourceTransactionManager, which can serve
033: * as implementation guide for other transaction strategies.
034: *
035: * @author Rod Johnson
036: * @author Juergen Hoeller
037: * @since 16.05.2003
038: * @see org.springframework.transaction.support.TransactionTemplate
039: * @see org.springframework.transaction.interceptor.TransactionInterceptor
040: * @see org.springframework.transaction.interceptor.TransactionProxyFactoryBean
041: * @see org.springframework.transaction.support.AbstractPlatformTransactionManager
042: * @see org.springframework.transaction.jta.JtaTransactionManager
043: * @see org.springframework.jdbc.datasource.DataSourceTransactionManager
044: */
045: public interface PlatformTransactionManager {
046:
047: /**
048: * Return a currently active transaction or create a new one, according to
049: * the specified propagation behavior.
050: * <p>Note that parameters like isolation level or timeout will only be applied
051: * to new transactions, and thus be ignored when participating in active ones.
052: * <p>Furthermore, not all transaction definition settings will be supported
053: * by every transaction manager: A proper transaction manager implementation
054: * should thrown an exception when unsupported settings are encountered.
055: * <p>An exception to the above rule is the read-only flag, which should be
056: * ignored if no explicit read-only mode is supported. Essentially, the
057: * read-only flag is just a hint for potential optimization.
058: * @param definition TransactionDefinition instance (can be <code>null</code> for defaults),
059: * describing propagation behavior, isolation level, timeout etc.
060: * @return transaction status object representing the new or current transaction
061: * @throws TransactionException in case of lookup, creation, or system errors
062: * @throws IllegalTransactionStateException if the given transaction definition
063: * cannot be executed (for example, if a currently active transaction is in
064: * conflict with the specified propagation behavior)
065: * @see TransactionDefinition#getPropagationBehavior
066: * @see TransactionDefinition#getIsolationLevel
067: * @see TransactionDefinition#getTimeout
068: * @see TransactionDefinition#isReadOnly
069: */
070: TransactionStatus getTransaction(TransactionDefinition definition)
071: throws TransactionException;
072:
073: /**
074: * Commit the given transaction, with regard to its status. If the transaction
075: * has been marked rollback-only programmatically, perform a rollback.
076: * <p>If the transaction wasn't a new one, omit the commit for proper
077: * participation in the surrounding transaction. If a previous transaction
078: * has been suspended to be able to create a new one, resume the previous
079: * transaction after committing the new one.
080: * <p>Note that when the commit call completes, no matter if normally or
081: * throwing an exception, the transaction must be fully completed and
082: * cleaned up. No rollback call should be expected in such a case.
083: * @param status object returned by the <code>getTransaction</code> method
084: * @throws TransactionException in case of commit or system errors
085: * @throws IllegalTransactionStateException if the given transaction
086: * is already completed (that is, committed or rolled back)
087: * @see TransactionStatus#setRollbackOnly
088: */
089: void commit(TransactionStatus status) throws TransactionException;
090:
091: /**
092: * Perform a rollback of the given transaction.
093: * <p>If the transaction wasn't a new one, just set it rollback-only for proper
094: * participation in the surrounding transaction. If a previous transaction
095: * has been suspended to be able to create a new one, resume the previous
096: * transaction after rolling back the new one.
097: * <p><b>Do not call rollback on a transaction if commit threw an exception.</b>
098: * The transaction will already have been completed and cleaned up when commit
099: * returns, even in case of a commit exception. Consequently, a rollback call
100: * after commit failure will lead to an IllegalTransactionStateException.
101: * @param status object returned by the <code>getTransaction</code> method
102: * @throws TransactionException in case of system errors
103: * @throws IllegalTransactionStateException if the given transaction
104: * is already completed (that is, committed or rolled back)
105: */
106: void rollback(TransactionStatus status) throws TransactionException;
107:
108: }
|