[jboss-remoting-commits] JBoss Remoting SVN: r4399 - remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi.

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

Author: david.lloyd at jboss.com
Date: 2008-07-18 20:16:52 -0400 (Fri, 18 Jul 2008)
New Revision: 4399

Modified:
   remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/AbstractAutoCloseable.java
Log:
Javadoc

Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/AbstractAutoCloseable.java
===================================================================
--- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/AbstractAutoCloseable.java	2008-07-19 00:04:32 UTC (rev 4398)
+++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/AbstractAutoCloseable.java	2008-07-19 00:16:52 UTC (rev 4399)
@@ -31,7 +31,8 @@
 import org.jboss.xnio.log.Logger;
 
 /**
- *
+ * A closeable implementation that supports reference counting.  Since the initial reference count is zero, implementors
+ * must be careful to ensure that the first operation invoked is a call to {@link #getHandle()}.
  */
 public abstract class AbstractAutoCloseable<T> extends AbstractCloseable<T> {
 
@@ -40,19 +41,21 @@
 
     private static final Logger log = Logger.getLogger(AbstractAutoCloseable.class);
 
+    /**
+     * Basic constructor.
+     *
+     * @param executor the executor used to execute the close notification handlers
+     */
     protected AbstractAutoCloseable(final Executor executor) {
         super(executor);
         this.executor = executor;
     }
 
-    protected void safeDec() {
-        try {
-            dec();
-        } catch (Throwable t) {
-            log.trace("Failed to decrement reference count: %s", t);
-        }
-    }
-
+    /**
+     * Decrement the reference count by one.  If the count drops to zero, the resource is closed.
+     *
+     * @throws RemotingException if the reference count dropped to zero and the close operation threw an exception
+     */
     protected void dec() throws RemotingException {
         final int v = refcount.decrementAndGet();
         if (v == 0) {
@@ -72,6 +75,11 @@
         // otherwise, the resource remains open
     }
 
+    /**
+     * Increment the reference count by one.  If the resource is closed, an exception is thrown.
+     *
+     * @throws RemotingException if the resource is closed
+     */
     protected void inc() throws RemotingException {
         final int v = refcount.getAndIncrement();
         log.trace("Adding reference to %s to %d", this, Integer.valueOf(v + 1));
@@ -82,6 +90,13 @@
         }
     }
 
+    /**
+     * Get a handle to this resource.  Increments the reference count by one.  If the resource is closed, an exception
+     * is thrown.
+     *
+     * @return the handle
+     * @throws RemotingException if the resource is closed
+     */
     public Handle<T> getHandle() throws RemotingException {
         return new HandleImpl();
     }