Update and add documentation, add tests, fix minor issues (#1070)

Rename extractBsonValue

Fix access modifiers

Remove excess comments

Update docs

Fix: behaviour of get

Add notNull to API, add notNullApi test

Fix docs/annotations, tests

Fix docs, annotations, since

Fix docs

Revert external

Add missing MqlUnchecked

Fix missing null checks

Checkstyle

JAVA-4799

Author: katcharov

driver-core/src/main/com/mongodb/annotations/Sealed.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ * Copyright 2010 The Guava Authors
+ * Copyright 2011 The Guava Authors
+ *
+ * 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.annotations;
+
+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;
+
+/**
+ * Signifies that the annotated class or interface should be treated as sealed:
+ * it must not be extended or implemented.
+ *
+ * <p>Using such classes and interfaces is no different from using ordinary
+ * unannotated classes and interfaces.
+ *
+ * <p>This annotation does not imply that the API is experimental or
+ * {@link Beta}, or that the quality or performance of the API is inferior.
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.TYPE)
+@Documented
+@Sealed
+public @interface Sealed {
+}

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

@@ -16,6 +16,9 @@
 
 package com.mongodb.client.model.expressions;
 
+import com.mongodb.annotations.Beta;
+import com.mongodb.annotations.Sealed;
+
 import java.util.function.Function;
 
 import static com.mongodb.client.model.expressions.Expressions.of;
@@ -27,7 +30,10 @@
  * certain type. It is also known as a finite mathematical sequence.
  *
  * @param <T> the type of the elements
+ * @since 4.9.0
  */
+@Sealed
+@Beta(Beta.Reason.CLIENT)
 public interface ArrayExpression<T extends Expression> extends Expression {
 
     /**
@@ -58,15 +64,15 @@ public interface ArrayExpression<T extends Expression> extends Expression {
     IntegerExpression size();
 
     /**
-     * True if any value in {@code this} array satisfies the predicate.
+     * Whether any value in {@code this} array satisfies the predicate.
      *
      * @param predicate the predicate.
      * @return the resulting value.
      */
     BooleanExpression any(Function<? super T, BooleanExpression> predicate);
 
     /**
-     * True if all values in {@code this} array satisfy the predicate.
+     * Whether all values in {@code this} array satisfy the predicate.
      *
      * @param predicate the predicate.
      * @return the resulting value.
@@ -79,7 +85,7 @@ public interface ArrayExpression<T extends Expression> extends Expression {
      *
      * <p>The mapper may be used to transform the values of {@code this} array
      * into {@linkplain NumberExpression numbers}. If no transformation is
-     * necessary, then the identify function {@code array.sum(v -> v)} should
+     * necessary, then the identity function {@code array.sum(v -> v)} should
      * be used.
      *
      * @param mapper the mapper function.
@@ -93,7 +99,7 @@ public interface ArrayExpression<T extends Expression> extends Expression {
      *
      * <p>The mapper may be used to transform the values of {@code this} array
      * into {@linkplain NumberExpression numbers}. If no transformation is
-     * necessary, then the identify function {@code array.multiply(v -> v)}
+     * necessary, then the identity function {@code array.multiply(v -> v)}
      * should be used.
      *
      * @param mapper the mapper function.
@@ -150,7 +156,7 @@ public interface ArrayExpression<T extends Expression> extends Expression {
      *
      * <p>The mapper may be used to transform the values of {@code this} array
      * into {@linkplain StringExpression strings}. If no transformation is
-     * necessary, then the identify function {@code array.join(v -> v)} should
+     * necessary, then the identity function {@code array.join(v -> v)} should
      * be used.
      *
      * @param mapper the mapper function.
@@ -159,13 +165,14 @@ public interface ArrayExpression<T extends Expression> extends Expression {
     StringExpression join(Function<? super T, StringExpression> mapper);
 
     /**
-     * The array-concatenation of all the array values of {@code this} array,
+     * The {@linkplain #concat(ArrayExpression) array-concatenation}
+     * of all the array values of {@code this} array,
      * via the provided {@code mapper}. Returns the empty array if the array
      * is empty.
      *
      * <p>The mapper may be used to transform the values of {@code this} array
      * into {@linkplain ArrayExpression arrays}. If no transformation is
-     * necessary, then the identify function {@code array.concat(v -> v)} should
+     * necessary, then the identity function {@code array.concat(v -> v)} should
      * be used.
      *
      * @param mapper the mapper function.
@@ -175,13 +182,14 @@ public interface ArrayExpression<T extends Expression> extends Expression {
     <R extends Expression> ArrayExpression<R> concat(Function<? super T, ? extends ArrayExpression<? extends R>> mapper);
 
     /**
-     * The set union of all the array values of {@code this} array,
+     * The {@linkplain #union(ArrayExpression) set-union}
+     * of all the array values of {@code this} array,
      * via the provided {@code mapper}. Returns the empty array if the array
      * is empty.
      *
      * <p>The mapper may be used to transform the values of {@code this} array
      * into {@linkplain ArrayExpression arrays}. If no transformation is
-     * necessary, then the identify function {@code array.union(v -> v)} should
+     * necessary, then the identity function {@code array.union(v -> v)} should
      * be used.
      *
      * @param mapper the mapper function.
@@ -193,12 +201,12 @@ public interface ArrayExpression<T extends Expression> extends Expression {
     /**
      * The {@linkplain MapExpression map} value corresponding to the
      * {@linkplain EntryExpression entry} values of {@code this} array,
-     * via the provided {@code mapper}. Returns the empty array if the array
+     * via the provided {@code mapper}. Returns the empty map if the array
      * is empty.
      *
      * <p>The mapper may be used to transform the values of {@code this} array
      * into {@linkplain EntryExpression entries}. If no transformation is
-     * necessary, then the identify function {@code array.union(v -> v)} should
+     * necessary, then the identity function {@code array.union(v -> v)} should
      * be used.
      *
      * @see MapExpression#entrySet()
@@ -215,7 +223,7 @@ public interface ArrayExpression<T extends Expression> extends Expression {
      * <p>Warning: The use of this method is an assertion that
      * the index {@code i} is in bounds for the array.
      * If the index is out of bounds for this array, then
-     * the behaviour of the API is not defined.
+     * the behaviour of the API is not specified.
      *
      * @param i the index.
      * @return the resulting value.
@@ -230,7 +238,7 @@ public interface ArrayExpression<T extends Expression> extends Expression {
      * <p>Warning: The use of this method is an assertion that
      * the index {@code i} is in bounds for the array.
      * If the index is out of bounds for this array, then
-     * the behaviour of the API is not defined.
+     * the behaviour of the API is not specified.
      *
      * @param i the index.
      * @return the resulting value.
@@ -245,7 +253,7 @@ default T elementAt(final int i) {
      *
      * <p>Warning: The use of this method is an assertion that
      * the array is not empty.
-     * If the array is empty then the behaviour of the API is not defined.
+     * If the array is empty then the behaviour of the API is not specified.
      *
      * @mongodb.server.release 4.4
      * @return the resulting value.
@@ -258,15 +266,16 @@ default T elementAt(final int i) {
      *
      * <p>Warning: The use of this method is an assertion that
      * the array is not empty.
-     * If the array is empty then the behaviour of the API is not defined.
+     * If the array is empty then the behaviour of the API is not specified.
      *
      * @mongodb.server.release 4.4
      * @return the resulting value.
      */
+    @MqlUnchecked(PRESENT)
     T last();
 
     /**
-     * True if {@code this} array contains a value that is
+     * Whether {@code this} array contains a value that is
      * {@linkplain #eq equal} to the provided {@code value}.
      *
      * @param value the value.

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

@@ -16,12 +16,19 @@
 
 package com.mongodb.client.model.expressions;
 
+import com.mongodb.annotations.Beta;
+import com.mongodb.annotations.Sealed;
+
 import java.util.function.Function;
 
 /**
  * A boolean {@linkplain Expression value} in the context of the
  * MongoDB Query Language (MQL).
+ *
+ * @since 4.9.0
  */
+@Sealed
+@Beta(Beta.Reason.CLIENT)
 public interface BooleanExpression extends Expression {
 
     /**

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

@@ -16,6 +16,9 @@
 
 package com.mongodb.client.model.expressions;
 
+import com.mongodb.annotations.Beta;
+import com.mongodb.assertions.Assertions;
+
 import java.util.ArrayList;
 import java.util.List;
 import java.util.function.Function;
@@ -28,10 +31,12 @@
  * to succeed will produce the value that it specifies. If no check succeeds,
  * then the operation
  * {@linkplain BranchesIntermediary#defaults(Function) defaults} to a default
- * value, or if none is specified, the operation causes an error.
+ * value, or if none is specified, the operation will cause an error.
  *
  * @param <T> the type of the values that may be checked.
+ * @since 4.9.0
  */
+@Beta(Beta.Reason.CLIENT)
 public final class Branches<T extends Expression> {
 
     Branches() {
@@ -59,6 +64,8 @@ private static <T extends Expression> MqlExpression<?> mqlEx(final T value) {
      * @return the appended sequence of checks.
      */
     public <R extends Expression> BranchesIntermediary<T, R> is(final Function<? super T, BooleanExpression> predicate, final Function<? super T, ? extends R> mapping) {
+        Assertions.notNull("predicate", predicate);
+        Assertions.notNull("mapping", mapping);
         return with(value -> new SwitchCase<>(predicate.apply(value), mapping.apply(value)));
     }
 
@@ -74,6 +81,8 @@ public <R extends Expression> BranchesIntermediary<T, R> is(final Function<? sup
      * @return the appended sequence of checks.
      */
     public <R extends Expression> BranchesIntermediary<T, R> eq(final T v, final Function<? super T, ? extends R> mapping) {
+        Assertions.notNull("v", v);
+        Assertions.notNull("mapping", mapping);
         return is(value -> value.eq(v), mapping);
     }
 
@@ -89,6 +98,8 @@ public <R extends Expression> BranchesIntermediary<T, R> eq(final T v, final Fun
      * @return the appended sequence of checks.
      */
     public <R extends Expression> BranchesIntermediary<T, R> lt(final T v, final Function<? super T, ? extends R> mapping) {
+        Assertions.notNull("v", v);
+        Assertions.notNull("mapping", mapping);
         return is(value -> value.lt(v), mapping);
     }
 
@@ -104,6 +115,8 @@ public <R extends Expression> BranchesIntermediary<T, R> lt(final T v, final Fun
      * @return the appended sequence of checks.
      */
     public <R extends Expression> BranchesIntermediary<T, R> lte(final T v, final Function<? super T, ? extends R> mapping) {
+        Assertions.notNull("v", v);
+        Assertions.notNull("mapping", mapping);
         return is(value -> value.lte(v), mapping);
     }
 
@@ -119,12 +132,13 @@ public <R extends Expression> BranchesIntermediary<T, R> lte(final T v, final Fu
      * @param <R> the type of the produced value.
      */
     public <R extends Expression> BranchesIntermediary<T, R> isBoolean(final Function<? super BooleanExpression, ? extends R> mapping) {
+        Assertions.notNull("mapping", mapping);
         return is(v -> mqlEx(v).isBoolean(), v -> mapping.apply((BooleanExpression) v));
     }
 
     /**
      * A successful check for
-     * {@linkplain Expression#isBooleanOr(BooleanExpression) being a boolean}
+     * {@linkplain Expression#isNumberOr(NumberExpression) being a number}
      * produces a value specified by the {@code mapping}.
      *
      * @mongodb.server.release 4.4
@@ -133,6 +147,7 @@ public <R extends Expression> BranchesIntermediary<T, R> isBoolean(final Functio
      * @param <R> the type of the produced value.
      */
     public <R extends Expression> BranchesIntermediary<T, R> isNumber(final Function<? super NumberExpression, ? extends R> mapping) {
+        Assertions.notNull("mapping", mapping);
         return is(v -> mqlEx(v).isNumber(), v -> mapping.apply((NumberExpression) v));
     }
 
@@ -147,6 +162,7 @@ public <R extends Expression> BranchesIntermediary<T, R> isNumber(final Function
      * @param <R> the type of the produced value.
      */
     public <R extends Expression> BranchesIntermediary<T, R> isInteger(final Function<? super IntegerExpression, ? extends R> mapping) {
+        Assertions.notNull("mapping", mapping);
         return is(v -> mqlEx(v).isInteger(), v -> mapping.apply((IntegerExpression) v));
     }
 
@@ -160,6 +176,7 @@ public <R extends Expression> BranchesIntermediary<T, R> isInteger(final Functio
      * @param <R> the type of the produced value.
      */
     public <R extends Expression> BranchesIntermediary<T, R> isString(final Function<? super StringExpression, ? extends R> mapping) {
+        Assertions.notNull("mapping", mapping);
         return is(v -> mqlEx(v).isString(), v -> mapping.apply((StringExpression) v));
     }
 
@@ -173,6 +190,7 @@ public <R extends Expression> BranchesIntermediary<T, R> isString(final Function
      * @param <R> the type of the produced value.
      */
     public <R extends Expression> BranchesIntermediary<T, R> isDate(final Function<? super DateExpression, ? extends R> mapping) {
+        Assertions.notNull("mapping", mapping);
         return is(v -> mqlEx(v).isDate(), v -> mapping.apply((DateExpression) v));
     }
 
@@ -192,33 +210,33 @@ 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<@MqlUnchecked(TYPE_ARGUMENT) Q>, ? extends R> mapping) {
+        Assertions.notNull("mapping", mapping);
         return is(v -> mqlEx(v).isArray(), v -> mapping.apply((ArrayExpression<Q>) v));
     }
 
     /**
      * A successful check for
      * {@linkplain Expression#isDocumentOr(DocumentExpression) being a document}
+     * (or document-like value, see
+     * {@link MapExpression} and {@link EntryExpression})
      * produces a value specified by the {@code mapping}.
      *
-     * <p>Note: Any value considered to be a document by this API
-     * will also be considered a map, and vice-versa.
-     *
      * @param mapping the mapping.
      * @return the appended sequence of checks.
      * @param <R> the type of the produced value.
      */
     public <R extends Expression> BranchesIntermediary<T, R> isDocument(final Function<? super DocumentExpression, ? extends R> mapping) {
+        Assertions.notNull("mapping", mapping);
         return is(v -> mqlEx(v).isDocumentOrMap(), v -> mapping.apply((DocumentExpression) v));
     }
 
     /**
      * A successful check for
      * {@linkplain Expression#isMapOr(MapExpression) being a map}
+     * (or map-like value, see
+     * {@link DocumentExpression} and {@link EntryExpression})
      * produces a value specified by the {@code mapping}.
      *
-     * <p>Note: Any value considered to be a map by this API
-     * will also be considered a document, and vice-versa.
-     *
      * <p>Warning: The type argument of the map is not
      * enforced by the API. The use of this method is an
      * unchecked assertion that the type argument is correct.
@@ -230,6 +248,7 @@ public <R extends Expression> BranchesIntermediary<T, R> isDocument(final Functi
      */
     @SuppressWarnings("unchecked")
     public <R extends Expression, Q extends Expression> BranchesIntermediary<T, R> isMap(final Function<? super MapExpression<@MqlUnchecked(TYPE_ARGUMENT) Q>, ? extends R> mapping) {
+        Assertions.notNull("mapping", mapping);
         return is(v -> mqlEx(v).isDocumentOrMap(), v -> mapping.apply((MapExpression<Q>) v));
     }
 
@@ -243,6 +262,7 @@ public <R extends Expression, Q extends Expression> BranchesIntermediary<T, R> i
      * @param <R> the type of the produced value.
      */
     public <R extends Expression> BranchesIntermediary<T, R> isNull(final Function<? super Expression, ? extends R> mapping) {
+        Assertions.notNull("mapping", mapping);
         return is(v -> mqlEx(v).isNull(), v -> mapping.apply(v));
     }
 }