KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > transaction > PlatformTransactionManager


1 /*
2  * Copyright 2002-2006 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package org.springframework.transaction;
18
19 /**
20  * This is the central interface in Spring's transaction infrastructure.
21  * Applications can use this directly, but it is not primarily meant as API:
22  * Typically, applications will work with either TransactionTemplate or
23  * declarative transaction demarcation through AOP.
24  *
25  * <p>For implementors, it is recommended to derive from the provided
26  * AbstractPlatformTransactionManager class, which pre-implements the defined
27  * propagation behavior and completely handles transaction synchronization.
28  * Subclasses have to implement template methods for specific states of the
29  * underlying transaction, for example: begin, suspend, resume, commit.
30  *
31  * <p>The default implementations of this strategy interface are
32  * JtaTransactionManager and DataSourceTransactionManager, which can serve
33  * as implementation guide for other transaction strategies.
34  *
35  * @author Rod Johnson
36  * @author Juergen Hoeller
37  * @since 16.05.2003
38  * @see org.springframework.transaction.support.TransactionTemplate
39  * @see org.springframework.transaction.interceptor.TransactionInterceptor
40  * @see org.springframework.transaction.interceptor.TransactionProxyFactoryBean
41  * @see org.springframework.transaction.support.AbstractPlatformTransactionManager
42  * @see org.springframework.transaction.jta.JtaTransactionManager
43  * @see org.springframework.jdbc.datasource.DataSourceTransactionManager
44  */
45 public interface PlatformTransactionManager {
46
47     /**
48      * Return a currently active transaction or create a new one, according to
49      * the specified propagation behavior.
50      * <p>Note that parameters like isolation level or timeout will only be applied
51      * to new transactions, and thus be ignored when participating in active ones.
52      * <p>Furthermore, not all transaction definition settings will be supported
53      * by every transaction manager: A proper transaction manager implementation
54      * should thrown an exception when unsupported settings are encountered.
55      * <p>An exception to the above rule is the read-only flag, which should be
56      * ignored if no explicit read-only mode is supported. Essentially, the
57      * read-only flag is just a hint for potential optimization.
58      * @param definition TransactionDefinition instance (can be <code>null</code> for defaults),
59      * describing propagation behavior, isolation level, timeout etc.
60      * @return transaction status object representing the new or current transaction
61      * @throws TransactionException in case of lookup, creation, or system errors
62      * @throws IllegalTransactionStateException if the given transaction definition
63      * cannot be executed (for example, if a currently active transaction is in
64      * conflict with the specified propagation behavior)
65      * @see TransactionDefinition#getPropagationBehavior
66      * @see TransactionDefinition#getIsolationLevel
67      * @see TransactionDefinition#getTimeout
68      * @see TransactionDefinition#isReadOnly
69      */
70     TransactionStatus getTransaction(TransactionDefinition definition)
71         throws TransactionException;
72
73     /**
74      * Commit the given transaction, with regard to its status. If the transaction
75      * has been marked rollback-only programmatically, perform a rollback.
76      * <p>If the transaction wasn't a new one, omit the commit for proper
77      * participation in the surrounding transaction. If a previous transaction
78      * has been suspended to be able to create a new one, resume the previous
79      * transaction after committing the new one.
80      * <p>Note that when the commit call completes, no matter if normally or
81      * throwing an exception, the transaction must be fully completed and
82      * cleaned up. No rollback call should be expected in such a case.
83      * @param status object returned by the <code>getTransaction</code> method
84      * @throws TransactionException in case of commit or system errors
85      * @throws IllegalTransactionStateException if the given transaction
86      * is already completed (that is, committed or rolled back)
87      * @see TransactionStatus#setRollbackOnly
88      */
89     void commit(TransactionStatus status) throws TransactionException;
90
91     /**
92      * Perform a rollback of the given transaction.
93      * <p>If the transaction wasn't a new one, just set it rollback-only for proper
94      * participation in the surrounding transaction. If a previous transaction
95      * has been suspended to be able to create a new one, resume the previous
96      * transaction after rolling back the new one.
97      * <p><b>Do not call rollback on a transaction if commit threw an exception.</b>
98      * The transaction will already have been completed and cleaned up when commit
99      * 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 }
109
Popular Tags