[jboss-svn-commits] JBL Code SVN: r37444 - labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Aug 30 10:46:16 EDT 2011
Author: mark.little at jboss.com
Date: 2011-08-30 10:46:16 -0400 (Tue, 30 Aug 2011)
New Revision: 37444
Modified:
labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/InvalidAnnotationException.java
labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/LockException.java
labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/PersistentContainer.java
labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/RecoverableContainer.java
labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/TransactionException.java
Log:
improved javadocs
Modified: labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/InvalidAnnotationException.java
===================================================================
--- labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/InvalidAnnotationException.java 2011-08-26 13:26:27 UTC (rev 37443)
+++ labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/InvalidAnnotationException.java 2011-08-30 14:46:16 UTC (rev 37444)
@@ -22,6 +22,13 @@
package org.jboss.stm;
+/**
+ * Typically thrown when save_state and restore_state are not present and they should be.
+ *
+ * @author marklittle
+ *
+ */
+
public class InvalidAnnotationException extends Exception
{
public InvalidAnnotationException (String reason)
Modified: labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/LockException.java
===================================================================
--- labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/LockException.java 2011-08-26 13:26:27 UTC (rev 37443)
+++ labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/LockException.java 2011-08-30 14:46:16 UTC (rev 37444)
@@ -22,6 +22,13 @@
package org.jboss.stm;
+/**
+ * Thrown when an error occurs during lock acquisition or release.
+ *
+ * @author marklittle
+ *
+ */
+
public class LockException extends RuntimeException
{
public LockException (String reason)
Modified: labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/PersistentContainer.java
===================================================================
--- labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/PersistentContainer.java 2011-08-26 13:26:27 UTC (rev 37443)
+++ labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/PersistentContainer.java 2011-08-30 14:46:16 UTC (rev 37444)
@@ -28,12 +28,12 @@
import com.arjuna.ats.arjuna.common.Uid;
/**
- * Instances of this class represent the transactional memory within which user objects
+ * Instances of this class represent the transactional memory within which persistent user objects
* can be placed and managed.
*
* Objects must implement an interface through which all transactional accesses occur. We don't
* mandate what the interface is, since that will depend upon the business logic. The interface, or
- * the implementing class, must also use the @Lockable annotation.
+ * the implementing class, must also use the @Transactional annotation.
*
* @author marklittle
*/
@@ -50,19 +50,36 @@
public class PersistentContainer<T> extends RecoverableContainer<T>
{
+ /**
+ * Create a container without a name. A name will be assigned automatically.
+ */
+
public PersistentContainer ()
{
super();
}
+ /**
+ * Create a named container.
+ *
+ * @param name the name (should be unique, but this is not enforced).
+ */
+
public PersistentContainer (final String name)
{
super(name);
}
/**
- * Return a handle through which the object should be used, rather than the one
- * passed in.
+ * Given an object we create a new transactional instance of it and return that
+ * for future use. All accesses on the returned object will be managed according to
+ * the rules defined in the various annotations. If the original object instance is used
+ * then no transactional manipulation will occur so you need to be careful!
+ *
+ * All handles are uniquely identified using Uid.
+ *
+ * @param member the instance of type T that you want to be made transactional and persistent.
+ * @return a handle into the transactional memory that the application should use to manipulate the object.
*/
public synchronized T enlist (T member)
@@ -70,6 +87,15 @@
return super.createHandle(member, ObjectType.ANDPERSISTENT);
}
+ /**
+ * Given a unique identifier, the container will either return an existing handle to the object or
+ * recreate the handle with the same state that existed at the commit of the last transaction to use it.
+ *
+ * @param member the instance of type T that you want to be made transactional and persistent.
+ * @param id the unique identifier for the instance.
+ * @return a handle into the transactional memory that the application should use to manipulate the object.
+ */
+
@SuppressWarnings(value={"unchecked"})
public synchronized T recreate (T member, Uid id)
{
@@ -99,6 +125,10 @@
return proxy;
}
+ /**
+ * Gives the name of the container.
+ */
+
public String toString ()
{
return "PersistentContainer "+name();
Modified: labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/RecoverableContainer.java
===================================================================
--- labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/RecoverableContainer.java 2011-08-26 13:26:27 UTC (rev 37443)
+++ labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/RecoverableContainer.java 2011-08-30 14:46:16 UTC (rev 37444)
@@ -35,12 +35,12 @@
import com.arjuna.ats.txoj.LockManager;
/**
- * Instances of this class represent the transactional memory within which user objects
+ * Instances of this class represent the transactional memory within which non-persistent user objects
* can be placed and managed.
*
* Objects must implement an interface through which all transactional accesses occur. We don't
* mandate what the interface is, since that will depend upon the business logic. The interface, or
- * the implementing class, must also use the @Lockable annotation.
+ * the implementing class, must also use the @Transactional annotation.
*
* @author marklittle
*/
@@ -57,16 +57,32 @@
public class RecoverableContainer<T>
{
+ /**
+ * Create a container without a name. A name will be assigned automatically.
+ */
+
public RecoverableContainer ()
{
this(new Uid().stringForm());
}
+ /**
+ * Create a named container.
+ *
+ * @param name the name (should be unique, but this is not enforced).
+ */
+
public RecoverableContainer (final String name)
{
_name = name;
}
+ /**
+ * Get the name of the container.
+ *
+ * @return the name.
+ */
+
public final String name ()
{
return _name;
@@ -77,12 +93,12 @@
* for future use. All accesses on the returned object will be managed according to
* the rules defined in the various annotations. If the original object instance is used
* then no transactional manipulation will occur so you need to be careful!
+ *
+ * All handles are uniquely identified using Uid.
+ *
+ * @param member the instance of type T that you want to be made transactional and persistent.
+ * @return a handle into the transactional memory that the application should use to manipulate the object.
*/
-
- /**
- * Return a handle through which the object should be used, rather than the one
- * passed in.
- */
public synchronized T enlist (T member)
{
@@ -123,7 +139,7 @@
return proxy;
}
- /**
+ /*
* Should the following methods all be protected/package scope, i.e., not for applications
* to view and/or call?
*/
@@ -131,8 +147,8 @@
/**
* Given a Uid, return the proxy for that instance.
*
- * @param reference
- * @return
+ * @param reference the unique identifier for the handle.
+ * @return the handle or null if not present.
*/
@SuppressWarnings("unchecked")
@@ -166,8 +182,9 @@
/**
* Given a real object, return the Uid if it exists in this container.
*
- * @param member
- * @return
+ * @param member the real object.
+ * @return the Uid for the object.
+ * @exception throws IllegalArgumentException if the real object is not within the container.
*/
@SuppressWarnings(value={"unchecked"})
@@ -193,8 +210,9 @@
/**
* Given a real object, return the Uid if it exists in this container.
*
- * @param member
- * @return
+ * @param member the real object.
+ * @return the Uid for the object if it exists in the container.
+ * @exception throws IllegalArgumentException if the instance is not within the container.
*/
@SuppressWarnings(value={"unchecked"})
@@ -212,6 +230,10 @@
}
}
+ /**
+ * Gives the name of the container.
+ */
+
public String toString ()
{
return "RecoverableContainer "+_name;
Modified: labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/TransactionException.java
===================================================================
--- labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/TransactionException.java 2011-08-26 13:26:27 UTC (rev 37443)
+++ labs/jbosstm/workspace/mlittle/STM-Arjuna/src/main/java/org/jboss/stm/TransactionException.java 2011-08-30 14:46:16 UTC (rev 37444)
@@ -22,6 +22,13 @@
package org.jboss.stm;
+/**
+ * Thrown if an error occurs during transaction processing, e.g., commit fails.
+ *
+ * @author marklittle
+ *
+ */
+
public class TransactionException extends RuntimeException
{
public TransactionException (String reason, int status)
More information about the jboss-svn-commits
mailing list