Junked unused TimeZoneRoundingBuilder; added more comments

Author: Andrew Clegg

src/main/java/com/pearson/entech/elasticsearch/search/facet/approx/date/external/TimeZoneRoundingBuilder.java renamed to junk/TimeZoneRoundingBuilder.java

@@ -62,8 +62,12 @@ public DateFacetBuilder(final String name) {
     }
 
     /**
-     * The field name to perform the histogram facet. Translates to perform the histogram facet
-     * using the provided field as both the {@link #keyField(String)} and {@link #valueField(String)}.
+     * The field name to use in order to control where the hit will "fall into" within the histogram
+     * entries -- synonym for keyField(). Essentially, using the key field numeric value, the hit
+     * will be "rounded" into the relevant bucket controlled by the interval.
+     * 
+     * @param field 
+     * @return the builder
      */
     public DateFacetBuilder field(final String field) {
         this.keyFieldName = field;
@@ -72,8 +76,11 @@ public DateFacetBuilder field(final String field) {
 
     /**
      * The field name to use in order to control where the hit will "fall into" within the histogram
-     * entries. Essentially, using the key field numeric value, the hit will be "rounded" into the relevant
-     * bucket controlled by the interval.
+     * entries -- synonym for field(). Essentially, using the key field numeric value, the hit
+     * will be "rounded" into the relevant bucket controlled by the interval.
+     * 
+     * @param keyField 
+     * @return the builder
      */
     public DateFacetBuilder keyField(final String keyField) {
         this.keyFieldName = keyField;
@@ -83,6 +90,9 @@ public DateFacetBuilder keyField(final String keyField) {
     /**
      * The field name to use as the value of the hit to compute data based on values within the interval
      * (for example, total).
+     * 
+     * @param valueField 
+     * @return the builder 
      */
     public DateFacetBuilder valueField(final String valueField) {
         this.valueFieldName = valueField;
@@ -91,25 +101,44 @@ public DateFacetBuilder valueField(final String valueField) {
 
     /**
      * The field name to count distinct values of.
+     * 
+     * @param distinctField 
+     * @return the builder 
      */
     public DateFacetBuilder distinctField(final String distinctField) {
         this.distinctFieldName = distinctField;
         return this;
     }
 
     /**
-     * The field name to slice the _output by.
+     * The field name to slice the output by.
+     * 
+     * @param sliceField 
+     * @return the builder
      */
     public DateFacetBuilder sliceField(final String sliceField) {
         this.sliceFieldName = sliceField;
         return this;
     }
 
+    /**
+     * A value script to apply -- NOT YET IMPLEMENTED.
+     * 
+     * @param valueScript
+     * @return the builder
+     */
     public DateFacetBuilder valueScript(final String valueScript) {
         this.valueScript = valueScript;
         return this;
     }
 
+    /**
+     * Arbitrary additional parameters -- currently none are used.
+     * 
+     * @param name the parameter name
+     * @param value the parameter value
+     * @return the builder
+     */
     public DateFacetBuilder param(final String name, final Object value) {
         if(params == null) {
             params = Maps.newHashMap();
@@ -119,7 +148,10 @@ public DateFacetBuilder param(final String name, final Object value) {
     }
 
     /**
-     * The language of the value script.
+     * The language of the value script -- NOT YET IMPLEMENTED.
+     * 
+     * @param lang the language
+     * @return the builder
      */
     public DateFacetBuilder lang(final String lang) {
         this.lang = lang;
@@ -129,6 +161,9 @@ public DateFacetBuilder lang(final String lang) {
     /**
      * The interval used to control the bucket "size" where each key value of a hit will fall into. Check
      * the docs for all available values.
+     * 
+     * @param interval the interval setting 
+     * @return the builder
      */
     public DateFacetBuilder interval(final String interval) {
         this.interval = interval;
@@ -137,6 +172,9 @@ public DateFacetBuilder interval(final String interval) {
 
     /**
      * Should pre zone be adjusted for large (day and above) intervals. Defaults to <tt>false</tt>.
+     * 
+     * @param preZoneAdjustLargeInterval true/false 
+     * @return the builder
      */
     public DateFacetBuilder preZoneAdjustLargeInterval(final boolean preZoneAdjustLargeInterval) {
         this.preZoneAdjustLargeInterval = preZoneAdjustLargeInterval;
@@ -149,6 +187,9 @@ public DateFacetBuilder preZoneAdjustLargeInterval(final boolean preZoneAdjustLa
      * <p/>
      * Can either be in the form of "-10:00" or
      * one of the values listed here: http://joda-time.sourceforge.net/timezones.html.
+     * 
+     * @param preZone a timezone string 
+     * @return the builder
      */
     public DateFacetBuilder preZone(final String preZone) {
         this.preZone = preZone;
@@ -161,6 +202,9 @@ public DateFacetBuilder preZone(final String preZone) {
      * <p/>
      * Can either be in the form of "-10:00" or
      * one of the values listed here: http://joda-time.sourceforge.net/timezones.html.
+     * 
+     * @param postZone a timezone string 
+     * @return the builder
      */
     public DateFacetBuilder postZone(final String postZone) {
         this.postZone = postZone;
@@ -169,6 +213,9 @@ public DateFacetBuilder postZone(final String postZone) {
 
     /**
      * Sets a pre offset that will be applied before rounding the results.
+     * 
+     * @param preOffset a valid time value
+     * @return the builder
      */
     public DateFacetBuilder preOffset(final TimeValue preOffset) {
         this.preOffset = preOffset.millis();
@@ -177,6 +224,9 @@ public DateFacetBuilder preOffset(final TimeValue preOffset) {
 
     /**
      * Sets a post offset that will be applied after rounding the results.
+     * 
+     * @param postOffset a valid time value
+     * @return the builder
      */
     public DateFacetBuilder postOffset(final TimeValue postOffset) {
         this.postOffset = postOffset.millis();
@@ -186,6 +236,9 @@ public DateFacetBuilder postOffset(final TimeValue postOffset) {
     /**
      * Sets the factor that will be used to multiply the value with before and divided
      * by after the rounding of the results.
+     * 
+     * @param factor the rounding factor
+     * @return the builder
      */
     public DateFacetBuilder factor(final float factor) {
         this.factor = factor;
@@ -195,6 +248,9 @@ public DateFacetBuilder factor(final float factor) {
     /**
      * How many distinct terms can we collect in each result bucket before
      * flipping over to approximate counting? (Distinct mode only)
+     * 
+     * @param threshold the threshold
+     * @return the builder
      */
     public DateFacetBuilder exactThreshold(final int threshold) {
         this.exactThreshold = threshold;
@@ -204,6 +260,9 @@ public DateFacetBuilder exactThreshold(final int threshold) {
     /**
      * Should the facet run in global mode (not bounded by the search query) or not (bounded by
      * the search query). Defaults to <tt>false</tt>.
+     * 
+     * @param global true/false
+     * @return the builder
      */
     @Override
     public DateFacetBuilder global(final boolean global) {
@@ -213,6 +272,9 @@ public DateFacetBuilder global(final boolean global) {
 
     /**
      * An additional filter used to further filter down the set of documents the facet will run on.
+     * 
+     * @param the filter to use
+     * @return the builder
      */
     @Override
     public DateFacetBuilder facetFilter(final FilterBuilder filter) {
@@ -223,6 +285,9 @@ public DateFacetBuilder facetFilter(final FilterBuilder filter) {
     /**
      * Sets the nested path the facet will execute on. A match (root object) will then cause all the
      * nested objects matching the path to be computed into the facet.
+     * 
+     * @param nested a nested path using dot notation
+     * @return the builder
      */
     @Override
     public DateFacetBuilder nested(final String nested) {

src/main/java/com/pearson/entech/elasticsearch/search/facet/approx/date/external/DateFacetBuilder.java

@@ -4,11 +4,22 @@
 
 import org.elasticsearch.common.xcontent.XContentBuilder;
 
-
+/**
+ * A slice which reports distinct values.
+ * 
+ * @param <L> the data type of the slice label
+ */
 public class DistinctSlice<L> extends Slice<L> implements HasDistinct {
 
     private final long _distinctCount;
 
+    /**
+     * Create a new DistinctSlice.
+     * 
+     * @param label the slice label to use
+     * @param count the count of values in this slice
+     * @param distinctCount the count of distinct values in this slice
+     */
     public DistinctSlice(final L label, final long count, final long distinctCount) {
         super(label, count);
         _distinctCount = distinctCount;

src/main/java/com/pearson/entech/elasticsearch/search/facet/approx/date/external/DistinctSlice.java

@@ -5,17 +5,34 @@
 import org.elasticsearch.common.xcontent.ToXContent;
 import org.elasticsearch.common.xcontent.XContentBuilder;
 
-
+/**
+ * A time period which reports distinct values.
+ * 
+ * @param <E> the data type of the time period entry
+ */
 public class DistinctTimePeriod<E extends ToXContent> extends TimePeriod<E> {
 
     private final long _distinctCount;
 
-    public DistinctTimePeriod(final long time, final long totalCount,
+    /**
+     * Create a new DistinctTimePeriod.
+     * 
+     * @param time the timestamp of this period
+     * @param count the count of values in this period
+     * @param distinctCount the count of distinct values in this period
+     * @param entry the actual facet entry for this time period
+     */
+    public DistinctTimePeriod(final long time, final long count,
             final long distinctCount, final E entry) {
-        super(time, totalCount, entry);
+        super(time, count, entry);
         _distinctCount = distinctCount;
     }
 
+    /**
+     * Get the distinct count for this time period.
+     * 
+     * @return the distinct count
+     */
     public long getDistinctCount() {
         return _distinctCount;
     }

src/main/java/com/pearson/entech/elasticsearch/search/facet/approx/date/external/DistinctTimePeriod.java

@@ -1,7 +1,15 @@
 package com.pearson.entech.elasticsearch.search.facet.approx.date.external;
 
+/**
+ * An interface for objects which report a distinct count.
+ */
 public interface HasDistinct {
 
+    /**
+     * Get the distinct count.
+     * 
+     * @return the distinct count
+     */
     long getDistinctCount();
 
 }

src/main/java/com/pearson/entech/elasticsearch/search/facet/approx/date/external/HasDistinct.java

@@ -5,8 +5,15 @@
 import org.elasticsearch.common.xcontent.ToXContent;
 import org.elasticsearch.common.xcontent.XContentBuilder;
 
+/**
+ * A placeholder for use in facets which don't have any individual entries.
+ * Follows the enum singleton pattern. Just implements a no-op toXContent() call.
+ */
 public enum NullEntry implements ToXContent {
 
+    /**
+     * The only instance of NullEntry you'll ever need.
+     */
     INSTANCE;
 
     @Override

src/main/java/com/pearson/entech/elasticsearch/search/facet/approx/date/external/NullEntry.java

@@ -5,21 +5,41 @@
 import org.elasticsearch.common.xcontent.ToXContent;
 import org.elasticsearch.common.xcontent.XContentBuilder;
 
-
+/**
+ * A slice in a sliced facet.
+ * 
+ * @param <L> the data type of the slice label
+ */
 public class Slice<L> implements ToXContent {
 
     private final L _label;
     private final long _totalCount;
 
+    /**
+     * Create a new slice.
+     * 
+     * @param label the label
+     * @param totalCount the count of values in this slice
+     */
     public Slice(final L label, final long totalCount) {
         _label = label;
         _totalCount = totalCount;
     }
 
+    /**
+     * Get the label for this slice.
+     * 
+     * @return the label
+     */
     public L getLabel() {
         return _label;
     }
 
+    /**
+     * Get the value count for this slice.
+     * 
+     * @return the count
+     */
     public long getTotalCount() {
         return _totalCount;
     }
@@ -34,8 +54,14 @@ public XContentBuilder toXContent(final XContentBuilder builder, final Params pa
         return builder;
     }
 
-    protected void injectSliceXContent(final XContentBuilder builder) throws IOException {
-        // override to add extra content in a slice object
-    }
+    /**
+     * Override this method to inject additional fields after the label and count,
+     * e.g. distinct counts. This method will be called at the appropriate time
+     * by Slice's own toXContent() method.
+     * 
+     * @param builder an XContentBuilder to use
+     * @throws IOException
+     */
+    protected void injectSliceXContent(final XContentBuilder builder) throws IOException {}
 
 }