KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > transaction > TransactionManager


1 /*
2  * The contents of this file are subject to the terms
3  * of the Common Development and Distribution License
4  * (the License). You may not use this file except in
5  * compliance with the License.
6  *
7  * You can obtain a copy of the license at
8  * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9  * glassfish/bootstrap/legal/CDDLv1.0.txt.
10  * See the License for the specific language governing
11  * permissions and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL
14  * Header Notice in each file and include the License file
15  * at glassfish/bootstrap/legal/CDDLv1.0.txt.
16  * If applicable, add the following below the CDDL Header,
17  * with the fields enclosed by brackets [] replaced by
18  * you own identifying information:
19  * "Portions Copyrighted [year] [name of copyright owner]"
20  *
21  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22  */

23
24 package javax.transaction;
25
26 import java.lang.IllegalArgumentException JavaDoc;
27 import java.lang.IllegalStateException JavaDoc;
28 import java.lang.SecurityException JavaDoc;
29
30 /**
31  * The TransactionManager interface defines the methods that allow an
32  * application server to manage transaction boundaries.
33  */

34 public interface TransactionManager {
35
36     /**
37      * Create a new transaction and associate it with the current thread.
38      *
39      * @exception NotSupportedException Thrown if the thread is already
40      * associated with a transaction and the Transaction Manager
41      * implementation does not support nested transactions.
42      *
43      * @exception SystemException Thrown if the transaction manager
44      * encounters an unexpected error condition.
45      *
46      */

47     public void begin() throws NotSupportedException JavaDoc, SystemException JavaDoc;
48
49     /**
50      * Complete the transaction associated with the current thread. When this
51      * method completes, the thread is no longer associated with a transaction.
52      *
53      * @exception RollbackException Thrown to indicate that
54      * the transaction has been rolled back rather than committed.
55      *
56      * @exception HeuristicMixedException Thrown to indicate that a heuristic
57      * decision was made and that some relevant updates have been committed
58      * while others have been rolled back.
59      *
60      * @exception HeuristicRollbackException Thrown to indicate that a
61      * heuristic decision was made and that all relevant updates have been
62      * rolled back.
63      *
64      * @exception SecurityException Thrown to indicate that the thread is
65      * not allowed to commit the transaction.
66      *
67      * @exception IllegalStateException Thrown if the current thread is
68      * not associated with a transaction.
69      *
70      * @exception SystemException Thrown if the transaction manager
71      * encounters an unexpected error condition.
72      *
73      */

74     public void commit() throws RollbackException JavaDoc,
75     HeuristicMixedException JavaDoc, HeuristicRollbackException JavaDoc, SecurityException JavaDoc,
76     IllegalStateException JavaDoc, SystemException JavaDoc;
77
78     /**
79      * Obtain the status of the transaction associated with the current thread.
80      *
81      * @return The transaction status. If no transaction is associated with
82      * the current thread, this method returns the Status.NoTransaction
83      * value.
84      *
85      * @exception SystemException Thrown if the transaction manager
86      * encounters an unexpected error condition.
87      *
88      */

89     public int getStatus() throws SystemException JavaDoc;
90
91     /**
92      * Get the transaction object that represents the transaction
93      * context of the calling thread.
94      *
95      * @return the <code>Transaction</code> object representing the
96      * transaction associated with the calling thread.
97      *
98      * @exception SystemException Thrown if the transaction manager
99      * encounters an unexpected error condition.
100      *
101      */

102     public Transaction JavaDoc getTransaction() throws SystemException JavaDoc;
103
104     /**
105      * Resume the transaction context association of the calling thread
106      * with the transaction represented by the supplied Transaction object.
107      * When this method returns, the calling thread is associated with the
108      * transaction context specified.
109      *
110      * @param tobj The <code>Transaction</code> object that represents the
111      * transaction to be resumed.
112      *
113      * @exception InvalidTransactionException Thrown if the parameter
114      * transaction object contains an invalid transaction.
115      *
116      * @exception IllegalStateException Thrown if the thread is already
117      * associated with another transaction.
118      *
119      * @exception SystemException Thrown if the transaction manager
120      * encounters an unexpected error condition.
121      */

122     public void resume(Transaction JavaDoc tobj)
123             throws InvalidTransactionException JavaDoc, IllegalStateException JavaDoc,
124             SystemException JavaDoc;
125
126     /**
127      * Roll back the transaction associated with the current thread. When this
128      * method completes, the thread is no longer associated with a
129      * transaction.
130      *
131      * @exception SecurityException Thrown to indicate that the thread is
132      * not allowed to roll back the transaction.
133      *
134      * @exception IllegalStateException Thrown if the current thread is
135      * not associated with a transaction.
136      *
137      * @exception SystemException Thrown if the transaction manager
138      * encounters an unexpected error condition.
139      *
140      */

141     public void rollback() throws IllegalStateException JavaDoc, SecurityException JavaDoc,
142                             SystemException JavaDoc;
143
144     /**
145      * Modify the transaction associated with the current thread such that
146      * the only possible outcome of the transaction is to roll back the
147      * transaction.
148      *
149      * @exception IllegalStateException Thrown if the current thread is
150      * not associated with a transaction.
151      *
152      * @exception SystemException Thrown if the transaction manager
153      * encounters an unexpected error condition.
154      *
155      */

156     public void setRollbackOnly() throws IllegalStateException JavaDoc, SystemException JavaDoc;
157
158     /**
159      * Modify the timeout value that is associated with transactions started
160      * by the current thread with the begin method.
161      *
162      * <p> If an application has not called this method, the transaction
163      * service uses some default value for the transaction timeout.
164      *
165      * @param seconds The value of the timeout in seconds. If the value is zero,
166      * the transaction service restores the default value. If the value
167      * is negative a SystemException is thrown.
168      *
169      * @exception SystemException Thrown if the transaction manager
170      * encounters an unexpected error condition.
171      *
172      */

173     public void setTransactionTimeout(int seconds) throws SystemException JavaDoc;
174
175     /**
176      * Suspend the transaction currently associated with the calling
177      * thread and return a Transaction object that represents the
178      * transaction context being suspended. If the calling thread is
179      * not associated with a transaction, the method returns a null
180      * object reference. When this method returns, the calling thread
181      * is not associated with a transaction.
182      *
183      * @return Transaction object representing the suspended transaction.
184      *
185      * @exception SystemException Thrown if the transaction manager
186      * encounters an unexpected error condition.
187      *
188      */

189     public Transaction JavaDoc suspend() throws SystemException JavaDoc;
190 }
191
Popular Tags