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

spring-oxm/src/main/java/org/springframework/oxm/castor/package-info.java

@@ -2,4 +2,7 @@
  * Package providing integration of <a href="http://castor-data-binding.github.io/castor/reference-guides/1.3.3/html-single/index.html#xml.mapping">Castor</a>
  * within Spring's O/X Mapping support.
  */
+@NonNullApi
 package org.springframework.oxm.castor;
+
+import org.springframework.lang.NonNullApi;

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

@@ -1,4 +1,7 @@
 /**
  * Provides an namespace handler for the Spring Object/XML namespace.
  */
+@NonNullApi
 package org.springframework.oxm.config;
+
+import org.springframework.lang.NonNullApi;

spring-oxm/src/main/java/org/springframework/oxm/jaxb/package-info.java

@@ -2,4 +2,7 @@
  * Package providing integration of <a href="http://java.sun.com/webservices/jaxb/">JAXB</a>
  * with Spring's O/X Mapping support.
  */
+@NonNullApi
 package org.springframework.oxm.jaxb;
+
+import org.springframework.lang.NonNullApi;

spring-oxm/src/main/java/org/springframework/oxm/jibx/package-info.java

@@ -2,4 +2,7 @@
  * Package providing integration of <a href="http://jibx.sourceforge.net/">JiBX</a>
  * with Spring's O/X Mapping support.
  */
+@NonNullApi
 package org.springframework.oxm.jibx;
+
+import org.springframework.lang.NonNullApi;

spring-oxm/src/main/java/org/springframework/oxm/mime/MimeContainer.java

@@ -18,6 +18,8 @@ package org.springframework.oxm.mime;
 
 import javax.activation.DataHandler;
 
+import org.springframework.lang.Nullable;
+
 /**
  * Represents a container for MIME attachments
  * Concrete implementations might adapt a SOAPMessage or an email message.
@@ -56,6 +58,7 @@ public interface MimeContainer {
 	 * @param contentId the content id
 	 * @return the attachment, as a data handler
 	 */
+	@Nullable
 	DataHandler getAttachment(String contentId);
 
 }

spring-oxm/src/main/java/org/springframework/oxm/mime/package-info.java

@@ -1,4 +1,7 @@
 /**
  * Contains (un)marshallers optimized to store binary data in MIME attachments.
  */
+@NonNullApi
 package org.springframework.oxm.mime;
+
+import org.springframework.lang.NonNullApi;

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

@@ -3,4 +3,7 @@
  * Contains generic Marshaller and Unmarshaller interfaces,
  * and XmlMappingExceptions related to O/X Mapping
  */
+@NonNullApi
 package org.springframework.oxm;
+
+import org.springframework.lang.NonNullApi;

spring-oxm/src/main/java/org/springframework/oxm/support/AbstractMarshaller.java

@@ -22,6 +22,7 @@ import java.io.OutputStream;
 import java.io.Reader;
 import java.io.StringReader;
 import java.io.Writer;
+
 import javax.xml.parsers.DocumentBuilder;
 import javax.xml.parsers.DocumentBuilderFactory;
 import javax.xml.parsers.ParserConfigurationException;
@@ -50,6 +51,7 @@ import org.xml.sax.SAXException;
 import org.xml.sax.XMLReader;
 import org.xml.sax.ext.LexicalHandler;
 
+import org.springframework.lang.Nullable;
 import org.springframework.oxm.Marshaller;
 import org.springframework.oxm.Unmarshaller;
 import org.springframework.oxm.UnmarshallingFailureException;
@@ -199,6 +201,7 @@ public abstract class AbstractMarshaller implements Marshaller, Unmarshaller {
 	 * a byte stream, or {@code null} if none.
 	 * <p>The default implementation returns {@code null}.
 	 */
+	@Nullable
 	protected String getDefaultEncoding() {
 		return null;
 	}
@@ -519,7 +522,7 @@ public abstract class AbstractMarshaller implements Marshaller, Unmarshaller {
 	 * @throws XmlMappingException if the given object cannot be marshalled to the handlers
 	 */
 	protected abstract void marshalSaxHandlers(
-			Object graph, ContentHandler contentHandler, LexicalHandler lexicalHandler)
+			Object graph, ContentHandler contentHandler, @Nullable LexicalHandler lexicalHandler)
 			throws XmlMappingException;
 
 	/**

spring-oxm/src/main/java/org/springframework/oxm/support/SaxResourceUtils.java

@@ -21,6 +21,7 @@ import java.io.IOException;
 import org.xml.sax.InputSource;
 
 import org.springframework.core.io.Resource;
+import org.springframework.lang.Nullable;
 
 /**
  * Convenient utility methods for dealing with SAX.
@@ -50,6 +51,7 @@ public abstract class SaxResourceUtils {
 	 * Retrieve the URL from the given resource as System ID.
 	 * <p>Returns {@code null} if it cannot be opened.
 	 */
+	@Nullable
 	private static String getSystemId(Resource resource) {
 		try {
 			return resource.getURI().toString();

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

@@ -4,4 +4,7 @@
  * with TrAX, MarshallingView for use withing Spring Web MVC, and the
  * MarshallingMessageConverter for use within Spring's JMS support.
  */
+@NonNullApi
 package org.springframework.oxm.support;
+
+import org.springframework.lang.NonNullApi;

spring-oxm/src/main/java/org/springframework/oxm/xstream/package-info.java

@@ -2,4 +2,7 @@
  * Package providing integration of <a href="http://x-stream.github.io/">XStream</a>
  * with Spring's O/X Mapping support.
  */
+@NonNullApi
 package org.springframework.oxm.xstream;
+
+import org.springframework.lang.NonNullApi;