java: add javadoc for Cache, refactor TestResultHandler, add Cache#run with ResultHandler

2 files changed, 64 insertions, 2 deletions

diff --git a/java/src/main/java/org/pablotron/luigi/Cache.java b/java/src/main/java/org/pablotron/luigi/Cache.java
index 7be8f6c..b93d564 100644
--- a/java/src/main/java/org/pablotron/luigi/Cache.java
+++ b/java/src/main/java/org/pablotron/luigi/Cache.java
@@ -2,17 +2,27 @@ package org.pablotron.luigi;
 
 import java.util.Map;
 import java.util.HashMap;
+
 import org.pablotron.luigi.Filter;
 import org.pablotron.luigi.Template;
 import org.pablotron.luigi.errors.LuigiError;
 import org.pablotron.luigi.errors.UnknownTemplateError;
 import org.pablotron.luigi.actions.Action;
 
+/**
+ * Template cache.
+ */
 public final class Cache {
   private final Map<String, String> strings;
   private final Map<String, Filter.Handler> filters;
   private final Map<String, Template> templates = new HashMap<String, Template>();
 
+  /**
+   * Create a new Cache instance with the given templates and filters.
+   *
+   * @param strings Template key to template string map.
+   * @param filters Filter key to filter handler map.
+   */
   public Cache(
     final Map<String, String> strings,
     final Map<String, Filter.Handler> filters
@@ -21,10 +31,26 @@ public final class Cache {
     this.filters = filters;
   }
 
+  /**
+   * Create a new Cache instance with the given template string map and
+   * the default filter map.
+   *
+   * @param strings Template key to template string map.
+   */
   public Cache(final Map<String, String> strings) {
     this(strings, Filter.FILTERS);
   }
 
+  /**
+   * Run specified template in this cache with the given arguments and
+   * return the result as a string.
+   *
+   * @param key Template key.
+   * @param args Template arguments map.
+   *
+   * @return Result of template run.
+   * @throws UnknownTemplateError if the given template does not exist.
+   */
   public String run(
     final String key,
     final Map<String, String> args
@@ -33,10 +59,46 @@ public final class Cache {
     return get(key).run(args);
   }
 
+  /**
+   * Run specified template in this cache with the given arguments and
+   * pass the expanded chunks to the given result handler.
+   *
+   * @param key Template key.
+   * @param args Template arguments map.
+   * @param rh Result handler.
+   *
+   * @throws UnknownTemplateError if the given template does not exist.
+   */
+  public void run(
+    final String key,
+    final Map<String, String> args,
+    final ResultHandler rh
+  ) throws LuigiError {
+    // run template with args and result handler
+    get(key).run(args, rh);
+  }
+
+  /**
+   * Does the given template exist in this cache?
+   * if the given template does not exist.
+   *
+   * @param key Template key
+   *
+   * @return True if the template exists in this cache, otherwise false.
+   */
   public boolean containsKey(final String key) {
     return strings.containsKey(key);
   }
 
+  /**
+   * Get specified template from cache, or raise an UnknownTemplateError
+   * if the given template does not exist.
+   *
+   * @param key Template key
+   *
+   * @return Template instance.
+   * @throws UnknownTemplateError if the given template does not exist.
+   */
   public Template get(final String key) throws LuigiError {
     if (!templates.containsKey(key)) {
       // make sure template exists
diff --git a/java/src/main/java/org/pablotron/luigi/Template.java b/java/src/main/java/org/pablotron/luigi/Template.java
index 91c6f9f..8ce8793 100644
--- a/java/src/main/java/org/pablotron/luigi/Template.java
+++ b/java/src/main/java/org/pablotron/luigi/Template.java
@@ -76,9 +76,9 @@ public final class Template {
     final String template,
     final Map<String, String> args,
     final Map<String, Filter.Handler> filters,
-    final ResultHandler r
+    final ResultHandler rh
   ) throws LuigiError {
     final Template t = new Template(template, filters);
-    t.run(args, r);
+    t.run(args, rh);
   }
 };