JAVA-2886: Add missing Nullable annotations

Added to:

* id parameter of Aggregates#group
* value parameter of some Filters methods
* value parameter for some Updates methods
* return value of MongoCollection#findOneAnd* methods

Author: jyemin

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

@@ -350,27 +350,27 @@ public static <TExpression> Bson graphLookup(final String from, final TExpressio
      * Creates a $group pipeline stage for the specified filter
      *
      * @param <TExpression>     the expression type
-     * @param id                the id expression for the group
+     * @param id                the id expression for the group, which may be null
      * @param fieldAccumulators zero or more field accumulator pairs
      * @return the $group pipeline stage
      * @mongodb.driver.manual reference/operator/aggregation/group/ $group
      * @mongodb.driver.manual meta/aggregation-quick-reference/#aggregation-expressions Expressions
      */
-    public static <TExpression> Bson group(final TExpression id, final BsonField... fieldAccumulators) {
+    public static <TExpression> Bson group(@Nullable final TExpression id, final BsonField... fieldAccumulators) {
         return group(id, asList(fieldAccumulators));
     }
 
     /**
      * Creates a $group pipeline stage for the specified filter
      *
      * @param <TExpression>     the expression type
-     * @param id                the id expression for the group
+     * @param id                the id expression for the group, which may be null
      * @param fieldAccumulators zero or more field accumulator pairs
      * @return the $group pipeline stage
      * @mongodb.driver.manual reference/operator/aggregation/group/ $group
      * @mongodb.driver.manual meta/aggregation-quick-reference/#aggregation-expressions Expressions
      */
-    public static <TExpression> Bson group(final TExpression id, final List<BsonField> fieldAccumulators) {
+    public static <TExpression> Bson group(@Nullable final TExpression id, final List<BsonField> fieldAccumulators) {
         return new GroupStage<TExpression>(id, fieldAccumulators);
     }
 

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

@@ -58,14 +58,14 @@ private Filters() {
      * Creates a filter that matches all documents where the value of _id field equals the specified value. Note that this doesn't
      * actually generate a $eq operator, as the query language doesn't require it.
      *
-     * @param value     the value
+     * @param value     the value, which may be null
      * @param <TItem>   the value type
      * @return the filter
      * @mongodb.driver.manual reference/operator/query/eq $eq
      *
      * @since 3.4
      */
-    public static <TItem> Bson eq(final TItem value) {
+    public static <TItem> Bson eq(@Nullable final TItem value) {
         return eq("_id", value);
     }
 
@@ -74,25 +74,25 @@ public static <TItem> Bson eq(final TItem value) {
      * actually generate a $eq operator, as the query language doesn't require it.
      *
      * @param fieldName the field name
-     * @param value     the value
+     * @param value     the value, which may be null
      * @param <TItem>   the value type
      * @return the filter
      * @mongodb.driver.manual reference/operator/query/eq $eq
      */
-    public static <TItem> Bson eq(final String fieldName, final TItem value) {
+    public static <TItem> Bson eq(final String fieldName, @Nullable final TItem value) {
         return new SimpleEncodingFilter<TItem>(fieldName, value);
     }
 
     /**
      * Creates a filter that matches all documents where the value of the field name does not equal the specified value.
      *
      * @param fieldName the field name
-     * @param value     the value
+     * @param value     the value, which may be null
      * @param <TItem>   the value type
      * @return the filter
      * @mongodb.driver.manual reference/operator/query/ne $ne
      */
-    public static <TItem> Bson ne(final String fieldName, final TItem value) {
+    public static <TItem> Bson ne(final String fieldName, @Nullable final TItem value) {
         return new OperatorFilter<TItem>("$ne", fieldName, value);
     }
 

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

@@ -16,6 +16,7 @@
 
 package com.mongodb.client.model;
 
+import com.mongodb.lang.Nullable;
 import org.bson.BsonDocument;
 import org.bson.BsonDocumentWriter;
 import org.bson.BsonInt32;
@@ -68,12 +69,12 @@ public static Bson combine(final List<? extends Bson> updates) {
      * Creates an update that sets the value of the field with the given name to the given value.
      *
      * @param fieldName the non-null field name
-     * @param value     the value
+     * @param value     the value, which may be null
      * @param <TItem>   the value type
      * @return the update
      * @mongodb.driver.manual reference/operator/update/set/ $set
      */
-    public static <TItem> Bson set(final String fieldName, final TItem value) {
+    public static <TItem> Bson set(final String fieldName, @Nullable final TItem value) {
         return new SimpleUpdate<TItem>(fieldName, value, "$set");
     }
 
@@ -93,13 +94,13 @@ public static Bson unset(final String fieldName) {
      * results in an insert of a document.
      *
      * @param fieldName the non-null field name
-     * @param value     the value
+     * @param value     the value, which may be null
      * @param <TItem>   the value type
      * @return the update
      * @mongodb.driver.manual reference/operator/update/setOnInsert/ $setOnInsert
      * @see UpdateOptions#upsert(boolean)
      */
-    public static <TItem> Bson setOnInsert(final String fieldName, final TItem value) {
+    public static <TItem> Bson setOnInsert(final String fieldName, @Nullable final TItem value) {
         return new SimpleUpdate<TItem>(fieldName, value, "$setOnInsert");
     }
 
@@ -200,12 +201,12 @@ public static Bson currentTimestamp(final String fieldName) {
      * already present, in which case it does nothing
      *
      * @param fieldName the non-null field name
-     * @param value     the value
+     * @param value     the value, which may be null
      * @param <TItem>   the value type
      * @return the update
      * @mongodb.driver.manual reference/operator/update/addToSet/ $addToSet
      */
-    public static <TItem> Bson addToSet(final String fieldName, final TItem value) {
+    public static <TItem> Bson addToSet(final String fieldName, @Nullable final TItem value) {
         return new SimpleUpdate<TItem>(fieldName, value, "$addToSet");
     }
 
@@ -227,12 +228,12 @@ public static <TItem> Bson addEachToSet(final String fieldName, final List<TItem
      * Creates an update that adds the given value to the array value of the field with the given name.
      *
      * @param fieldName the non-null field name
-     * @param value     the value
+     * @param value     the value, which may be null
      * @param <TItem>   the value type
      * @return the update
      * @mongodb.driver.manual reference/operator/update/push/ $push
      */
-    public static <TItem> Bson push(final String fieldName, final TItem value) {
+    public static <TItem> Bson push(final String fieldName, @Nullable final TItem value) {
         return new SimpleUpdate<TItem>(fieldName, value, "$push");
     }
 
@@ -268,12 +269,12 @@ public static <TItem> Bson pushEach(final String fieldName, final List<TItem> va
      * Creates an update that removes all instances of the given value from the array value of the field with the given name.
      *
      * @param fieldName the non-null field name
-     * @param value     the value
+     * @param value     the value, which may be null
      * @param <TItem>   the value type
      * @return the update
      * @mongodb.driver.manual reference/operator/update/pull/ $pull
      */
-    public static <TItem> Bson pull(final String fieldName, final TItem value) {
+    public static <TItem> Bson pull(final String fieldName, @Nullable final TItem value) {
         return new SimpleUpdate<TItem>(fieldName, value, "$pull");
     }
 

driver-sync/src/main/com/mongodb/client/MongoCollection.java

@@ -41,6 +41,7 @@
 import com.mongodb.client.model.WriteModel;
 import com.mongodb.client.result.DeleteResult;
 import com.mongodb.client.result.UpdateResult;
+import com.mongodb.lang.Nullable;
 import org.bson.Document;
 import org.bson.codecs.configuration.CodecRegistry;
 import org.bson.conversions.Bson;
@@ -1151,6 +1152,7 @@ BulkWriteResult bulkWrite(ClientSession clientSession, List<? extends WriteModel
      * @param filter the query filter to find the document with
      * @return the document that was removed.  If no documents matched the query filter, then null will be returned
      */
+    @Nullable
     TDocument findOneAndDelete(Bson filter);
 
     /**
@@ -1161,6 +1163,7 @@ BulkWriteResult bulkWrite(ClientSession clientSession, List<? extends WriteModel
      * @param options the options to apply to the operation
      * @return the document that was removed.  If no documents matched the query filter, then null will be returned
      */
+    @Nullable
     TDocument findOneAndDelete(Bson filter, FindOneAndDeleteOptions options);
 
     /**
@@ -1173,6 +1176,7 @@ BulkWriteResult bulkWrite(ClientSession clientSession, List<? extends WriteModel
      * @since 3.6
      * @mongodb.server.release 3.6
      */
+    @Nullable
     TDocument findOneAndDelete(ClientSession clientSession, Bson filter);
 
     /**
@@ -1186,6 +1190,7 @@ BulkWriteResult bulkWrite(ClientSession clientSession, List<? extends WriteModel
      * @since 3.6
      * @mongodb.server.release 3.6
      */
+    @Nullable
     TDocument findOneAndDelete(ClientSession clientSession, Bson filter, FindOneAndDeleteOptions options);
 
     /**
@@ -1198,6 +1203,7 @@ BulkWriteResult bulkWrite(ClientSession clientSession, List<? extends WriteModel
      * document as it was before the update or as it is after the update.  If no documents matched the query filter, then null will be
      * returned
      */
+    @Nullable
     TDocument findOneAndReplace(Bson filter, TDocument replacement);
 
     /**
@@ -1211,6 +1217,7 @@ BulkWriteResult bulkWrite(ClientSession clientSession, List<? extends WriteModel
      * document as it was before the update or as it is after the update.  If no documents matched the query filter, then null will be
      * returned
      */
+    @Nullable
     TDocument findOneAndReplace(Bson filter, TDocument replacement, FindOneAndReplaceOptions options);
 
     /**
@@ -1226,6 +1233,7 @@ BulkWriteResult bulkWrite(ClientSession clientSession, List<? extends WriteModel
      * @since 3.6
      * @mongodb.server.release 3.6
      */
+    @Nullable
     TDocument findOneAndReplace(ClientSession clientSession, Bson filter, TDocument replacement);
 
     /**
@@ -1242,6 +1250,7 @@ BulkWriteResult bulkWrite(ClientSession clientSession, List<? extends WriteModel
      * @since 3.6
      * @mongodb.server.release 3.6
      */
+    @Nullable
     TDocument findOneAndReplace(ClientSession clientSession, Bson filter, TDocument replacement, FindOneAndReplaceOptions options);
 
     /**
@@ -1253,6 +1262,7 @@ BulkWriteResult bulkWrite(ClientSession clientSession, List<? extends WriteModel
      * @return the document that was updated before the update was applied.  If no documents matched the query filter, then null will be
      * returned
      */
+    @Nullable
     TDocument findOneAndUpdate(Bson filter, Bson update);
 
     /**
@@ -1266,6 +1276,7 @@ BulkWriteResult bulkWrite(ClientSession clientSession, List<? extends WriteModel
      * document as it was before the update or as it is after the update.  If no documents matched the query filter, then null will be
      * returned
      */
+    @Nullable
     TDocument findOneAndUpdate(Bson filter, Bson update, FindOneAndUpdateOptions options);
 
     /**
@@ -1280,6 +1291,7 @@ BulkWriteResult bulkWrite(ClientSession clientSession, List<? extends WriteModel
      * @since 3.6
      * @mongodb.server.release 3.6
      */
+    @Nullable
     TDocument findOneAndUpdate(ClientSession clientSession, Bson filter, Bson update);
 
     /**
@@ -1296,6 +1308,7 @@ BulkWriteResult bulkWrite(ClientSession clientSession, List<? extends WriteModel
      * @since 3.6
      * @mongodb.server.release 3.6
      */
+    @Nullable
     TDocument findOneAndUpdate(ClientSession clientSession, Bson filter, Bson update, FindOneAndUpdateOptions options);
 
     /**

driver-sync/src/main/com/mongodb/client/internal/MongoCollectionImpl.java

@@ -649,80 +649,95 @@ public UpdateResult updateMany(final ClientSession clientSession, final Bson fil
     }
 
     @Override
+    @Nullable
     public TDocument findOneAndDelete(final Bson filter) {
         return findOneAndDelete(filter, new FindOneAndDeleteOptions());
     }
 
     @Override
+    @Nullable
     public TDocument findOneAndDelete(final Bson filter, final FindOneAndDeleteOptions options) {
         return executeFindOneAndDelete(null, filter, options);
     }
 
     @Override
+    @Nullable
     public TDocument findOneAndDelete(final ClientSession clientSession, final Bson filter) {
         return findOneAndDelete(clientSession, filter, new FindOneAndDeleteOptions());
     }
 
     @Override
+    @Nullable
     public TDocument findOneAndDelete(final ClientSession clientSession, final Bson filter, final FindOneAndDeleteOptions options) {
         notNull("clientSession", clientSession);
         return executeFindOneAndDelete(clientSession, filter, options);
     }
 
+    @Nullable
     private TDocument executeFindOneAndDelete(@Nullable final ClientSession clientSession, final Bson filter,
                                               final FindOneAndDeleteOptions options) {
         return executor.execute(operations.findOneAndDelete(filter, options), readConcern, clientSession);
     }
 
     @Override
+    @Nullable
     public TDocument findOneAndReplace(final Bson filter, final TDocument replacement) {
         return findOneAndReplace(filter, replacement, new FindOneAndReplaceOptions());
     }
 
     @Override
+    @Nullable
     public TDocument findOneAndReplace(final Bson filter, final TDocument replacement, final FindOneAndReplaceOptions options) {
         return executeFindOneAndReplace(null, filter, replacement, options);
     }
 
     @Override
+    @Nullable
     public TDocument findOneAndReplace(final ClientSession clientSession, final Bson filter, final TDocument replacement) {
         return findOneAndReplace(clientSession, filter, replacement, new FindOneAndReplaceOptions());
     }
 
     @Override
+    @Nullable
     public TDocument findOneAndReplace(final ClientSession clientSession, final Bson filter, final TDocument replacement,
                                        final FindOneAndReplaceOptions options) {
         notNull("clientSession", clientSession);
         return executeFindOneAndReplace(clientSession, filter, replacement, options);
     }
 
+    @Nullable
     private TDocument executeFindOneAndReplace(@Nullable final ClientSession clientSession, final Bson filter, final TDocument replacement,
                                                final FindOneAndReplaceOptions options) {
         return executor.execute(operations.findOneAndReplace(filter, replacement, options), readConcern, clientSession);
     }
 
     @Override
+    @Nullable
     public TDocument findOneAndUpdate(final Bson filter, final Bson update) {
         return findOneAndUpdate(filter, update, new FindOneAndUpdateOptions());
     }
 
     @Override
+    @Nullable
     public TDocument findOneAndUpdate(final Bson filter, final Bson update, final FindOneAndUpdateOptions options) {
         return executeFindOneAndUpdate(null, filter, update, options);
     }
 
     @Override
+    @Nullable
     public TDocument findOneAndUpdate(final ClientSession clientSession, final Bson filter, final Bson update) {
         return findOneAndUpdate(clientSession, filter, update, new FindOneAndUpdateOptions());
     }
 
     @Override
+    @Nullable
     public TDocument findOneAndUpdate(final ClientSession clientSession, final Bson filter, final Bson update,
                                       final FindOneAndUpdateOptions options) {
         notNull("clientSession", clientSession);
         return executeFindOneAndUpdate(clientSession, filter, update, options);
     }
 
+    @Nullable
     private TDocument executeFindOneAndUpdate(@Nullable final ClientSession clientSession, final Bson filter, final Bson update,
                                               final FindOneAndUpdateOptions options) {
         return executor.execute(operations.findOneAndUpdate(filter, update, options), readConcern, clientSession);