Replace @OptionalParameter with JSpecify's @nullable

This commit removes OptionalParameter in favor of the nullness support
introduced in Spring Framework 7. The parameter of an action can now
be flagged as optional using JSpecify's @nullable, and simplifies the
setup for those who are using JSpecify as only a single annotation is
required.

Closes gh-45390

Author: snicoll

configuration-metadata/spring-boot-configuration-processor/src/main/java/org/springframework/boot/configurationprocessor/ConfigurationMetadataAnnotationProcessor.java

@@ -109,8 +109,6 @@ public class ConfigurationMetadataAnnotationProcessor extends AbstractProcessor
 
 	static final String READ_OPERATION_ANNOTATION = "org.springframework.boot.actuate.endpoint.annotation.ReadOperation";
 
-	static final String OPTIONAL_PARAMETER_ANNOTATION = "org.springframework.boot.actuate.endpoint.annotation.OptionalParameter";
-
 	static final String NAME_ANNOTATION = "org.springframework.boot.context.properties.bind.Name";
 
 	static final String ENDPOINT_ACCESS_ENUM = "org.springframework.boot.actuate.endpoint.Access";
@@ -166,10 +164,6 @@ protected String nameAnnotation() {
 		return NAME_ANNOTATION;
 	}
 
-	protected String optionalParameterAnnotation() {
-		return OPTIONAL_PARAMETER_ANNOTATION;
-	}
-
 	protected String endpointAccessEnum() {
 		return ENDPOINT_ACCESS_ENUM;
 	}
@@ -194,8 +188,7 @@ public synchronized void init(ProcessingEnvironment env) {
 		this.metadataEnv = new MetadataGenerationEnvironment(env, configurationPropertiesAnnotation(),
 				configurationPropertiesSourceAnnotation(), nestedConfigurationPropertyAnnotation(),
 				deprecatedConfigurationPropertyAnnotation(), constructorBindingAnnotation(), autowiredAnnotation(),
-				defaultValueAnnotation(), endpointAnnotations(), readOperationAnnotation(),
-				optionalParameterAnnotation(), nameAnnotation());
+				defaultValueAnnotation(), endpointAnnotations(), readOperationAnnotation(), nameAnnotation());
 	}
 
 	@Override
@@ -383,18 +376,13 @@ private boolean hasMainReadOperation(TypeElement element) {
 
 	private boolean hasNoOrOptionalParameters(ExecutableElement method) {
 		for (VariableElement parameter : method.getParameters()) {
-			if (!isOptionalParameter(parameter)) {
+			if (!this.metadataEnv.hasNullableAnnotation(parameter)) {
 				return false;
 			}
 		}
 		return true;
 	}
 
-	private boolean isOptionalParameter(VariableElement parameter) {
-		return this.metadataEnv.hasNullableAnnotation(parameter)
-				|| this.metadataEnv.hasOptionalParameterAnnotation(parameter);
-	}
-
 	private String getPrefix(AnnotationMirror annotation) {
 		String prefix = this.metadataEnv.getAnnotationElementStringValue(annotation, "prefix");
 		if (prefix != null) {

configuration-metadata/spring-boot-configuration-processor/src/main/java/org/springframework/boot/configurationprocessor/MetadataGenerationEnvironment.java

@@ -98,8 +98,6 @@ class MetadataGenerationEnvironment {
 
 	private final String readOperationAnnotation;
 
-	private final String optionalParameterAnnotation;
-
 	private final String nameAnnotation;
 
 	private final String autowiredAnnotation;
@@ -108,7 +106,7 @@ class MetadataGenerationEnvironment {
 			String configurationPropertiesSourceAnnotation, String nestedConfigurationPropertyAnnotation,
 			String deprecatedConfigurationPropertyAnnotation, String constructorBindingAnnotation,
 			String autowiredAnnotation, String defaultValueAnnotation, Set<String> endpointAnnotations,
-			String readOperationAnnotation, String optionalParameterAnnotation, String nameAnnotation) {
+			String readOperationAnnotation, String nameAnnotation) {
 		this.typeUtils = new TypeUtils(environment);
 		this.elements = environment.getElementUtils();
 		this.messager = environment.getMessager();
@@ -123,7 +121,6 @@ class MetadataGenerationEnvironment {
 		this.defaultValueAnnotation = defaultValueAnnotation;
 		this.endpointAnnotations = endpointAnnotations;
 		this.readOperationAnnotation = readOperationAnnotation;
-		this.optionalParameterAnnotation = optionalParameterAnnotation;
 		this.nameAnnotation = nameAnnotation;
 	}
 
@@ -382,10 +379,6 @@ boolean hasNullableAnnotation(Element element) {
 		return getTypeUseAnnotation(element, NULLABLE_ANNOTATION) != null;
 	}
 
-	boolean hasOptionalParameterAnnotation(Element element) {
-		return getAnnotation(element, this.optionalParameterAnnotation) != null;
-	}
-
 	private boolean isElementDeprecated(Element element) {
 		return hasAnnotation(element, "java.lang.Deprecated")
 				|| hasAnnotation(element, this.deprecatedConfigurationPropertyAnnotation);

configuration-metadata/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationprocessor/EndpointMetadataGenerationTests.java

@@ -29,7 +29,6 @@
 import org.springframework.boot.configurationsample.endpoint.EnabledEndpoint;
 import org.springframework.boot.configurationsample.endpoint.NoAccessEndpoint;
 import org.springframework.boot.configurationsample.endpoint.NullableParameterEndpoint;
-import org.springframework.boot.configurationsample.endpoint.OptionalParameterEndpoint;
 import org.springframework.boot.configurationsample.endpoint.ReadOnlyAccessEndpoint;
 import org.springframework.boot.configurationsample.endpoint.SimpleEndpoint;
 import org.springframework.boot.configurationsample.endpoint.SimpleEndpoint2;
@@ -153,7 +152,7 @@ void incrementalEndpointBuildChangeCacheFlag() {
 		assertThat(metadata).has(access("incremental", Access.UNRESTRICTED));
 		assertThat(metadata).has(cacheTtl("incremental"));
 		assertThat(metadata.getItems()).hasSize(3);
-		project.replaceText(IncrementalEndpoint.class, "@OptionalParameter String param", "String param");
+		project.replaceText(IncrementalEndpoint.class, "@Nullable String param", "String param");
 		metadata = project.compile();
 		assertThat(metadata)
 			.has(Metadata.withGroup("management.endpoint.incremental").fromSource(IncrementalEndpoint.class));
@@ -205,16 +204,6 @@ void endpointWithNullableParameter() {
 		assertThat(metadata.getItems()).hasSize(3);
 	}
 
-	@Test
-	void endpointWithOptionalParameter() {
-		ConfigurationMetadata metadata = compile(OptionalParameterEndpoint.class);
-		assertThat(metadata)
-			.has(Metadata.withGroup("management.endpoint.optional").fromSource(OptionalParameterEndpoint.class));
-		assertThat(metadata).has(access("optional", Access.UNRESTRICTED));
-		assertThat(metadata).has(cacheTtl("optional"));
-		assertThat(metadata.getItems()).hasSize(3);
-	}
-
 	private Metadata.MetadataItemCondition access(String endpointId, Access defaultValue) {
 		return defaultAccess(endpointId, endpointId, defaultValue);
 	}

configuration-metadata/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationprocessor/MetadataGenerationEnvironmentFactory.java

@@ -49,7 +49,6 @@ public MetadataGenerationEnvironment apply(ProcessingEnvironment environment) {
 				TestConfigurationMetadataAnnotationProcessor.AUTOWIRED_ANNOTATION,
 				TestConfigurationMetadataAnnotationProcessor.DEFAULT_VALUE_ANNOTATION, endpointAnnotations,
 				TestConfigurationMetadataAnnotationProcessor.READ_OPERATION_ANNOTATION,
-				TestConfigurationMetadataAnnotationProcessor.OPTIONAL_PARAMETER_ANNOTATION,
 				TestConfigurationMetadataAnnotationProcessor.NAME_ANNOTATION);
 	}
 

configuration-metadata/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationprocessor/test/TestConfigurationMetadataAnnotationProcessor.java

@@ -75,8 +75,6 @@ public class TestConfigurationMetadataAnnotationProcessor extends ConfigurationM
 
 	public static final String READ_OPERATION_ANNOTATION = "org.springframework.boot.configurationsample.ReadOperation";
 
-	public static final String OPTIONAL_PARAMETER_ANNOTATION = "org.springframework.boot.configurationsample.OptionalParameter";
-
 	public static final String NAME_ANNOTATION = "org.springframework.boot.configurationsample.Name";
 
 	public static final String ENDPOINT_ACCESS_ENUM = "org.springframework.boot.configurationsample.Access";
@@ -130,11 +128,6 @@ protected String readOperationAnnotation() {
 		return READ_OPERATION_ANNOTATION;
 	}
 
-	@Override
-	protected String optionalParameterAnnotation() {
-		return OPTIONAL_PARAMETER_ANNOTATION;
-	}
-
 	@Override
 	protected String nameAnnotation() {
 		return NAME_ANNOTATION;

configuration-metadata/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationsample/OptionalParameter.java

@@ -16,8 +16,9 @@
 
 package org.springframework.boot.configurationsample.endpoint;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.boot.configurationsample.Access;
-import org.springframework.boot.configurationsample.OptionalParameter;
 import org.springframework.boot.configurationsample.ReadOperation;
 import org.springframework.boot.configurationsample.WebEndpoint;
 
@@ -31,7 +32,7 @@
 public class SpecificEndpoint {
 
 	@ReadOperation
-	String invoke(@OptionalParameter String param) {
+	String invoke(@Nullable String param) {
 		return "test";
 	}
 

configuration-metadata/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationsample/endpoint/OptionalParameterEndpoint.java

@@ -16,8 +16,9 @@
 
 package org.springframework.boot.configurationsample.endpoint.incremental;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.boot.configurationsample.Endpoint;
-import org.springframework.boot.configurationsample.OptionalParameter;
 import org.springframework.boot.configurationsample.ReadOperation;
 
 /**
@@ -29,7 +30,7 @@
 public class IncrementalEndpoint {
 
 	@ReadOperation
-	public String invoke(@OptionalParameter String param) {
+	public String invoke(@Nullable String param) {
 		return "test";
 	}
 

configuration-metadata/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationsample/endpoint/SpecificEndpoint.java

@@ -412,7 +412,7 @@ Operations on an endpoint receive input through their parameters.
 When exposed over the web, the values for these parameters are taken from the URL's query parameters and from the JSON request body.
 When exposed over JMX, the parameters are mapped to the parameters of the MBean's operations.
 Parameters are required by default.
-They can be made optional by annotating them with either javadoc:org.springframework.boot.actuate.endpoint.annotation.OptionalParameter[format=annotation] or JSpecify's javadoc:org.jspecify.annotations.Nullable[format=annotation].
+They can be made optional by annotating them with JSpecify's javadoc:org.jspecify.annotations.Nullable[format=annotation].
 Kotlin null safety is also supported.
 
 You can map each root property in the JSON request body to a parameter of the endpoint.
@@ -544,7 +544,7 @@ When using Spring MVC or Spring Web Flux, operations that return a javadoc:org.s
 ==== Web Endpoint Security
 
 An operation on a web endpoint or a web-specific endpoint extension can receive the current javadoc:java.security.Principal[] or javadoc:org.springframework.boot.actuate.endpoint.SecurityContext[] as a method parameter.
-The former is typically used in conjunction with either javadoc:org.springframework.boot.actuate.endpoint.annotation.OptionalParameter[format=annotation] or javadoc:org.jspecify.annotations.Nullable[format=annotation] to provide different behavior for authenticated and unauthenticated users.
+The former is typically used in conjunction with javadoc:org.jspecify.annotations.Nullable[format=annotation] to provide different behavior for authenticated and unauthenticated users.
 The latter is typically used to perform authorization checks by using its `isUserInRole(String)` method.