Introduce null-safety of Spring Framework API

This commit introduces 2 new @nullable and @NonNullApi
annotations that leverage JSR 305 (dormant but available via
Findbugs jsr305 dependency and already used by libraries
like OkHttp) meta-annotations to specify explicitly
null-safety of Spring Framework parameters and return values.

In order to avoid adding too much annotations, the
default is set at package level with @NonNullApi and
@nullable annotations are added when needed at parameter or
return value level. These annotations are intended to be used
on Spring Framework itself but also by other Spring projects.

@nullable annotations have been introduced based on Javadoc
and search of patterns like "return null;". It is expected that
nullability of Spring Framework API will be polished with
complementary commits.

In practice, this will make the whole Spring Framework API
null-safe for Kotlin projects (when KT-10942 will be fixed)
since Kotlin will be able to leverage these annotations to
know if a parameter or a return value is nullable or not. But
this is also useful for Java developers as well since IntelliJ
IDEA, for example, also understands these annotations to
generate warnings when unsafe nullable usages are detected.

Issue: SPR-15540

Author: sdeleuze

build.gradle

@@ -177,6 +177,7 @@ configure(allprojects) { project ->
 	}
 
 	dependencies {
+		provided("com.google.code.findbugs:jsr305:3.0.2")
 		testCompile("junit:junit:${junitVersion}") {
 			exclude group:'org.hamcrest', module:'hamcrest-core'
 		}

spring-aop/src/main/java/org/aopalliance/aop/AspectException.java

@@ -16,6 +16,8 @@
 
 package org.aopalliance.aop;
 
+import org.springframework.lang.Nullable;
+
 /**
  * Superclass for all AOP infrastructure exceptions.
  * Unchecked, as such exceptions are fatal and end user
@@ -41,7 +43,7 @@ public AspectException(String message) {
 	 * @param message the exception message
 	 * @param cause the root cause, if any
 	 */
-	public AspectException(String message, Throwable cause) {
+	public AspectException(String message, @Nullable Throwable cause) {
 		super(message, cause);
 	}
 

spring-aop/src/main/java/org/aopalliance/intercept/MethodInterceptor.java

@@ -16,6 +16,8 @@
 
 package org.aopalliance.intercept;
 
+import org.springframework.lang.Nullable;
+
 /**
  * Intercepts calls on an interface on its way to the target. These
  * are nested "on top" of the target.
@@ -52,6 +54,7 @@ public interface MethodInterceptor extends Interceptor {
 	 * @throws Throwable if the interceptors or the target object
 	 * throws an exception
 	 */
+	@Nullable
 	Object invoke(MethodInvocation invocation) throws Throwable;
 
 }

spring-aop/src/main/java/org/springframework/aop/AfterReturningAdvice.java

@@ -18,6 +18,8 @@
 
 import java.lang.reflect.Method;
 
+import org.springframework.lang.Nullable;
+
 /**
  * After returning advice is invoked only on normal method return, not if an
  * exception is thrown. Such advice can see the return value, but cannot change it.
@@ -39,6 +41,6 @@ public interface AfterReturningAdvice extends AfterAdvice {
 	 * allowed by the method signature. Otherwise the exception
 	 * will be wrapped as a runtime exception.
 	 */
-	void afterReturning(Object returnValue, Method method, Object[] args, Object target) throws Throwable;
+	void afterReturning(@Nullable Object returnValue, Method method, Object[] args, @Nullable Object target) throws Throwable;
 
 }

spring-aop/src/main/java/org/springframework/aop/IntroductionAwareMethodMatcher.java

@@ -18,6 +18,8 @@
 
 import java.lang.reflect.Method;
 
+import org.springframework.lang.Nullable;
+
 /**
  * A specialized type of {@link MethodMatcher} that takes into account introductions
  * when matching methods. If there are no introductions on the target class,
@@ -39,6 +41,6 @@ public interface IntroductionAwareMethodMatcher extends MethodMatcher {
 	 * asking is the subject on one or more introductions; {@code false} otherwise
 	 * @return whether or not this method matches statically
 	 */
-	boolean matches(Method method, Class<?> targetClass, boolean hasIntroductions);
+	boolean matches(Method method, @Nullable Class<?> targetClass, boolean hasIntroductions);
 
 }

spring-aop/src/main/java/org/springframework/aop/MethodBeforeAdvice.java

@@ -18,6 +18,8 @@
 
 import java.lang.reflect.Method;
 
+import org.springframework.lang.Nullable;
+
 /**
  * Advice invoked before a method is invoked. Such advices cannot
  * prevent the method call proceeding, unless they throw a Throwable.
@@ -39,6 +41,6 @@ public interface MethodBeforeAdvice extends BeforeAdvice {
 	 * allowed by the method signature. Otherwise the exception
 	 * will be wrapped as a runtime exception.
 	 */
-	void before(Method method, Object[] args, Object target) throws Throwable;
+	void before(Method method, Object[] args, @Nullable Object target) throws Throwable;
 
 }

spring-aop/src/main/java/org/springframework/aop/MethodMatcher.java

@@ -18,6 +18,8 @@
 
 import java.lang.reflect.Method;
 
+import org.springframework.lang.Nullable;
+
 /**
  * Part of a {@link Pointcut}: Checks whether the target method is eligible for advice.
  *
@@ -57,7 +59,7 @@ public interface MethodMatcher {
 	 * the candidate class must be taken to be the method's declaring class)
 	 * @return whether or not this method matches statically
 	 */
-	boolean matches(Method method, Class<?> targetClass);
+	boolean matches(Method method, @Nullable Class<?> targetClass);
 
 	/**
 	 * Is this MethodMatcher dynamic, that is, must a final call be made on the
@@ -86,7 +88,7 @@ public interface MethodMatcher {
 	 * @return whether there's a runtime match
 	 * @see MethodMatcher#matches(Method, Class)
 	 */
-	boolean matches(Method method, Class<?> targetClass, Object... args);
+	boolean matches(Method method, @Nullable Class<?> targetClass, Object... args);
 
 
 	/**

spring-aop/src/main/java/org/springframework/aop/ProxyMethodInvocation.java

@@ -18,6 +18,8 @@
 
 import org.aopalliance.intercept.MethodInvocation;
 
+import org.springframework.lang.Nullable;
+
 /**
  * Extension of the AOP Alliance {@link org.aopalliance.intercept.MethodInvocation}
  * interface, allowing access to the proxy that the method invocation was made through.
@@ -73,14 +75,15 @@ public interface ProxyMethodInvocation extends MethodInvocation {
 	 * @param key the name of the attribute
 	 * @param value the value of the attribute, or {@code null} to reset it
 	 */
-	void setUserAttribute(String key, Object value);
+	void setUserAttribute(String key, @Nullable Object value);
 
 	/**
 	 * Return the value of the specified user attribute.
 	 * @param key the name of the attribute
 	 * @return the value of the attribute, or {@code null} if not set
 	 * @see #setUserAttribute
 	 */
+	@Nullable
 	Object getUserAttribute(String key);
 
 }

spring-aop/src/main/java/org/springframework/aop/TargetClassAware.java

@@ -16,6 +16,8 @@
 
 package org.springframework.aop;
 
+import org.springframework.lang.Nullable;
+
 /**
  * Minimal interface for exposing the target class behind a proxy.
  *
@@ -34,6 +36,7 @@ public interface TargetClassAware {
 	 * (typically a proxy configuration or an actual proxy).
 	 * @return the target Class, or {@code null} if not known
 	 */
+	@Nullable
 	Class<?> getTargetClass();
 
 }

spring-aop/src/main/java/org/springframework/aop/TargetSource.java

@@ -16,6 +16,8 @@
 
 package org.springframework.aop;
 
+import org.springframework.lang.Nullable;
+
 /**
  * A {@code TargetSource} is used to obtain the current "target" of
  * an AOP invocation, which will be invoked via reflection if no around
@@ -58,6 +60,7 @@ public interface TargetSource extends TargetClassAware {
 	 * @return the target object, which contains the joinpoint
 	 * @throws Exception if the target object can't be resolved
 	 */
+	@Nullable
 	Object getTarget() throws Exception;
 
 	/**