Documentation.

Author: samstokes

pom.xml

@@ -21,4 +21,15 @@
       <version>1.1</version>
     </dependency>
   </dependencies>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <version>2.8</version>
+        <configuration>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
 </project>

src/main/java/com/rapportive/storm/scheme/SimpleJSONScheme.java

@@ -13,20 +13,53 @@
 import backtype.storm.tuple.Fields;
 
 
+/**
+ * Deserialisation scheme for JSON values using the json-simple library.
+ * Emits one-element tuples with the field name <tt>object</tt>, containing
+ * the parsed JSON value.
+ *
+ * <strong>N.B.</strong> if passed invalid JSON it will throw an
+ * IllegalArgumentException.
+ *
+ * @author Sam Stokes ([email protected])
+ * @see <a href="http://code.google.com/p/json-simple/">json-simple</a>
+ */
 public class SimpleJSONScheme implements Scheme {
     private static final long serialVersionUID = -7734176307841199017L;
 
     private final String encoding;
 
 
+    /**
+     * Create a new JSON deserialisation scheme using the given character
+     * encoding.
+     *
+     * @param encoding  character encoding used to deserialise JSON from raw
+     *                  bytes
+     */
     public SimpleJSONScheme(String encoding) {
         this.encoding = encoding;
     }
+    /**
+     * Create a new JSON deserialisation scheme using UTF-8 as the character
+     * encoding.
+     */
     public SimpleJSONScheme() {
         this("UTF-8");
     }
 
 
+    /**
+     * Deserialise a JSON value from <tt>bytes</tt> using the requested
+     * character encoding.
+     *
+     * @return a one-element tuple containing the parsed JSON value.
+     *
+     * @throws IllegalArgumentException  if <tt>bytes</tt> does not contain
+     *           valid JSON encoded using the requested encoding.
+     * @throws IllegalStateException  if the requested character encoding is
+     *           not supported.
+     */
     @Override
     public List<Object> deserialize(byte[] bytes) {
         final String chars;
@@ -45,6 +78,9 @@ public List<Object> deserialize(byte[] bytes) {
     }
 
 
+    /**
+     * Emits tuples containing only one field, named "object".
+     */
     @Override
     public Fields getOutputFields() {
         return new Fields("object");

src/main/java/com/rapportive/storm/serializer/SimpleJSONSerializer.java

@@ -15,16 +15,51 @@
 
 import backtype.storm.serialization.ISerialization;
 
+/**
+ * Serialisation scheme for JSON values using the json-simple library.
+ * Assumes the deserialised form will be a UTF-8-encoded string, and serialises
+ * into that form.
+ *
+ * <strong>N.B.</strong> currently this only supports JSON objects and arrays
+ * at the top level (though nested values are fine).
+ *
+ * <strong>N.B.</strong> if passed invalid JSON it will throw an
+ * IllegalArgumentException.
+ *
+ * @author Sam Stokes ([email protected])
+ * @see <a href="http://code.google.com/p/json-simple/">json-simple</a>
+ */
 public class SimpleJSONSerializer implements ISerialization<Object> {
+    /**
+     * Encoding used to serialise and deserialise between byte streams and
+     * JSON structures.
+     *
+     * This is hard-coded to UTF-8 because the mechanism for registering a
+     * serialisation does not allow passing arguments to the serialisation
+     * constructor.
+     */
     public static final String ENCODING = "UTF-8";
 
+    /**
+     * Returns whether this serialisation can handle the given type.
+     *
+     * @return <tt>true</tt> if c is {@link org.json.simple.JSONObject} or
+     *           {@link org.json.simple.JSONArray}.
+     */
     @SuppressWarnings("rawtypes")
     @Override
     public boolean accept(Class c) {
         return JSONObject.class.equals(c) ||
           JSONArray.class.equals(c);
     }
 
+    /**
+     * Serialise a JSON object or array to the stream.
+     *
+     * @throws IllegalArgumentException  if <tt>object</tt> is not a JSON
+     *           object or array
+     * @throws IOException  if there is an error writing to the stream.
+     */
     @Override
     public void serialize(Object object, DataOutputStream stream)
             throws IOException {
@@ -39,6 +74,12 @@ public void serialize(Object object, DataOutputStream stream)
         writer.flush();
     }
 
+    /**
+     * Deserialise a JSON value from the stream.
+     *
+     * @throws IllegalArgumentException  if unable to parse a JSON value from
+     *           the stream
+     */
     @Override
     public Object deserialize(DataInputStream stream) throws IOException {
         final Reader reader = new InputStreamReader(stream, ENCODING);