Polish "Support @Name with JavaBean-based configuration properties"

See 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

@@ -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.
@@ -26,6 +26,9 @@
  * 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

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2023 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.
@@ -62,11 +62,11 @@ class KotlinConfigurationPropertiesTests {
 	}
 
 	@Test
-	fun `renamed property can be bound to late init attribute`() {
-		this.context.register(EnableRenamedLateInitProperties::class.java)
+	fun `renamed property can be bound`() {
+		this.context.register(EnableRenamedProperties::class.java)
 		TestPropertySourceUtils.addInlinedPropertiesToEnvironment(this.context, "renamed.var=beta")
 		this.context.refresh()
-		assertThat(this.context.getBean(RenamedLateInitProperties::class.java).bar).isEqualTo("beta")
+		assertThat(this.context.getBean(RenamedProperties::class.java).bar).isEqualTo("beta")
 	}
 
 	@Test
@@ -90,15 +90,6 @@ class KotlinConfigurationPropertiesTests {
 	@ConfigurationProperties(prefix = "foo")
 	class BingProperties(@Suppress("UNUSED_PARAMETER") bar: String)
 
-	@ConfigurationProperties(prefix = "renamed")
-	class RenamedLateInitProperties{
-		@Name("var")
-		lateinit var bar: String
-	}
-
-	@EnableConfigurationProperties(RenamedLateInitProperties::class)
-	class EnableRenamedLateInitProperties
-
 	@EnableConfigurationProperties
 	class EnableConfigProperties
 
@@ -136,4 +127,13 @@ class KotlinConfigurationPropertiesTests {
 		var prop: String = ""
 	)
 
+	@EnableConfigurationProperties(RenamedProperties::class)
+	class EnableRenamedProperties
+
+	@ConfigurationProperties(prefix = "renamed")
+	class RenamedProperties{
+		@Name("var")
+		var bar: String = ""
+	}
+
 }