Author: ozeigermann
Date: Tue Aug 14 14:34:50 2007
New Revision: 565923
URL: http://svn.apache.org/viewvc?view=rev&rev=565923
Log:
Finished Javadocs for base package and fixed document related flaws in code.
Modified:
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/AbstractTransactionalResourceManager.java
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/DefaultTransaction.java
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/ManageableResourceManager.java
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/Transaction.java
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/TransactionException.java
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/TransactionalResourceManager.java
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/package.html
Modified:
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/AbstractTransactionalResourceManager.java
URL:
http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/AbstractTransactionalResourceManager.java?view=diff&rev=565923&r1=565922&r2=565923
==============================================================================
---
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/AbstractTransactionalResourceManager.java
(original)
+++
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/AbstractTransactionalResourceManager.java
Tue Aug 14 14:34:50 2007
@@ -22,9 +22,14 @@
import org.apache.commons.transaction.locking.LockManager;
/**
- * Not thread-safe. FIXME: Should it be?
- *
- * @author olli
+ * Abstract base class for transactional resource managers.
+ * <p>
+ * This implementation takes care of most administrative tasks a transactional
+ * resource manager has to perform. Sublcass
+ * [EMAIL PROTECTED] AbstractTransactionalResourceManager.AbstractTxContext}
to hold all
+ * information necessary for each transaction. Additionally, you have to
+ * implement [EMAIL PROTECTED] #createContext()} to create an object of that
type, and
+ * [EMAIL PROTECTED] #commitCanFail()}.
*
* @param <T>
*/
@@ -53,7 +58,7 @@
}
@Override
- public boolean isTransactionMarkedForRollback() {
+ public boolean isRollbackOnly() {
T txContext = getCheckedActiveTx();
return (txContext.isMarkedForRollback());
@@ -76,6 +81,13 @@
T txContext = getCheckedActiveTx();
txContext.rollback();
+ forgetTransaction();
+ }
+
+ @Override
+ public void forgetTransaction() {
+ T txContext = getCheckedActiveTx();
+
txContext.dispose();
setActiveTx(null);
}
@@ -90,8 +102,7 @@
}
txContext.commit();
- txContext.dispose();
- setActiveTx(null);
+ forgetTransaction();
return true;
}
@@ -113,7 +124,7 @@
activeTx.set(txContext);
}
- public boolean isReadOnlyTransaction() {
+ public boolean isReadOnly() {
T txContext = getCheckedActiveTx();
return (txContext.isReadOnly());
}
@@ -165,9 +176,9 @@
public void rollback() {
}
-
+
public boolean prepare() {
- return true;
+ return isMarkedForRollback();
}
}
@@ -194,7 +205,7 @@
public abstract boolean commitCanFail();
@Override
- public void joinTransaction(LockManager lm) {
+ public void joinTransaction(LockManager<Object, Object> lm) {
if (getActiveTx() != null) {
throw new IllegalStateException("Active thread " +
Thread.currentThread()
+ " already associated with a transaction!");
@@ -207,17 +218,10 @@
}
@Override
- public void setRollbackOnly() {
- T txContext = getCheckedActiveTx();
- txContext.markForRollback();
-
- }
-
- @Override
public boolean prepareTransaction() {
T txContext = getCheckedActiveTx();
return txContext.prepare();
}
-}
+}
\ No newline at end of file
Modified:
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/DefaultTransaction.java
URL:
http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/DefaultTransaction.java?view=diff&rev=565923&r1=565922&r2=565923
==============================================================================
---
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/DefaultTransaction.java
(original)
+++
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/DefaultTransaction.java
Tue Aug 14 14:34:50 2007
@@ -23,85 +23,124 @@
import org.apache.commons.transaction.locking.LockManager;
/**
- * A managed transaction meant as interface to the user. Meant to operate on
- * more than one resource manager. This is a light weight replacement for a
- * complex 2PC xa transaction.
+ * Default implementation for the [EMAIL PROTECTED] Transaction} interface.
Needs a common
+ * lock manager shared by all resource managers to make detection of
distributed
+ * deadlocks possible.
*
- * @author olli
+ * <p>
+ * Sample usage:
*
+ * <pre><tt>
+ * LockManager<Object, Object> lm = new RWLockManager<Object,
Object>();
+ * Transaction t = new DefaultTransaction(lm);
+ * TxMap<String, Object> txMap1 = new PessimisticTxMap<String,
Object>("TxMap1");
+ * t.enlistResourceManager(txMap1);
+ * TxMap<String, Object> txMap2 = new PessimisticTxMap<String,
Object>("TxMap2");
+ * t.enlistResourceManager(txMap2);
*
+ * try {
+ * t.start(60, TimeUnit.SECONDS);
+ * txMap1.put("Olli", "Huhu");
+ * txMap2.put("Olli", "Haha");
+ * t.commit();
+ * } catch (Throwable throwable) {
+ * t.rollback();
+ * }
+ * </tt></pre>
+ *
+ * <p>
+ * This implementation is <em>thread-safe</em>.
*/
public class DefaultTransaction implements Transaction {
- protected LockManager lm;
+ protected LockManager<Object, Object> lm;
+
+ protected boolean started = false;
protected List<ManageableResourceManager> rms;
- public DefaultTransaction(LockManager lm) {
+ /**
+ * Creates a new transaction implementation.
+ *
+ * @param lm the lock manager shared by all resource managers
+ */
+ public DefaultTransaction(LockManager<Object, Object> lm) {
this.lm = lm;
this.rms = new LinkedList<ManageableResourceManager>();
}
- public void commit() throws TransactionException {
- lm.endWork();
- if (isRollbackOnly()) {
- throw new
TransactionException(TransactionException.Code.ROLLBACK_ONLY);
- }
- if (!prepare()) {
- throw new
TransactionException(TransactionException.Code.PREPARE_FAILED);
- }
+ public synchronized void commit() throws TransactionException {
+ try {
+ lm.endWork();
+ if (isRollbackOnly()) {
+ throw new
TransactionException(TransactionException.Code.ROLLBACK_ONLY);
+ }
+ if (!prepare()) {
+ throw new
TransactionException(TransactionException.Code.PREPARE_FAILED);
+ }
- for (ManageableResourceManager manager : rms) {
- if (!manager.isReadOnlyTransaction()) {
- try {
- if (!manager.commitTransaction()) {
- throw new
TransactionException(TransactionException.Code.COMMIT_FAILED);
+ for (ManageableResourceManager manager : rms) {
+ if (!manager.isReadOnly()) {
+ try {
+ if (!manager.commitTransaction()) {
+ throw new
TransactionException(TransactionException.Code.COMMIT_FAILED);
+ }
+ } catch (Exception e) {
+ throw new TransactionException(e,
TransactionException.Code.COMMIT_FAILED);
+ } catch (Error e) {
+ // XXX is this really a good idea?
+ rollback();
+ throw e;
}
- } catch (Exception e) {
- throw new TransactionException(e,
TransactionException.Code.COMMIT_FAILED);
- } catch (Error e) {
- // XXX is this really a good idea?
- rollback();
- throw e;
}
}
+ } finally {
+ started = false;
}
}
- public void enlistResourceManager(ManageableResourceManager
resourceManager) {
+ public synchronized void enlistResourceManager(ManageableResourceManager
resourceManager) {
// if the manager might fail upon commit, tried it as early as possible
if (resourceManager.commitCanFail()) {
rms.add(0, resourceManager);
} else {
rms.add(resourceManager);
}
+ if (started) {
+ resourceManager.joinTransaction(lm);
+ }
}
- public boolean isRollbackOnly() {
+ public synchronized boolean isRollbackOnly() {
for (ManageableResourceManager manager : rms) {
- if (manager.isTransactionMarkedForRollback())
+ if (manager.isRollbackOnly())
return true;
}
return false;
}
- public void rollback() {
- lm.endWork();
- for (ManageableResourceManager manager : rms) {
- if (!manager.isReadOnlyTransaction()) {
- manager.rollbackTransaction();
+ public synchronized void rollback() {
+ try {
+ lm.endWork();
+ for (ManageableResourceManager manager : rms) {
+ if (!manager.isReadOnly()) {
+ manager.rollbackTransaction();
+ }
}
+ } finally {
+ started = false;
}
}
- public void start(long timeout, TimeUnit unit) {
+ public synchronized void start(long timeout, TimeUnit unit) {
+ started = true;
for (ManageableResourceManager manager : rms) {
manager.joinTransaction(lm);
}
lm.startWork(timeout, unit);
}
- protected boolean prepare() {
+ protected synchronized boolean prepare() {
for (ManageableResourceManager manager : rms) {
if (!manager.prepareTransaction())
return false;
Modified:
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/ManageableResourceManager.java
URL:
http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/ManageableResourceManager.java?view=diff&rev=565923&r1=565922&r2=565923
==============================================================================
---
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/ManageableResourceManager.java
(original)
+++
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/ManageableResourceManager.java
Tue Aug 14 14:34:50 2007
@@ -18,29 +18,67 @@
import org.apache.commons.transaction.locking.LockManager;
+/**
+ * Needs to be implemented by all resource managers that want to take part in a
+ * [EMAIL PROTECTED] Transaction combined transaction}. This interface is not
meant for
+ * user interaction.
+ *
+ */
public interface ManageableResourceManager extends
TransactionalResourceManager {
- void setRollbackOnly();
- boolean commitCanFail();
-
+ /**
+ * Checks whether this resource manager is willing and able to commit its
+ * part of the complex transaction.
+ *
+ * @return <code>true</code> if this resource manager can commit its part
+ * of the transaction
+ */
boolean prepareTransaction();
/**
- * Checks whether this transaction has been marked to allow a rollback as
- * the only valid outcome. This can be set my method
- * [EMAIL PROTECTED] #markTransactionForRollback()} or might be set
internally be any
- * fatal error. Once a transaction is marked for rollback there is no way
to
- * undo this. A transaction that is marked for rollback can not be
- * committed, also rolled back.
+ * Instructs the resource manager to forget about the current transaction.
*
- * @return <code>true</code> if this transaction has been marked for a
- * roll back
- * @see #markTransactionForRollback()
*/
- public boolean isTransactionMarkedForRollback();
+ void forgetTransaction();
- public boolean isReadOnlyTransaction();
+ /**
+ * Lets this resource manager join a transaction that is protected by a
+ * common lock manager. An implementation is required to perform all
locking
+ * operations on the given lock manager as long as it takes part in the
+ * complex transaction.
+ *
+ * @param lm
+ * the common lock maanger
+ */
+ void joinTransaction(LockManager<Object, Object> lm);
+
+ /**
+ * Checks whether this resource manager allows a rollback as the only valid
+ * outcome. Once a transaction is marked for rollback there is no way to
+ * undo this. A transaction that is marked for rollback can not be
+ * committed.
+ *
+ * @return <code>true</code> if this resource manager can only roll back
+ */
+ boolean isRollbackOnly();
- public void joinTransaction(LockManager<Object, Object> lm);
+ /**
+ * Checks if there had been any write operations on this resource manager
+ * since the start of the transaction. If not the transaction is not
+ * required to call either
+ * [EMAIL PROTECTED] TransactionalResourceManager#commitTransaction()} or
+ * [EMAIL PROTECTED] TransactionalResourceManager#rollbackTransaction()},
but only
+ * [EMAIL PROTECTED] #forgetTransaction()}.
+ *
+ * @return <code>true</code> if there had been read operations only
+ */
+ boolean isReadOnly();
+ /**
+ * Checks whether a tried commit could possibly fail because of logical
+ * reasons.
+ *
+ * @return <code>true</code> if a commit could fail
+ */
+ boolean commitCanFail();
}
Modified:
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/Transaction.java
URL:
http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/Transaction.java?view=diff&rev=565923&r1=565922&r2=565923
==============================================================================
---
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/Transaction.java
(original)
+++
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/Transaction.java
Tue Aug 14 14:34:50 2007
@@ -19,22 +19,62 @@
import java.util.concurrent.TimeUnit;
/**
- * A managed transaction meant as interface to the user. Meant to operate on
more than one resource manager.
- * This is a light weight replacement for a complex 2PC xa transaction.
+ * A managed transaction meant as interface to the user.
+ * <p>Should be used to
+ * combine multiple resource managers into a complex transaction. Once a
+ * resource manager has joined such a complex transaction all transactional
+ * control is performed by this transaction. Do not call transactional methods
+ * on the resource managers directly.
*
- * @author olli
- *
+ * <p>This is a light weight replacement for a complex 2PC xa transaction.
*
+ * @see DefaultTransaction
*/
public interface Transaction {
- public void start(long timeout, TimeUnit unit);
+ /**
+ * Starts a new transactions having a specific timeout. You can
+ * [EMAIL PROTECTED] #enlistResourceManager(ManageableResourceManager) add
resource managers}
+ * before start or afterwards.
+ *
+ * @param timeout
+ * the maximum time this transaction can run before it times out
+ * @param unit
+ * the time unit of the [EMAIL PROTECTED] timeout} argument
+ */
+ void start(long timeout, TimeUnit unit);
+ /**
+ * Checks whether this transaction allows a rollback as the only valid
+ * outcome. Once a transaction is marked for rollback there is no way to
+ * undo this. A transaction that is marked for rollback can not be
+ * committed.
+ *
+ * @return <code>true</code> if this transaction can only rolled back
+ */
boolean isRollbackOnly();
- public void rollback();
+ /**
+ * Rolls back the complex transaction meaning that all changes made to
+ * participating resource managers are undone.
+ */
+ void rollback();
- public void commit();
+ /**
+ * Commits the complex transaction meaning that all changes made to
+ * participating resource managers are made permanent.
+ */
+ void commit();
+ /**
+ * Adds a resource manager to this complex transaction. This means the
+ * resource manager will from now on be controlled by this transaction.
+ * Access to transactional methods is not allowed until the complex
+ * transaction has finished. Of course, it is legal to call the other
+ * methods if this manager to perform some real work.
+ *
+ * @param resourceManager
+ * the resource manager to add
+ */
void enlistResourceManager(ManageableResourceManager resourceManager);
}
Modified:
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/TransactionException.java
URL:
http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/TransactionException.java?view=diff&rev=565923&r1=565922&r2=565923
==============================================================================
---
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/TransactionException.java
(original)
+++
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/TransactionException.java
Tue Aug 14 14:34:50 2007
@@ -16,6 +16,10 @@
*/
package org.apache.commons.transaction;
+/**
+ * General exception for all kinds of transactional problems.
+ *
+ */
public class TransactionException extends RuntimeException {
/**
Modified:
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/TransactionalResourceManager.java
URL:
http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/TransactionalResourceManager.java?view=diff&rev=565923&r1=565922&r2=565923
==============================================================================
---
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/TransactionalResourceManager.java
(original)
+++
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/TransactionalResourceManager.java
Tue Aug 14 14:34:50 2007
@@ -20,14 +20,14 @@
/**
- * Interface for something that makes up a transactional resource manager.
+ * Interface for something that makes up a transactional resource manager.
Used for user control.
* Comparable to an XA resource.
*
*/
public interface TransactionalResourceManager {
/**
* Starts a new transaction and associates it with the current thread. All
- * subsequent changes in the same thread made to the map are invisible from
+ * subsequent changes in the same thread made to the resource manager are
invisible from
* other threads until [EMAIL PROTECTED] #commitTransaction()} is called.
Use
* [EMAIL PROTECTED] #rollbackTransaction()} to discard your changes.
After calling
* either method there will be no transaction associated to the current
@@ -39,7 +39,7 @@
* @see #commitTransaction()
* @see #rollbackTransaction()
*/
- public void startTransaction(long timeout, TimeUnit unit);
+ void startTransaction(long timeout, TimeUnit unit);
/**
* Discards all changes made in the current transaction and deletes the
@@ -48,7 +48,7 @@
* @see #startTransaction(long, TimeUnit)
* @see #commitTransaction()
*/
- public void rollbackTransaction();
+ void rollbackTransaction();
/**
* Commits all changes made in the current transaction and deletes the
@@ -57,5 +57,5 @@
* @see #startTransaction(long, TimeUnit)
* @see #rollbackTransaction()
*/
- public boolean commitTransaction();
+ boolean commitTransaction();
}
Modified:
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/package.html
URL:
http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/package.html?view=diff&rev=565923&r1=565922&r2=565923
==============================================================================
---
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/package.html
(original)
+++
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/package.html
Tue Aug 14 14:34:50 2007
@@ -2,30 +2,16 @@
<body>
<h1>Apache Commons Transaction</h1>
<p>Making concurrent programming transactional.
-</p>
-<p>When you <a
-href="../apidocs/org/apache/commons/transaction/file/FileResourceManager.html#startTransaction(java.lang.Object)">start</a>
-a transaction you need to provide an indentifier to later refer to
-this newly started transaction. You can also let an identifier be <a
-href="../apidocs/org/apache/commons/transaction/file/FileResourceManager.html#generatedUniqueTxId()">generated</a>
-for you. Calls to e.g. <a
-href="../apidocs/org/apache/commons/transaction/file/FileResourceManager.html#readResource(java.lang.Object,%20java.lang.Object)">read</a>,
-<a
-href="../apidocs/org/apache/commons/transaction/file/FileResourceManager.html#createResource(java.lang.Object,%20java.lang.Object)">create</a>
-or <a
-href="../apidocs/org/apache/commons/transaction/file/FileResourceManager.html#writeResource(java.lang.Object,%20java.lang.Object)">write
-to</a> will need the identifier to know which transaction they belong to.</p>
+<p>This package contains the most important interfaces of the whole component.
+If you want to add transaction control to your resource managers you will have
to implement the
+<a href="TransactionalResourceManager.html">transactional resource manager
interface</a>. It is recommended that you start your work by inheriting from
+the <a href="AbstractTransactionalResourceManager.html">abstract transactional
resource manager</a>.
-<p>Finally when you want to
-commit the transaction call <a
-href="../apidocs/org/apache/commons/transaction/file/FileResourceManager.html#commitTransaction(java.lang.Object)">commit</a>
-or <a
-href="../apidocs/org/apache/commons/transaction/file/FileResourceManager.html#rollbackTransaction(java.lang.Object)">rollback</a>
-to undo all changes. The transactionality is achieved by first writing to
-temporary files and upon commit moving or copying them to the primary
-location. Locks and a delicate commit mechanism will assure that no
-data corruption occurs.
-</p>
+<p>The user is supposed to control transactionality using the methods of this
interface.
+<p>In case you want more than one transactional resource manager to take part
in a single transaction use the
+<a href="Transaction.html">transaction interface</a> along with its <a
href="DefaultTransaction.html">default implementation</a>.
+Resource managers that want to participate need to be <a
href="ManageableResourceManager.html">manageable resource managers</a>. This
interface
+is not supposed to be called by the user, but is used by the complex
transaction.
</body>
</html>
