Add @MqlUnchecked

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

@@ -19,37 +19,42 @@
 import java.util.function.Function;
 
 import static com.mongodb.client.model.expressions.Expressions.of;
+import static com.mongodb.client.model.expressions.MqlUnchecked.Unchecked.PRESENT;
 
 /**
- * Expresses an array value. An array value is a finite, ordered collection of
- * elements of a certain type.
+ * An array {@link Expression value} in the context of the MongoDB Query
+ * Language (MQL). An array is a finite, ordered collection of elements of a
+ * certain type. It is also known as a finite mathematical sequence.
  *
- * @param <T> the type of the elements in the array
+ * @param <T> the type of the elements
  */
 public interface ArrayExpression<T extends Expression> extends Expression {
 
     /**
-     * Returns an array consisting of those elements in this array that match
-     * the given predicate condition. Evaluates each expression in this array
-     * according to the cond function. If cond evaluates to logical true, then
-     * the element is preserved; if cond evaluates to logical false, the element
-     * is omitted.
+     * An array consisting of only those elements in {@code this} array that
+     * match the provided predicate.
      *
-     * @param cond the function to apply to each element
-     * @return the new array
+     * @param predicate the predicate to apply to each element to determine if
+     *                  it should be included.
+     * @return the resulting array.
      */
-    ArrayExpression<T> filter(Function<? super T, ? extends BooleanExpression> cond);
+    ArrayExpression<T> filter(Function<? super T, ? extends BooleanExpression> predicate);
 
     /**
-     * Returns an array consisting of the results of applying the given function
-     * to the elements of this array.
+     * An array consisting of the results of applying the provided function to
+     * the elements of {@code this} array.
      *
-     * @param in the function to apply to each element
-     * @return the new array
-     * @param <R> the type contained in the resulting array
+     * @param in the function to apply to each element.
+     * @return the resulting array.
+     * @param <R> the type of the elements of the resulting array.
      */
     <R extends Expression> ArrayExpression<R> map(Function<? super T, ? extends R> in);
 
+    /**
+     * The size of {@code this} array.
+     *
+     * @return the size.
+     */
     IntegerExpression size();
 
     BooleanExpression any(Function<? super T, BooleanExpression> predicate);
@@ -81,6 +86,7 @@ public interface ArrayExpression<T extends Expression> extends Expression {
      * @param i
      * @return
      */
+    @MqlUnchecked(PRESENT)
     T elementAt(IntegerExpression i);
 
     default T elementAt(final int i) {
@@ -91,6 +97,7 @@ default T elementAt(final int i) {
      * user asserts that array is not empty
      * @return
      */
+    @MqlUnchecked(PRESENT)
     T first();
 
     /**
@@ -113,7 +120,25 @@ default ArrayExpression<T> slice(final int start, final int length) {
 
     ArrayExpression<T> distinct();
 
+    /**
+     * The result of passing {@code this} value to the provided function.
+     * Equivalent to {@code f.apply(this)}, and allows lambdas and static,
+     * user-defined functions to use the chaining syntax.
+     *
+     * @see Expression#passTo
+     * @param f the function to apply.
+     * @return the resulting value.
+     * @param <R> the type of the resulting value.
+     */
     <R extends Expression> R passArrayTo(Function<? super ArrayExpression<T>, ? extends R> f);
 
-    <R extends Expression> R switchArrayOn(Function<Branches<ArrayExpression<T>>, ? extends BranchesTerminal<ArrayExpression<T>, ? extends R>> on);
+    /**
+     * The result of applying the provided switch mapping to {@code this} value.
+     *
+     * @see Expression#switchOn
+     * @param mapping the switch mapping.
+     * @return the resulting value.
+     * @param <R> the type of the resulting value.
+     */
+    <R extends Expression> R switchArrayOn(Function<Branches<ArrayExpression<T>>, ? extends BranchesTerminal<ArrayExpression<T>, ? extends R>> mapping);
 }

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

@@ -19,7 +19,8 @@
 import java.util.function.Function;
 
 /**
- * A logical boolean value, either true or false.
+ * A boolean {@linkplain Expression value} in the context of the
+ * MongoDB Query Language (MQL).
  */
 public interface BooleanExpression extends Expression {
 
@@ -45,20 +46,37 @@ public interface BooleanExpression extends Expression {
      * @return the resulting value.
      */
     BooleanExpression and(BooleanExpression other);
-    // TODO-END check the evaluation semantics of and/or
 
     /**
-     * The {@code left} branch when {@code this} is true,
-     * and the {@code right} branch otherwise.
+     * The {@code ifTrue} value when {@code this} is true,
+     * and the {@code ifFalse} value otherwise.
      *
-     * @param left the left branch.
-     * @param right the right branch.
+     * @param ifTrue the ifTrue value.
+     * @param ifFalse the ifFalse value.
      * @return the resulting value.
      * @param <T> The type of the resulting expression.
      */
-    <T extends Expression> T cond(T left, T right);
+    <T extends Expression> T cond(T ifTrue, T ifFalse);
 
+    /**
+     * The result of passing {@code this} value to the provided function.
+     * Equivalent to {@code f.apply(this)}, and allows lambdas and static,
+     * user-defined functions to use the chaining syntax.
+     *
+     * @see Expression#passTo
+     * @param f the function to apply.
+     * @return the resulting value.
+     * @param <R> the type of the resulting value.
+     */
     <R extends Expression> R passBooleanTo(Function<? super BooleanExpression, ? extends R> f);
 
-    <R extends Expression> R switchBooleanOn(Function<Branches<BooleanExpression>, ? extends BranchesTerminal<BooleanExpression, ? extends R>> on);
+    /**
+     * The result of applying the provided switch mapping to {@code this} value.
+     *
+     * @see Expression#switchOn
+     * @param mapping the switch mapping.
+     * @return the resulting value.
+     * @param <R> the type of the resulting value.
+     */
+    <R extends Expression> R switchBooleanOn(Function<Branches<BooleanExpression>, ? extends BranchesTerminal<BooleanExpression, ? extends R>> mapping);
 }

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/DateExpression.java

@@ -19,8 +19,9 @@
 import java.util.function.Function;
 
 /**
- * An instantaneous date and time. Tracks a UTC datetime, the number of
- * milliseconds since the Unix epoch. Does not track the timezone.
+ * A UTC date-time {@linkplain Expression value} in the context
+ * of the MongoDB Query Language (MQL). Tracks the number of
+ * milliseconds since the Unix epoch, and does not track the timezone.
  */
 public interface DateExpression extends Expression {
 
@@ -123,11 +124,30 @@ public interface DateExpression extends Expression {
      * provided {@code timezone}, and formatted according to the {@code format}.
      *
      * @param timezone the UTC Offset or Olson Timezone Identifier.
-     * @param format the format specifier. TODO-END what standard is this?
+     * @param format the format specifier.
      * @return the resulting value.
      */
     StringExpression asString(StringExpression timezone, StringExpression format);
 
+    /**
+     * The result of passing {@code this} value to the provided function.
+     * Equivalent to {@code f.apply(this)}, and allows lambdas and static,
+     * user-defined functions to use the chaining syntax.
+     *
+     * @see Expression#passTo
+     * @param f the function to apply.
+     * @return the resulting value.
+     * @param <R> the type of the resulting value.
+     */
     <R extends Expression> R passDateTo(Function<? super DateExpression, ? extends R> f);
-    <R extends Expression> R switchDateOn(Function<Branches<DateExpression>, ? extends BranchesTerminal<DateExpression, ? extends R>> on);
+
+    /**
+     * The result of applying the provided switch mapping to {@code this} value.
+     *
+     * @see Expression#switchOn
+     * @param mapping the switch mapping.
+     * @return the resulting value.
+     * @param <R> the type of the resulting value.
+     */
+    <R extends Expression> R switchDateOn(Function<Branches<DateExpression>, ? extends BranchesTerminal<DateExpression, ? extends R>> mapping);
 }

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);
@@ -102,6 +106,25 @@ default <T extends Expression> MapExpression<T> getMap(final String fieldName, f
 
     MapExpression<Expression> asMap();
 
+    /**
+     * The result of passing {@code this} value to the provided function.
+     * Equivalent to {@code f.apply(this)}, and allows lambdas and static,
+     * user-defined functions to use the chaining syntax.
+     *
+     * @see Expression#passTo
+     * @param f the function to apply.
+     * @return the resulting value.
+     * @param <R> the type of the resulting value.
+     */
     <R extends Expression> R passDocumentTo(Function<? super DocumentExpression, ? extends R> f);
-    <R extends Expression> R switchDocumentOn(Function<Branches<DocumentExpression>, ? extends BranchesTerminal<DocumentExpression, ? extends R>> on);
+
+    /**
+     * The result of applying the provided switch mapping to {@code this} value.
+     *
+     * @see Expression#switchOn
+     * @param mapping the switch mapping.
+     * @return the resulting value.
+     * @param <R> the type of the resulting value.
+     */
+    <R extends Expression> R switchDocumentOn(Function<Branches<DocumentExpression>, ? extends BranchesTerminal<DocumentExpression, ? extends R>> mapping);
 }

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

@@ -18,6 +18,15 @@
 
 import static com.mongodb.client.model.expressions.Expressions.of;
 
+/**
+ * A map entry {@linkplain Expression value} in the context
+ * of the MongoDB Query Language (MQL). An entry has a
+ * {@linkplain StringExpression string} key and some
+ * {@linkplain Expression value}. Entries are used with
+ * {@linkplain MapExpression maps}.
+ *
+ * @param <T> The type of the value
+ */
 public interface EntryExpression<T extends Expression> extends Expression {
     StringExpression getKey();