Add support for USING TIMEOUT to QueryBuilder

Add support for adding USING TIMEOUT clause to SELECT, INSERT, UPDATE
queries. The value of the clause (the timeout) can be passed either
as a literal value (CqlDuration) or a BindMarker filled at a time
of execution.

Co-authored-by: Jeff Shaw <[email protected]>

Author: avelanarius

core/src/main/java/com/datastax/oss/driver/api/core/data/CqlDuration.java

@@ -13,6 +13,12 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
+/*
+ * Copyright (C) 2022 ScyllaDB
+ *
+ * Modified by ScyllaDB
+ */
 package com.datastax.oss.driver.api.core.data;
 
 import com.datastax.oss.driver.shaded.guava.common.annotations.VisibleForTesting;
@@ -365,15 +371,7 @@ public boolean equals(Object other) {
     }
   }
 
-  @Override
-  public int hashCode() {
-    return Objects.hashCode(days, months, nanoseconds);
-  }
-
-  @Override
-  public String toString() {
-    StringBuilder builder = new StringBuilder();
-
+  public void appendTo(@NonNull final StringBuilder builder) {
     if (months < 0 || days < 0 || nanoseconds < 0) {
       builder.append('-');
     }
@@ -390,6 +388,17 @@ public String toString() {
       remainder = append(builder, remainder, NANOS_PER_MICRO, "us");
       append(builder, remainder, 1, "ns");
     }
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hashCode(days, months, nanoseconds);
+  }
+
+  @Override
+  public String toString() {
+    StringBuilder builder = new StringBuilder();
+    appendTo(builder);
     return builder.toString();
   }
 

query-builder/src/main/java/com/datastax/oss/driver/api/querybuilder/insert/Insert.java

@@ -13,8 +13,15 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
+/*
+ * Copyright (C) 2022 ScyllaDB
+ *
+ * Modified by ScyllaDB
+ */
 package com.datastax.oss.driver.api.querybuilder.insert;
 
+import com.datastax.oss.driver.api.core.data.CqlDuration;
 import com.datastax.oss.driver.api.querybuilder.BindMarker;
 import com.datastax.oss.driver.api.querybuilder.BuildableQuery;
 import edu.umd.cs.findbugs.annotations.NonNull;
@@ -72,4 +79,29 @@ public interface Insert extends BuildableQuery {
    */
   @NonNull
   Insert usingTtl(@Nullable BindMarker bindMarker);
+
+  /**
+   * Adds a {@code USING TIMEOUT} clause to this statement with a literal value. Setting a value of
+   * {@code null} will remove the {@code USING TIMEOUT} clause on this statement.
+   *
+   * <p>If this method or {@link #usingTimeout(BindMarker) } is called multiple times, the value
+   * from the last invocation is used.
+   *
+   * @param timeout A timeout value controlling server-side query timeout.
+   */
+  @NonNull
+  Insert usingTimeout(@NonNull CqlDuration timeout);
+
+  /**
+   * Adds a {@code USING TIMEOUT} clause to this statement with a bind marker. Setting a value of
+   * {@code null} will remove the {@code USING TIMEOUT} clause on this statement.
+   *
+   * <p>If this method or {@link #usingTimeout(CqlDuration) } is called multiple times, the value
+   * from the last invocation is used.
+   *
+   * @param timeout A bind marker understood as {@link CqlDuration} controlling server-side query
+   *     timeout.
+   */
+  @NonNull
+  Insert usingTimeout(@NonNull BindMarker timeout);
 }

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

@@ -13,9 +13,16 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
+/*
+ * Copyright (C) 2022 ScyllaDB
+ *
+ * Modified by ScyllaDB
+ */
 package com.datastax.oss.driver.api.querybuilder.select;
 
 import com.datastax.oss.driver.api.core.CqlIdentifier;
+import com.datastax.oss.driver.api.core.data.CqlDuration;
 import com.datastax.oss.driver.api.core.metadata.schema.ClusteringOrder;
 import com.datastax.oss.driver.api.querybuilder.BindMarker;
 import com.datastax.oss.driver.api.querybuilder.BuildableQuery;
@@ -193,4 +200,29 @@ default Select orderBy(@NonNull String columnName, @NonNull ClusteringOrder orde
    */
   @NonNull
   Select allowFiltering();
+
+  /**
+   * Adds a {@code USING TIMEOUT} clause to this statement with a literal value. Setting a value of
+   * {@code null} will remove the {@code USING TIMEOUT} clause on this statement.
+   *
+   * <p>If this method or {@link #usingTimeout(BindMarker) } is called multiple times, the value
+   * from the last invocation is used.
+   *
+   * @param timeout A timeout value controlling server-side query timeout.
+   */
+  @NonNull
+  Select usingTimeout(@NonNull CqlDuration timeout);
+
+  /**
+   * Adds a {@code USING TIMEOUT} clause to this statement with a bind marker. Setting a value of
+   * {@code null} will remove the {@code USING TIMEOUT} clause on this statement.
+   *
+   * <p>If this method or {@link #usingTimeout(CqlDuration) } is called multiple times, the value
+   * from the last invocation is used.
+   *
+   * @param timeout A bind marker understood as {@link CqlDuration} controlling server-side query
+   *     timeout.
+   */
+  @NonNull
+  Select usingTimeout(@NonNull BindMarker timeout);
 }

query-builder/src/main/java/com/datastax/oss/driver/api/querybuilder/update/UpdateStart.java

@@ -13,8 +13,15 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
+/*
+ * Copyright (C) 2022 ScyllaDB
+ *
+ * Modified by ScyllaDB
+ */
 package com.datastax.oss.driver.api.querybuilder.update;
 
+import com.datastax.oss.driver.api.core.data.CqlDuration;
 import com.datastax.oss.driver.api.querybuilder.BindMarker;
 import edu.umd.cs.findbugs.annotations.NonNull;
 
@@ -69,4 +76,29 @@ public interface UpdateStart extends OngoingAssignment {
    */
   @NonNull
   UpdateStart usingTtl(@NonNull BindMarker bindMarker);
+
+  /**
+   * Adds a {@code USING TIMEOUT} clause to this statement with a literal value. Setting a value of
+   * {@code null} will remove the {@code USING TIMEOUT} clause on this statement.
+   *
+   * <p>If this method or {@link #usingTimeout(BindMarker) } is called multiple times, the value
+   * from the last invocation is used.
+   *
+   * @param timeout A timeout value controlling server-side query timeout.
+   */
+  @NonNull
+  UpdateStart usingTimeout(@NonNull CqlDuration timeout);
+
+  /**
+   * Adds a {@code USING TIMEOUT} clause to this statement with a bind marker. Setting a value of
+   * {@code null} will remove the {@code USING TIMEOUT} clause on this statement.
+   *
+   * <p>If this method or {@link #usingTimeout(CqlDuration) } is called multiple times, the value
+   * from the last invocation is used.
+   *
+   * @param timeout A bind marker understood as {@link CqlDuration} controlling server-side query
+   *     timeout.
+   */
+  @NonNull
+  UpdateStart usingTimeout(@NonNull BindMarker timeout);
 }