Update naming, terms, and missing checks and annotations (#1073)

JAVA-3879

Author: katcharov

driver-core/src/main/com/mongodb/client/model/mql/MqlArray.java

@@ -209,7 +209,7 @@ public interface MqlArray<T extends MqlValue> extends MqlValue {
      * necessary, then the identity function {@code array.union(v -> v)} should
      * be used.
      *
-     * @see MqlMap#entrySet()
+     * @see MqlMap#entries()
      * @param mapper the mapper function.
      * @return the resulting value.
      * @param <R> the type of the resulting map's values.

driver-core/src/main/com/mongodb/client/model/mql/MqlBoolean.java

@@ -61,7 +61,7 @@ public interface MqlBoolean extends MqlValue {
      * @param ifTrue the ifTrue value.
      * @param ifFalse the ifFalse value.
      * @return the resulting value.
-     * @param <T> The type of the resulting expression.
+     * @param <T> The type of the resulting value.
      */
     <T extends MqlValue> T cond(T ifTrue, T ifFalse);
 

driver-core/src/main/com/mongodb/client/model/mql/MqlDocument.java

@@ -186,7 +186,7 @@ default MqlBoolean getBoolean(final String fieldName, final boolean other) {
     default MqlNumber getNumber(final String fieldName, final Number other) {
         Assertions.notNull("fieldName", fieldName);
         Assertions.notNull("other", other);
-        return getNumber(fieldName, MqlValues.numberToExpression(other));
+        return getNumber(fieldName, MqlValues.numberToMqlNumber(other));
     }
 
     /**
@@ -521,7 +521,7 @@ default MqlDocument getDocument(final String fieldName, final Bson other) {
      * @param <T> the type.
      */
 
-    <T extends MqlValue> MqlMap<T> asMap();
+    <T extends MqlValue> MqlMap<@MqlUnchecked(TYPE_ARGUMENT) T> asMap();
 
     /**
      * The result of passing {@code this} value to the provided function.

driver-core/src/main/com/mongodb/client/model/mql/MqlEntry.java

@@ -19,8 +19,6 @@
 import com.mongodb.annotations.Beta;
 import com.mongodb.annotations.Sealed;
 
-import static com.mongodb.client.model.mql.MqlValues.of;
-
 /**
  * A map entry {@linkplain MqlValue value} in the context
  * of the MongoDB Query Language (MQL). An entry has a
@@ -74,16 +72,4 @@ public interface MqlEntry<T extends MqlValue> extends MqlValue {
      * @return the resulting entry.
      */
     MqlEntry<T> setKey(MqlString key);
-
-    /**
-     * An entry with the same value as {@code this} entry, and the
-     * specified {@code key}.
-     *
-     * @mongodb.server.release 5.0
-     * @param key the key.
-     * @return the resulting entry.
-     */
-    default MqlEntry<T> setKey(final String key) {
-        return setKey(of(key));
-    }
 }

driver-core/src/main/com/mongodb/client/model/mql/MqlExpression.java

@@ -43,8 +43,8 @@ final class MqlExpression<T extends MqlValue>
     }
 
     /**
-     * Exposes the evaluated BsonValue so that expressions may be used in
-     * aggregations. Non-public, as it is intended to be used only by the
+     * Exposes the evaluated BsonValue so that this mql expression may be used
+     * in aggregations. Non-public, as it is intended to be used only by the
      * {@link MqlExpressionCodec}.
      */
     BsonValue toBsonValue(final CodecRegistry codecRegistry) {
@@ -67,11 +67,13 @@ public T getValue() {
 
     @Override
     public MqlEntry<T> setValue(final T value) {
+        Assertions.notNull("value", value);
         return setFieldInternal("v", value);
     }
 
     @Override
     public MqlEntry<T> setKey(final MqlString key) {
+        Assertions.notNull("key", key);
         return setFieldInternal("k", key);
     }
 
@@ -1081,7 +1083,7 @@ public MqlMap<T> merge(final MqlMap<? extends T> other) {
     }
 
     @Override
-    public MqlArray<MqlEntry<T>> entrySet() {
+    public MqlArray<MqlEntry<T>> entries() {
         return newMqlExpression(ast("$objectToArray"));
     }
 

driver-core/src/main/com/mongodb/client/model/mql/MqlExpressionCodec.java

@@ -34,7 +34,7 @@ final class MqlExpressionCodec implements Codec<MqlExpression> {
 
     @Override
     public MqlExpression decode(final BsonReader reader, final DecoderContext decoderContext) {
-        throw new UnsupportedOperationException("Decoding to an expression is not supported");
+        throw new UnsupportedOperationException("Decoding to an MqlExpression is not supported");
     }
 
     @Override

driver-core/src/main/com/mongodb/client/model/mql/MqlMap.java

@@ -55,6 +55,7 @@ public interface MqlMap<T extends MqlValue> extends MqlValue {
      * @return the resulting value.
      */
     default MqlBoolean has(final String key) {
+        Assertions.notNull("key", key);
         return has(of(key));
     }
 
@@ -188,7 +189,7 @@ default MqlMap<T> unset(final String key) {
      * @see MqlArray#asMap
      * @return the resulting value.
      */
-    MqlArray<MqlEntry<T>> entrySet();
+    MqlArray<MqlEntry<T>> entries();
 
     /**
      * {@code this} map as a {@linkplain MqlDocument document}.

driver-core/src/main/com/mongodb/client/model/mql/MqlNumber.java

@@ -50,7 +50,7 @@ public interface MqlNumber extends MqlValue {
      */
     default MqlNumber multiply(final Number other) {
         Assertions.notNull("other", other);
-        return this.multiply(MqlValues.numberToExpression(other));
+        return this.multiply(MqlValues.numberToMqlNumber(other));
     }
 
     /**
@@ -73,7 +73,7 @@ default MqlNumber multiply(final Number other) {
      */
     default MqlNumber divide(final Number other) {
         Assertions.notNull("other", other);
-        return this.divide(MqlValues.numberToExpression(other));
+        return this.divide(MqlValues.numberToMqlNumber(other));
     }
 
     /**
@@ -92,7 +92,7 @@ default MqlNumber divide(final Number other) {
      */
     default MqlNumber add(final Number other) {
         Assertions.notNull("other", other);
-        return this.add(MqlValues.numberToExpression(other));
+        return this.add(MqlValues.numberToMqlNumber(other));
     }
 
     /**
@@ -111,7 +111,7 @@ default MqlNumber add(final Number other) {
      */
     default MqlNumber subtract(final Number other) {
         Assertions.notNull("other", other);
-        return this.subtract(MqlValues.numberToExpression(other));
+        return this.subtract(MqlValues.numberToMqlNumber(other));
     }
 
     /**

driver-core/src/main/com/mongodb/client/model/mql/MqlString.java

@@ -48,8 +48,8 @@ public interface MqlString extends MqlValue {
     MqlString toUpper();
 
     /**
-     * The concatenation of {@code this} string, followed by
-     * the {@code other} string.
+     * The result of appending the {@code other} string to the end of
+     * {@code this} string (strict concatenation).
      *
      * @param other the other value.
      * @return the resulting value.

driver-core/src/main/com/mongodb/client/model/mql/MqlValue.java

@@ -38,7 +38,7 @@
  * filtered and summed, in a style similar to that of the Java Stream API:
  *
  * <pre>{@code
- * import static com.mongodb.client.model.expressions.Expressions.current;
+ * import static com.mongodb.client.model.mql.MqlValues.current;
  * MongoCollection<Document> col = ...;
  * AggregateIterable<Document> result = col.aggregate(Arrays.asList(
  *     addFields(new Field<>("result", current()
@@ -254,7 +254,7 @@ public interface MqlValue {
      * @return the resulting value.
      * @param <T> the type of the values of the resulting map.
      */
-    <T extends MqlValue> MqlMap<T> isMapOr(MqlMap<@MqlUnchecked(TYPE_ARGUMENT) ? extends T> other);
+    <T extends MqlValue> MqlMap<@MqlUnchecked(TYPE_ARGUMENT) T> isMapOr(MqlMap<? extends T> other);
 
     /**
      * The {@linkplain MqlString string} representation of {@code this} value.

driver-core/src/main/com/mongodb/client/model/mql/MqlValues.java

@@ -368,9 +368,7 @@ public static <T extends MqlValue> MqlMap<T> ofMap() {
      */
     public static MqlDocument of(final Bson document) {
         Assertions.notNull("document", document);
-        // All documents are wrapped in a $literal. If we don't wrap, we need to
-        // check for empty documents and documents that are actually expressions
-        // (and need to be wrapped in $literal anyway). This would be brittle.
+        // All documents are wrapped in a $literal; this is the least brittle approach.
         return new MqlExpression<>((cr) -> new AstPlaceholder(new BsonDocument("$literal",
                 document.toBsonDocument(BsonDocument.class, cr))));
     }
@@ -391,13 +389,13 @@ public static MqlDocument of(final Bson document) {
      * @return the null value
      */
     public static MqlValue ofNull() {
-        // There is no specific expression type corresponding to Null,
-        // and Null is not a value in any other expression type.
+        // There is no specific mql type corresponding to Null,
+        // and Null is not a value in any other mql type.
         return new MqlExpression<>((cr) -> new AstPlaceholder(new BsonNull()))
                 .assertImplementsAllExpressions();
     }
 
-    static MqlNumber numberToExpression(final Number number) {
+    static MqlNumber numberToMqlNumber(final Number number) {
         Assertions.notNull("number", number);
         if (number instanceof Integer) {
             return of((int) number);

driver-core/src/test/functional/com/mongodb/client/model/mql/ArithmeticMqlValuesFunctionalTest.java

@@ -23,7 +23,7 @@
 import java.math.RoundingMode;
 
 import static com.mongodb.ClusterFixture.serverVersionAtLeast;
-import static com.mongodb.client.model.mql.MqlValues.numberToExpression;
+import static com.mongodb.client.model.mql.MqlValues.numberToMqlNumber;
 import static com.mongodb.client.model.mql.MqlValues.of;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotEquals;
@@ -55,12 +55,12 @@ public void literalsTest() {
         assertNotEquals(toBsonValue(1.0), evaluate(of(1L)));
 
         // Number conversions; used internally
-        assertExpression(1, numberToExpression(1));
-        assertExpression(1L, numberToExpression(1L));
-        assertExpression(1.0, numberToExpression(1.0));
-        assertExpression(Decimal128.parse("1.0"), numberToExpression(Decimal128.parse("1.0")));
+        assertExpression(1, numberToMqlNumber(1));
+        assertExpression(1L, numberToMqlNumber(1L));
+        assertExpression(1.0, numberToMqlNumber(1.0));
+        assertExpression(Decimal128.parse("1.0"), numberToMqlNumber(Decimal128.parse("1.0")));
         assertThrows(IllegalArgumentException.class,
-                () -> assertExpression("n/a", numberToExpression(BigDecimal.valueOf(1))));
+                () -> assertExpression("n/a", numberToMqlNumber(BigDecimal.valueOf(1))));
     }
 
     @Test

driver-core/src/test/functional/com/mongodb/client/model/mql/BooleanMqlValuesFunctionalTest.java

@@ -18,7 +18,7 @@
 
 import org.junit.jupiter.api.Test;
 
-@SuppressWarnings({"PointlessBooleanExpression", "ConstantConditions", "ConstantConditionalExpression"})
+@SuppressWarnings({"PointlessBooleanExpression", "ConstantConditions", "ConstantConditionalExpression", "SimplifyBooleanExpression"})
 class BooleanMqlValuesFunctionalTest extends AbstractMqlValuesFunctionalTest {
     // https://www.mongodb.com/docs/manual/reference/operator/aggregation/#boolean-expression-operators
     // (Complete as of 6.0)

driver-core/src/test/functional/com/mongodb/client/model/mql/ControlMqlValuesFunctionalTest.java

@@ -140,7 +140,7 @@ public void switchTypesTest() {
         assertExpression(
                 "12 - map",
                 ofMap(Document.parse("{a: '1', b: '2'}")).switchOn(on -> on
-                        .isMap((MqlMap<MqlString> v) -> v.entrySet()
+                        .isMap((MqlMap<MqlString> v) -> v.entries()
                                 .joinStrings(e -> e.getValue()).append(of(" - map")))));
         // arrays via isArray, and tests signature:
         assertExpression(

driver-core/src/test/functional/com/mongodb/client/model/mql/MapMqlValuesFunctionalTest.java

@@ -109,9 +109,6 @@ public void getSetEntryTest() {
         assertExpression(
                 Document.parse("{k: 'keyB', 'v': 1}"),
                 entryA1.setKey(of("keyB")));
-        assertExpression(
-                Document.parse("{k: 'keyB', 'v': 1}"),
-                entryA1.setKey("keyB"));
     }
 
     @Test
@@ -159,23 +156,23 @@ public void entrySetTest() {
         // https://www.mongodb.com/docs/manual/reference/operator/aggregation/objectToArray/ (23)
         assertExpression(
                 Arrays.asList(Document.parse("{'k': 'k1', 'v': 1}")),
-                MqlValues.<MqlInteger>ofMap().set("k1", of(1)).entrySet(),
+                MqlValues.<MqlInteger>ofMap().set("k1", of(1)).entries(),
                 "{'$objectToArray': {'$setField': "
                         + "{'field': 'k1', 'input': {'$literal': {}}, 'value': 1}}}");
 
         // key/value usage
         assertExpression(
                 "keyA|keyB|",
-                mapA1B2.entrySet().map(v -> v.getKey().append(of("|"))).joinStrings(v -> v));
+                mapA1B2.entries().map(v -> v.getKey().append(of("|"))).joinStrings(v -> v));
         assertExpression(
                 23,
-                mapA1B2.entrySet().map(v -> v.getValue().add(10)).sum(v -> v));
+                mapA1B2.entries().map(v -> v.getValue().add(10)).sum(v -> v));
 
         // combined entrySet-buildMap usage
         assertExpression(
                 Document.parse("{'keyA': 2, 'keyB': 3}"),
                 mapA1B2
-                        .entrySet()
+                        .entries()
                         .map(v -> v.setValue(v.getValue().add(1)))
                         .asMap(v -> v));
 
@@ -185,7 +182,7 @@ public void entrySetTest() {
                 Arrays.asList(
                         Document.parse("{'k': 'warehouse1', 'v': 2500}"),
                         Document.parse("{'k': 'warehouse2', 'v': 500}")),
-                doc.getMap("instock").entrySet(),
+                doc.getMap("instock").entries(),
                 "{'$objectToArray': {'$getField': {'input': {'$literal': "
                         + "{'instock': {'warehouse1': 2500, 'warehouse2': 500}}}, 'field': 'instock'}}}");
     }

driver-core/src/test/functional/com/mongodb/client/model/mql/NotNullApiTest.java

@@ -35,6 +35,7 @@
 import static com.mongodb.assertions.Assertions.fail;
 import static com.mongodb.client.model.mql.MqlValues.of;
 import static com.mongodb.client.model.mql.MqlValues.ofArray;
+import static com.mongodb.client.model.mql.MqlValues.ofEntry;
 import static com.mongodb.client.model.mql.MqlValues.ofMap;
 import static com.mongodb.client.model.mql.MqlValues.ofNull;
 
@@ -56,6 +57,7 @@ public void notNullApiTest() {
         mapping.put(MqlMap.class, ofMap(BsonDocument.parse("{}")));
         mapping.put(MqlArray.class, ofArray());
         mapping.put(MqlValue.class, ofNull());
+        mapping.put(MqlEntry.class, ofEntry(of(""), of("")));
         mapping.put(Branches.class, new Branches<>());
         mapping.put(BranchesIntermediary.class, new BranchesIntermediary<>(Collections.emptyList()));
         mapping.put(BranchesTerminal.class, new BranchesTerminal<>(Collections.emptyList(), null));