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: * This interface allows an application to explicitly manage transactions.
026: *
027: * @version $Revision: 57196 $
028: */
029: public interface UserTransaction {
030: /**
031: * Starts a new transaction, and associate it with the calling thread.
032: *
033: * @throws NotSupportedException If the calling thread is already
034: * associated with a transaction, and nested transactions are
035: * not supported.
036: * @throws SystemException If the transaction service fails in an
037: * unexpected way.
038: */
039: public void begin() throws NotSupportedException, SystemException;
040:
041: /**
042: * Commit the transaction associated with the calling thread.
043: *
044: * @throws RollbackException If the transaction was marked for rollback
045: * only, the transaction is rolled back and this exception is
046: * thrown.
047: * @throws IllegalStateException If the calling thread is not associated
048: * with a transaction.
049: * @throws SystemException If the transaction service fails in an
050: * unexpected way.
051: * @throws HeuristicMixedException If a heuristic decision was made and
052: * some some parts of the transaction have been committed while
053: * other parts have been rolled back.
054: * @throws HeuristicRollbackException If a heuristic decision to roll
055: * back the transaction was made.
056: * @throws SecurityException If the caller is not allowed to commit this
057: * transaction.
058: */
059: public void commit() throws RollbackException,
060: HeuristicMixedException, HeuristicRollbackException,
061: SecurityException, IllegalStateException, SystemException;
062:
063: /**
064: * Rolls back the transaction associated with the calling thread.
065: *
066: * @throws IllegalStateException If the transaction is in a state
067: * where it cannot be rolled back. This could be because the
068: * calling thread is not associated with a transaction, or
069: * because it is in the
070: * {@link Status#STATUS_PREPARED prepared state}.
071: * @throws SecurityException If the caller is not allowed to roll back
072: * this transaction.
073: * @throws SystemException If the transaction service fails in an
074: * unexpected way.
075: */
076: public void rollback() throws IllegalStateException,
077: SecurityException, SystemException;
078:
079: /**
080: * Mark the transaction associated with the calling thread for rollback
081: * only.
082: *
083: * @throws IllegalStateException If the transaction is in a state
084: * where it cannot be rolled back. This could be because the
085: * calling thread is not associated with a transaction, or
086: * because it is in the
087: * {@link Status#STATUS_PREPARED prepared state}.
088: * @throws SystemException If the transaction service fails in an
089: * unexpected way.
090: */
091: public void setRollbackOnly() throws IllegalStateException,
092: SystemException;
093:
094: /**
095: * Get the status of the transaction associated with the calling thread.
096: *
097: * @return The status of the transaction. This is one of the
098: * {@link Status} constants. If no transaction is associated
099: * with the calling thread,
100: * {@link Status#STATUS_NO_TRANSACTION} is returned.
101: *
102: * @throws SystemException If the transaction service fails in an
103: * unexpected way.
104: */
105: public int getStatus() throws SystemException;
106:
107: /**
108: * Change the transaction timeout for transactions started by the calling
109: * thread with the {@link #begin()} method.
110: *
111: * @param seconds The new timeout value, in seconds. If this parameter
112: * is <code>0</code>, the timeout value is reset to the default
113: * value.
114: *
115: * @throws SystemException If the transaction service fails in an
116: * unexpected way.
117: */
118: public void setTransactionTimeout(int seconds)
119: throws SystemException;
120: }
|