Implement boolean expressions (#1025)

JAVA-4779

Author: katcharov

config/checkstyle/suppressions.xml

@@ -157,4 +157,6 @@
     <suppress checks="ParameterName" files=".*org[\\/]bson[\\/]codecs[\\/]pojo[\\/]bench[\\/].*"/>
     <suppress checks="Regexp" files=".*org[\\/]bson[\\/]codecs[\\/]pojo[\\/]bench[\\/].*"/>
 
+    <!-- Complicated expressions for demo purposes -->
+    <suppress checks="SimplifyBooleanExpressionCheck" files="ExpressionsFunctionalTest"/>
 </suppressions>

driver-core/src/main/com/mongodb/MongoClientSettings.java

@@ -19,6 +19,7 @@
 import com.mongodb.annotations.Immutable;
 import com.mongodb.annotations.NotThreadSafe;
 import com.mongodb.client.gridfs.codecs.GridFSFileCodecProvider;
+import com.mongodb.client.model.expressions.ExpressionCodecProvider;
 import com.mongodb.client.model.geojson.codecs.GeoJsonCodecProvider;
 import com.mongodb.connection.ClusterSettings;
 import com.mongodb.connection.ConnectionPoolSettings;
@@ -76,6 +77,7 @@ public final class MongoClientSettings {
                     new JsonObjectCodecProvider(),
                     new BsonCodecProvider(),
                     new EnumCodecProvider(),
+                    new ExpressionCodecProvider(),
                     new Jep395RecordCodecProvider()));
 
     private final ReadPreference readPreference;
@@ -123,6 +125,7 @@ public final class MongoClientSettings {
      * <li>{@link org.bson.codecs.JsonObjectCodecProvider}</li>
      * <li>{@link org.bson.codecs.BsonCodecProvider}</li>
      * <li>{@link org.bson.codecs.EnumCodecProvider}</li>
+     * <li>{@link ExpressionCodecProvider}</li>
      * <li>{@link com.mongodb.Jep395RecordCodecProvider}</li>
      * </ul>
      *

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

@@ -0,0 +1,27 @@
+/*
+ * 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;
+
+/**
+ * Expresses an array value. An array value is a finite, ordered collection of
+ * elements of a certain type.
+ *
+ * @param <T> the type of the elements in the array
+ */
+public interface ArrayExpression<T extends Expression> extends Expression {
+
+}

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

@@ -0,0 +1,61 @@
+/*
+ * 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;
+
+/**
+ * Expresses a boolean value.
+ */
+public interface BooleanExpression extends Expression {
+
+    /**
+     * Returns logical true if this expression evaluates to logical false.
+     * Returns logical false if this expression evaluates to logical true.
+     *
+     * @return True if false; false if true.
+     */
+    BooleanExpression not();
+
+    /**
+     * Returns logical true if this or the other expression evaluates to logical
+     * true. Returns logical false if both evaluate to logical false.
+     *
+     * @param or the other boolean expression.
+     * @return True if either true, false if both false.
+     */
+    BooleanExpression or(BooleanExpression or);
+
+    /**
+     * Returns logical true if both this and the other expression evaluate to
+     * logical true. Returns logical false if either evaluate to logical false.
+     *
+     * @param and the other boolean expression.
+     * @return true if both true, false if either false.
+     */
+    BooleanExpression and(BooleanExpression and);
+
+    /**
+     * If this expression evaluates to logical true, returns the result of the
+     * evaluated left branch expression. If this evaluates to logical false,
+     * returns the result of the evaluated right branch expression.
+     *
+     * @param left the left branch expression
+     * @param right the right branch expression
+     * @return left if true, right if false.
+     * @param <T> The type of the resulting expression.
+     */
+    <T extends Expression> T cond(T left, T right);
+}

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

@@ -0,0 +1,24 @@
+/*
+ * 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;
+
+/**
+ * Expresses a date value.
+ */
+public interface DateExpression extends Expression {
+
+}

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

@@ -0,0 +1,25 @@
+/*
+ * 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;
+
+/**
+ * Expresses a document value. A document is an ordered set of fields, where the
+ * key is a string value, mapping to a value of any other expression type.
+ */
+public interface DocumentExpression extends Expression {
+
+}

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

@@ -0,0 +1,47 @@
+/*
+ * 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 com.mongodb.annotations.Evolving;
+
+/**
+ * Expressions express values that may be represented in (or computations that
+ * may be performed within) a MongoDB server. Each expression evaluates to some
+ * value, much like any Java expression evaluates to some value. Expressions may
+ * be thought of as boxed values. Evaluation of an expression will usually occur
+ * on a MongoDB server.
+ *
+ * <p>Users should treat these interfaces as sealed, and must not implement any
+ * expression interfaces.
+ *
+ * <p>Expressions are typed. It is possible to execute expressions against data
+ * that is of the wrong type, such as by applying the "not" boolean expression
+ * to a document field that is an integer, null, or missing. This API does not
+ * define the output in such cases (though the output may be defined within the
+ * execution context - the server - where the expression is evaluated). Users of
+ * this API must mitigate any risk of applying an expression to some type where
+ * resulting behaviour is not defined by this API (for example, by checking for
+ * null, by ensuring that field types are correctly specified). Likewise, unless
+ * otherwise specified, this API does not define the order of evaluation for all
+ * arguments, and whether all arguments to some expression will be evaluated.
+ *
+ * @see Expressions
+ */
+@Evolving
+public interface Expression {
+
+}

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

@@ -0,0 +1,53 @@
+/*
+ * 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 com.mongodb.annotations.Beta;
+import com.mongodb.annotations.Immutable;
+import com.mongodb.lang.Nullable;
+import org.bson.codecs.Codec;
+import org.bson.codecs.configuration.CodecProvider;
+import org.bson.codecs.configuration.CodecRegistry;
+
+/**
+ * Provides Codec instances for MQL expressions.
+ *
+ * <p>Responsible for converting values and computations expressed using the
+ * driver's implementation of the {@link Expression} API into the corresponding
+ * values and computations expressed in MQL BSON. Booleans are converted to BSON
+ * booleans, documents to BSON documents, and so on. The specific structure
+ * representing numbers is preserved where possible (that is, number literals
+ * specified as Java longs are converted into BSON int64, and so on).
+ *
+ * <p>This API is marked Beta because it may be replaced with a generalized
+ * mechanism for converting expressions. This would only affect users who use
+ * MqlExpressionCodecProvider directly in custom codec providers. This Beta
+ * annotation does not imply that the Expressions API in general is Beta.
+ */
+@Beta(Beta.Reason.CLIENT)
+@Immutable
+public final class ExpressionCodecProvider implements CodecProvider {
+    @Override
+    @SuppressWarnings("unchecked")
+    @Nullable
+    public <T> Codec<T> get(final Class<T> clazz, final CodecRegistry registry) {
+        if (MqlExpression.class.equals(clazz)) {
+            return (Codec<T>) new MqlExpressionCodec(registry);
+        }
+        return null;
+    }
+}

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

@@ -0,0 +1,63 @@
+/*
+ * 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 org.bson.BsonBoolean;
+import org.bson.BsonInt32;
+import org.bson.BsonString;
+
+/**
+ * Convenience methods related to {@link Expression}.
+ */
+public final class Expressions {
+
+    private Expressions() {}
+
+    /**
+     * Returns an expression having the same boolean value as the provided
+     * boolean primitive.
+     *
+     * @param of the boolean primitive
+     * @return the boolean expression
+     */
+    public static BooleanExpression of(final boolean of) {
+        // we intentionally disallow ofBoolean(null)
+        return new MqlExpression<>((codecRegistry) -> new BsonBoolean(of));
+    }
+
+    /**
+     * Returns an expression having the same integer value as the provided
+     * int primitive.
+     *
+     * @param of the int primitive
+     * @return the integer expression
+     */
+    public static IntegerExpression of(final int of) {
+        return new MqlExpression<>((codecRegistry) -> new BsonInt32(of));
+    }
+
+    /**
+     * Returns an expression having the same string value as the provided
+     * string.
+     *
+     * @param of the string
+     * @return the string expression
+     */
+    public static StringExpression of(final String of) {
+        return new MqlExpression<>((codecRegistry) -> new BsonString(of));
+    }
+}

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

@@ -0,0 +1,24 @@
+/*
+ * 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;
+
+/**
+ * Expresses an integer value.
+ */
+public interface IntegerExpression extends NumberExpression {
+
+}