Compound order for histogram aggregations. (#22343)

This commit adds support for histogram and date_histogram agg compound order by refactoring and reusing terms agg order code. The major change is that the Terms.Order and Histogram.Order classes have been replaced/refactored into a new class BucketOrder. This is a breaking change for the Java Transport API. For backward compatibility with previous ES versions the (date)histogram compound order will use the first order. Also the _term and _time aggregation order keys have been deprecated; replaced by _key.

Relates to #20003: now that all these aggregations use the same order code, it should be easier to move validation to parse time (as a follow up PR).

Relates to #14771: histogram and date_histogram aggregation order will now be validated at reduce time.

Closes #23613: if a single BucketOrder that is not a tie-breaker is added with the Java Transport API, it will be converted into a CompoundOrder with a tie-breaker.

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

@@ -67,3 +67,7 @@ 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]
 --------------------------------------------------
+
+===== Order
+
+Supports the same order functionality as the <<java-aggs-bucket-terms,`Terms Aggregation`>>.

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

@@ -42,3 +42,7 @@ for (Histogram.Bucket entry : agg.getBuckets()) {
     logger.info("key [{}], doc_count [{}]", key, docCount);
 }
 --------------------------------------------------
+
+===== Order
+
+Supports the same order functionality as the <<java-aggs-bucket-terms,`Terms Aggregation`>>.

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

@@ -39,7 +39,14 @@ for (Terms.Bucket entry : genders.getBuckets()) {
 }
 --------------------------------------------------
 
-==== Order
+===== Order
+
+Import bucket ordering strategy classes:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.aggregations.BucketOrder;
+--------------------------------------------------
 
 Ordering the buckets by their `doc_count` in an ascending manner:
 
@@ -48,7 +55,7 @@ Ordering the buckets by their `doc_count` in an ascending manner:
 AggregationBuilders
     .terms("genders")
     .field("gender")
-    .order(Terms.Order.count(true))
+    .order(BucketOrder.count(true))
 --------------------------------------------------
 
 Ordering the buckets alphabetically by their terms in an ascending manner:
@@ -58,7 +65,7 @@ Ordering the buckets alphabetically by their terms in an ascending manner:
 AggregationBuilders
     .terms("genders")
     .field("gender")
-    .order(Terms.Order.term(true))
+    .order(BucketOrder.key(true))
 --------------------------------------------------
 
 Ordering the buckets by single value metrics sub-aggregation (identified by the aggregation name):
@@ -68,7 +75,22 @@ Ordering the buckets by single value metrics sub-aggregation (identified by the
 AggregationBuilders
     .terms("genders")
     .field("gender")
-    .order(Terms.Order.aggregation("avg_height", false))
+    .order(BucketOrder.aggregation("avg_height", false))
+    .subAggregation(
+        AggregationBuilders.avg("avg_height").field("height")
+    )
+--------------------------------------------------
+
+Ordering the buckets by multiple criteria:
+
+[source,java]
+--------------------------------------------------
+AggregationBuilders
+    .terms("genders")
+    .field("gender")
+    .order(BucketOrder.compound( // in order of priority:
+        BucketOrder.aggregation("avg_height", false), // sort by sub-aggregation first
+        BucketOrder.count(true))) // then bucket count as a tie-breaker
     .subAggregation(
         AggregationBuilders.avg("avg_height").field("height")
     )