Merge pull request #39452 from BenchmarkingBuffalo

* gh-39452:
  Polish "Support `@Name` with JavaBean-based configuration properties"
  Support `@Name` with JavaBean-based configuration properties

Closes gh-39452

Author: wilkinsona

spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/external-config.adoc

@@ -713,6 +713,8 @@ The preceding POJO defines the following properties:
 * `my.service.security.password`.
 * `my.service.security.roles`, with a collection of `String` that defaults to `USER`.
 
+TIP: To use a reserved keyword in the name of a property, such as `my.service.import`, use the `@Name` annotation on the property's field.
+
 NOTE: The properties that map to `@ConfigurationProperties` classes available in Spring Boot, which are configured through properties files, YAML files, environment variables, and other mechanisms, are public API but the accessors (getters/setters) of the class itself are not meant to be used directly.
 
 [NOTE]

spring-boot-project/spring-boot-tools/spring-boot-configuration-processor/src/main/java/org/springframework/boot/configurationprocessor/PropertyDescriptorResolver.java

@@ -85,7 +85,7 @@ private Stream<PropertyDescriptor> resolveConstructorBoundProperties(TypeElement
 
 	private PropertyDescriptor extracted(TypeElement declaringElement, TypeElementMembers members,
 			VariableElement parameter) {
-		String name = getParameterName(parameter);
+		String name = getPropertyName(parameter);
 		TypeMirror type = parameter.asType();
 		ExecutableElement getter = members.getPublicGetter(name, type);
 		ExecutableElement setter = members.getPublicSetter(name, type);
@@ -98,12 +98,16 @@ private PropertyDescriptor extracted(TypeElement declaringElement, TypeElementMe
 						field);
 	}
 
-	private String getParameterName(VariableElement parameter) {
+	private String getPropertyName(VariableElement parameter) {
+		return getPropertyName(parameter, parameter.getSimpleName().toString());
+	}
+
+	private String getPropertyName(VariableElement parameter, String fallback) {
 		AnnotationMirror nameAnnotation = this.environment.getNameAnnotation(parameter);
 		if (nameAnnotation != null) {
 			return this.environment.getAnnotationElementStringValue(nameAnnotation, "value");
 		}
-		return parameter.getSimpleName().toString();
+		return fallback;
 	}
 
 	private Stream<PropertyDescriptor> resolveJavaBeanProperties(TypeElement declaringElement,
@@ -114,16 +118,16 @@ private Stream<PropertyDescriptor> resolveJavaBeanProperties(TypeElement declari
 			VariableElement field = members.getFields().get(name);
 			ExecutableElement getter = findMatchingGetter(members, getters, field);
 			TypeMirror propertyType = getter.getReturnType();
-			register(candidates, new JavaBeanPropertyDescriptor(name, propertyType, declaringElement, getter,
-					members.getPublicSetter(name, propertyType), field, factoryMethod));
+			register(candidates, new JavaBeanPropertyDescriptor(getPropertyName(field, name), propertyType,
+					declaringElement, getter, members.getPublicSetter(name, propertyType), field, factoryMethod));
 		});
 		// Then check for Lombok ones
 		members.getFields().forEach((name, field) -> {
 			TypeMirror propertyType = field.asType();
 			ExecutableElement getter = members.getPublicGetter(name, propertyType);
 			ExecutableElement setter = members.getPublicSetter(name, propertyType);
-			register(candidates, new LombokPropertyDescriptor(name, propertyType, declaringElement, getter, setter,
-					field, factoryMethod));
+			register(candidates, new LombokPropertyDescriptor(getPropertyName(field, name), propertyType,
+					declaringElement, getter, setter, field, factoryMethod));
 		});
 		return candidates.values().stream();
 	}

spring-boot-project/spring-boot-tools/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationprocessor/ImmutableNameAnnotationPropertiesTests.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2012-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.configurationprocessor;
+
+import org.junit.jupiter.api.Test;
+
+import org.springframework.boot.configurationprocessor.metadata.ConfigurationMetadata;
+import org.springframework.boot.configurationprocessor.metadata.Metadata;
+import org.springframework.boot.configurationsample.immutable.ConstructorParameterNameAnnotationProperties;
+import org.springframework.boot.configurationsample.immutable.JavaBeanNameAnnotationProperties;
+import org.springframework.boot.configurationsample.immutable.RecordComponentNameAnnotationProperties;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Metadata generation tests for using {@code @Name}.
+ *
+ * @author Phillip Webb
+ */
+class NameAnnotationPropertiesTests extends AbstractMetadataGenerationTests {
+
+	@Test
+	void constructorParameterNameAnnotationProperties() {
+		ConfigurationMetadata metadata = compile(ConstructorParameterNameAnnotationProperties.class);
+		assertThat(metadata).has(Metadata.withProperty("named.import", String.class)
+			.fromSource(ConstructorParameterNameAnnotationProperties.class));
+	}
+
+	@Test
+	void recordComponentNameAnnotationProperties() {
+		ConfigurationMetadata metadata = compile(RecordComponentNameAnnotationProperties.class);
+		assertThat(metadata).has(Metadata.withProperty("named.import", String.class)
+			.fromSource(RecordComponentNameAnnotationProperties.class));
+	}
+
+	@Test
+	void javaBeanNameAnnotationProperties() {
+		ConfigurationMetadata metadata = compile(JavaBeanNameAnnotationProperties.class);
+		assertThat(metadata).has(
+				Metadata.withProperty("named.import", String.class).fromSource(JavaBeanNameAnnotationProperties.class));
+	}
+
+}

spring-boot-project/spring-boot-tools/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationprocessor/NameAnnotationPropertiesTests.java

@@ -31,11 +31,13 @@
 import org.springframework.boot.configurationprocessor.metadata.ItemMetadata;
 import org.springframework.boot.configurationprocessor.test.RoundEnvironmentTester;
 import org.springframework.boot.configurationprocessor.test.TestableAnnotationProcessor;
+import org.springframework.boot.configurationsample.immutable.ConstructorParameterNameAnnotationProperties;
 import org.springframework.boot.configurationsample.immutable.ImmutableClassConstructorBindingProperties;
 import org.springframework.boot.configurationsample.immutable.ImmutableDeducedConstructorBindingProperties;
 import org.springframework.boot.configurationsample.immutable.ImmutableMultiConstructorProperties;
-import org.springframework.boot.configurationsample.immutable.ImmutableNameAnnotationProperties;
 import org.springframework.boot.configurationsample.immutable.ImmutableSimpleProperties;
+import org.springframework.boot.configurationsample.immutable.JavaBeanNameAnnotationProperties;
+import org.springframework.boot.configurationsample.immutable.RecordComponentNameAnnotationProperties;
 import org.springframework.boot.configurationsample.lombok.LombokExplicitProperties;
 import org.springframework.boot.configurationsample.lombok.LombokSimpleDataProperties;
 import org.springframework.boot.configurationsample.lombok.LombokSimpleProperties;
@@ -155,8 +157,20 @@ void propertiesWithMultiConstructorNoDirective() {
 	}
 
 	@Test
-	void propertiesWithNameAnnotationParameter() {
-		process(ImmutableNameAnnotationProperties.class,
+	void contructorParameterPropertyWithNameAnnotationParameter() {
+		process(ConstructorParameterNameAnnotationProperties.class,
+				propertyNames((stream) -> assertThat(stream).containsExactly("import")));
+	}
+
+	@Test
+	void recordComponentPropertyWithNameAnnotationParameter() {
+		process(RecordComponentNameAnnotationProperties.class,
+				propertyNames((stream) -> assertThat(stream).containsExactly("import")));
+	}
+
+	@Test
+	void javaBeanPropertyWithNameAnnotationParameter() {
+		process(JavaBeanNameAnnotationProperties.class,
 				propertyNames((stream) -> assertThat(stream).containsExactly("import")));
 	}
 

spring-boot-project/spring-boot-tools/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationprocessor/PropertyDescriptorResolverTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2020 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -28,7 +28,7 @@
  *
  * @author Phillip Webb
  */
-@Target(ElementType.PARAMETER)
+@Target({ ElementType.PARAMETER, ElementType.FIELD })
 @Retention(RetentionPolicy.RUNTIME)
 @Documented
 public @interface Name {

spring-boot-project/spring-boot-tools/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationsample/Name.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2022 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -20,16 +20,16 @@
 import org.springframework.boot.configurationsample.Name;
 
 /**
- * Immutable properties making use of {@code @Name}.
+ * Immutable class properties making use of {@code @Name}.
  *
  * @author Phillip Webb
  */
 @ConfigurationProperties("named")
-public class ImmutableNameAnnotationProperties {
+public class ConstructorParameterNameAnnotationProperties {
 
 	private final String imports;
 
-	public ImmutableNameAnnotationProperties(@Name("import") String imports) {
+	public ConstructorParameterNameAnnotationProperties(@Name("import") String imports) {
 		this.imports = imports;
 	}
 

spring-boot-project/spring-boot-tools/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationsample/immutable/ImmutableNameAnnotationProperties.java renamed to spring-boot-project/spring-boot-tools/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationsample/immutable/ConstructorParameterNameAnnotationProperties.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2012-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.configurationsample.immutable;
+
+import org.springframework.boot.configurationsample.ConfigurationProperties;
+import org.springframework.boot.configurationsample.Name;
+
+/**
+ * Java bean properties making use of {@code @Name}.
+ *
+ * @author Andy Wilkinson
+ */
+@ConfigurationProperties("named")
+public class JavaBeanNameAnnotationProperties {
+
+	@Name("import")
+	private String imports;
+
+	public String getImports() {
+		return this.imports;
+	}
+
+	public void setImports(String imports) {
+		this.imports = imports;
+	}
+
+}

spring-boot-project/spring-boot-tools/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationsample/immutable/JavaBeanNameAnnotationProperties.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2012-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.configurationsample.immutable;
+
+import org.springframework.boot.configurationsample.ConfigurationProperties;
+import org.springframework.boot.configurationsample.Name;
+
+/**
+ * Immutable record properties making use of {@code @Name}.
+ *
+ * @author Andy Wilkinson
+ */
+@ConfigurationProperties("named")
+public record RecordComponentNameAnnotationProperties(@Name("import") String imports) {
+
+}

spring-boot-project/spring-boot-tools/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationsample/immutable/RecordComponentNameAnnotationProperties.java

@@ -46,6 +46,7 @@
  *
  * @author Phillip Webb
  * @author Madhura Bhave
+ * @author Lasse Wulff
  */
 class JavaBeanBinder implements DataObjectBinder {
 
@@ -92,7 +93,7 @@ private <T> boolean bind(DataObjectPropertyBinder propertyBinder, Bean<T> bean,
 
 	private <T> boolean bind(BeanSupplier<T> beanSupplier, DataObjectPropertyBinder propertyBinder,
 			BeanProperty property) {
-		String propertyName = property.getName();
+		String propertyName = determinePropertyName(property);
 		ResolvableType type = property.getType();
 		Supplier<Object> value = property.getValue(beanSupplier);
 		Annotation[] annotations = property.getAnnotations();
@@ -110,6 +111,15 @@ else if (value == null || !bound.equals(value.get())) {
 		return true;
 	}
 
+	private String determinePropertyName(BeanProperty property) {
+		return Arrays.stream((property.getAnnotations() != null) ? property.getAnnotations() : new Annotation[0])
+			.filter((annotation) -> annotation.annotationType() == Name.class)
+			.findFirst()
+			.map(Name.class::cast)
+			.map(Name::value)
+			.orElse(property.getName());
+	}
+
 	/**
 	 * The properties of a bean that may be bound.
 	 */

spring-boot-project/spring-boot/src/main/java/org/springframework/boot/context/properties/bind/JavaBeanBinder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2022 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,15 +23,19 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotation that can be used to specify the name when binding to an immutable property.
- * This annotation may be required when binding to names that clash with reserved language
+ * Annotation that can be used to specify the name when binding to a property. This
+ * annotation may be required when binding to names that clash with reserved language
  * keywords.
+ * <p>
+ * When naming a JavaBean-based property, annotate the field. When naming a
+ * constructor-bound property, annotate the constructor parameter or record component.
  *
  * @author Phillip Webb
+ * @author Lasse Wulff
  * @since 2.4.0
  */
 @Retention(RetentionPolicy.RUNTIME)
-@Target(ElementType.PARAMETER)
+@Target({ ElementType.FIELD, ElementType.PARAMETER })
 @Documented
 public @interface Name {