DATAMONGO-1762 - Add @nullable and @NonNullApi annotations.

Marked all packages with Spring Frameworks @NonNullApi. Added Spring's @nullable to methods, parameters and fields that take or produce null values. Adapted using code to make sure the IDE can evaluate the null flow properly. Fixed Javadoc in places where an invalid null handling policy was advertised. Strengthened null requirements for types that expose null-instances.

Author: christophstrobl

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/config/MongoCredentialPropertyEditor.java

@@ -25,6 +25,7 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+import org.springframework.lang.Nullable;
 import org.springframework.util.StringUtils;
 
 import com.mongodb.MongoCredential;
@@ -51,7 +52,7 @@ public class MongoCredentialPropertyEditor extends PropertyEditorSupport {
 	 * @see java.beans.PropertyEditorSupport#setAsText(java.lang.String)
 	 */
 	@Override
-	public void setAsText(String text) throws IllegalArgumentException {
+	public void setAsText(@Nullable String text) throws IllegalArgumentException {
 
 		if (!StringUtils.hasText(text)) {
 			return;

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/config/ReadPreferencePropertyEditor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2015 the original author or authors.
+ * Copyright 2015-2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,6 +17,8 @@
 
 import java.beans.PropertyEditorSupport;
 
+import org.springframework.lang.Nullable;
+
 import com.mongodb.ReadPreference;
 
 /**
@@ -32,7 +34,7 @@ public class ReadPreferencePropertyEditor extends PropertyEditorSupport {
 	 * @see java.beans.PropertyEditorSupport#setAsText(java.lang.String)
 	 */
 	@Override
-	public void setAsText(String readPreferenceString) throws IllegalArgumentException {
+	public void setAsText(@Nullable String readPreferenceString) throws IllegalArgumentException {
 
 		if (readPreferenceString == null) {
 			return;
@@ -59,8 +61,8 @@ public void setAsText(String readPreferenceString) throws IllegalArgumentExcepti
 		} else if ("NEAREST".equalsIgnoreCase(readPreferenceString)) {
 			setValue(ReadPreference.nearest());
 		} else {
-			throw new IllegalArgumentException(String.format("Cannot find matching ReadPreference for %s",
-					readPreferenceString));
+			throw new IllegalArgumentException(
+					String.format("Cannot find matching ReadPreference for %s", readPreferenceString));
 		}
 	}
 }

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/config/ServerAddressPropertyEditor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2011-2013 the original author or authors.
+ * Copyright 2011-2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,6 +23,7 @@
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 import org.springframework.util.StringUtils;
 
@@ -34,6 +35,7 @@
  * @author Mark Pollack
  * @author Oliver Gierke
  * @author Thomas Darimont
+ * @author Christoph Strobl
  */
 public class ServerAddressPropertyEditor extends PropertyEditorSupport {
 
@@ -49,7 +51,7 @@ public class ServerAddressPropertyEditor extends PropertyEditorSupport {
 	 * @see java.beans.PropertyEditorSupport#setAsText(java.lang.String)
 	 */
 	@Override
-	public void setAsText(String replicaSetString) {
+	public void setAsText(@Nullable String replicaSetString) {
 
 		if (!StringUtils.hasText(replicaSetString)) {
 			setValue(null);

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/config/WriteConcernPropertyEditor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2011 the original author or authors.
+ * Copyright 2011-2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,6 +17,9 @@
 
 import java.beans.PropertyEditorSupport;
 
+import org.springframework.lang.Nullable;
+import org.springframework.util.StringUtils;
+
 import com.mongodb.WriteConcern;
 
 /**
@@ -26,14 +29,19 @@
  * string value.
  * 
  * @author Mark Pollack
+ * @author Christoph Strobl
  */
 public class WriteConcernPropertyEditor extends PropertyEditorSupport {
 
 	/**
 	 * Parse a string to a List<ServerAddress>
 	 */
 	@Override
-	public void setAsText(String writeConcernString) {
+	public void setAsText(@Nullable String writeConcernString) {
+
+		if (!StringUtils.hasText(writeConcernString)) {
+			return;
+		}
 
 		WriteConcern writeConcern = WriteConcern.valueOf(writeConcernString);
 		if (writeConcern != null) {

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/config/package-info.java

@@ -1,5 +1,6 @@
 /**
  * Spring XML namespace configuration for MongoDB specific repositories.
  */
+@org.springframework.lang.NonNullApi
 package org.springframework.data.mongodb.config;
 

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/CollectionCallback.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2010-2016 the original author or authors.
+ * Copyright 2010-2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,12 +17,13 @@
 
 import org.bson.Document;
 import org.springframework.dao.DataAccessException;
+import org.springframework.lang.Nullable;
 
 import com.mongodb.MongoException;
 import com.mongodb.client.MongoCollection;
 
 /**
- * Callback interface for executing actions against a {@link MongoCollection}
+ * Callback interface for executing actions against a {@link MongoCollection}.
  *
  * @author Mark Pollak
  * @author Grame Rocher
@@ -35,10 +36,11 @@ public interface CollectionCallback<T> {
 
 	/**
 	 * @param collection never {@literal null}.
-	 * @return
+	 * @return can be {@literal null}.
 	 * @throws MongoException
 	 * @throws DataAccessException
 	 */
+	@Nullable
 	T doInCollection(MongoCollection<Document> collection) throws MongoException, DataAccessException;
 
 }

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/CollectionOptions.java

@@ -18,6 +18,7 @@
 import java.util.Optional;
 
 import org.springframework.data.mongodb.core.query.Collation;
+import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
@@ -29,26 +30,27 @@
  */
 public class CollectionOptions {
 
-	private Long maxDocuments;
-	private Long size;
-	private Boolean capped;
-	private Collation collation;
+	private @Nullable Long maxDocuments;
+	private @Nullable Long size;
+	private @Nullable Boolean capped;
+	private @Nullable Collation collation;
 
 	/**
 	 * Constructs a new <code>CollectionOptions</code> instance.
 	 *
-	 * @param size the collection size in bytes, this data space is preallocated.
-	 * @param maxDocuments the maximum number of documents in the collection.
+	 * @param size the collection size in bytes, this data space is preallocated. Can be {@literal null}.
+	 * @param maxDocuments the maximum number of documents in the collection. Can be {@literal null}.
 	 * @param capped true to created a "capped" collection (fixed size with auto-FIFO behavior based on insertion order),
-	 *          false otherwise.
+	 *          false otherwise. Can be {@literal null}.
 	 * @deprecated since 2.0 please use {@link CollectionOptions#empty()} as entry point.
 	 */
 	@Deprecated
-	public CollectionOptions(Long size, Long maxDocuments, Boolean capped) {
+	public CollectionOptions(@Nullable Long size, @Nullable Long maxDocuments, @Nullable Boolean capped) {
 		this(size, maxDocuments, capped, null);
 	}
 
-	private CollectionOptions(Long size, Long maxDocuments, Boolean capped, Collation collation) {
+	private CollectionOptions(@Nullable Long size, @Nullable Long maxDocuments, @Nullable Boolean capped,
+			@Nullable Collation collation) {
 
 		this.maxDocuments = maxDocuments;
 		this.size = size;
@@ -120,7 +122,7 @@ public CollectionOptions size(long size) {
 	 * @return new {@link CollectionOptions}.
 	 * @since 2.0
 	 */
-	public CollectionOptions collation(Collation collation) {
+	public CollectionOptions collation(@Nullable Collation collation) {
 		return new CollectionOptions(size, maxDocuments, capped, collation);
 	}
 

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/DbCallback.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2010-2016 the original author or authors.
+ * Copyright 2010-2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,15 +16,29 @@
 package org.springframework.data.mongodb.core;
 
 import org.springframework.dao.DataAccessException;
+import org.springframework.lang.Nullable;
 
 import com.mongodb.MongoException;
 import com.mongodb.client.MongoDatabase;
 
 /**
+ * Callback interface for executing actions against a {@link MongoDatabase}.
  *
- * @param <T>
+ * @author Mark Pollak
+ * @author Graeme Rocher
+ * @author Thomas Risberg
+ * @author Oliver Gierke
+ * @author John Brisbin
+ * @author Christoph Strobl
  */
 public interface DbCallback<T> {
 
+	/**
+	 * @param db must not be {@literal null}.
+	 * @return can be {@literal null}.
+	 * @throws MongoException
+	 * @throws DataAccessException
+	 */
+	@Nullable
 	T doInDB(MongoDatabase db) throws MongoException, DataAccessException;
 }

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/DbHolder.java

@@ -35,6 +35,7 @@
 import org.springframework.data.mongodb.core.query.Query;
 import org.springframework.data.mongodb.core.query.Update;
 import org.springframework.data.util.Pair;
+import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 import com.mongodb.BulkWriteException;
@@ -67,7 +68,7 @@ class DefaultBulkOperations implements BulkOperations {
 	private final List<WriteModel<Document>> models = new ArrayList<>();
 
 	private PersistenceExceptionTranslator exceptionTranslator;
-	private WriteConcern defaultWriteConcern;
+	private @Nullable WriteConcern defaultWriteConcern;
 
 	private BulkWriteOptions bulkOptions;
 
@@ -99,7 +100,7 @@ class DefaultBulkOperations implements BulkOperations {
 	 *
 	 * @param exceptionTranslator can be {@literal null}.
 	 */
-	public void setExceptionTranslator(PersistenceExceptionTranslator exceptionTranslator) {
+	public void setExceptionTranslator(@Nullable PersistenceExceptionTranslator exceptionTranslator) {
 		this.exceptionTranslator = exceptionTranslator == null ? new MongoExceptionTranslator() : exceptionTranslator;
 	}
 
@@ -108,7 +109,7 @@ public void setExceptionTranslator(PersistenceExceptionTranslator exceptionTrans
 	 *
 	 * @param defaultWriteConcern can be {@literal null}.
 	 */
-	void setDefaultWriteConcern(WriteConcern defaultWriteConcern) {
+	void setDefaultWriteConcern(@Nullable WriteConcern defaultWriteConcern) {
 		this.defaultWriteConcern = defaultWriteConcern;
 	}