LUCENE-4525: improve javadoc on ReferenceManager

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1405165 13f79535-47bb-0310-9956-ffa450edef68

lucene/core/src/java/org/apache/lucene/search/ReferenceManager.java

@@ -58,18 +58,24 @@ public abstract class ReferenceManager<G> implements Closeable {
     release(oldReference);
   }
 
-  /** Decrement reference counting on the given reference. */
+  /**
+   * Decrement reference counting on the given reference. 
+   * @throws IOException if reference decrement on the given resource failed.
+   * */
   protected abstract void decRef(G reference) throws IOException;
   
   /**
    * Refresh the given reference if needed. Returns {@code null} if no refresh
    * was needed, otherwise a new refreshed reference.
+   * @throws AlreadyClosedException if the reference manager has been {@link #close() closed}.
+   * @throws IOException if the refresh operation failed
    */
   protected abstract G refreshIfNeeded(G referenceToRefresh) throws IOException;
 
   /**
    * Try to increment reference counting on the given reference. Return true if
    * the operation was successful.
+   * @throws AlreadyClosedException if the reference manager has been {@link #close() closed}. 
    */
   protected abstract boolean tryIncRef(G reference);
 
@@ -78,6 +84,7 @@ public abstract class ReferenceManager<G> implements Closeable {
    * call to {@link #release}; it's best to do so in a finally clause, and set
    * the reference to {@code null} to prevent accidental usage after it has been
    * released.
+   * @throws AlreadyClosedException if the reference manager has been {@link #close() closed}. 
    */
   public final G acquire() {
     G ref;
@@ -88,12 +95,27 @@ public abstract class ReferenceManager<G> implements Closeable {
     } while (!tryIncRef(ref));
     return ref;
   }
-
+  
   /**
-   * Close this ReferenceManager to future {@link #acquire() acquiring}. Any
-   * references that were previously {@link #acquire() acquired} won't be
-   * affected, and they should still be {@link #release released} when they are
-   * not needed anymore.
+    * <p>
+    * Closes this ReferenceManager to prevent future {@link #acquire() acquiring}. A
+    * reference manager should be closed if the reference to the managed resource
+    * should be disposed or the application using the {@link ReferenceManager}
+    * is shutting down. The managed resource might not be released immediately,
+    * if the {@link ReferenceManager} user is holding on to a previously
+    * {@link #acquire() acquired} reference. The resource will be released once
+    * when the last reference is {@link #release(Object) released}. Those
+    * references can still be used as if the manager was still active.
+    * </p>
+    * <p>
+    * Applications should not {@link #acquire() acquire} new references from this
+    * manager once this method has been called. {@link #acquire() Acquiring} a
+    * resource on a closed {@link ReferenceManager} will throw an
+    * {@link AlreadyClosedException}.
+    * </p>
+    * 
+    * @throws IOException
+    *           if the underlying reader of the current reference could not be closed
    */
   public final synchronized void close() throws IOException {
     if (current != null) {
@@ -105,7 +127,10 @@ public abstract class ReferenceManager<G> implements Closeable {
     }
   }
 
-  /** Called after close(), so subclass can free any resources. */
+  /**
+   *  Called after close(), so subclass can free any resources.
+   *  @throws IOException if the after close operation in a sub-class throws an {@link IOException} 
+   * */
   protected void afterClose() throws IOException {
   }
 
@@ -158,6 +183,9 @@ public abstract class ReferenceManager<G> implements Closeable {
    * If this method returns true it means the calling thread either refreshed or
    * that there were no changes to refresh. If it returns false it means another
    * thread is currently refreshing.
+   * </p>
+   * @throws IOException if refreshing the resource causes an {@link IOException}
+   * @throws AlreadyClosedException if the reference manager has been {@link #close() closed}. 
    */
   public final boolean maybeRefresh() throws IOException {
     ensureOpen();
@@ -185,6 +213,8 @@ public abstract class ReferenceManager<G> implements Closeable {
    * useful if you want to guarantee that the next call to {@link #acquire()}
    * will return a refreshed instance. Otherwise, consider using the
    * non-blocking {@link #maybeRefresh()}.
+   * @throws IOException if refreshing the resource causes an {@link IOException}
+   * @throws AlreadyClosedException if the reference manager has been {@link #close() closed}. 
    */
   public final void maybeRefreshBlocking() throws IOException {
     ensureOpen();
@@ -199,14 +229,17 @@ public abstract class ReferenceManager<G> implements Closeable {
   }
 
   /** Called after swapReference has installed a new
-   *  instance. */
+   *  instance.
+   *  @throws IOException if a low level I/O exception occurs  
+   **/
   protected void afterRefresh() throws IOException {
   }
   
   /**
-   * Release the refernce previously obtained via {@link #acquire()}.
+   * Release the reference previously obtained via {@link #acquire()}.
    * <p>
    * <b>NOTE:</b> it's safe to call this after {@link #close()}.
+   * @throws IOException if the release operation on the given resource throws an {@link IOException}
    */
   public final void release(G reference) throws IOException {
     assert reference != null;