Make Terms order assignative (#2921)

Deprecate Terms order _terms with Obsolete attributes

Closes #2840

Author: russcam

src/Nest/Aggregations/Bucket/Terms/TermsAggregation.cs

@@ -47,7 +47,6 @@ public interface ITermsAggregation<TFieldType> : ITermsAggregation
 	{
 		[JsonProperty("missing")]
 		TFieldType Missing { get; set; }
-
 	}
 
 	public class TermsAggregation<TFieldType> : BucketAggregationBase, ITermsAggregation<TFieldType>
@@ -125,23 +124,8 @@ public TermsAggregationDescriptor<T, TFieldType> MinimumDocumentCount(int minimu
 		public TermsAggregationDescriptor<T, TFieldType> ExecutionHint(TermsAggregationExecutionHint executionHint) =>
 			Assign(a => a.ExecutionHint = executionHint);
 
-		public TermsAggregationDescriptor<T, TFieldType> Order(TermsOrder order) => Assign(a =>
-		{
-			a.Order = a.Order ?? new List<TermsOrder>();
-			a.Order.Add(order);
-		});
-
-		public TermsAggregationDescriptor<T, TFieldType> OrderAscending(string key) => Assign(a =>
-		{
-			a.Order = a.Order ?? new List<TermsOrder>();
-			a.Order.Add(new TermsOrder { Key = key, Order = SortOrder.Ascending });
-		});
-
-		public TermsAggregationDescriptor<T, TFieldType> OrderDescending(string key) => Assign(a =>
-		{
-			a.Order = a.Order ?? new List<TermsOrder>();
-			a.Order.Add(new TermsOrder { Key = key, Order = SortOrder.Descending });
-		});
+		public TermsAggregationDescriptor<T, TFieldType> Order(Func<TermsOrderDescriptor<T>, IPromise<IList<TermsOrder>>> selector) =>
+			Assign(a => a.Order = selector?.Invoke(new TermsOrderDescriptor<T>())?.Value);
 
 		public TermsAggregationDescriptor<T, TFieldType> Include(long partition, long numberOfPartitions) =>
 			Assign(a => a.Include = new TermsInclude(partition, numberOfPartitions));

src/Nest/Aggregations/Bucket/Terms/TermsOrder.cs

@@ -1,4 +1,5 @@
-using Newtonsoft.Json;
+using System;
+using Newtonsoft.Json;
 
 namespace Nest
 {
@@ -10,11 +11,10 @@ public class TermsOrder
 
 		public static TermsOrder CountAscending => new TermsOrder { Key = "_count", Order = SortOrder.Ascending };
 		public static TermsOrder CountDescending => new TermsOrder { Key = "_count", Order = SortOrder.Descending };
-
-		//here for backwards compatibility reasons, elasticsearch deprecrated _term as sort order in favor of _key
+		[Obsolete("Deprecated in Elasticsearch 6.0. Use KeyAscending")]
 		public static TermsOrder TermAscending => new TermsOrder { Key = "_key", Order = SortOrder.Ascending };
+		[Obsolete("Deprecated in Elasticsearch 6.0. Use KeyDescending")]
 		public static TermsOrder TermDescending => new TermsOrder { Key = "_key", Order = SortOrder.Descending };
-
 		public static TermsOrder KeyAscending => new TermsOrder { Key = "_key", Order = SortOrder.Ascending };
 		public static TermsOrder KeyDescending => new TermsOrder { Key = "_key", Order = SortOrder.Descending };
 	}

src/Nest/Aggregations/Bucket/Terms/TermsOrderDescriptor.cs

@@ -0,0 +1,24 @@
+using System.Collections.Generic;
+
+namespace Nest
+{
+	public class TermsOrderDescriptor<T> : DescriptorPromiseBase<TermsOrderDescriptor<T>, IList<TermsOrder>>
+		where T : class
+	{
+		public TermsOrderDescriptor() : base(new List<TermsOrder>()) { }
+
+		public TermsOrderDescriptor<T> CountAscending() => Assign(a => a.Add(TermsOrder.CountAscending));
+
+		public TermsOrderDescriptor<T> CountDescending() => Assign(a => a.Add(TermsOrder.CountDescending));
+
+		public TermsOrderDescriptor<T> KeyAscending() => Assign(a => a.Add(TermsOrder.KeyAscending));
+
+		public TermsOrderDescriptor<T> KeyDescending() => Assign(a => a.Add(TermsOrder.KeyDescending));
+
+		public TermsOrderDescriptor<T> Ascending(string key) =>
+			string.IsNullOrWhiteSpace(key) ? this : Assign(a => a.Add(new TermsOrder { Key = key, Order = SortOrder.Ascending }));
+
+		public TermsOrderDescriptor<T> Descending(string key) =>
+			string.IsNullOrWhiteSpace(key) ? this : Assign(a => a.Add(new TermsOrder { Key = key, Order = SortOrder.Descending }));
+	}
+}

src/Tests/Aggregations/Bucket/Terms/TermsAggregationUsageTests.cs

@@ -64,8 +64,10 @@ public TermsAggregationUsageTests(ReadOnlyCluster i, EndpointUsage usage) : base
 					.ExecutionHint(TermsAggregationExecutionHint.Map)
 					.Missing("n/a")
 					.Script(ss => ss.Source("'State of Being: '+_value"))
-					.Order(TermsOrder.TermAscending)
-					.Order(TermsOrder.CountDescending)
+					.Order(o => o
+						.KeyAscending()
+						.CountDescending()
+					)
 					.Meta(m => m
 						.Add("foo", "bar")
 					)
@@ -87,7 +89,7 @@ public TermsAggregationUsageTests(ReadOnlyCluster i, EndpointUsage usage) : base
 					Script = new InlineScript("'State of Being: '+_value"),
 					Order = new List<TermsOrder>
 					{
-						TermsOrder.TermAscending,
+						TermsOrder.KeyAscending,
 						TermsOrder.CountDescending
 					},
 					Meta = new Dictionary<string, object>
@@ -171,8 +173,10 @@ public TermsAggregationIncludePatternUsageTests(ReadOnlyCluster i, EndpointUsage
 					.ExecutionHint(TermsAggregationExecutionHint.Map)
 					.Missing("n/a")
 					.Include("(Stable|VeryActive)")
-					.Order(TermsOrder.TermAscending)
-					.Order(TermsOrder.CountDescending)
+					.Order(o => o
+						.KeyAscending()
+						.CountDescending()
+					)
 					.Meta(m => m
 						.Add("foo", "bar")
 					)
@@ -194,7 +198,7 @@ public TermsAggregationIncludePatternUsageTests(ReadOnlyCluster i, EndpointUsage
 					Include = new TermsInclude("(Stable|VeryActive)"),
 					Order = new List<TermsOrder>
 					{
-						TermsOrder.TermAscending,
+						TermsOrder.KeyAscending,
 						TermsOrder.CountDescending
 					},
 					Meta = new Dictionary<string, object>
@@ -278,8 +282,10 @@ public TermsAggregationIncludeExactValuesUsageTests(ReadOnlyCluster i, EndpointU
 					.ExecutionHint(TermsAggregationExecutionHint.Map)
 					.Missing("n/a")
 					.Include(new[] {StateOfBeing.Stable.ToString(), StateOfBeing.VeryActive.ToString()})
-					.Order(TermsOrder.TermAscending)
-					.Order(TermsOrder.CountDescending)
+					.Order(o => o
+						.KeyAscending()
+						.CountDescending()
+					)
 					.Meta(m => m
 						.Add("foo", "bar")
 					)
@@ -301,7 +307,7 @@ public TermsAggregationIncludeExactValuesUsageTests(ReadOnlyCluster i, EndpointU
 					Include = new TermsInclude(new[] { StateOfBeing.Stable.ToString(), StateOfBeing.VeryActive.ToString() }),
 					Order = new List<TermsOrder>
 					{
-						TermsOrder.TermAscending,
+						TermsOrder.KeyAscending,
 						TermsOrder.CountDescending
 					},
 					Meta = new Dictionary<string, object>