[jboss-svn-commits] JBL Code SVN: r35313 - in labs/jbosstm/trunk/XTS/demo: src/com/jboss/jbosstm/xts/demo/services/recovery and 4 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Mon Sep 27 12:07:12 EDT 2010
Author: adinn
Date: 2010-09-27 12:07:11 -0400 (Mon, 27 Sep 2010)
New Revision: 35313
Modified:
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/recovery/DemoATRecoveryModule.java
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/recovery/DemoBARecoveryModule.java
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantConstants.java
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantParticipantAT.java
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantParticipantBA.java
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantServiceBA.java
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantState.java
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/state/ServiceState.java
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/state/ServiceStateManager.java
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/taxi/TaxiManager.java
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/taxi/TaxiParticipantBA.java
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreConstants.java
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreManager.java
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreParticipantAT.java
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreParticipantBA.java
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreServiceBA.java
labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreState.java
labs/jbosstm/trunk/XTS/demo/xts-build.xml
Log:
updated some of the javadoc -- fixes for JBTM-790
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/recovery/DemoATRecoveryModule.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/recovery/DemoATRecoveryModule.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/recovery/DemoATRecoveryModule.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -67,7 +67,7 @@
* @param id the id used when the participant was created
* @param stream a stream from which the application should deserialise the participant
* if it recognises that the id belongs to the module's application
- * @return
+ * @return a recovered durable participant if the id belongs to this application otherwise null
* @throws Exception if an error occurs deserializing the durable participant
*/
public Durable2PCParticipant deserialize(String id, ObjectInputStream stream) throws Exception
@@ -103,9 +103,8 @@
* @param id the id used when the participant was created
* @param recoveryState a byte array returned form the original participant via a call to
* method getRecoveryState of interface PersistableATParticipant
- * @return
- * @throws Exception if an error occurs converting the recoveryState back to a
- * durable participant
+ * @return null as the demo application does not use this recovery method
+ * @throws Exception if the id belongs to this application
*/
public Durable2PCParticipant recreate(String id, byte[] recoveryState) throws Exception {
if (id.startsWith("org.jboss.jbossts.xts-demo:restauarantAT") ||
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/recovery/DemoBARecoveryModule.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/recovery/DemoBARecoveryModule.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/recovery/DemoBARecoveryModule.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -68,7 +68,8 @@
* @param id the id used when the participant was created
* @param stream a stream from which the application should deserialise the participant
* if it recognises that the id belongs to the module's application
- * @return the deserialized ParticipantCompletion participant
+ * @return the deserialized ParticipantCompletion participant if the id identifies a restaurant
+ * participant otherwise null
* @throws Exception if an error occurs deserializing the ParticipantCompletion participant
*/
public BusinessAgreementWithParticipantCompletionParticipant deserializeParticipantCompletionParticipant(String id, ObjectInputStream stream) throws Exception
@@ -100,9 +101,8 @@
* @param id the id used when the participant was created
* @param recoveryState a byte array returned form the original participant via a call to
* method getRecoveryState of interface PersistableBAParticipant
- * @return the recreated ParticipantCompletion participant
- * @throws Exception if an error occurs converting the recoveryState back to a
- * ParticipantCompletion participant
+ * @return null as the demo application does not use this recovery method
+ * @throws Exception if the id belongs to this application
*/
public BusinessAgreementWithParticipantCompletionParticipant recreateParticipantCompletionParticipant(String id, byte[] recoveryState) throws Exception
{
@@ -125,7 +125,8 @@
* @param id the id used when the participant was created
* @param stream a stream from which the application should deserialise the participant
* if it recognises that the id belongs to the module's application
- * @return the deserialized ParticipantCompletion participant
+ * @return the deserialized ParticipantCompletion participant if the id identifies a theatre
+ * or taxi participant otherwise null
* @throws Exception if an error occurs deserializing the CoordinatorCompletion participant
*/
public BusinessAgreementWithCoordinatorCompletionParticipant deserializeCoordinatorCompletionParticipant(String id, ObjectInputStream stream) throws Exception {
@@ -161,9 +162,8 @@
* @param id the id used when the participant was created
* @param recoveryState a byte array returned form the original participant via a call to
* method getRecoveryState of interface PersistableBAParticipant
- * @return the recreated ParticipantCompletion participant
- * @throws Exception if an error occurs converting the recoveryState back to a
- * CoordinatorCompletion participant
+ * @return null as the demo application does not use this recovery method
+ * @throws Exception if the id belongs to this application
*/
public BusinessAgreementWithCoordinatorCompletionParticipant recreateCoordinatorCompletionParticipant(String id, byte[] recoveryState) throws Exception {
if (id.startsWith("org.jboss.jbossts.xts-demo:restauarantBA") ||
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantConstants.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantConstants.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantConstants.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -10,8 +10,14 @@
*/
public static final int DEFAULT_SEATING_CAPACITY = 100;
+ /**
+ * the name of the file used to persist the current restaurant state
+ */
public final static String STATE_FILENAME = "restaurantManagerState";
+ /**
+ * the name of the file used to persist the shadow restaurant state
+ */
public final static String SHADOW_STATE_FILENAME = "restaurantManagerShadowState";
}
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantParticipantAT.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantParticipantAT.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantParticipantAT.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -35,8 +35,7 @@
import java.util.HashMap;
/**
- * An adapter class that exposes the RestaurantManager transaction lifecycle
- * API as a WS-T Atomic Transaction participant.
+ * An adapter class that exposes the RestaurantManager as a WS-T Atomic Transaction participant.
* Also logs events to a RestaurantView object.
*
* @author Jonathan Halliday (jonathan.halliday at arjuna.com)
@@ -181,8 +180,8 @@
/************************************************************************/
/**
* keep track of a participant
- * @param txID
- * @param participant
+ * @param txID the participant's transaction id
+ * @param participant the participant
*/
public static synchronized void recordParticipant(String txID, RestaurantParticipantAT participant)
{
@@ -191,8 +190,7 @@
/**
* forget about a participant
- * @param txID
- * @param participant
+ * @param txID the participant's transaction id
*/
public static synchronized RestaurantParticipantAT removeParticipant(String txID)
{
@@ -201,8 +199,8 @@
/**
* lookup a participant
- * @param txID
- * @return the participant
+ * @param txID the participant's transaction id
+ * @param participant the participant
*/
public static synchronized RestaurantParticipantAT getParticipant(String txID)
{
@@ -220,7 +218,7 @@
/**
* check if a participant is invalid
*
- * @return
+ * @return true if the participant is still valid otherwise false
*/
public boolean isValid()
{
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantParticipantBA.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantParticipantBA.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantParticipantBA.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -36,9 +36,8 @@
import java.util.HashMap;
/**
- * An adapter class that exposes the RestaurantManager transaction lifecycle
- * API as a WS-T Participant Completion Business Activity participant.
- * Also logs events to a RestaurantView object.
+ * An adapter class that exposes the RestaurantManager as a WS-T Participant Completion
+ * Business Activity participant. Also logs events to a RestaurantView object.
*
* The Restaurant Service only allows a single booking in any given transaction. So, this
* means it can complete at the end of the booking call. Hence it uses a participant which
@@ -224,8 +223,8 @@
/************************************************************************/
/**
* keep track of a participant
- * @param txID
- * @param participant
+ * @param txID the participant's transaction id
+ * @param participant the participant
*/
public static synchronized void recordParticipant(String txID, RestaurantParticipantBA participant)
{
@@ -234,8 +233,7 @@
/**
* forget about a participant
- * @param txID
- * @param participant
+ * @param txID the participant's transaction id
*/
public static synchronized RestaurantParticipantBA removeParticipant(String txID)
{
@@ -244,8 +242,8 @@
/**
* lookup a participant
- * @param txID
- * @return the participant
+ * @param txID the participant's transaction id
+ * @param participant the participant
*/
public static synchronized RestaurantParticipantBA getParticipant(String txID)
{
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantServiceBA.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantServiceBA.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantServiceBA.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -43,14 +43,6 @@
* An adapter class that exposes the RestaurantManager business API as a
* transactional Web Service. Also logs events to a RestaurantView object.
*
- * The BA Restaurant Service only allows the client to make one booking in any given transaction.
- * So, this means that it can complete its changes as soon as the booking has been made. Hence
- * it uses a participant which implements the participant completion protocol. When the client
- * closes the activity the coordinator will ensure that the participant has completed then
- * it only has to send a CLOSE message. This means that if the client cancels the activity after
- * booking the restaurant then the coordinator cannot just CANCEL the participant. It will have to
- * send a COMPENSATE message in order to make sure that the committed booking is undone.
- *
* @author Jonathan Halliday (jonathan.halliday at arjuna.com)
* @version $Revision: 1.5 $
*/
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantState.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantState.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/restaurant/RestaurantState.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -14,7 +14,7 @@
/**
* create a new initial restaurant state
- * @return
+ * @return an initial restaurant state containing no booked seats
*/
public static RestaurantState initialState()
{
@@ -23,7 +23,8 @@
/**
* derive a child restaurant state from this state
- * @return
+ * @return a derived restaurant state containing the same data as this state
+ * but having a version id one greater
*/
public RestaurantState derivedState()
{
@@ -46,8 +47,6 @@
}
/**
* create a new initial restaurant state
- *
- * @param totalSeats
*/
private RestaurantState()
{
@@ -58,11 +57,10 @@
}
/**
- * create a derived restaurant state with a given number of bookings and a specific version
+ * create a restaurant state derived from a parent state
*
- * @param totalSeats
- * @param bookedSeats
- * @param version
+ * @param parent the parent state whose data should be copied into this state
+ * and whose version should be incremented by 1 and then installed in this state.
*/
private RestaurantState(RestaurantState parent)
{
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/state/ServiceState.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/state/ServiceState.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/state/ServiceState.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -23,18 +23,18 @@
}
/**
- * construct a new state from an existing state bumping up the version number by one
- * @param parent
+ * construct a new state derived from this state bumping up the version number by one
+ * @param parent the state from which the new state is to be derived
*/
public ServiceState(ServiceState parent) {
this.version = parent.version + 1;
}
/**
- * test whether the child state was immediately derived from this state by checking the version numbers
+ * test whether the child state was derived from this state by checking the version numbers
*
* @param child the child state to be tested
- * @return true if the child state was immediately derived from this state otherwise false
+ * @return true if the child state was derived from this state otherwise false
*/
public boolean isParentOf(ServiceState child)
{
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/state/ServiceStateManager.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/state/ServiceStateManager.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/state/ServiceStateManager.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -113,7 +113,7 @@
* lock the current state so the specified transaction can begin prepare. this method must only be
* called when synchronized on the method call recipient and when the current lock id is null. also,
* the derived state associated with the prepared transaction id must be a child of the current state.
- * @param txId the id of the transaction which will become the locking transaction.
+ * @param preparedTxID the id of the transaction which will become the locking transaction.
*/
protected void lock(Object preparedTxID)
{
@@ -146,11 +146,12 @@
/**
* persist the prepared state for a transaction including the transaction id and the derived state
- * containing the modified booking information blah blah blah. this is normally only called by {@link #prepare}.
+ * containing the modified booking information. this is normally only called by {@link #prepare}.
* however it is also exposed to subclasses so they can install the initial current state or reset
* the current state to the default settings.
- * @param txId
- * @param childState
+ * @param txId the id of the transaction which created the child state
+ * @param childState a derived state storing any new state values written by
+ * the transaction.
* @throws java.io.IOException
*/
protected void writeShadowState(Object txId, T childState) throws IOException
@@ -176,8 +177,7 @@
* {@link #rollback}. however it is also exposed to subclasses so they can deal wiht any
* errors which happen when they try to install the initial current state or reset
* the current state to the default settings.
- * @param txId
- * @param childState
+ * @param txId the id of the transaction which persisted the shadow state
* @throws java.io.IOException
*/
protected void clearShadowState(Object txId)
@@ -193,6 +193,7 @@
* install the persisted prepared state as the persisted current state. this is normally
* only called by {@link #commit}. however it is also exposed to subclasses so they can install
* the initial current state or reset the current state to the default settings.
+ * @param txId the id of the transaction which persisted the shadow state
*/
protected void commitShadowState(Object txId)
{
@@ -315,8 +316,8 @@
/**
* called by the AT and BA recovery modules to notify the manager that a participant associated with
* a specific AT or BA transaction has been recovered from a participant log record.
- * @param txID
- * @param txType
+ * @param txID the id of the recovered transaction
+ * @param txType identifies whether the recovered transaction is an AT or a BA transaction
* @return true if there is prepared local state for this transaction which needs to be committed or
* rolled back otherwise false
*/
@@ -359,7 +360,7 @@
* more AT or BA participant recovery records to process. this allows the manager to automatically
* roll back local prepared state if it is not needed for subsequent recovery
*
- * @param txType
+ * @param txType identifies whether the completed scan was for AT or BA transactions
*/
public void recoveryScanCompleted(int txType)
{
@@ -440,7 +441,7 @@
/**
* commit local state changes for the supplied transaction
*
- * @param txID
+ * @param txID The transaction identifier
*/
public void commit(Object txID)
{
@@ -460,7 +461,8 @@
/**
* roll back local state changes for the supplied transaction
- * @param txID
+
+ * @param txID The transaction identifier
*/
public void rollback(Object txID)
{
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/taxi/TaxiManager.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/taxi/TaxiManager.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/taxi/TaxiManager.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -35,10 +35,12 @@
/**
* The application logic for the Taxi Service
* <p/>
- * Manages taxi reservations. Knows nothing about Web Services.
- * <p/>
- * Taxis are an unlimited resource so this manager does not maintain any
- * persistent state.
+ * Manages taxi reservations, providing prepare, commit and rollback calls for
+ * modifying taxi bookings in memory. Taxis are an unlimited resource and it does
+ * not really matter if a taxi does not turn up (there's always another one round the
+ * corner) nor does it matter of the clients don't appear (someone else will take
+ * the ride). so this manager does not maintain any persistent state and any bookings
+ * made are not resilient to crashes.
*
* @author Jonathan Halliday (jonathan.halliday at arjuna.com)
* @version $Revision: 1.3 $
@@ -148,8 +150,8 @@
}
/**
- * method called during prepare of local state changes allowing the user to force a prepare failue
- * @return true if the prepare shoudl succeed and false if it should fail
+ * method called during prepare of local state changes allowing the user to force a prepare failure
+ * @return true if the prepare should succeed and false if it should fail
*/
public boolean confirmPrepare()
{
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/taxi/TaxiParticipantBA.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/taxi/TaxiParticipantBA.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/taxi/TaxiParticipantBA.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -243,7 +243,7 @@
/************************************************************************/
/**
* keep track of a participant
- * @param txID
+ * @param txID the participant's transaction id
* @param participant
*/
public static synchronized void recordParticipant(String txID, TaxiParticipantBA participant, com.arjuna.wst11.BAParticipantManager manager)
@@ -254,8 +254,7 @@
/**
* forget about a participant
- * @param txID
- * @param participant
+ * @param txID the participant's transaction id
*/
public static synchronized TaxiParticipantBA removeParticipant(String txID)
{
@@ -265,7 +264,7 @@
/**
* lookup a participant
- * @param txID
+ * @param txID the participant's transaction id
* @return the participant
*/
public static synchronized TaxiParticipantBA getParticipant(String txID)
@@ -275,8 +274,8 @@
/**
* lookup a participant manager
- * @param txID
- * @return the participant
+ * @param txID the participant's transaction id
+ * @return the participant's manager
*/
public static synchronized com.arjuna.wst11.BAParticipantManager getManager(String txID)
{
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreConstants.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreConstants.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreConstants.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -31,12 +31,12 @@
public static final int DEFAULT_SEATING_CAPACITY = 100;
/**
- * the name of the file used to store the restaurant manager state
+ * the name of the file used to store the current theatre manager state
*/
final static public String STATE_FILENAME = "theatreManagerState";
/**
- * the name of the file used to store the restaurant manager shadow state
+ * the name of the file used to store the shadow theatre manager state
*/
final static public String SHADOW_STATE_FILENAME = "theatreManagerShadowState";
}
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreManager.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreManager.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreManager.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -173,9 +173,6 @@
/**
* Reset to the initial state.
- *
- * @param txID The transaction identifier
- * @param nSeats The number of seats requested
*/
public synchronized void reset()
{
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreParticipantAT.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreParticipantAT.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreParticipantAT.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -35,8 +35,7 @@
import java.util.HashMap;
/**
- * An adapter class that exposes the TheatreManager transaction lifecycle
- * API as a WS-T Atomic Transaction participant.
+ * An adapter class that exposes the TheatreManager as a WS-T Atomic Transaction participant.
* Also logs events to a TheatreView object.
*
* @author Jonathan Halliday (jonathan.halliday at arjuna.com)
@@ -173,8 +172,8 @@
/************************************************************************/
/**
* keep track of a participant
- * @param txID
- * @param participant
+ * @param txID the participant's transaction identifier
+ * @param participant the participant to be recorded
*/
public static synchronized void recordParticipant(String txID, TheatreParticipantAT participant)
{
@@ -183,8 +182,8 @@
/**
* forget about a participant
- * @param txID
- * @param participant
+ * @param txID the participant's transaction identifier
+ * @return the removed participant
*/
public static synchronized TheatreParticipantAT removeParticipant(String txID)
{
@@ -193,7 +192,7 @@
/**
* lookup a participant
- * @param txID
+ * @param txID the participant's transaction identifier
* @return the participant
*/
public static synchronized TheatreParticipantAT getParticipant(String txID)
@@ -212,7 +211,7 @@
/**
* check if a participant is invalid
*
- * @return
+ * @return true if the participant is still valid otherwise false
*/
public boolean isValid()
{
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreParticipantBA.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreParticipantBA.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreParticipantBA.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -37,10 +37,17 @@
import java.util.HashMap;
/**
- * An adapter class that exposes the TheatreManager transaction lifecycle
- * API as a WS-T Coordinator Completion Business Activity participant.
- * Also logs events to a TheatreView object.
+ * An adapter class that exposes the TheatreManager as a WS-T Coordinator Completion
+ * Business Activity participant. Also logs events to a TheatreView object.
*
+ * The Theatre Service allows up to three bookings in any given transaction, one for
+ * each seating area. This means that teh service cannot decide when to complete.
+ * After the first or, possibly, second booking request the service cannot determine
+ * whether the client still wants to send another request. Hence it uses a participant
+ * which implements the coordinator completion protocol. WHen the client asks the
+ * coordinator to close the transaction the coordinator will tell the participant
+ * to complete.
+ *
* @author Jonathan Halliday (jonathan.halliday at arjuna.com)
* @version $Revision: 1.3 $
*/
@@ -56,12 +63,13 @@
* Participant instances are related to business method calls
* in a one to one manner.
*
- * @param txID uniq id String for the transaction instance.
+ * @param txID uniq id String for the transaction instance.
+ * @param bookings holds counts of the seats booked in each of the three seating areas
*/
public TheatreParticipantBA(String txID, int[] bookings)
{
// we need to save the txID for later use when logging
- // and the seat count and seat area for use during compensation
+ // and the seat counts for use during compensation
this.txID = txID;
this.bookings = bookings;
}
@@ -78,13 +86,9 @@
/* BusinessAgreementWithCoordinatorCompletionParticipant methods */
/************************************************************************/
/**
- * The transaction has completed successfully. The participant previously
- * informed the coordinator that it was ready to complete.
- *
- * @throws WrongStateException never in this implementation.
- * @throws SystemException never in this implementation.
+ * The coordinator is informing the participant that all work it needs to
+ * do within the scope of this business activity has been received.
*/
-
public void complete() throws WrongStateException, SystemException
{
BAParticipantManager participantManager = managers.get(txID);
@@ -116,6 +120,10 @@
}
}
+ /**
+ * The transaction has completed successfully. The participant previously
+ * informed the coordinator that it was ready to complete.
+ */
public void close() throws WrongStateException, SystemException
{
// nothing to do here as the seats are already booked
@@ -130,14 +138,10 @@
}
/**
- * The transaction has cancelled, and the participant should undo any work.
- * The participant cannot have informed the coordinator that it has
- * completed.
- *
- * @throws WrongStateException never in this implementation.
- * @throws SystemException never in this implementation.
+ * The transaction has cancelled. The participant previously
+ * informed the coordinator that it had finished work but could compensate
+ * later if required, so it is now requested to do so.
*/
-
public void cancel() throws WrongStateException, SystemException
{
// let the manager know that this activity has been cancelled
@@ -157,9 +161,6 @@
* The transaction has cancelled. The participant previously
* informed the coordinator that it had finished work but could compensate
* later if required, so it is now requested to do so.
- *
- * @throws WrongStateException never in this implementation.
- * @throws SystemException if unable to perform the compensating transaction.
*/
public void compensate() throws FaultedException, WrongStateException, SystemException
@@ -204,10 +205,14 @@
public void unknown() throws SystemException
{
-
removeParticipant(txID);
}
+ /**
+ * If the participant enquired as to the status of the transaction it was
+ * registered with and an unrecoverable error occurs then this operation will be
+ * invoked.
+ */
public void error() throws SystemException
{
System.out.println("TheatreParticipantBA.error");
@@ -238,7 +243,6 @@
* @param confirmed true if the log record has been written and changes should be rolled forward and false
* if it has not been written and changes should be rolled back
*/
-
public void confirmCompleted(boolean confirmed) {
if (confirmed) {
getTheatreManager().commit(txID);
@@ -255,9 +259,10 @@
/* tracking active participants */
/************************************************************************/
/**
- * keep track of a participant
- * @param txID
- * @param participant
+ * keep track of a participant and its participant manager
+ * @param txID the participant's transaction identifier
+ * @param participant the participant to be recorded
+ * @param manager the participant manager to be recorded
*/
public static synchronized void recordParticipant(String txID, TheatreParticipantBA participant, BAParticipantManager manager)
{
@@ -266,9 +271,9 @@
}
/**
- * forget about a participant
- * @param txID
- * @param participant
+ * forget about a participant and its participant manager
+ * @param txID the participant's transaction identifier
+ * @return the removed participant
*/
public static synchronized TheatreParticipantBA removeParticipant(String txID)
{
@@ -278,7 +283,7 @@
/**
* lookup a participant
- * @param txID
+ * @param txID the participant's transaction identifier
* @return the participant
*/
public static synchronized TheatreParticipantBA getParticipant(String txID)
@@ -288,8 +293,8 @@
/**
* lookup a participant manager
- * @param txID
- * @return the participant
+ * @param txID the participant's transaction identifier
+ * @return the participant's manager
*/
public static synchronized BAParticipantManager getManager(String txID)
{
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreServiceBA.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreServiceBA.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreServiceBA.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -44,15 +44,6 @@
* An adapter class that exposes the TheatreManager business API as a
* transactional Web Service. Also logs events to a TheatreView object.
*
- * The BA Theatre Service allows the client to make up to three bookings in any given transaction,
- * one for each seating area. So, this means that it cannot know when the client has finished
- * making service requests. Hence it uses a participant which implements the coordinator
- * completion protocol. When the client closes the activity the coordinator sends a COMPLETED
- * message to the BA participant before sending the CLOSE message. If the client cancels the
- * activity then the coordinator only has to send a CANCEL message. The service may still be told
- * to COMPENSATE if it successfully completes and then some other service (e.g. the Taxi service)
- * fails to complete.
- *
* @author Jonathan Halliday (jonathan.halliday at arjuna.com)
* @version $Revision: 1.5 $
*/
Modified: labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreState.java
===================================================================
--- labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreState.java 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/src/com/jboss/jbosstm/xts/demo/services/theatre/TheatreState.java 2010-09-27 16:07:11 UTC (rev 35313)
@@ -17,8 +17,7 @@
/**
* create a new initial theatre state
- * @param count
- * @return
+ * @return an initial theatre state containing no booked seats
*/
public static TheatreState initialState()
{
@@ -26,7 +25,8 @@
}
/**
* derive a child theatre state from this state
- * @return
+ * @return a derived theatre state containing the same data as this state
+ * but having a version id one greater
*/
public TheatreState derivedState()
{
@@ -61,8 +61,6 @@
}
/**
* create a new initial restaurant state
- *
- * @param totalSeats
*/
private TheatreState()
{
@@ -77,11 +75,10 @@
}
/**
- * create a restaurant state with a given number of bookings and a specific version
+ * create a theatre state derived from a parent state
*
- * @param totalSeats
- * @param bookedSeats
- * @param version
+ * @param parent the parent state whose data should be copied into this state
+ * and whose version should be incremented by 1 and then installed in this state.
*/
private TheatreState(TheatreState parent)
{
Modified: labs/jbosstm/trunk/XTS/demo/xts-build.xml
===================================================================
--- labs/jbosstm/trunk/XTS/demo/xts-build.xml 2010-09-27 14:52:01 UTC (rev 35312)
+++ labs/jbosstm/trunk/XTS/demo/xts-build.xml 2010-09-27 16:07:11 UTC (rev 35313)
@@ -323,8 +323,30 @@
</ear>
</target>
- <target name="build" depends="jboss-ear"/>
+ <target name="docs">
+ <javadoc packagenames="com.jboss.jbosstm.xts.demo.*" destdir="docs">
+ <classpath>
+ <path refid="compile.path"/>
+ </classpath>
+ <sourcefiles>
+ <fileset dir="${src.dir}" includes="**/*.java"/>
+ </sourcefiles>
+ </javadoc>
+ </target>
+ <target name="docsrpc">
+ <javadoc packagenames="com.jboss.jbosstm.xts.demo.*" destdir="docsrpc">
+ <classpath>
+ <path refid="compile.path"/>
+ </classpath>
+ <sourcefiles>
+ <fileset dir="${src.dir}" includes="**/*.java"/>
+ </sourcefiles>
+ </javadoc>
+ </target>
+
+ <target name="build" depends="jboss-ear, docs"/>
+
<target name="buildrpc" depends="jboss-earrpc"/>
<target name="deploy" depends="build, undeploy">
More information about the jboss-svn-commits
mailing list