[jboss-cvs] JBossAS SVN: r104343 - projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/server/lock.

[jboss-cvs-commits at lists.jboss.org]

Author: bstansberry at jboss.com
Date: 2010-04-29 17:11:34 -0400 (Thu, 29 Apr 2010)
New Revision: 104343

Modified:
   projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/server/lock/LocalAndClusterLockManager.java
Log:
Javadoc

Modified: projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/server/lock/LocalAndClusterLockManager.java
===================================================================
--- projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/server/lock/LocalAndClusterLockManager.java	2010-04-29 21:03:56 UTC (rev 104342)
+++ projects/cluster/ha-server-api/trunk/src/main/java/org/jboss/ha/framework/server/lock/LocalAndClusterLockManager.java	2010-04-29 21:11:34 UTC (rev 104343)
@@ -34,6 +34,17 @@
 import org.jboss.ha.framework.interfaces.HAPartition;
 
 /**
+ * Distributed lock manager that supports a single, exclusive cluster wide lock
+ * or concurrent locally-exclusive locks on the various cluster nodes. A request
+ * to acquire a local lock will block while the cluster-wide lock is held or while
+ * another thread holds the local lock, and a request to acquire the cluster-wide 
+ * lock will block while the local lock is held on any node.
+ * <p>
+ * Users should not attempt to acquire the cluster-wide lock while holding
+ * a local lock or vice versa; failure to respect this requirement may
+ * lead to deadlocks.
+ * </p>
+ * 
  * @author Brian Stansberry
  * 
  * @version $Revision:$
@@ -151,6 +162,18 @@
    
    // ----------------------------------------------------------------- Public
    
+   /**
+    * Acquires a local lock, blocking if another thread is holding it or
+    * if the global, cluster-wide lock is held.
+    * 
+    * @param lockName unique name identifying the lock to acquire
+    * @param timeout max number of ms to wait to acquire the lock before failing
+    *                with a TimeoutException
+    * 
+    * @throws TimeoutException if the lock cannot be acquired before
+    *                          <code>timeout</code> ms have elapsed
+    * @throws InterruptedException if the thread is interrupted
+    */
    public void lockLocally(Serializable lockName, long timeout)
          throws TimeoutException, InterruptedException
    {
@@ -162,6 +185,11 @@
       doLock(lockName, this.localNode, timeout);
    }
    
+   /**
+    * Releases a previously acquired local lock.
+    * 
+    * @param lockName unique name identifying the lock to release
+    */
    public void unlockLocally(Serializable lockName)
    {
       if (this.localNode == null)
@@ -172,22 +200,51 @@
       doUnlock(lockName, this.localNode);   
    }
    
+   /**
+    * Acquires a globally exclusive cluster-wide lock, blocking if another 
+    * thread is holding it locally, another node is holding it, or
+    * if the local lock is held on any node in the cluster.
+    * 
+    * @param lockName unique name identifying the lock to acquire
+    * @param timeout max number of ms to wait to acquire the lock before failing
+    *                with a TimeoutException
+    * 
+    * @throws TimeoutException if the lock cannot be acquired before
+    *                          <code>timeout</code> ms have elapsed
+    * @throws InterruptedException if the thread is interrupted
+    */
    public void lockGlobally(Serializable lockName, long timeout)
          throws TimeoutException, InterruptedException
    {
       this.clusterSupport.lock(lockName, timeout);
    }
    
+   /**
+    * Releases a previously acquired local lock.
+    * 
+    * @param lockName unique name identifying the lock to release
+    */
    public void unlockGlobally(Serializable lockName)
    {
       this.clusterSupport.unlock(lockName);
    }
    
+   /**
+    * Brings this object to a state where it is ready for normal operation.
+    * 
+    * @throws Exception
+    */
    public void start() throws Exception
    {
       this.clusterSupport.start();
    }
    
+   /**
+    * Removes this object from a state where it is ready for normal oepration
+    * and performs cleanup work.
+    * 
+    * @throws Exception
+    */
    public void stop() throws Exception
    {
       this.clusterSupport.stop();