Re-work ordering clause support in query builder behind a single OrderingClause abstraction. This allows for

custom impls to define their own logic for managing "ORDER BY" clauses.

patch by Bret McGuire; reviewed by Bret McGuire and Lukasz Antoniak
reference: #2047

Author: absurdfarce

query-builder/src/main/java/com/datastax/oss/driver/api/querybuilder/select/AnnOrderingClause.java

@@ -0,0 +1,50 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.datastax.oss.driver.api.querybuilder.select;
+
+import com.datastax.oss.driver.api.core.CqlIdentifier;
+import com.datastax.oss.driver.api.core.data.CqlVector;
+import com.datastax.oss.driver.api.querybuilder.QueryBuilder;
+import edu.umd.cs.findbugs.annotations.NonNull;
+
+/**
+ * Concrete implementation of {@link OrderingClause} which supports ordering by
+ * the adjacent nearest-neighbor (ANN) calculation.  This usage is primarily used
+ * for vector calculations.
+ */
+public class AnnOrderingClause extends OrderingClause {
+
+  private final CqlIdentifier identifier;
+  private final CqlVector<?> vector;
+
+  AnnOrderingClause(CqlIdentifier identifier, CqlVector<?> vector) {
+
+    this.identifier = identifier;
+    this.vector = vector;
+  }
+
+  public static AnnOrderingClause create(CqlIdentifier identifier, CqlVector<?> vector) {
+    return new AnnOrderingClause(identifier, vector);
+  }
+
+  @Override
+  public void appendTo(@NonNull StringBuilder builder) {
+    builder.append(" ORDER BY ").append(this.identifier.asCql(true)).append(" ANN OF ");
+    QueryBuilder.literal(this.vector).appendTo(builder);
+  }
+}

query-builder/src/main/java/com/datastax/oss/driver/api/querybuilder/select/ColumnsOrderingClause.java

@@ -0,0 +1,68 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.datastax.oss.driver.api.querybuilder.select;
+
+import com.datastax.oss.driver.api.core.CqlIdentifier;
+import com.datastax.oss.driver.api.core.metadata.schema.ClusteringOrder;
+import com.datastax.oss.driver.internal.querybuilder.ImmutableCollections;
+import com.datastax.oss.driver.shaded.guava.common.collect.ImmutableMap;
+import edu.umd.cs.findbugs.annotations.NonNull;
+import java.util.Map;
+
+/**
+ * Concrete implementation of {@link OrderingClause} which supports ordering by
+ * specified columns.  This usages is the default ORDER BY syntax for Apache Cassandra.
+ */
+public class ColumnsOrderingClause extends OrderingClause {
+
+  private final ImmutableMap<CqlIdentifier, ClusteringOrder> orderings;
+
+  ColumnsOrderingClause(ImmutableMap<CqlIdentifier, ClusteringOrder> orderings) {
+
+    this.orderings = orderings;
+  }
+
+  public static ColumnsOrderingClause create() {
+    return new ColumnsOrderingClause(ImmutableMap.of());
+  }
+
+  public ColumnsOrderingClause add(
+      @NonNull CqlIdentifier identifier, @NonNull ClusteringOrder order) {
+    return new ColumnsOrderingClause(
+        ImmutableCollections.append(this.orderings, identifier, order));
+  }
+
+  public ColumnsOrderingClause add(@NonNull Map<CqlIdentifier, ClusteringOrder> orderMap) {
+    return new ColumnsOrderingClause(ImmutableCollections.concat(this.orderings, orderMap));
+  }
+
+  @Override
+  public void appendTo(@NonNull StringBuilder builder) {
+
+    boolean first = true;
+    for (Map.Entry<CqlIdentifier, ClusteringOrder> entry : orderings.entrySet()) {
+      if (first) {
+        builder.append(" ORDER BY ");
+        first = false;
+      } else {
+        builder.append(",");
+      }
+      builder.append(entry.getKey().asCql(true)).append(" ").append(entry.getValue().name());
+    }
+  }
+}

query-builder/src/main/java/com/datastax/oss/driver/api/querybuilder/select/OrderingClause.java

@@ -0,0 +1,27 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.datastax.oss.driver.api.querybuilder.select;
+
+import com.datastax.oss.driver.api.querybuilder.CqlSnippet;
+
+/**
+ * Abstract representation of an ordering clause (i.e. ORDER BY) in a CQL statement.
+ * Alternate implementations may be provided if servers wind up implementing customized
+ * orderings.
+ */
+public abstract class OrderingClause implements CqlSnippet {}