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

spring-web/src/main/java/org/springframework/http/client/package-info.java

@@ -4,6 +4,8 @@
  * as well as a basic implementation of these interfaces.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.client;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/client/reactive/package-info.java

@@ -5,6 +5,8 @@
  * {@link org.springframework.http.client.reactive.ClientHttpConnector}.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.client.reactive;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/client/support/package-info.java

@@ -3,6 +3,8 @@
  * to be used by higher-level classes like RestTemplate.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.client.support;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/codec/json/package-info.java

@@ -2,6 +2,8 @@
  * JSON encoder and decoder support.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.codec.json;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/codec/multipart/package-info.java

@@ -2,6 +2,8 @@
  * Multipart support.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.codec.multipart;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/codec/package-info.java

@@ -8,6 +8,8 @@
  * writing the body of HTTP requests and responses.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.codec;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/codec/xml/package-info.java

@@ -2,6 +2,8 @@
  * XML encoder and decoder support.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.codec.xml;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/converter/cbor/package-info.java

@@ -2,6 +2,8 @@
  * Provides an HttpMessageConverter for the CBOR data format.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.converter.cbor;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/converter/feed/package-info.java

@@ -3,6 +3,8 @@
  * Based on the <a href="https://github.com/rometools/rome">ROME tools</a> project.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.converter.feed;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/converter/json/package-info.java

@@ -2,6 +2,8 @@
  * Provides HttpMessageConverter implementations for handling JSON.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.converter.json;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/converter/package-info.java

@@ -2,6 +2,8 @@
  * Provides an HttpMessageConverter abstraction to convert between Java objects and HTTP input/output messages.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.converter;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/converter/protobuf/package-info.java

@@ -3,6 +3,8 @@
  * <a href="https://developers.google.com/protocol-buffers/">Google Protocol Buffers</a>.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.converter.protobuf;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/converter/smile/package-info.java

@@ -2,6 +2,8 @@
  * Provides an HttpMessageConverter for the Smile data format ("binary JSON").
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.converter.smile;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/converter/support/package-info.java

@@ -2,6 +2,8 @@
  * Provides a comprehensive HttpMessageConverter variant for form handling.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.converter.support;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/converter/xml/package-info.java

@@ -2,6 +2,8 @@
  * Provides HttpMessageConverter implementations for handling XML.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.converter.xml;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/package-info.java

@@ -3,6 +3,8 @@
  * the {@code HttpInputMessage} and {@code HttpOutputMessage} interfaces.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/server/package-info.java

@@ -4,6 +4,8 @@
  * as well as a Servlet-based implementation of these interfaces.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.server;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/http/server/reactive/package-info.java

@@ -8,6 +8,8 @@
  * including Servlet 3.1 containers, Netty + Reactor IO, and Undertow.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.http.server.reactive;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/remoting/caucho/package-info.java

@@ -8,6 +8,8 @@
  * <a href="http://www.caucho.com/hessian">Hessian website</a>
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.remoting.caucho;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/remoting/httpinvoker/package-info.java

@@ -9,6 +9,8 @@
  * which is its main advantage compared to RMI.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.remoting.httpinvoker;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/remoting/jaxws/package-info.java

@@ -4,6 +4,8 @@
  * factories for accessing JAX-WS services and ports.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.remoting.jaxws;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/accept/package-info.java

@@ -13,6 +13,8 @@
  * ore more of the above strategies in a specific order.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.accept;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

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

@@ -3,6 +3,8 @@
  * as well as for binding request parameters to method arguments.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.bind.annotation;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/bind/package-info.java

@@ -2,6 +2,8 @@
  * Provides web-specific data binding functionality.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.bind;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

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

@@ -2,6 +2,8 @@
  * Support classes for web data binding.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.bind.support;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/client/package-info.java

@@ -3,6 +3,8 @@
  * Provides a RestTemplate class and various callback interfaces.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.client;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

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

@@ -3,6 +3,8 @@
  * Contains a base class for RestTemplate usage.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.client.support;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

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

@@ -2,6 +2,8 @@
  * Provides convenience annotations for web scopes.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.context.annotation;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

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

@@ -3,6 +3,8 @@
  * and the ContextLoaderListener that bootstraps a root web application context.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.context;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/context/request/package-info.java

@@ -3,6 +3,8 @@
  * scoping of application objects per HTTP request or HTTP session.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.context.request;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

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

@@ -3,6 +3,8 @@
  * such as WebApplicationContext implementations and various utility classes.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.context.support;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/cors/package-info.java

@@ -3,6 +3,8 @@
  * based on a common {@code CorsProcessor} strategy.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.cors;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/cors/reactive/package-info.java

@@ -3,6 +3,8 @@
  * based on a common {@code CorsProcessor} strategy.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.cors.reactive;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/filter/package-info.java

@@ -2,6 +2,8 @@
  * Provides generic filter base classes allowing for bean-style configuration.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.filter;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/filter/reactive/package-info.java

@@ -3,6 +3,8 @@
  * reactive web applications.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.filter.reactive;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/jsf/el/package-info.java

@@ -3,6 +3,8 @@
  * which is hosted in a Spring root WebApplicationContext.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.jsf.el;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/jsf/package-info.java

@@ -6,6 +6,8 @@
  * from JSF EL expressions, for example in property values of JSF-managed beans.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.jsf;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

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

@@ -2,6 +2,8 @@
  * Support classes for annotation-based handler method processing.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.method.annotation;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/method/package-info.java

@@ -3,6 +3,8 @@
  * Spring MVC's {@code org.springframework.web.servlet.mvc.method} package.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.method;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

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

@@ -2,6 +2,8 @@
  * Generic support classes for handler method processing.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.method.support;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/multipart/commons/package-info.java

@@ -3,6 +3,8 @@
  * <a href="http://commons.apache.org/proper/commons-fileupload">Apache Commons FileUpload</a>.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.multipart.commons;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/multipart/package-info.java

@@ -5,6 +5,8 @@
  * for accessing multipart files in web application code.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.multipart;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

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

@@ -4,6 +4,8 @@
  * for multipart handling without Spring's Web MVC.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.multipart.support;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

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

@@ -3,6 +3,8 @@
  * between Spring's web infrastructure and other framework modules.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/server/adapter/package-info.java

@@ -4,6 +4,8 @@
  * and {@link org.springframework.http.server.reactive.HttpHandler}.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.server.adapter;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/server/handler/package-info.java

@@ -3,6 +3,8 @@
  * {@link org.springframework.web.server.handler.WebHandlerDecorator}.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.server.handler;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/server/i18n/package-info.java

@@ -3,6 +3,8 @@
  * Provides standard LocaleContextResolver implementations.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.server.i18n;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/server/package-info.java

@@ -5,6 +5,8 @@
  * WebHandler, WebFilter, WebSession among others.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.server;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/server/session/package-info.java

@@ -3,6 +3,8 @@
  * {@link org.springframework.web.server.WebSession} support.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.server.session;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/util/package-info.java

@@ -3,6 +3,8 @@
  * Log4j initialization, and cookie handling.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.util;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-web/src/main/java/org/springframework/web/util/pattern/package-info.java

@@ -7,6 +7,8 @@
  * used for matching purposes at request time.
  */
 @NonNullApi
+@NonNullFields
 package org.springframework.web.util.pattern;
 
 import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;