Add nullability support

This reviews the entire code base to explicitly declare APIs that
accept and/or return a null value. The code base is validated using
ErrorProne.

Closes gh-1562

Author: snicoll

gradle/plugins/conventions-plugin/build.gradle

@@ -15,6 +15,7 @@ dependencies {
 	checkstyle("io.spring.javaformat:spring-javaformat-checkstyle:${javaFormatVersion}")
 
 	implementation("com.github.ben-manes:gradle-versions-plugin:$gradleVersionsPluginVersion")
+	implementation("io.spring.gradle.nullability:nullability-plugin:$nullabilityPluginVersion")
 	implementation("io.spring.javaformat:spring-javaformat-gradle-plugin:$javaFormatVersion")
 
 	testImplementation("org.junit.jupiter:junit-jupiter")

gradle/plugins/conventions-plugin/src/main/java/org/springframework/ws/gradle/conventions/ConventionsPlugin.java

@@ -16,6 +16,7 @@
 
 package org.springframework.ws.gradle.conventions;
 
+import io.spring.gradle.nullability.NullabilityPlugin;
 import org.gradle.api.Plugin;
 import org.gradle.api.Project;
 import org.gradle.api.plugins.JavaBasePlugin;
@@ -37,7 +38,10 @@ public void apply(Project project) {
 			new JavaBasePluginConventions().apply(project);
 			new CheckstyleConventions().apply(project);
 		});
-		project.getPlugins().withType(JavaPlugin.class).all((plugin) -> new JavaPluginConventions().apply(project));
+		project.getPlugins().withType(JavaPlugin.class).all((plugin) -> {
+			project.getPlugins().apply(NullabilityPlugin.class);
+			new JavaPluginConventions().apply(project);
+		});
 		project.getPlugins()
 			.withType(MavenPublishPlugin.class)
 			.all((plugin) -> new MavenPublishPluginConventions().apply(project));

gradle/plugins/gradle.properties

@@ -1,4 +1,5 @@
 assertJVersion=3.25.3
 gradleVersionsPluginVersion=0.52.0
-javaFormatVersion=0.0.45
+javaFormatVersion=0.0.46
 junitVersion=5.11.0
+nullabilityPluginVersion=0.0.1

spring-ws-core/src/main/java/org/springframework/ws/FaultAwareWebServiceMessage.java

@@ -18,6 +18,8 @@
 
 import javax.xml.namespace.QName;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * Sub-interface of {@link WebServiceMessage} that can contain special Fault messages.
  * Fault messages (such as {@link org.springframework.ws.soap.SoapFault} SOAP Faults)
@@ -39,14 +41,14 @@ public interface FaultAwareWebServiceMessage extends WebServiceMessage {
 	/**
 	 * Returns the fault code, if any.
 	 */
-	QName getFaultCode();
+	@Nullable QName getFaultCode();
 
 	/**
 	 * Returns the fault reason message.
 	 * @return the fault reason message, if any; returns {@code null} when no fault is
 	 * present.
 	 * @see #hasFault()
 	 */
-	String getFaultReason();
+	@Nullable String getFaultReason();
 
 }

spring-ws-core/src/main/java/org/springframework/ws/WebServiceException.java

@@ -16,6 +16,8 @@
 
 package org.springframework.ws;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.core.NestedRuntimeException;
 
 /**
@@ -31,7 +33,7 @@ public abstract class WebServiceException extends NestedRuntimeException {
 	 * Create a new instance of the {@code WebServiceException} class.
 	 * @param msg the detail message
 	 */
-	public WebServiceException(String msg) {
+	public WebServiceException(@Nullable String msg) {
 		super(msg);
 	}
 
@@ -40,7 +42,7 @@ public WebServiceException(String msg) {
 	 * @param msg the detail message
 	 * @param ex the root {@link Throwable exception}
 	 */
-	public WebServiceException(String msg, Throwable ex) {
+	public WebServiceException(@Nullable String msg, Throwable ex) {
 		super(msg, ex);
 	}
 

spring-ws-core/src/main/java/org/springframework/ws/WebServiceMessage.java

@@ -22,6 +22,8 @@
 import javax.xml.transform.Result;
 import javax.xml.transform.Source;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * Represents a protocol-agnostic XML message.
  * <p>
@@ -41,7 +43,7 @@ public interface WebServiceMessage {
 	 * single time.
 	 * @return the message contents
 	 */
-	Source getPayloadSource();
+	@Nullable Source getPayloadSource();
 
 	/**
 	 * Returns the contents of the message as a {@link Result}.

spring-ws-core/src/main/java/org/springframework/ws/client/WebServiceClientException.java

@@ -16,6 +16,8 @@
 
 package org.springframework.ws.client;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.ws.WebServiceException;
 
 /**
@@ -31,7 +33,7 @@ public abstract class WebServiceClientException extends WebServiceException {
 	 * Create a new instance of the {@code WebServiceClientException} class.
 	 * @param msg the detail message
 	 */
-	public WebServiceClientException(String msg) {
+	public WebServiceClientException(@Nullable String msg) {
 		super(msg);
 	}
 

spring-ws-core/src/main/java/org/springframework/ws/client/WebServiceFaultException.java

@@ -16,6 +16,8 @@
 
 package org.springframework.ws.client;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.ws.FaultAwareWebServiceMessage;
 
 /**
@@ -27,7 +29,7 @@
 @SuppressWarnings("serial")
 public class WebServiceFaultException extends WebServiceClientException {
 
-	private final FaultAwareWebServiceMessage faultMessage;
+	private final @Nullable FaultAwareWebServiceMessage faultMessage;
 
 	/** Create a new instance of the {@code WebServiceFaultException} class. */
 	public WebServiceFaultException(String msg) {
@@ -45,7 +47,7 @@ public WebServiceFaultException(FaultAwareWebServiceMessage faultMessage) {
 	}
 
 	/** Returns the fault message. */
-	public FaultAwareWebServiceMessage getWebServiceMessage() {
+	public @Nullable FaultAwareWebServiceMessage getWebServiceMessage() {
 		return this.faultMessage;
 	}
 

spring-ws-core/src/main/java/org/springframework/ws/client/WebServiceIOException.java

@@ -18,6 +18,8 @@
 
 import java.io.IOException;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * Exception thrown whenever an I/O error occurs on the client-side.
  *
@@ -31,7 +33,7 @@ public class WebServiceIOException extends WebServiceClientException {
 	 * Create a new instance of the {@code WebServiceIOException} class.
 	 * @param msg the detail message
 	 */
-	public WebServiceIOException(String msg) {
+	public WebServiceIOException(@Nullable String msg) {
 		super(msg);
 	}
 

spring-ws-core/src/main/java/org/springframework/ws/client/WebServiceTransportException.java

@@ -16,6 +16,8 @@
 
 package org.springframework.ws.client;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.ws.transport.TransportException;
 
 /**
@@ -31,7 +33,7 @@ public class WebServiceTransportException extends WebServiceIOException {
 	 * Create a new instance of the {@code WebServiceTransportException} class.
 	 * @param msg the detail message
 	 */
-	public WebServiceTransportException(String msg) {
+	public WebServiceTransportException(@Nullable String msg) {
 		super(msg);
 	}
 

spring-ws-core/src/main/java/org/springframework/ws/client/core/SourceExtractor.java

@@ -21,6 +21,8 @@
 import javax.xml.transform.Source;
 import javax.xml.transform.TransformerException;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * Callback interface for extracting a result object from a
  * {@link javax.xml.transform.Source} instance.
@@ -49,6 +51,6 @@ public interface SourceExtractor<T> {
 	 * typically be stateful in the latter case)
 	 * @throws IOException in case of I/O errors
 	 */
-	T extractData(Source source) throws IOException, TransformerException;
+	@Nullable T extractData(@Nullable Source source) throws IOException, TransformerException;
 
 }

spring-ws-core/src/main/java/org/springframework/ws/client/core/WebServiceMessageExtractor.java

@@ -20,6 +20,8 @@
 
 import javax.xml.transform.TransformerException;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.ws.WebServiceMessage;
 
 /**
@@ -50,6 +52,6 @@ public interface WebServiceMessageExtractor<T> {
 	 * @throws IOException in case of I/O errors
 	 * @throws TransformerException in case of transformation errors
 	 */
-	T extractData(WebServiceMessage message) throws IOException, TransformerException;
+	@Nullable T extractData(WebServiceMessage message) throws IOException, TransformerException;
 
 }

spring-ws-core/src/main/java/org/springframework/ws/client/core/WebServiceOperations.java

@@ -19,6 +19,8 @@
 import javax.xml.transform.Result;
 import javax.xml.transform.Source;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.oxm.XmlMappingException;
 import org.springframework.ws.client.WebServiceClientException;
 
@@ -46,8 +48,8 @@ public interface WebServiceOperations {
 	 * @throws WebServiceClientException if there is a problem sending or receiving the
 	 * message
 	 */
-	<T> T sendAndReceive(WebServiceMessageCallback requestCallback, WebServiceMessageExtractor<T> responseExtractor)
-			throws WebServiceClientException;
+	<T> @Nullable T sendAndReceive(WebServiceMessageCallback requestCallback,
+			WebServiceMessageExtractor<T> responseExtractor) throws WebServiceClientException;
 
 	/**
 	 * Sends a web service message that can be manipulated with the given callback,
@@ -61,7 +63,7 @@ <T> T sendAndReceive(WebServiceMessageCallback requestCallback, WebServiceMessag
 	 * @throws WebServiceClientException if there is a problem sending or receiving the
 	 * message
 	 */
-	<T> T sendAndReceive(String uri, WebServiceMessageCallback requestCallback,
+	<T> @Nullable T sendAndReceive(String uri, WebServiceMessageCallback requestCallback,
 			WebServiceMessageExtractor<T> responseExtractor) throws WebServiceClientException;
 
 	/**
@@ -112,7 +114,7 @@ boolean sendAndReceive(String uri, WebServiceMessageCallback requestCallback,
 	 * @see WebServiceTemplate#setMarshaller(org.springframework.oxm.Marshaller)
 	 * @see WebServiceTemplate#setUnmarshaller(org.springframework.oxm.Unmarshaller)
 	 */
-	Object marshalSendAndReceive(Object requestPayload) throws XmlMappingException, WebServiceClientException;
+	@Nullable Object marshalSendAndReceive(Object requestPayload) throws XmlMappingException, WebServiceClientException;
 
 	/**
 	 * Sends a web service message that contains the given payload, marshalled by the
@@ -128,7 +130,7 @@ boolean sendAndReceive(String uri, WebServiceMessageCallback requestCallback,
 	 * @see WebServiceTemplate#setMarshaller(org.springframework.oxm.Marshaller)
 	 * @see WebServiceTemplate#setUnmarshaller(org.springframework.oxm.Unmarshaller)
 	 */
-	Object marshalSendAndReceive(String uri, Object requestPayload)
+	@Nullable Object marshalSendAndReceive(String uri, Object requestPayload)
 			throws XmlMappingException, WebServiceClientException;
 
 	/**
@@ -148,7 +150,7 @@ Object marshalSendAndReceive(String uri, Object requestPayload)
 	 * @see WebServiceTemplate#setMarshaller(org.springframework.oxm.Marshaller)
 	 * @see WebServiceTemplate#setUnmarshaller(org.springframework.oxm.Unmarshaller)
 	 */
-	Object marshalSendAndReceive(Object requestPayload, WebServiceMessageCallback requestCallback)
+	@Nullable Object marshalSendAndReceive(Object requestPayload, @Nullable WebServiceMessageCallback requestCallback)
 			throws XmlMappingException, WebServiceClientException;
 
 	/**
@@ -167,8 +169,8 @@ Object marshalSendAndReceive(Object requestPayload, WebServiceMessageCallback re
 	 * @see WebServiceTemplate#setMarshaller(org.springframework.oxm.Marshaller)
 	 * @see WebServiceTemplate#setUnmarshaller(org.springframework.oxm.Unmarshaller)
 	 */
-	Object marshalSendAndReceive(String uri, Object requestPayload, WebServiceMessageCallback requestCallback)
-			throws XmlMappingException, WebServiceClientException;
+	@Nullable Object marshalSendAndReceive(String uri, @Nullable Object requestPayload,
+			@Nullable WebServiceMessageCallback requestCallback) throws XmlMappingException, WebServiceClientException;
 
 	// -----------------------------------------------------------------------------------------------------------------
 	// Convenience methods for sending Sources
@@ -185,7 +187,7 @@ Object marshalSendAndReceive(String uri, Object requestPayload, WebServiceMessag
 	 * @throws WebServiceClientException if there is a problem sending or receiving the
 	 * message
 	 */
-	<T> T sendSourceAndReceive(Source requestPayload, SourceExtractor<T> responseExtractor)
+	<T> @Nullable T sendSourceAndReceive(Source requestPayload, SourceExtractor<T> responseExtractor)
 			throws WebServiceClientException;
 
 	/**
@@ -198,7 +200,7 @@ <T> T sendSourceAndReceive(Source requestPayload, SourceExtractor<T> responseExt
 	 * @throws WebServiceClientException if there is a problem sending or receiving the
 	 * message
 	 */
-	<T> T sendSourceAndReceive(String uri, Source requestPayload, SourceExtractor<T> responseExtractor)
+	<T> @Nullable T sendSourceAndReceive(String uri, Source requestPayload, SourceExtractor<T> responseExtractor)
 			throws WebServiceClientException;
 
 	/**
@@ -216,7 +218,7 @@ <T> T sendSourceAndReceive(String uri, Source requestPayload, SourceExtractor<T>
 	 * @throws WebServiceClientException if there is a problem sending or receiving the
 	 * message
 	 */
-	<T> T sendSourceAndReceive(Source requestPayload, WebServiceMessageCallback requestCallback,
+	<T> @Nullable T sendSourceAndReceive(Source requestPayload, WebServiceMessageCallback requestCallback,
 			SourceExtractor<T> responseExtractor) throws WebServiceClientException;
 
 	/**
@@ -233,8 +235,9 @@ <T> T sendSourceAndReceive(Source requestPayload, WebServiceMessageCallback requ
 	 * @throws WebServiceClientException if there is a problem sending or receiving the
 	 * message
 	 */
-	<T> T sendSourceAndReceive(String uri, Source requestPayload, WebServiceMessageCallback requestCallback,
-			SourceExtractor<T> responseExtractor) throws WebServiceClientException;
+	<T> @Nullable T sendSourceAndReceive(String uri, Source requestPayload,
+			@Nullable WebServiceMessageCallback requestCallback, SourceExtractor<T> responseExtractor)
+			throws WebServiceClientException;
 
 	// -----------------------------------------------------------------------------------------------------------------
 	// Convenience methods for sending Sources and receiving to Results