Add @MqlUnchecked and a few usage examples (#1059)

 JAVA-4799

Author: stIncMale

driver-core/src/main/com/mongodb/client/model/expressions/ArrayExpression.java

@@ -19,6 +19,8 @@
 import java.util.function.Function;
 
 import static com.mongodb.client.model.expressions.Expressions.of;
+import static com.mongodb.client.model.expressions.MqlUnchecked.Unchecked.PRESENT;
+import static com.mongodb.client.model.expressions.MqlUnchecked.Unchecked.NON_EMPTY;
 
 /**
  * An array {@link Expression value} in the context of the MongoDB Query
@@ -85,6 +87,7 @@ public interface ArrayExpression<T extends Expression> extends Expression {
      * @param i
      * @return
      */
+    @MqlUnchecked(PRESENT)
     T elementAt(IntegerExpression i);
 
     default T elementAt(final int i) {
@@ -95,6 +98,7 @@ default T elementAt(final int i) {
      * user asserts that array is not empty
      * @return
      */
+    @MqlUnchecked(NON_EMPTY)
     T first();
 
     /**

driver-core/src/main/com/mongodb/client/model/expressions/Branches.java

@@ -20,6 +20,8 @@
 import java.util.List;
 import java.util.function.Function;
 
+import static com.mongodb.client.model.expressions.MqlUnchecked.Unchecked.TYPE_ARGUMENT;
+
 public final class Branches<T extends Expression> {
 
     Branches() {
@@ -78,7 +80,7 @@ public <R extends Expression> BranchesIntermediary<T, R> isDate(final Function<?
     }
 
     @SuppressWarnings("unchecked")
-    public <R extends Expression, Q extends Expression> BranchesIntermediary<T, R> isArray(final Function<? super ArrayExpression<Q>, ? extends R> r) {
+    public <R extends Expression, Q extends Expression> BranchesIntermediary<T, R> isArray(final Function<? super ArrayExpression<@MqlUnchecked(TYPE_ARGUMENT) Q>, ? extends R> r) {
         return is(v -> mqlEx(v).isArray(), v -> r.apply((ArrayExpression<Q>) v));
     }
 

driver-core/src/main/com/mongodb/client/model/expressions/DocumentExpression.java

@@ -23,6 +23,8 @@
 
 import static com.mongodb.client.model.expressions.Expressions.of;
 import static com.mongodb.client.model.expressions.Expressions.ofMap;
+import static com.mongodb.client.model.expressions.MqlUnchecked.Unchecked.PRESENT;
+import static com.mongodb.client.model.expressions.MqlUnchecked.Unchecked.TYPE;
 
 /**
  * Expresses a document value. A document is an ordered set of fields, where the
@@ -34,8 +36,10 @@ public interface DocumentExpression extends Expression {
 
     DocumentExpression unsetField(String fieldName);
 
+    @MqlUnchecked(PRESENT)
     Expression getField(String fieldName);
 
+    @MqlUnchecked({PRESENT, TYPE})
     BooleanExpression getBoolean(String fieldName);
 
     BooleanExpression getBoolean(String fieldName, BooleanExpression other);

driver-core/src/main/com/mongodb/client/model/expressions/Expression.java

@@ -20,6 +20,8 @@
 
 import java.util.function.Function;
 
+import static com.mongodb.client.model.expressions.MqlUnchecked.Unchecked.TYPE_ARGUMENT;
+
 /**
  * A value in the context of the MongoDB Query Language (MQL).
  *
@@ -215,7 +217,7 @@ public interface Expression {
      * @return the resulting value.
      * @param <T> the type of the elements of the resulting array.
      */
-    <T extends Expression> ArrayExpression<T> isArrayOr(ArrayExpression<? extends T> other);
+    <T extends Expression> ArrayExpression<@MqlUnchecked(TYPE_ARGUMENT) T> isArrayOr(ArrayExpression<? extends T> other);
 
     /**
      * {@code this} value as a {@linkplain DocumentExpression document} if

driver-core/src/main/com/mongodb/client/model/expressions/MapExpression.java

@@ -19,6 +19,7 @@
 import java.util.function.Function;
 
 import static com.mongodb.client.model.expressions.Expressions.of;
+import static com.mongodb.client.model.expressions.MqlUnchecked.Unchecked.PRESENT;
 
 public interface MapExpression<T extends Expression> extends Expression {
 
@@ -29,6 +30,7 @@ default BooleanExpression has(String key) {
     }
 
     // TODO-END doc "user asserts"
+    @MqlUnchecked(PRESENT)
     T get(StringExpression key);
 
     // TODO-END doc "user asserts"

driver-core/src/main/com/mongodb/client/model/expressions/MqlUnchecked.java

@@ -0,0 +1,75 @@
+/*
+ * 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.expressions;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Documents places where the API relies on a user asserting
+ * something that is not checked at run-time.
+ * If the assertion turns out to be false, the API behavior is unspecified.
+ *
+ * <p>This class is not part of the public API and may be removed or changed at any time</p>
+ */
+@Documented
+@Retention(RetentionPolicy.SOURCE)
+@Target({ElementType.METHOD, ElementType.TYPE_USE})
+public @interface MqlUnchecked {
+    /**
+     * @return A hint on the user assertion the API relies on.
+     */
+    Unchecked[] value();
+
+    /**
+     * @see MqlUnchecked#value()
+     */
+    enum Unchecked {
+        /**
+         * The API relies on the values it encounters being of the type
+         * implied/specified by or inferred from the user code.
+         * For example, {@link com.mongodb.client.model.expressions.DocumentExpression#getBoolean(String)}
+         * relies on the values of the document field being of the
+         * {@linkplain com.mongodb.client.model.expressions.BooleanExpression boolean} type.
+         */
+        TYPE,
+        /**
+         * The API checks the raw type, but relies on the type argument
+         * implied/specified by or inferred from the user code being correct.
+         * For example, {@link com.mongodb.client.model.expressions.Expression#isArrayOr(ArrayExpression)}
+         * checks that the value is of the
+         * {@linkplain com.mongodb.client.model.expressions.ArrayExpression array} raw type,
+         * but relies on the elements of the array being of the type derived from the user code.
+         *
+         * <p>One may think of it as a more specific version of {@link #TYPE}.</p>
+         */
+        TYPE_ARGUMENT,
+        /**
+         * The API relies on the array being non-empty.
+         * For example, {@link com.mongodb.client.model.expressions.ArrayExpression#first()}.
+         */
+        NON_EMPTY,
+        /**
+         * The API relies on the element identified by index, name, etc., being present in the
+         * {@linkplain com.mongodb.client.model.expressions.DocumentExpression document} involved.
+         * For example, {@link com.mongodb.client.model.expressions.DocumentExpression#getField(String)}.
+         */
+        PRESENT,
+    }
+}