Support for server hedged reads

JAVA-3666

Author: jstewart148

driver-core/src/main/com/mongodb/ReadPreference.java

@@ -48,6 +48,59 @@ public abstract class ReadPreference {
     ReadPreference() {
     }
 
+    /**
+     * Create a new ReadPreference instance with a new tag set.
+     * <p>
+     * Note: this method is not supported for a primary read preference.
+     * </p>
+     *
+     * @param tagSet the new tag set
+     * @return a new ReadPreference instance with a new tag set
+     * @since 4.1
+     */
+    public abstract ReadPreference withTagSet(TagSet tagSet);
+
+    /**
+     * Create a new ReadPreference instance with a new tag set list.
+     * <p>
+     * Note: this method is not supported for a primary read preference.
+     * </p>
+     *
+     * @param tagSet the new tag set list
+     * @return a new ReadPreference instance with a new tag set list
+     * @since 4.1
+     */
+    public abstract ReadPreference withTagSetList(List<TagSet> tagSet);
+
+    /**
+     * Create a new ReadPreference instance with the maximum acceptable staleness of a secondary in order to be considered for
+     * read operations.
+     * <p>
+     * Note: this method is not supported for a primary read preference.
+     * </p>
+     *
+     * @param maxStalenessMS the max allowable staleness of secondaries. The minimum value is either 90 seconds, or the heartbeat frequency
+     *                       plus 10 seconds, whichever is greatest.
+     * @param timeUnit the time unit of maxStaleness
+     * @return a new ReadPreference instance with a new maximum allowable staleness
+     * @since 4.1
+     * @mongodb.server.release 3.4
+     */
+    public abstract ReadPreference withMaxStalenessMS(Long maxStalenessMS, TimeUnit timeUnit);
+
+    /**
+     * Create a new ReadPreference instance with hedge options.
+     * <p>
+     * Note: this method is not supported for a primary read preference.
+     * </p>
+     *
+     * @param hedgeOptions the hedge options
+     * @return a new ReadPreference instance with hedge options
+     * @since 4.1
+     * @mongodb.server.release 4.4
+     */
+    public abstract ReadPreference withHedgeOptions(ReadPreferenceHedgeOptions hedgeOptions);
+
     /**
      * True if this read preference allows reading from a secondary member of a replica set.
      *
@@ -573,7 +626,7 @@ private static TaggableReadPreference valueOf(final String name, final List<TagS
         String nameToCheck = name.toLowerCase();
 
         if (nameToCheck.equals(PRIMARY.getName().toLowerCase())) {
-            throw new IllegalArgumentException("Primary read preference can not also specify tag sets or max staleness");
+            throw new IllegalArgumentException("Primary read preference can not also specify tag sets, max staleness or hedge");
         }
 
         if (nameToCheck.equals(SECONDARY.getName().toLowerCase())) {
@@ -599,6 +652,26 @@ private static final class PrimaryReadPreference extends ReadPreference {
         private PrimaryReadPreference() {
         }
 
+        @Override
+        public ReadPreference withTagSet(final TagSet tagSet) {
+            throw new UnsupportedOperationException("Primary read preference can not also specify tag sets");
+        }
+
+        @Override
+        public TaggableReadPreference withTagSetList(final List<TagSet> tagSet) {
+            throw new UnsupportedOperationException("Primary read preference can not also specify tag sets");
+        }
+
+        @Override
+        public TaggableReadPreference withMaxStalenessMS(final Long maxStalenessMS, final TimeUnit timeUnit) {
+            throw new UnsupportedOperationException("Primary read preference can not also specify max staleness");
+        }
+
+        @Override
+        public TaggableReadPreference withHedgeOptions(final ReadPreferenceHedgeOptions hedgeOptions) {
+            throw new UnsupportedOperationException("Primary read preference can not also specify hedge");
+        }
+
         @Override
         public boolean isSlaveOk() {
             return false;

driver-core/src/main/com/mongodb/ReadPreferenceHedgeOptions.java

@@ -0,0 +1,120 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * Licensed 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.mongodb;
+
+import com.mongodb.annotations.Immutable;
+import org.bson.BsonBoolean;
+import org.bson.BsonDocument;
+
+/**
+ * Options to apply to hedged reads in the server.
+ *
+ * @since 4.1
+ * @mongodb.server.release 4.4
+ */
+@Immutable
+public final class ReadPreferenceHedgeOptions {
+    private final boolean enabled;
+
+    /**
+     * Gets whether hedged reads are enabled in the server.
+     *
+     * @return true if hedged reads are enabled in the server
+     */
+    public boolean isEnabled() {
+        return enabled;
+    }
+
+    /**
+     * Gets an instance of a builder
+     *
+     * @return a builder instance
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * Convert the hedge options to a BsonDocument.
+     *
+     * @return a BsonDocument containing the hedge options
+     */
+    public BsonDocument toBsonDocument() {
+        return new BsonDocument("enabled", new BsonBoolean(enabled));
+    }
+
+    @Override
+    public boolean equals(final Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+
+        ReadPreferenceHedgeOptions that = (ReadPreferenceHedgeOptions) o;
+
+        return enabled == that.enabled;
+    }
+
+    @Override
+    public int hashCode() {
+        return enabled ? 1 : 0;
+    }
+
+    @Override
+    public String toString() {
+        return "ReadPreferenceHedgeOptions{"
+                + "enabled=" + enabled
+                + '}';
+    }
+
+    /**
+     * The builder for read preference hedge options
+     */
+    public static final class Builder {
+        private boolean enabled;
+
+        /**
+         * Sets whether hedged reads are enabled in the server.
+         *
+         * @param enabled true if hedged reads are enabled
+         * @return this
+         */
+        public Builder enabled(final boolean enabled) {
+            this.enabled = enabled;
+            return this;
+        }
+
+        /**
+         * Build the transaction options instance.
+         *
+         * @return The {@code TransactionOptions}
+         */
+        public ReadPreferenceHedgeOptions build() {
+            return new ReadPreferenceHedgeOptions(this);
+        }
+
+        private Builder() {
+        }
+    }
+
+
+    private ReadPreferenceHedgeOptions(final Builder builder) {
+        enabled = builder.enabled;
+    }
+}