Javadoc for expressions, part 2

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,19 +16,24 @@
 
 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;
 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
  * 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
+ * @since 4.9.0
  */
+@Sealed
+@Beta(Beta.Reason.CLIENT)
 public interface ArrayExpression<T extends Expression> extends Expression {
 
     /**
@@ -58,67 +63,276 @@ public interface ArrayExpression<T extends Expression> extends Expression {
      */
     IntegerExpression size();
 
+    /**
+     * 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);
 
+    /**
+     * Whether all values in {@code this} array satisfy the predicate.
+     *
+     * @param predicate the predicate.
+     * @return the resulting value.
+     */
     BooleanExpression all(Function<? super T, BooleanExpression> predicate);
 
+    /**
+     * The sum of adding together all the values of {@code this} array,
+     * via the provided {@code mapper}. Returns 0 if the array is empty.
+     *
+     * <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 identity function {@code array.sum(v -> v)} should
+     * be used.
+     *
+     * @param mapper the mapper function.
+     * @return the resulting value.
+     */
     NumberExpression sum(Function<? super T, ? extends NumberExpression> mapper);
 
+    /**
+     * The product of multiplying together all the values of {@code this} array,
+     * via the provided {@code mapper}. Returns 1 if the array is empty.
+     *
+     * <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 identity function {@code array.multiply(v -> v)}
+     * should be used.
+     *
+     * @param mapper the mapper function.
+     * @return the resulting value.
+     */
     NumberExpression multiply(Function<? super T, ? extends NumberExpression> mapper);
 
+    /**
+     * The {@linkplain #gt(Expression) largest} value all the values of
+     * {@code this} array, or the {@code other} value if this array is empty.
+     *
+     * @mongodb.server.release 5.2
+     * @param other the other value.
+     * @return the resulting value.
+     */
     T max(T other);
 
+    /**
+     * The {@linkplain #lt(Expression) smallest} value all the values of
+     * {@code this} array, or the {@code other} value if this array is empty.
+     *
+     * @mongodb.server.release 5.2
+     * @param other the other value.
+     * @return the resulting value.
+     */
     T min(T other);
 
+    /**
+     * The {@linkplain #gt(Expression) largest} {@code n} elements of
+     * {@code this} array, or all elements if the array contains fewer than
+     * {@code n} elements.
+     *
+     * @mongodb.server.release 5.2
+     * @param n the number of elements.
+     * @return the resulting value.
+     */
     ArrayExpression<T> maxN(IntegerExpression n);
+
+    /**
+     * The {@linkplain #lt(Expression) smallest} {@code n} elements of
+     * {@code this} array, or all elements if the array contains fewer than
+     * {@code n} elements.
+     *
+     * @mongodb.server.release 5.2
+     * @param n the number of elements.
+     * @return the resulting value.
+     */
     ArrayExpression<T> minN(IntegerExpression n);
 
+    /**
+     * The string-concatenation of all the values of {@code this} array,
+     * via the provided {@code mapper}. Returns the empty string if the array
+     * is empty.
+     *
+     * <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 identity function {@code array.join(v -> v)} should
+     * be used.
+     *
+     * @param mapper the mapper function.
+     * @return the resulting value.
+     */
     StringExpression join(Function<? super T, StringExpression> mapper);
 
+    /**
+     * 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 identity function {@code array.concat(v -> v)} should
+     * be used.
+     *
+     * @param mapper the mapper function.
+     * @return the resulting value.
+     * @param <R> the type of the elements of the array.
+     */
     <R extends Expression> ArrayExpression<R> concat(Function<? super T, ? extends ArrayExpression<? extends R>> mapper);
 
+    /**
+     * 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 identity function {@code array.union(v -> v)} should
+     * be used.
+     *
+     * @param mapper the mapper function.
+     * @return the resulting value.
+     * @param <R> the type of the elements of the array.
+     */
     <R extends Expression> ArrayExpression<R> union(Function<? super T, ? extends ArrayExpression<? extends R>> mapper);
 
+    /**
+     * The {@linkplain MapExpression map} value corresponding to the
+     * {@linkplain EntryExpression entry} values of {@code this} 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 identity function {@code array.union(v -> v)} should
+     * be used.
+     *
+     * @see MapExpression#entrySet()
+     * @param mapper the mapper function.
+     * @return the resulting value.
+     * @param <R> the type of the resulting map's values.
+     */
     <R extends Expression> MapExpression<R> asMap(Function<? super T, ? extends EntryExpression<? extends R>> mapper);
 
     /**
-     * user asserts that i is in bounds for the array
+     * Returns the element at the provided index {@code i} for
+     * {@code this} array.
      *
-     * @param i
-     * @return
+     * <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 specified.
+     *
+     * @param i the index.
+     * @return the resulting value.
      */
     @MqlUnchecked(PRESENT)
     T elementAt(IntegerExpression i);
 
+    /**
+     * Returns the element at the provided index {@code i} for
+     * {@code this} array.
+     *
+     * <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 specified.
+     *
+     * @param i the index.
+     * @return the resulting value.
+     */
+    @MqlUnchecked(PRESENT)
     default T elementAt(final int i) {
         return this.elementAt(of(i));
     }
 
     /**
-     * user asserts that array is not empty
-     * @return
+     * Returns the first element of {@code this} array.
+     *
+     * <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 specified.
+     *
+     * @mongodb.server.release 4.4
+     * @return the resulting value.
      */
-    @MqlUnchecked(NON_EMPTY)
+    @MqlUnchecked(PRESENT)
     T first();
 
     /**
-     * user asserts that array is not empty
-     * @return
+     * Returns the last element of {@code this} array.
+     *
+     * <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 specified.
+     *
+     * @mongodb.server.release 4.4
+     * @return the resulting value.
      */
+    @MqlUnchecked(PRESENT)
     T last();
 
-    BooleanExpression contains(T contains);
+    /**
+     * Whether {@code this} array contains a value that is
+     * {@linkplain #eq equal} to the provided {@code value}.
+     *
+     * @param value the value.
+     * @return the resulting value.
+     */
+    BooleanExpression contains(T value);
 
-    ArrayExpression<T> concat(ArrayExpression<? extends T> array);
+    /**
+     * The result of concatenating {@code this} array first with
+     * the {@code other} array ensuing.
+     *
+     * @param other the other array.
+     * @return the resulting array.
+     */
+    ArrayExpression<T> concat(ArrayExpression<? extends T> other);
 
+    /**
+     * The subarray of {@code this} array, from the {@code start} index
+     * inclusive, and continuing for the specified {@code length}, up to
+     * the end of the array.
+     *
+     * @param start start index
+     * @param length length
+     * @return the resulting value
+     */
     ArrayExpression<T> slice(IntegerExpression start, IntegerExpression length);
 
+    /**
+     * The subarray of {@code this} array, from the {@code start} index
+     * inclusive, and continuing for the specified {@code length}, or
+     * to the end of the array.
+     *
+     * @param start start index
+     * @param length length
+     * @return the resulting value
+     */
     default ArrayExpression<T> slice(final int start, final int length) {
         return this.slice(of(start), of(length));
     }
 
-    ArrayExpression<T> union(ArrayExpression<? extends T> set);
+    /**
+     * The set-union of {@code this} array and the {@code other} array ensuing,
+     * containing only the distinct values of both.
+     * No guarantee is made regarding order.
+     *
+     * @param other the other array.
+     * @return the resulting array.
+     */
+    ArrayExpression<T> union(ArrayExpression<? extends T> other);
+
 
+    /**
+     * An array containing only the distinct values of {@code this} array.
+     * No guarantee is made regarding order.
+     *
+     * @return the resulting value
+     */
     ArrayExpression<T> distinct();
 
     /**

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 {
 
     /**