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;
27 import java.lang.IllegalStateException;
28 import java.lang.SecurityException;
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, SystemException;
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,
75 HeuristicMixedException, HeuristicRollbackException, SecurityException,
76 IllegalStateException, SystemException;
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;
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 getTransaction() throws SystemException;
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 tobj)
123 throws InvalidTransactionException, IllegalStateException,
124 SystemException;
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, SecurityException,
142 SystemException;
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, SystemException;
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;
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 suspend() throws SystemException;
190 }