Revisit nullability annotations

This commit introduces the following changes.

1) It adds a new Spring @nonnull annotation which allows to apply
@NonNullApi semantic on a specific element, like @nullable does.
Combined with @nullable, it allows partial null-safety support when
package granularity is too broad.

2) @nullable and @nonnull can apply to ElementType.TYPE_USE in order
to be used on generic type arguments (SPR-15942).

3) Annotations does not apply to ElementType.TYPE_PARAMETER anymore
since it is not supported yet (applicability for such use case is
controversial and need to be discussed).

4) @NonNullApi does not apply to ElementType.FIELD anymore since in a
lot of use cases (private, protected) it is not part for the public API
+ its usage should remain opt-in. A dedicated @NonNullFields annotation
has been added in order to set fields default to non-nullable.

5) Updated Javadoc and reference documentation.

Issue: SPR-15756

Author: sdeleuze

spring-aop/src/main/java/org/springframework/aop/aspectj/annotation/package-info.java

@@ -4,6 +4,8 @@
  * <p>Normally to be used through an AspectJAutoProxyCreator rather than directly.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.aop.aspectj.annotation;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-aop/src/main/java/org/springframework/aop/aspectj/autoproxy/package-info.java

@@ -3,6 +3,8 @@
  * Support for AspectJ annotation aspects resides in the "aspectj.annotation" package.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.aop.aspectj.autoproxy;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-aop/src/main/java/org/springframework/aop/aspectj/package-info.java

@@ -9,6 +9,8 @@
  * functionality, with consistent semantics, with the proxy-based Spring AOP framework.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.aop.aspectj;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

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

@@ -3,6 +3,8 @@
  * with XML schema being the primary configuration format.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.aop.config;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-aop/src/main/java/org/springframework/aop/framework/adapter/package-info.java

@@ -10,6 +10,8 @@
  * <p>These adapters do not depend on any other Spring framework classes to allow such usage.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.aop.framework.adapter;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-aop/src/main/java/org/springframework/aop/framework/autoproxy/package-info.java

@@ -10,6 +10,8 @@
  * Post-processors can be explicitly registered on a ConfigurableBeanFactory instead.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.aop.framework.autoproxy;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-aop/src/main/java/org/springframework/aop/framework/package-info.java

@@ -13,6 +13,8 @@
  * ProxyFactory class.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.aop.framework;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-aop/src/main/java/org/springframework/aop/interceptor/package-info.java

@@ -4,6 +4,8 @@
  * functionality packages, like "transaction" and "orm".
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.aop.interceptor;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-aop/src/main/java/org/springframework/aop/package-info.java

@@ -18,6 +18,8 @@
  * integrated with the Spring IoC container.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.aop;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-aop/src/main/java/org/springframework/aop/scope/package-info.java

@@ -2,6 +2,8 @@
  * Support for AOP-based scoping of target objects, with configurable backend.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.aop.scope;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-aop/src/main/java/org/springframework/aop/support/annotation/package-info.java

@@ -2,6 +2,8 @@
  * Annotation support for AOP pointcuts.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.aop.support.annotation;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-aop/src/main/java/org/springframework/aop/support/package-info.java

@@ -2,6 +2,8 @@
  * Convenience classes for using Spring's AOP API.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.aop.support;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-beans/src/main/java/org/springframework/beans/annotation/package-info.java

@@ -2,6 +2,8 @@
  * Support package for beans-style handling of Java 5 annotations.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.beans.annotation;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-beans/src/main/java/org/springframework/beans/factory/annotation/package-info.java

@@ -2,6 +2,8 @@
  * Support package for annotation-driven bean configuration.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.beans.factory.annotation;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-beans/src/main/java/org/springframework/beans/factory/config/package-info.java

@@ -2,6 +2,8 @@
  * SPI interfaces and configuration-related convenience classes for bean factories.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.beans.factory.config;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-beans/src/main/java/org/springframework/beans/factory/package-info.java

@@ -10,6 +10,8 @@
  * by Rod Johnson (Wrox, 2002).
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.beans.factory;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-beans/src/main/java/org/springframework/beans/factory/parsing/package-info.java

@@ -2,6 +2,8 @@
  * Support infrastructure for bean definition parsing.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.beans.factory.parsing;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-beans/src/main/java/org/springframework/beans/factory/serviceloader/package-info.java

@@ -2,6 +2,8 @@
  * Support package for the Java 6 ServiceLoader facility.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.beans.factory.serviceloader;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-beans/src/main/java/org/springframework/beans/factory/support/package-info.java

@@ -3,6 +3,8 @@
  * Contains abstract base classes for {@code BeanFactory} implementations.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.beans.factory.support;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-beans/src/main/java/org/springframework/beans/factory/wiring/package-info.java

@@ -3,6 +3,8 @@
  * Foundation for aspect-driven bean configuration.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.beans.factory.wiring;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-beans/src/main/java/org/springframework/beans/factory/xml/package-info.java

@@ -3,6 +3,8 @@
  * including a standard "spring-beans" XSD.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.beans.factory.xml;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-beans/src/main/java/org/springframework/beans/package-info.java

@@ -10,6 +10,8 @@
  * by Rod Johnson (Wrox, 2002).
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.beans;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-beans/src/main/java/org/springframework/beans/propertyeditors/package-info.java

@@ -7,6 +7,8 @@
  * specific binding processes, as they are localized or the like.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.beans.propertyeditors;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-beans/src/main/java/org/springframework/beans/support/package-info.java

@@ -3,6 +3,8 @@
  * such as utility classes for sorting and holding lists of beans.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.beans.support;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-context-support/src/main/java/org/springframework/cache/caffeine/package-info.java

@@ -4,6 +4,8 @@
  * allowing to set up Caffeine caches within Spring's cache abstraction.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.cache.caffeine;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-context-support/src/main/java/org/springframework/cache/ehcache/package-info.java

@@ -10,6 +10,8 @@
  * Spring's support in {@code org.springframework.cache.jcache}.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.cache.ehcache;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-context-support/src/main/java/org/springframework/cache/jcache/package-info.java

@@ -5,6 +5,8 @@
  * use in a Spring context, using a JSR-107 compliant cache provider.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.cache.jcache;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-context-support/src/main/java/org/springframework/cache/transaction/package-info.java

@@ -3,6 +3,8 @@
  * Provides synchronization of put operations with Spring-managed transactions.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.cache.transaction;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-context-support/src/main/java/org/springframework/mail/javamail/package-info.java

@@ -4,6 +4,8 @@
  * class for convenient population of a JavaMail MimeMessage.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.mail.javamail;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-context-support/src/main/java/org/springframework/mail/package-info.java

@@ -3,6 +3,8 @@
  * Concrete implementations are provided in the subpackages.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.mail;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-context-support/src/main/java/org/springframework/scheduling/commonj/package-info.java

@@ -3,6 +3,8 @@
  * facility, as supported by IBM WebSphere 6.0+ and BEA WebLogic 9.0+.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.scheduling.commonj;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-context-support/src/main/java/org/springframework/scheduling/quartz/package-info.java

@@ -6,6 +6,8 @@
  * convenience classes for implementing Quartz Jobs.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.scheduling.quartz;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-context-support/src/main/java/org/springframework/ui/freemarker/package-info.java

@@ -4,6 +4,8 @@
  * within a Spring application context.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.ui.freemarker;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-context/src/main/java/org/springframework/cache/annotation/package-info.java

@@ -4,6 +4,8 @@
  * {@link org.springframework.cache.interceptor.CacheOperationSource}.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.cache.annotation;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-context/src/main/java/org/springframework/cache/concurrent/package-info.java

@@ -5,6 +5,8 @@
  * use in a Spring context, using a JDK based thread pool at runtime.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.cache.concurrent;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-context/src/main/java/org/springframework/cache/config/package-info.java

@@ -5,6 +5,8 @@
  * for details on code-based configuration without XML.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.cache.config;
 
-import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;