Three new article modules: configuration binding, profiles and config data, Spring AOP
configuration-properties/ @ConfigurationProperties vs @Value on Spring Boot 4.1.1. The relaxed-binding matrix is generated by binding each spelling rather than transcribed, and re-checked against real processes -- the in-process probe was wrong twice before it was right. Records the three findings that came out of it: @Value does get relaxed resolution inside Spring Boot (Boot attaches ConfigurationPropertySources), the configuration processor silently stops generating metadata on JDK 23+ when declared as a plain dependency, and @Valid is not what makes nested constraints run. profiles-and-config/ Precedence, profiles, spring.config.import and config trees. /precedence reports every source holding a property in rank order with file and line, which turns "my profile file had no effect" into a two-line answer. Also pins the counterintuitive one: an imported file outranks the file that imported it. spring-aop/ Designators, proxy types, and aspects that do not fire. One advice per supported designator so the reference table is generated from real matches; all fourteen unsupported designators fed to the parser. Two corrections to the reference documentation: unsupported designators throw UnsupportedPointcutPrimitiveException (extends RuntimeException, not IllegalArgumentException), and spring-boot-starter-aop was renamed to spring-boot-starter-aspectj in Boot 4. 19 contract tests across the three modules, 15 captured transcripts, all regenerated by scripts/run-all.sh. Verified on Spring Boot 4.1.1, Spring Framework 7.0.9, JDK 25.0.4.1. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Gip4srpzMwjgoba6uEfbr5
This commit is contained in:
7
configuration-properties/docs/output/00-versions.txt
Normal file
7
configuration-properties/docs/output/00-versions.txt
Normal file
@@ -0,0 +1,7 @@
|
||||
== versions ==
|
||||
openjdk version "25.0.4.1" 2026-08-18 LTS
|
||||
OpenJDK Runtime Environment Temurin-25.0.4.1+1 (build 25.0.4.1+1-LTS)
|
||||
OpenJDK 64-Bit Server VM Temurin-25.0.4.1+1 (build 25.0.4.1+1-LTS, mixed mode, sharing)
|
||||
|
||||
|
||||
spring-boot-starter-parent: 4.1.1
|
||||
22
configuration-properties/docs/output/01-relaxed-matrix.txt
Normal file
22
configuration-properties/docs/output/01-relaxed-matrix.txt
Normal file
@@ -0,0 +1,22 @@
|
||||
== relaxed binding matrix ==
|
||||
canonical property: demo.relaxed.api-key
|
||||
|
||||
SPELLING SOURCE BINDER ${} plain ${} boot
|
||||
--------------------------------------------------------------
|
||||
demo.relaxed.api-key map bound bound bound
|
||||
demo.relaxed.apiKey map bound MISS bound
|
||||
demo.relaxed.api_key map bound MISS bound
|
||||
demo.relaxed.APIKEY map bound MISS bound
|
||||
DEMO.RELAXED.API-KEY map bound MISS bound
|
||||
demo.relaxed.apikey map bound MISS bound
|
||||
demo.relaxed.api.key map MISS MISS MISS
|
||||
DEMO_RELAXED_API_KEY env bound bound bound
|
||||
DEMO_RELAXED_APIKEY env bound MISS bound
|
||||
demo_relaxed_api_key env bound bound bound
|
||||
DEMO.RELAXED.API-KEY env bound bound bound
|
||||
|
||||
BINDER = what @ConfigurationProperties sees (Binder)
|
||||
${} plain = placeholder resolution against a bare StandardEnvironment
|
||||
${} boot = the same, after ConfigurationPropertySources.attach(env),
|
||||
which Spring Boot performs on every environment it prepares
|
||||
bound = the value arrived; MISS = the property was not found
|
||||
43
configuration-properties/docs/output/02-env-var-binding.txt
Normal file
43
configuration-properties/docs/output/02-env-var-binding.txt
Normal file
@@ -0,0 +1,43 @@
|
||||
== real process, real environment: binding demo.relaxed.api-key ==
|
||||
|
||||
canonical property : demo.relaxed.api-key
|
||||
(MISS) means the property was not found and the declared default was used
|
||||
|
||||
--- as an operating-system environment variable ---
|
||||
|
||||
$ DEMO_RELAXED_API_KEY=secret-value java -jar target/configuration-properties-1.0.0.jar
|
||||
env-var-set : DEMO_RELAXED_API_KEY=secret-value
|
||||
@ConfigurationProps: secret-value
|
||||
@Value : secret-value
|
||||
Environment.get : secret-value
|
||||
|
||||
$ DEMO_RELAXED_APIKEY=secret-value java -jar target/configuration-properties-1.0.0.jar
|
||||
env-var-set : DEMO_RELAXED_APIKEY=secret-value
|
||||
@ConfigurationProps: secret-value
|
||||
@Value : secret-value
|
||||
Environment.get : secret-value
|
||||
|
||||
--- as a JVM system property (-D), i.e. the 'map' rows of the matrix ---
|
||||
|
||||
$ java -Ddemo.relaxed.api-key=secret-value -jar target/configuration-properties-1.0.0.jar
|
||||
@ConfigurationProps: secret-value
|
||||
@Value : secret-value
|
||||
Environment.get : secret-value
|
||||
|
||||
$ java -Ddemo.relaxed.apiKey=secret-value -jar target/configuration-properties-1.0.0.jar
|
||||
@ConfigurationProps: secret-value
|
||||
@Value : secret-value
|
||||
Environment.get : secret-value
|
||||
|
||||
$ java -Ddemo.relaxed.apikey=secret-value -jar target/configuration-properties-1.0.0.jar
|
||||
@ConfigurationProps: secret-value
|
||||
@Value : secret-value
|
||||
Environment.get : secret-value
|
||||
|
||||
$ java -Ddemo.relaxed.api.key=secret-value -jar target/configuration-properties-1.0.0.jar
|
||||
@ConfigurationProps: (unset)
|
||||
@Value : (MISS)
|
||||
Environment.get : (MISS)
|
||||
|
||||
The last one is not a spelling of the property. api.key is two name elements;
|
||||
api-key is one. Nothing relaxed will ever join them.
|
||||
79
configuration-properties/docs/output/03-value-vs-binding.txt
Normal file
79
configuration-properties/docs/output/03-value-vs-binding.txt
Normal file
@@ -0,0 +1,79 @@
|
||||
== @ConfigurationProperties vs @Value, same application, same application.yaml ==
|
||||
|
||||
$ curl -s localhost:8080/diag/bound
|
||||
{
|
||||
"mail": {
|
||||
"host": "smtp.example.com",
|
||||
"port": 587,
|
||||
"timeout": "PT45S",
|
||||
"retries": {
|
||||
"maxAttempts": 5,
|
||||
"backoff": "PT1.5S"
|
||||
},
|
||||
"recipients": [
|
||||
"ops@example.com",
|
||||
"oncall@example.com"
|
||||
],
|
||||
"headers": {
|
||||
"X-Env": "demo",
|
||||
"X-Team": "platform"
|
||||
}
|
||||
},
|
||||
"validated": {
|
||||
"name": "demo-service",
|
||||
"port": 8443,
|
||||
"endpoint": "https://api.example.com",
|
||||
"pool": {
|
||||
"size": 25
|
||||
}
|
||||
},
|
||||
"fromValueAnnotation": {
|
||||
"host": "smtp.example.com",
|
||||
"port": 587,
|
||||
"timeout": "PT45S",
|
||||
"recipients": [],
|
||||
"poolSize": 25,
|
||||
"computedThreads": 4
|
||||
}
|
||||
}
|
||||
|
||||
demo.mail.recipients is a YAML block list. The binder produced both elements.
|
||||
@Value produced an empty list -- placeholder resolution has no concept of a YAML
|
||||
sequence, so ${demo.mail.recipients:} fell through to its own empty default.
|
||||
|
||||
== the same list written as a comma-separated string, at higher precedence ==
|
||||
$ ./scripts/run.sh "" --demo.mail.recipients=x@e.com,y@e.com,z@e.com
|
||||
binder : ['x@e.com', 'y@e.com', 'z@e.com']
|
||||
@Value : ['x@e.com', 'y@e.com', 'z@e.com']
|
||||
|
||||
Both see it. A comma-separated string is the one list shape @Value understands, and
|
||||
the command-line source outranks the YAML file for the binder as well.
|
||||
|
||||
== where did that value come from? ==
|
||||
$ curl -s 'localhost:8080/diag/origin?name=demo.mail.recipients'
|
||||
{
|
||||
"property": "demo.mail.recipients",
|
||||
"effectiveValue": "x@e.com,y@e.com,z@e.com",
|
||||
"candidatesInPrecedenceOrder": [
|
||||
{
|
||||
"source": "SimpleCommandLinePropertySource {name='commandLineArgs'}",
|
||||
"value": "x@e.com,y@e.com,z@e.com",
|
||||
"origin": "\"demo.mail.recipients\" from property source \"commandLineArgs\""
|
||||
}
|
||||
],
|
||||
"shadowedBy": null
|
||||
}
|
||||
|
||||
$ curl -s 'localhost:8080/diag/origin?name=demo.mail.host'
|
||||
{
|
||||
"property": "demo.mail.host",
|
||||
"effectiveValue": "smtp.example.com",
|
||||
"candidatesInPrecedenceOrder": [
|
||||
{
|
||||
"source": "OriginTrackedMapPropertySource {name='Config resource 'class path resource [application.yaml]' via location 'optional:classpath:/''}",
|
||||
"value": "smtp.example.com",
|
||||
"origin": "class path resource [application.yaml] from configuration-properties-1.0.0.jar - 15:11"
|
||||
}
|
||||
],
|
||||
"shadowedBy": null
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
== startup with demo.validated.* deliberately out of range ==
|
||||
$ java -jar target/configuration-properties-1.0.0.jar --spring.profiles.active=badvalidation
|
||||
|
||||
APPLICATION FAILED TO START
|
||||
***************************
|
||||
|
||||
Description:
|
||||
|
||||
Binding to target com.ankurm.configprops.props.ValidatedProperties failed:
|
||||
|
||||
Property: demo.validated.pool.size
|
||||
Value: "4000"
|
||||
Reason: must be less than or equal to 100
|
||||
|
||||
Property: demo.validated.endpoint
|
||||
Value: "ftp://files.example.com"
|
||||
Origin: class path resource [application-badvalidation.yaml] from configuration-properties-1.0.0.jar - 8:15
|
||||
Reason: must match "https?://.*"
|
||||
|
||||
Property: demo.validated.port
|
||||
Value: "99999"
|
||||
Origin: class path resource [application-badvalidation.yaml] from configuration-properties-1.0.0.jar - 6:11
|
||||
Reason: must be less than or equal to 65535
|
||||
|
||||
Property: demo.validated.name
|
||||
Value: " "
|
||||
Origin: class path resource [application-badvalidation.yaml] from configuration-properties-1.0.0.jar - 4:11
|
||||
Reason: must not be blank
|
||||
|
||||
|
||||
Action:
|
||||
|
||||
Update your application's configuration
|
||||
@@ -0,0 +1,68 @@
|
||||
== is the annotation processor discovered? ==
|
||||
|
||||
openjdk version "25.0.4.1" 2026-08-18 LTS
|
||||
processor jar: spring-boot-configuration-processor-4.1.1.jar
|
||||
|
||||
A) processor on the classpath, javac defaults -- what an <optional> dependency gives you
|
||||
$ javac -cp <deps>:spring-boot-configuration-processor.jar -d a $SOURCES
|
||||
spring-configuration-metadata.json files produced: 0
|
||||
|
||||
B) identical, plus -proc:full
|
||||
$ javac -proc:full -cp <deps>:spring-boot-configuration-processor.jar -d b $SOURCES
|
||||
spring-configuration-metadata.json files produced: 1
|
||||
|
||||
Both compilations succeed. Only one of them has metadata.
|
||||
|
||||
== what this project's pom does instead ==
|
||||
The processor is declared as an <annotationProcessorPath> on maven-compiler-plugin,
|
||||
which puts it on javac's --processor-path where discovery is not disabled:
|
||||
|
||||
$ mvn clean package && ls target/classes/META-INF/
|
||||
spring-configuration-metadata.json
|
||||
|
||||
== the generated metadata, first entries ==
|
||||
{
|
||||
"groups": [
|
||||
{
|
||||
"name": "demo.mail",
|
||||
"type": "com.ankurm.configprops.props.MailProperties",
|
||||
"sourceType": "com.ankurm.configprops.props.MailProperties"
|
||||
},
|
||||
{
|
||||
"name": "demo.mail.retries",
|
||||
"type": "com.ankurm.configprops.props.MailProperties$RetryProperties",
|
||||
"sourceType": "com.ankurm.configprops.props.MailProperties",
|
||||
"sourceMethod": "retries()"
|
||||
},
|
||||
{
|
||||
"name": "demo.relaxed",
|
||||
"type": "com.ankurm.configprops.props.RelaxedProperties",
|
||||
"sourceType": "com.ankurm.configprops.props.RelaxedProperties"
|
||||
},
|
||||
{
|
||||
"name": "demo.validated",
|
||||
"type": "com.ankurm.configprops.props.ValidatedProperties",
|
||||
"sourceType": "com.ankurm.configprops.props.ValidatedProperties"
|
||||
},
|
||||
{
|
||||
"name": "demo.validated.pool",
|
||||
"type": "com.ankurm.configprops.props.ValidatedProperties$Pool",
|
||||
"sourceType": "com.ankurm.configprops.props.ValidatedProperties",
|
||||
"sourceMethod": "pool()"
|
||||
}
|
||||
],
|
||||
"properties": [
|
||||
{
|
||||
"name": "demo.mail.headers",
|
||||
"type": "java.util.Map<java.lang.String,java.lang.String>",
|
||||
"description": "Bound from arbitrary sub-keys under {@code demo.mail.headers.*}.",
|
||||
"sourceType": "com.ankurm.configprops.props.MailProperties"
|
||||
},
|
||||
{
|
||||
"name": "demo.mail.host",
|
||||
"type": "java.lang.String",
|
||||
"description": "SMTP host. No default: absent means the application must not start.",
|
||||
"sourceType": "com.ankurm.configprops.props.MailProperties"
|
||||
},
|
||||
{
|
||||
"name": "demo.mail.port",
|
||||
Reference in New Issue
Block a user