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

5 files changed, 94 insertions, 13 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);
   }
 };
diff --git a/java/src/test/java/org/pablotron/luigi/tests/CacheTest.java b/java/src/test/java/org/pablotron/luigi/tests/CacheTest.java
index 9aff8fc..f0e2ab5 100644
--- a/java/src/test/java/org/pablotron/luigi/tests/CacheTest.java
+++ b/java/src/test/java/org/pablotron/luigi/tests/CacheTest.java
@@ -1,3 +1,5 @@
+package org.pablotron.luigi.tests;
+
 import java.util.Map;
 import java.util.HashMap;
 
@@ -40,4 +42,15 @@ public final class CacheTest {
     final Cache cache = new Cache(TEST_TEMPLATES, TEST_FILTERS);
     assertEquals("foo-custom-foo-filter-foo", cache.run("foo-custom", TEST_ARGS));
   }
+
+  @Test
+  public void testCacheGetWithResultHandler() throws LuigiError {
+    final Cache cache = new Cache(TEST_TEMPLATES);
+    final StringBuilder sb = new StringBuilder();
+    final TestResultHandler rh = new TestResultHandler(sb);
+    cache.run("foo", TEST_ARGS, rh);
+
+    assertEquals("foofoofoo", sb.toString());
+  }
+
 };
diff --git a/java/src/test/java/org/pablotron/luigi/tests/TemplateTest.java b/java/src/test/java/org/pablotron/luigi/tests/TemplateTest.java
index f4960cc..83a137d 100644
--- a/java/src/test/java/org/pablotron/luigi/tests/TemplateTest.java
+++ b/java/src/test/java/org/pablotron/luigi/tests/TemplateTest.java
@@ -1,3 +1,5 @@
+package org.pablotron.luigi.tests;
+
 import java.util.Map;
 import java.util.HashMap;
 
@@ -41,17 +43,6 @@ public final class TemplateTest {
     assertEquals("foofoo", r);
   }
 
-  private static final class TestResultHandler implements ResultHandler {
-    private final StringBuilder sb;
-    public TestResultHandler(final StringBuilder sb) {
-      this.sb = sb;
-    }
-
-    public void append(final String s) {
-      sb.append(s);
-    }
-  };
-
   @Test
   public void testResultHandler() throws LuigiError {
     final Template t = new Template("foo%{bar}");
diff --git a/java/src/test/java/org/pablotron/luigi/tests/TestResultHandler.java b/java/src/test/java/org/pablotron/luigi/tests/TestResultHandler.java
new file mode 100644
index 0000000..a847e79
--- /dev/null
+++ b/java/src/test/java/org/pablotron/luigi/tests/TestResultHandler.java
@@ -0,0 +1,15 @@
+package org.pablotron.luigi.tests;
+
+import org.pablotron.luigi.ResultHandler;
+
+public final class TestResultHandler implements ResultHandler {
+  private final StringBuilder sb;
+
+  public TestResultHandler(final StringBuilder sb) {
+    this.sb = sb;
+  }
+
+  public void append(final String s) {
+    sb.append(s);
+  }
+};