JAVA-6168: QE prefix/suffix/substring GA + rename Text API to String

.gitignore

@@ -68,3 +68,4 @@ driver-benchmarks/.factorypath
 # bin build directories
 **/bin
 
+docs/superpowers/

driver-core/src/main/com/mongodb/client/model/vault/EncryptOptions.java

@@ -34,6 +34,7 @@ public class EncryptOptions {
     private String queryType;
     private RangeOptions rangeOptions;
     private TextOptions textOptions;
+    private StringOptions stringOptions;
 
     /**
      * Construct an instance with the given algorithm.
@@ -54,12 +55,12 @@ public EncryptOptions(final String algorithm) {
      *     <li>Indexed</li>
      *     <li>Unindexed</li>
      *     <li>Range</li>
-     *     <li>TextPreview</li>
+     *     <li>String</li>
      * </ul>
      *
-     * <p>The "TextPreview" algorithm is in preview and should be used for experimental workloads only.
-     *   These features are unstable and their security is not guaranteed until released as Generally Available (GA).
-     *   The GA version of these features may not be backwards compatible with the preview version.</p>
+     * <p>The "String" algorithm supports Queryable Encryption prefix, suffix, and substring string queries.
+     *   Use the "String" algorithm with query types "prefix"/"suffix"/"substring" (server 9.0+) or the deprecated
+     *   aliases "prefixPreview"/"suffixPreview"/"substringPreview" (server 8.2 to pre-9.0).</p>
      *
      * @return the encryption algorithm
      */
@@ -149,8 +150,12 @@ public Long getContentionFactor() {
     /**
      * The QueryType.
      *
-     * <p>Currently, we support only "equality", "range", "prefixPreview", "suffixPreview" or "substringPreview" queryType.</p>
-     * <p>It is an error to set queryType when the algorithm is not "Indexed", "Range" or "TextPreview".</p>
+     * <p>Currently, we support only "equality", "range", "prefix", "suffix", "substring", "prefixPreview",
+     * "suffixPreview" or "substringPreview" queryType.</p>
+     * <p>The "prefix", "suffix", "substring", "prefixPreview", "suffixPreview" and "substringPreview" query types are
+     * only valid with the "String" algorithm. "prefixPreview"/"suffixPreview"/"substringPreview" are deprecated
+     * aliases supported for servers 8.2 to pre-9.0; use "prefix"/"suffix"/"substring" on server 9.0+.</p>
+     * <p>It is an error to set queryType when the algorithm is not "Indexed", "Range" or "String".</p>
      * @param queryType the query type
      * @return this
      * @since 4.7
@@ -164,7 +169,7 @@ public EncryptOptions queryType(@Nullable final String queryType) {
     /**
      * Gets the QueryType.
      *
-     * <p>Currently, we support only "equality" or "range" queryType.</p>
+     * <p>See {@link #queryType(String)} for the supported query types.</p>
      * @see #queryType(String)
      * @return the queryType or null
      * @since 4.7
@@ -205,13 +210,15 @@ public RangeOptions getRangeOptions() {
     /**
      * The TextOptions
      *
-     * <p>It is an error to set TextOptions when the algorithm is not "TextPreview".
+     * <p>It is an error to set TextOptions when the algorithm is not "String".
      * @param textOptions the text options
      * @return this
      * @since 5.6
      * @mongodb.server.release 8.2
      * @mongodb.driver.manual /core/queryable-encryption/ queryable encryption
+     * @deprecated Use {@link #stringOptions(StringOptions)} instead.
      */
+    @Deprecated
     @Alpha(Reason.SERVER)
     public EncryptOptions textOptions(@Nullable final TextOptions textOptions) {
         this.textOptions = textOptions;
@@ -225,13 +232,45 @@ public EncryptOptions textOptions(@Nullable final TextOptions textOptions) {
      * @since 5.6
      * @mongodb.server.release 8.2
      * @mongodb.driver.manual /core/queryable-encryption/ queryable encryption
+     * @deprecated Use {@link #getStringOptions()} instead.
      */
+    @Deprecated
     @Alpha(Reason.SERVER)
     @Nullable
     public TextOptions getTextOptions() {
         return textOptions;
     }
 
+    /**
+     * The StringOptions
+     *
+     * <p>It is an error to set StringOptions when the algorithm is not "String".
+     * @param stringOptions the string options
+     * @return this
+     * @since 5.9
+     * @mongodb.server.release 8.2
+     * @mongodb.driver.manual /core/queryable-encryption/ queryable encryption
+     */
+    @Alpha(Reason.SERVER)
+    public EncryptOptions stringOptions(@Nullable final StringOptions stringOptions) {
+        this.stringOptions = stringOptions;
+        return this;
+    }
+
+    /**
+     * Gets the StringOptions
+     * @see #stringOptions(StringOptions)
+     * @return the string options or null if not set
+     * @since 5.9
+     * @mongodb.server.release 8.2
+     * @mongodb.driver.manual /core/queryable-encryption/ queryable encryption
+     */
+    @Alpha(Reason.SERVER)
+    @Nullable
+    public StringOptions getStringOptions() {
+        return stringOptions;
+    }
+
     @Override
     public String toString() {
         return "EncryptOptions{"
@@ -241,6 +280,8 @@ public String toString() {
                 + ", contentionFactor=" + contentionFactor
                 + ", queryType='" + queryType + '\''
                 + ", rangeOptions=" + rangeOptions
+                + ", textOptions=" + textOptions
+                + ", stringOptions=" + stringOptions
                 + '}';
     }
 }

driver-core/src/main/com/mongodb/client/model/vault/StringOptions.java

@@ -0,0 +1,186 @@
+/*
+ * 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.client.model.vault;
+
+import com.mongodb.annotations.Alpha;
+import com.mongodb.annotations.Reason;
+import com.mongodb.lang.Nullable;
+import org.bson.BsonDocument;
+
+/**
+ * String options for a Queryable Encryption field that supports string queries (prefix, suffix, and substring).
+ *
+ * <p>Note: StringOptions is in Alpha and subject to backwards breaking changes.
+ *
+ * @since 5.9
+ * @mongodb.server.release 8.2
+ * @mongodb.driver.manual /core/queryable-encryption/ queryable encryption
+ */
+@Alpha(Reason.SERVER)
+public class StringOptions {
+    private boolean caseSensitive;
+    private boolean diacriticSensitive;
+    @Nullable
+    private BsonDocument prefixOptions;
+    @Nullable
+    private BsonDocument suffixOptions;
+    @Nullable
+    private BsonDocument substringOptions;
+
+    /**
+     * Construct a new instance
+     */
+    public StringOptions() {
+    }
+
+    /**
+     * @return true if string indexes for this field are case sensitive.
+     */
+    public boolean getCaseSensitive() {
+        return caseSensitive;
+    }
+
+    /**
+     * Set case sensitivity
+     *
+     * @param caseSensitive true if string indexes are case sensitive
+     * @return this
+     */
+    public StringOptions caseSensitive(final boolean caseSensitive) {
+        this.caseSensitive = caseSensitive;
+        return this;
+    }
+
+    /**
+     * @return true if string indexes are diacritic sensitive
+     */
+    public boolean getDiacriticSensitive() {
+        return diacriticSensitive;
+    }
+
+    /**
+     * Set diacritic sensitivity
+     *
+     * @param diacriticSensitive true if string indexes are diacritic sensitive
+     * @return this
+     */
+    public StringOptions diacriticSensitive(final boolean diacriticSensitive) {
+        this.diacriticSensitive = diacriticSensitive;
+        return this;
+    }
+
+    /**
+     * Set the prefix options.
+     *
+     * <p>Expected to be a {@link BsonDocument} in the format of:</p>
+     *
+     * <pre>
+     * {@code
+     *   {
+     *    // strMinQueryLength is the minimum allowed query length. Querying with a shorter string will error.
+     *    strMinQueryLength: BsonInt32,
+     *    // strMaxQueryLength is the maximum allowed query length. Querying with a longer string will error.
+     *    strMaxQueryLength: BsonInt32
+     *   }
+     * }
+     * </pre>
+     *
+     * @param prefixOptions the prefix options or null
+     * @return this
+     */
+    public StringOptions prefixOptions(@Nullable final BsonDocument prefixOptions) {
+        this.prefixOptions = prefixOptions;
+        return this;
+    }
+
+    /**
+     * @see #prefixOptions(BsonDocument)
+     * @return the prefix options document or null
+     */
+    @Nullable
+    public BsonDocument getPrefixOptions() {
+        return prefixOptions;
+    }
+
+    /**
+     * Set the suffix options.
+     *
+     * <p>Expected to be a {@link BsonDocument} in the format of:</p>
+     *
+     * <pre>
+     * {@code
+     *   {
+     *    // strMinQueryLength is the minimum allowed query length. Querying with a shorter string will error.
+     *    strMinQueryLength: BsonInt32,
+     *    // strMaxQueryLength is the maximum allowed query length. Querying with a longer string will error.
+     *    strMaxQueryLength: BsonInt32
+     *   }
+     * }
+     * </pre>
+     *
+     * @param suffixOptions the suffix options or null
+     * @return this
+     */
+    public StringOptions suffixOptions(@Nullable final BsonDocument suffixOptions) {
+        this.suffixOptions = suffixOptions;
+        return this;
+    }
+
+    /**
+     * @see #suffixOptions(BsonDocument)
+     * @return the suffix options document or null
+     */
+    @Nullable
+    public BsonDocument getSuffixOptions() {
+        return suffixOptions;
+    }
+
+    /**
+     * Set the substring options.
+     *
+     * <p>Expected to be a {@link BsonDocument} in the format of:</p>
+     *
+     * <pre>
+     * {@code
+     *   {
+     *    // strMaxLength is the maximum allowed length to insert. Inserting longer strings will error.
+     *    strMaxLength: BsonInt32,
+     *    // strMinQueryLength is the minimum allowed query length. Querying with a shorter string will error.
+     *    strMinQueryLength: BsonInt32,
+     *    // strMaxQueryLength is the maximum allowed query length. Querying with a longer string will error.
+     *    strMaxQueryLength: BsonInt32
+     *   }
+     * }
+     * </pre>
+     *
+     * @param substringOptions the substring options or null
+     * @return this
+     */
+    public StringOptions substringOptions(@Nullable final BsonDocument substringOptions) {
+        this.substringOptions = substringOptions;
+        return this;
+    }
+
+    /**
+     * @see #substringOptions(BsonDocument)
+     * @return the substring options document or null
+     */
+    @Nullable
+    public BsonDocument getSubstringOptions() {
+        return substringOptions;
+    }
+}

driver-core/src/main/com/mongodb/client/model/vault/TextOptions.java

@@ -29,11 +29,13 @@
  * @since 5.6
  * @mongodb.server.release 8.2
  * @mongodb.driver.manual /core/queryable-encryption/ queryable encryption
+ * @deprecated Use {@link StringOptions} instead.
  */
+@Deprecated
 @Alpha(Reason.SERVER)
 public class TextOptions {
-    private Boolean caseSensitive;
-    private Boolean diacriticSensitive;
+    private boolean caseSensitive;
+    private boolean diacriticSensitive;
     @Nullable
     private BsonDocument prefixOptions;
     @Nullable