Add java documentation for aggregations

Buckets:
--------

* terms
* range
* global
* filter
* filters
* missing
* nested
* reverse nested
* children
* significant terms
* date range
* ip range
* range
* histogram
* date histogram
* geo distance
* geo hash grid

Metrics:
--------

* min
* max
* sum
* avg
* stats
* extended stats
* value count
* percentiles
* percentile rank
* cardinality
* geo bounds
* top hits
* scripted metric

docs/java-api/aggregations/bucket.asciidoc

@@ -0,0 +1,33 @@
+[[java-aggregations-bucket]]
+
+include::bucket/global-aggregation.asciidoc[]
+
+include::bucket/filter-aggregation.asciidoc[]
+
+include::bucket/filters-aggregation.asciidoc[]
+
+include::bucket/missing-aggregation.asciidoc[]
+
+include::bucket/nested-aggregation.asciidoc[]
+
+include::bucket/reverse-nested-aggregation.asciidoc[]
+
+include::bucket/children-aggregation.asciidoc[]
+
+include::bucket/terms-aggregation.asciidoc[]
+
+include::bucket/significantterms-aggregation.asciidoc[]
+
+include::bucket/range-aggregation.asciidoc[]
+
+include::bucket/daterange-aggregation.asciidoc[]
+
+include::bucket/iprange-aggregation.asciidoc[]
+
+include::bucket/histogram-aggregation.asciidoc[]
+
+include::bucket/datehistogram-aggregation.asciidoc[]
+
+include::bucket/geodistance-aggregation.asciidoc[]
+
+include::bucket/geohashgrid-aggregation.asciidoc[]

docs/java-api/aggregations/bucket/children-aggregation.asciidoc

@@ -0,0 +1,37 @@
+[[java-aggs-bucket-children]]
+==== Children Aggregation
+
+Here is how you can use
+{ref}/search-aggregations-bucket-children-aggregation.html[Children Aggregation]
+with Java API.
+
+
+===== Prepare aggregation request
+
+Here is an example on how to create the aggregation request:
+
+[source,java]
+--------------------------------------------------
+AggregationBuilder aggregation =
+    AggregationBuilders
+        .children("agg")
+        .childType("reseller");
+--------------------------------------------------
+
+
+===== Use aggregation response
+
+Import Aggregation definition classes:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.aggregations.bucket.children.Children;
+--------------------------------------------------
+
+[source,java]
+--------------------------------------------------
+// sr is here your SearchResponse object
+Children agg = sr.getAggregations().get("agg");
+agg.getDocCount(); // Doc count
+--------------------------------------------------
+

docs/java-api/aggregations/bucket/datehistogram-aggregation.asciidoc

@@ -0,0 +1,69 @@
+[[java-aggs-bucket-datehistogram]]
+==== Date Histogram Aggregation
+
+Here is how you can use
+{ref}/search-aggregations-bucket-datehistogram-aggregation.html[Date Histogram Aggregation]
+with Java API.
+
+
+===== Prepare aggregation request
+
+Here is an example on how to create the aggregation request:
+
+[source,java]
+--------------------------------------------------
+AggregationBuilder aggregation =
+        AggregationBuilders
+                .dateHistogram("agg")
+                .field("dateOfBirth")
+                .interval(DateHistogram.Interval.YEAR);
+--------------------------------------------------
+
+Or if you want to set an interval of 10 days:
+
+[source,java]
+--------------------------------------------------
+AggregationBuilder aggregation =
+        AggregationBuilders
+                .dateHistogram("agg")
+                .field("dateOfBirth")
+                .interval(DateHistogram.Interval.days(10));
+--------------------------------------------------
+
+
+===== Use aggregation response
+
+Import Aggregation definition classes:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.aggregations.bucket.histogram.Histogram;
+--------------------------------------------------
+
+[source,java]
+--------------------------------------------------
+// sr is here your SearchResponse object
+DateHistogram agg = sr.getAggregations().get("agg");
+
+// For each entry
+for (DateHistogram.Bucket entry : agg.getBuckets()) {
+    String key = entry.getKey();                // Key
+    DateTime keyAsDate = entry.getKeyAsDate();  // Key as date
+    long docCount = entry.getDocCount();        // Doc count
+
+    logger.info("key [{}], date [{}], doc_count [{}]", key, keyAsDate.getYear(), docCount);
+}
+--------------------------------------------------
+
+This will basically produce for the first example:
+
+[source,text]
+--------------------------------------------------
+key [1942-01-01T00:00:00.000Z], date [1942], doc_count [1]
+key [1945-01-01T00:00:00.000Z], date [1945], doc_count [1]
+key [1946-01-01T00:00:00.000Z], date [1946], doc_count [1]
+...
+key [2005-01-01T00:00:00.000Z], date [2005], doc_count [1]
+key [2007-01-01T00:00:00.000Z], date [2007], doc_count [2]
+key [2008-01-01T00:00:00.000Z], date [2008], doc_count [3]
+--------------------------------------------------

docs/java-api/aggregations/bucket/daterange-aggregation.asciidoc

@@ -0,0 +1,59 @@
+[[java-aggs-bucket-daterange]]
+==== Date Range Aggregation
+
+Here is how you can use
+{ref}/search-aggregations-bucket-daterange-aggregation.html[Date Range Aggregation]
+with Java API.
+
+
+===== Prepare aggregation request
+
+Here is an example on how to create the aggregation request:
+
+[source,java]
+--------------------------------------------------
+AggregationBuilder aggregation =
+        AggregationBuilders
+                .dateRange("agg")
+                .field("dateOfBirth")
+                .format("yyyy")
+                .addUnboundedTo("1950")    // from -infinity to 1950 (excluded)
+                .addRange("1950", "1960")  // from 1950 to 1960 (excluded)
+                .addUnboundedFrom("1960"); // from 1960 to +infinity
+--------------------------------------------------
+
+
+===== Use aggregation response
+
+Import Aggregation definition classes:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.aggregations.bucket.range.date.DateRange;
+--------------------------------------------------
+
+[source,java]
+--------------------------------------------------
+// sr is here your SearchResponse object
+DateRange agg = sr.getAggregations().get("agg");
+
+// For each entry
+for (DateRange.Bucket entry : agg.getBuckets()) {
+    String key = entry.getKey();                    // Date range as key
+    DateTime fromAsDate = entry.getFromAsDate();    // Date bucket from as a Date
+    DateTime toAsDate = entry.getToAsDate();        // Date bucket to as a Date
+    long docCount = entry.getDocCount();            // Doc count
+
+    logger.info("key [{}], from [{}], to [{}], doc_count [{}]", key, fromAsDate, toAsDate, docCount);
+}
+--------------------------------------------------
+
+This will basically produce:
+
+[source,text]
+--------------------------------------------------
+key [*-1950], from [null], to [1950-01-01T00:00:00.000Z], doc_count [8]
+key [1950-1960], from [1950-01-01T00:00:00.000Z], to [1960-01-01T00:00:00.000Z], doc_count [5]
+key [1960-*], from [1960-01-01T00:00:00.000Z], to [null], doc_count [37]
+--------------------------------------------------
+

docs/java-api/aggregations/bucket/filter-aggregation.asciidoc

@@ -0,0 +1,36 @@
+[[java-aggs-bucket-filter]]
+==== Filter Aggregation
+
+Here is how you can use
+{ref}/search-aggregations-bucket-filter-aggregation.html[Filter Aggregation]
+with Java API.
+
+
+===== Prepare aggregation request
+
+Here is an example on how to create the aggregation request:
+
+[source,java]
+--------------------------------------------------
+AggregationBuilders
+    .filter("agg")
+    .filter(FilterBuilders.termFilter("gender", "male"));
+--------------------------------------------------
+
+
+===== Use aggregation response
+
+Import Aggregation definition classes:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.aggregations.bucket.filter.Filter;
+--------------------------------------------------
+
+[source,java]
+--------------------------------------------------
+// sr is here your SearchResponse object
+Filter agg = sr.getAggregations().get("agg");
+agg.getDocCount(); // Doc count
+--------------------------------------------------
+

docs/java-api/aggregations/bucket/filters-aggregation.asciidoc

@@ -0,0 +1,51 @@
+[[java-aggs-bucket-filters]]
+==== Filters Aggregation
+
+Here is how you can use
+{ref}/search-aggregations-bucket-filters-aggregation.html[Filters Aggregation]
+with Java API.
+
+
+===== Prepare aggregation request
+
+Here is an example on how to create the aggregation request:
+
+[source,java]
+--------------------------------------------------
+AggregationBuilder aggregation =
+    AggregationBuilders
+        .filters("agg")
+            .filter("men", FilterBuilders.termFilter("gender", "male"))
+            .filter("women", FilterBuilders.termFilter("gender", "female"));
+--------------------------------------------------
+
+
+===== Use aggregation response
+
+Import Aggregation definition classes:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.aggregations.bucket.filters.Filters;
+--------------------------------------------------
+
+[source,java]
+--------------------------------------------------
+// sr is here your SearchResponse object
+Filters agg = sr.getAggregations().get("agg");
+
+// For each entry
+for (Filters.Bucket entry : agg.getBuckets()) {
+    String key = entry.getKey();                    // bucket key
+    long docCount = entry.getDocCount();            // Doc count
+    logger.info("key [{}], doc_count [{}]", key, docCount);
+}
+--------------------------------------------------
+
+This will basically produce:
+
+[source,text]
+--------------------------------------------------
+key [men], doc_count [4982]
+key [women], doc_count [5018]
+--------------------------------------------------

docs/java-api/aggregations/bucket/geodistance-aggregation.asciidoc

@@ -0,0 +1,60 @@
+[[java-aggs-bucket-geodistance]]
+==== Geo Distance Aggregation
+
+Here is how you can use
+{ref}/search-aggregations-bucket-geodistance-aggregation.html[Geo Distance Aggregation]
+with Java API.
+
+
+===== Prepare aggregation request
+
+Here is an example on how to create the aggregation request:
+
+[source,java]
+--------------------------------------------------
+AggregationBuilder aggregation =
+        AggregationBuilders
+                .geoDistance("agg")
+                .field("address.location")
+                .point(new GeoPoint(48.84237171118314,2.33320027692004))
+                .unit(DistanceUnit.KILOMETERS)
+                .addUnboundedTo(3.0)
+                .addRange(3.0, 10.0)
+                .addRange(10.0, 500.0);
+--------------------------------------------------
+
+
+===== Use aggregation response
+
+Import Aggregation definition classes:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.aggregations.bucket.range.geodistance.GeoDistance;
+--------------------------------------------------
+
+[source,java]
+--------------------------------------------------
+// sr is here your SearchResponse object
+GeoDistance agg = sr.getAggregations().get("agg");
+
+// For each entry
+for (GeoDistance.Bucket entry : agg.getBuckets()) {
+    String key = entry.getKey();            // key as String
+    Number from = entry.getFrom();          // bucket from value
+    Number to = entry.getTo();              // bucket to value
+    long docCount = entry.getDocCount();    // Doc count
+
+    logger.info("key [{}], from [{}], to [{}], doc_count [{}]", key, from, to, docCount);
+}
+--------------------------------------------------
+
+This will basically produce:
+
+[source,text]
+--------------------------------------------------
+key [*-3.0], from [0.0], to [3.0], doc_count [161]
+key [3.0-10.0], from [3.0], to [10.0], doc_count [460]
+key [10.0-500.0], from [10.0], to [500.0], doc_count [4925]
+--------------------------------------------------
+