svn commit: r765704 - /lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/impl/common/RefreshHelper.java

[srowen]

Author: srowen
Date: Thu Apr 16 17:54:47 2009
New Revision: 765704

URL: http://svn.apache.org/viewvc?rev=765704&view=rev
Log:
More javadoc

Modified:
    
lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/impl/common/RefreshHelper.java

Modified: 
lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/impl/common/RefreshHelper.java
URL: 
http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/impl/common/RefreshHelper.java?rev=765704&r1=765703&r2=765704&view=diff
==============================================================================
--- 
lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/impl/common/RefreshHelper.java
 (original)
+++ 
lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/impl/common/RefreshHelper.java
 Thu Apr 16 17:54:47 2009
@@ -28,7 +28,10 @@
 import java.util.concurrent.locks.ReentrantLock;
 
 /**
- * A helper class for implementing {...@link Refreshable}.
+ * A helper class for implementing {...@link Refreshable}. This object is 
typically included in an implementation
+ * {...@link Refreshable} to implement {...@link 
Refreshable#refresh(Collection)}. It execute the class's own supplied
+ * update logic, after updating all the object's dependencies. This also 
ensures that dependencies are not
+ * updated multiple times.
  */
 public final class RefreshHelper implements Refreshable {
 
@@ -38,12 +41,18 @@
   private final ReentrantLock refreshLock;
   private final Callable<?> refreshRunnable;
 
+  /**
+   * @param refreshRunnable encapsulates the containing object's own refresh 
logic
+   */
   public RefreshHelper(Callable<?> refreshRunnable) {
     this.dependencies = new ArrayList<Refreshable>(3);
     this.refreshLock = new ReentrantLock();
     this.refreshRunnable = refreshRunnable;
   }
 
+  /**
+   * Add a dependency to be refreshed first when the encapsulating object does.
+   */
   public void addDependency(Refreshable refreshable) {
     if (refreshable != null) {
       dependencies.add(refreshable);
@@ -56,6 +65,10 @@
     }
   }
 
+  /**
+   * Typically this is called in {...@link 
Refreshable#refresh(java.util.Collection)} and is the entire body
+   * of that method.
+   */
   @Override
   public void refresh(Collection<Refreshable> alreadyRefreshed) {
     if (!refreshLock.isLocked()) {
@@ -94,12 +107,12 @@
    * @param refreshable the {...@link Refreshable} to potentially add and 
refresh
    */
   public static void maybeRefresh(Collection<Refreshable> alreadyRefreshed, 
Refreshable refreshable) {
-    log.debug("In Maybe refresh: " + refreshable);
+    log.debug("In maybeRefresh({})", refreshable);
     if (!alreadyRefreshed.contains(refreshable)) {
       alreadyRefreshed.add(refreshable);
-      log.info("Added refreshable: " + refreshable);
+      log.info("Added refreshable: {}", refreshable);
       refreshable.refresh(alreadyRefreshed);
-      log.info("Refreshed: " + alreadyRefreshed);
+      log.info("Refreshed: {}", alreadyRefreshed);
     }
   }
 }