Re-work ordering clause support in query builder

[absurdfarce]

Goal is to unify ordering clause support in the query builder into a single OrderingClause entity. This will enable future implementations to completely manage the structure of "ORDER BY" clauses at granular levels.

A concrete example: we've been able to leverage this functionality to implement support for BM25 queries on Astra. Ideally something like this can be added to cassandra-java-driver once it makes it's way to OSS Cassandra but until then we should be safe to get the support for these kinds of extensions (included in this PR) into the driver.

diff --git a/query-builder/src/main/java/com/datastax/oss/driver/api/querybuilder/select/BM25OrderingClause.java b/query-builder/src/main/java/com/datastax/oss/driver/api/querybuilder/select/BM25OrderingClause.java
new file mode 100644
index 00000000000..5f5daa7499e
--- /dev/null
+++ b/query-builder/src/main/java/com/datastax/oss/driver/api/querybuilder/select/BM25OrderingClause.java
@@ -0,0 +1,44 @@
+/*
+ * 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.querybuilder.QueryBuilder;
+import edu.umd.cs.findbugs.annotations.NonNull;
+
+public class BM25OrderingClause extends OrderingClause {
+
+  private final CqlIdentifier identifier;
+  private final String stringToMatch;
+
+  BM25OrderingClause(CqlIdentifier identifier, String stringToMatch) {
+
+    this.identifier = identifier;
+    this.stringToMatch = stringToMatch;
+  }
+
+  public static BM25OrderingClause create(CqlIdentifier identifier, String stringToMatch) {
+    return new BM25OrderingClause(identifier, stringToMatch);
+  }
+
+  @Override
+  public void appendTo(@NonNull StringBuilder builder) {
+    builder.append(" ORDER BY ").append(this.identifier.asCql(true)).append(" BM25 OF ");
+    QueryBuilder.literal(this.stringToMatch).appendTo(builder);
+  }
+}
diff --git a/query-builder/src/main/java/com/datastax/oss/driver/internal/querybuilder/select/BM25Select.java b/query-builder/src/main/java/com/datastax/oss/driver/internal/querybuilder/select/BM25Select.java
new file mode 100644
index 00000000000..4f22fa6d3db
--- /dev/null
+++ b/query-builder/src/main/java/com/datastax/oss/driver/internal/querybuilder/select/BM25Select.java
@@ -0,0 +1,56 @@
+/*
+ * 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.internal.querybuilder.select;
+
+import com.datastax.oss.driver.api.core.CqlIdentifier;
+import com.datastax.oss.driver.api.querybuilder.select.BM25OrderingClause;
+import com.datastax.oss.driver.api.querybuilder.select.Select;
+import edu.umd.cs.findbugs.annotations.NonNull;
+
+public class BM25Select extends DefaultSelect {
+
+  public BM25Select(DefaultSelect copy) {
+    super(
+        copy.getKeyspace(),
+        copy.getTable(),
+        copy.isJson(),
+        copy.isDistinct(),
+        copy.getSelectors(),
+        copy.getRelations(),
+        copy.getGroupByClauses(),
+        copy.getOrderingClause(),
+        copy.getLimit(),
+        copy.getPerPartitionLimit(),
+        copy.allowsFiltering());
+  }
+
+  public static BM25Select create(DefaultSelect copy) {
+    return new BM25Select(copy);
+  }
+
+  @NonNull
+  public Select orderByBM25Of(@NonNull String columnName, @NonNull String stringToMatch) {
+    return withOrderingClause(
+        BM25OrderingClause.create(CqlIdentifier.fromCql(columnName), stringToMatch));
+  }
+
+  @NonNull
+  public Select orderByBM25Of(@NonNull CqlIdentifier columnId, @NonNull String stringToMatch) {
+    return withOrderingClause(BM25OrderingClause.create(columnId, stringToMatch));
+  }
+}
diff --git a/query-builder/src/test/java/com/datastax/oss/driver/api/querybuilder/select/BM25SelectOrderingTest.java b/query-builder/src/test/java/com/datastax/oss/driver/api/querybuilder/select/BM25SelectOrderingTest.java
new file mode 100644
index 00000000000..03ba0bb5aa0
--- /dev/null
+++ b/query-builder/src/test/java/com/datastax/oss/driver/api/querybuilder/select/BM25SelectOrderingTest.java
@@ -0,0 +1,85 @@
+/*
+ * 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 static com.datastax.oss.driver.api.core.metadata.schema.ClusteringOrder.ASC;
+import static com.datastax.oss.driver.api.core.metadata.schema.ClusteringOrder.DESC;
+import static com.datastax.oss.driver.api.querybuilder.Assertions.assertThat;
+import static com.datastax.oss.driver.api.querybuilder.QueryBuilder.literal;
+import static com.datastax.oss.driver.api.querybuilder.QueryBuilder.selectFrom;
+
+import com.datastax.oss.driver.api.core.data.CqlVector;
+import com.datastax.oss.driver.api.querybuilder.relation.Relation;
+import com.datastax.oss.driver.internal.querybuilder.select.BM25Select;
+import com.datastax.oss.driver.internal.querybuilder.select.DefaultSelect;
+import org.junit.Test;
+
+public class BM25SelectOrderingTest {
+
+  @Test
+  public void should_generate_bm25_ordering_clauses() {
+    DefaultSelect base =
+        (DefaultSelect) selectFrom("foo").all().where(Relation.column("k").isEqualTo(literal(1)));
+    assertThat(BM25Select.create(base).orderByBM25Of("c1", "foo"))
+        .hasCql("SELECT * FROM foo WHERE k=1 ORDER BY c1 BM25 OF 'foo'");
+  }
+
+  @Test
+  public void should_replace_columns_ordering_with_bm25() {
+    DefaultSelect base =
+        (DefaultSelect)
+            selectFrom("foo")
+                .all()
+                .where(Relation.column("k").isEqualTo(literal(1)))
+                .orderBy("c1", ASC)
+                .orderBy("c2", DESC);
+    assertThat(BM25Select.create(base).orderByBM25Of("c1", "foo"))
+        .hasCql("SELECT * FROM foo WHERE k=1 ORDER BY c1 BM25 OF 'foo'");
+  }
+
+  @Test
+  public void should_replace_ann_ordering_with_bm25() {
+    DefaultSelect base =
+        (DefaultSelect)
+            selectFrom("foo")
+                .all()
+                .where(Relation.column("k").isEqualTo(literal(1)))
+                .orderByAnnOf("c1", CqlVector.newInstance(0.1, 0.2, 0.3));
+    assertThat(BM25Select.create(base).orderByBM25Of("c1", "foo"))
+        .hasCql("SELECT * FROM foo WHERE k=1 ORDER BY c1 BM25 OF 'foo'");
+  }
+
+  @Test
+  public void should_replace_bm25_ordering_with_columns() {
+    DefaultSelect base =
+        (DefaultSelect) selectFrom("foo").all().where(Relation.column("k").isEqualTo(literal(1)));
+    Select bm25Select = BM25Select.create(base).orderByBM25Of("c1", "foo");
+    Select finalSelect = bm25Select.orderBy("c1", ASC).orderBy("c2", DESC);
+    assertThat(finalSelect).hasCql("SELECT * FROM foo WHERE k=1 ORDER BY c1 ASC,c2 DESC");
+  }
+
+  @Test
+  public void should_replace_bm25_ordering_with_ann() {
+    DefaultSelect base =
+        (DefaultSelect) selectFrom("foo").all().where(Relation.column("k").isEqualTo(literal(1)));
+    Select bm25Select = BM25Select.create(base).orderByBM25Of("c1", "foo");
+    Select finalSelect = bm25Select.orderByAnnOf("c1", CqlVector.newInstance(0.1, 0.2, 0.3));
+    assertThat(finalSelect)
+        .hasCql("SELECT * FROM foo WHERE k=1 ORDER BY c1 ANN OF [0.1, 0.2, 0.3]");
+  }
+}

[lukasz-antoniak]

NIT, maybe just add one-liner JavaDoc to ColumnsOrderingClause and AnnOrderingClause?

[absurdfarce]

Good catch @lukasz-antoniak! Added a few sentences for each class... take a look and let me know if you're good with what's here now.