001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.transaction;
023:
024: /**
025: * The TransactionManager interface defines the methods that allow an
026: * application server to manage transactions on behalf of the applications.
027: * <p>
028: * User applications should not use this interface directly, but use
029: * {@link UserTransaction} insted if they need to do their own transaction
030: * management.
031: * <p>
032: * Internally, the transaction manager associates transactions with threads,
033: * and the methods here operate on the transaction associated with the
034: * calling thread.
035: *
036: * @version $Revision: 57196 $
037: */
038: public interface TransactionManager {
039: /**
040: * Starts a new transaction, and associate it with the calling thread.
041: *
042: * @throws NotSupportedException If the calling thread is already
043: * associated with a transaction, and nested transactions are
044: * not supported.
045: * @throws SystemException If the transaction service fails in an
046: * unexpected way.
047: */
048: public void begin() throws NotSupportedException, SystemException;
049:
050: /**
051: * Commit the transaction associated with the calling thread.
052: *
053: * @throws RollbackException If the transaction was marked for rollback
054: * only, the transaction is rolled back and this exception is
055: * thrown.
056: * @throws IllegalStateException If the calling thread is not associated
057: * with a transaction.
058: * @throws SystemException If the transaction service fails in an
059: * unexpected way.
060: * @throws HeuristicMixedException If a heuristic decision was made and
061: * some some parts of the transaction have been committed while
062: * other parts have been rolled back.
063: * @throws HeuristicRollbackException If a heuristic decision to roll
064: * back the transaction was made.
065: * @throws SecurityException If the caller is not allowed to commit this
066: * transaction.
067: */
068: public void commit() throws RollbackException,
069: HeuristicMixedException, HeuristicRollbackException,
070: SecurityException, IllegalStateException, SystemException;
071:
072: /**
073: * Rolls back the transaction associated with the calling thread.
074: *
075: * @throws IllegalStateException If the transaction is in a state
076: * where it cannot be rolled back. This could be because the
077: * calling thread is not associated with a transaction, or
078: * because it is in the
079: * {@link Status#STATUS_PREPARED prepared state}.
080: * @throws SecurityException If the caller is not allowed to roll back
081: * this transaction.
082: * @throws SystemException If the transaction service fails in an
083: * unexpected way.
084: */
085: public void rollback() throws IllegalStateException,
086: SecurityException, SystemException;
087:
088: /**
089: * Mark the transaction associated with the calling thread for rollback
090: * only.
091: *
092: * @throws IllegalStateException If the transaction is in a state
093: * where it cannot be rolled back. This could be because the
094: * calling thread is not associated with a transaction, or
095: * because it is in the
096: * {@link Status#STATUS_PREPARED prepared state}.
097: * @throws SystemException If the transaction service fails in an
098: * unexpected way.
099: */
100: public void setRollbackOnly() throws IllegalStateException,
101: SystemException;
102:
103: /**
104: * Get the status of the transaction associated with the calling thread.
105: *
106: * @return The status of the transaction. This is one of the
107: * {@link Status} constants. If no transaction is associated
108: * with the calling thread,
109: * {@link Status#STATUS_NO_TRANSACTION} is returned.
110: *
111: * @throws SystemException If the transaction service fails in an
112: * unexpected way.
113: */
114: public int getStatus() throws SystemException;
115:
116: /**
117: * Get the transaction associated with the calling thread.
118: *
119: * @return The transaction associated with the calling thread, or
120: * <code>null</code> if the calling thread is not associated
121: * with a transaction.
122: *
123: * @throws SystemException If the transaction service fails in an
124: * unexpected way.
125: */
126: public Transaction getTransaction() throws SystemException;
127:
128: /**
129: * Change the transaction timeout for transactions started by the calling
130: * thread with the {@link #begin()} method.
131: *
132: * @param seconds The new timeout value, in seconds. If this parameter
133: * is <code>0</code>, the timeout value is reset to the default
134: * value.
135: *
136: * @throws SystemException If the transaction service fails in an
137: * unexpected way.
138: */
139: public void setTransactionTimeout(int seconds)
140: throws SystemException;
141:
142: /**
143: * Suspend the association the calling thread has to a transaction,
144: * and return the suspended transaction.
145: * When returning from this method, the calling thread is no longer
146: * associated with a transaction.
147: *
148: * @return The transaction that the calling thread was associated with,
149: * or <code>null</code> if the calling thread was not associated
150: * with a transaction.
151: *
152: * @throws SystemException If the transaction service fails in an
153: * unexpected way.
154: */
155: public Transaction suspend() throws SystemException;
156:
157: /**
158: * Resume the association of the calling thread with the given
159: * transaction.
160: *
161: * @param tobj The transaction to be associated with the calling thread.
162: *
163: * @throws InvalidTransactionException If the argument does not represent
164: * a valid transaction.
165: * @throws IllegalStateException If the calling thread is already
166: * associated with a transaction.
167: * @throws SystemException If the transaction service fails in an
168: * unexpected way.
169: */
170: public void resume(Transaction tobj)
171: throws InvalidTransactionException, IllegalStateException,
172: SystemException;
173: }
|