This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch docs
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/docs by this push:
new d55411c5ba docs: document PropertySource hierarchy and unified $P
variable
d55411c5ba is described below
commit d55411c5ba06c050816d65bf6bb863e060ff5456
Author: James Bognar <[email protected]>
AuthorDate: Thu May 14 12:17:03 2026 -0400
docs: document PropertySource hierarchy and unified $P variable
Co-authored-by: Cursor <[email protected]>
---
pages/release-notes/9.5.0.md | 12 +++++++
pages/topics/02.21.02.SvlVariables.md | 5 +++
pages/topics/05.04.03.PropertySources.md | 45 ++++++++++++++++++++++++++
pages/topics/06.02.04.JuneauCommonsSettings.md | 22 +++++++------
pages/topics/23.01.V9.5-migration-guide.md | 2 ++
5 files changed, 76 insertions(+), 10 deletions(-)
diff --git a/pages/release-notes/9.5.0.md b/pages/release-notes/9.5.0.md
index 7d9bf11593..5c4754f4e2 100644
--- a/pages/release-notes/9.5.0.md
+++ b/pages/release-notes/9.5.0.md
@@ -10,6 +10,18 @@ Juneau 9.5.0 is a minor release with native TOML and YAML
support, BSON (Binary
### juneau-marshall
+### juneau-commons
+
+#### Unified Property Source Hierarchy (TODO-27 + TODO-13)
+
+- Added a new property-source SPI naming model: `PropertySource` /
`PropertyStore` and functional variants.
+- Added `PropertySourceProvider` (ServiceLoader SPI) so ambient sources can be
auto-registered onto `Settings`.
+- Added built-in property sources for args, manifest entries, system
properties, environment variables, and `.env`.
+- Added runtime source wiring via `Settings.addSource(PropertySource)` to
allow explicit opt-in sources.
+- Added `PropertyVar` (`$P{key[,default]}`) as the SVL unified property-stack
resolver.
+- Existing `$S` / `$E` / `$A` / `$MF` vars remain supported as source-specific
resolvers, now aligned with the unified settings model.
+- **Breaking:** `SettingSource`, `SettingStore`, `FunctionalSource`, and
`FunctionalStore` have been removed outright (no deprecation shims). Migrate to
`PropertySource`, `PropertyStore`, `FunctionalPropertySource`, and
`FunctionalPropertyStore` respectively.
+
#### Bean→Marshalled Rename (TODO-21)
A comprehensive rename of annotation and engine types to clarify the
distinction between *Java-bean-structure* types (which keep `BeanXxx` names)
and *marshalling-process* types (which are now `MarshallingXxx`).
diff --git a/pages/topics/02.21.02.SvlVariables.md
b/pages/topics/02.21.02.SvlVariables.md
index c028be81e8..4c40b9fde0 100644
--- a/pages/topics/02.21.02.SvlVariables.md
+++ b/pages/topics/02.21.02.SvlVariables.md
@@ -50,6 +50,7 @@ The following is the list of default variables defined in all
modules:
| Module | Class | Pattern |
|--------|-------|---------|
+| **juneau-svl** | <a
href="/site/apidocs/org/apache/juneau/commons/svl/vars/PropertyVar.html"
target="_blank">PropertyVar</a> | `$P{key[,default]}` |
| **juneau-svl** | <a
href="/site/apidocs/org/apache/juneau/commons/svl/vars/EnvVariablesVar.html"
target="_blank">EnvVariablesVar</a> | `$E{key[,default]}` |
| | <a
href="/site/apidocs/org/apache/juneau/commons/svl/vars/SystemPropertiesVar.html"
target="_blank">SystemPropertiesVar</a> | `$S{key[,default]}` |
| | <a href="/site/apidocs/org/apache/juneau/commons/svl/vars/ArgsVar.html"
target="_blank">ArgsVar</a> | `$A{key[,default]}` |
@@ -81,3 +82,7 @@ The following is the list of default variables defined in all
modules:
| | <a href="/site/apidocs/org/apache/juneau/rest/vars/SwaggerVar.html"
target="_blank">SwaggerVar</a> | `$SS{key1[,key2...]}` |
| | <a href="/site/apidocs/org/apache/juneau/rest/vars/UrlVar.html"
target="_blank">UrlVar</a> | `$U{uri}` |
| | <a href="/site/apidocs/org/apache/juneau/rest/vars/UrlEncodeVar.html"
target="_blank">UrlEncodeVar</a> | `$UE{uriPart}` |
+
+`$P{...}` is the unified property-stack resolver. It walks the configured
`Settings` property source precedence
+(local overrides, global overrides, args, system properties, environment,
`.env`, and any custom sources). Use
+`$S{...}` / `$E{...}` / `$A{...}` / `$MF{...}` / `$C{...}` when you need a
source-specific lookup.
diff --git a/pages/topics/05.04.03.PropertySources.md
b/pages/topics/05.04.03.PropertySources.md
new file mode 100644
index 0000000000..cc8d42034f
--- /dev/null
+++ b/pages/topics/05.04.03.PropertySources.md
@@ -0,0 +1,45 @@
+---
+title: "Property Sources"
+slug: PropertySources
+---
+
+Juneau 9.5 introduces a unified property-source model behind
+<a href="/site/apidocs/org/apache/juneau/commons/settings/Settings.html"
target="_blank">Settings</a>.
+
+## Core APIs
+
+- `PropertySource` - Read-only source of `name -> Optional<String>`.
+- `PropertyStore` - Read/write source (extends `PropertySource`).
+- `PropertySourceProvider` - ServiceLoader SPI for auto-registering ambient
sources.
+
+## Default Source Stack
+
+By default, the stack resolves in this priority order (highest first):
+
+1. Thread-local overrides (`Settings.setLocal(...)`)
+2. Global overrides (`Settings.setGlobal(...)`)
+3. CLI args (`ArgsPropertySource`)
+4. JVM system properties
+5. Environment variables
+6. `.env` file
+7. Manifest entries
+
+Applications can add custom sources with:
+
+```java
+Settings.get().addSource(mySource);
+```
+
+## Config Integration
+
+`Config` is explicitly wired to avoid hidden lifecycle ownership:
+
+```java
+Config config = Config.create().build();
+Settings.get().addSource(new ConfigPropertySource(config));
+```
+
+## SVL Integration
+
+- `$P{key[,default]}` is the unified property-stack lookup.
+- `$S`, `$E`, `$A`, `$MF`, `$C` remain source-specific lookups.
diff --git a/pages/topics/06.02.04.JuneauCommonsSettings.md
b/pages/topics/06.02.04.JuneauCommonsSettings.md
index 84c7dc9ce3..b739243d5a 100644
--- a/pages/topics/06.02.04.JuneauCommonsSettings.md
+++ b/pages/topics/06.02.04.JuneauCommonsSettings.md
@@ -65,7 +65,7 @@ springSource.set("spring.datasource.url",
"jdbc:postgresql://localhost/db");
Settings custom = Settings.create()
.addSource(springSource)
- .addSource(<java-class><a
href="/site/apidocs/org/apache/juneau/commons/settings/FunctionalSource.html"
target="_blank">FunctionalSource</a></java-class>.of(System::getProperty))
+ .addSource(<java-class><a
href="/site/apidocs/org/apache/juneau/commons/settings/FunctionalPropertySource.html"
target="_blank">FunctionalPropertySource</a></java-class>.of(System::getProperty))
.build();
```
@@ -79,22 +79,22 @@ When retrieving a property value, the lookup order is:
4. System property source (default, always second-to-last)
5. System environment variable source (default, always last)
-## Setting Sources and Stores
+## Property Sources and Stores
-### <java-interface><a
href="/site/apidocs/org/apache/juneau/commons/settings/SettingSource.html"
target="_blank">SettingSource</a></java-interface>
+### <java-interface><a
href="/site/apidocs/org/apache/juneau/commons/settings/PropertySource.html"
target="_blank">PropertySource</a></java-interface>
Provides read-only access to property values.
```java
// Functional source
-SettingSource source = <java-class><a
href="/site/apidocs/org/apache/juneau/commons/settings/FunctionalSource.html"
target="_blank">FunctionalSource</a></java-class>.of(System::getProperty);
+PropertySource source = <java-class><a
href="/site/apidocs/org/apache/juneau/commons/settings/FunctionalPropertySource.html"
target="_blank">FunctionalPropertySource</a></java-class>.of(System::getProperty);
// Map-based source
<java-class><a
href="/site/apidocs/org/apache/juneau/commons/settings/MapStore.html"
target="_blank">MapStore</a></java-class> store = new MapStore();
store.set("key", "value");
-SettingSource source2 = store; // Stores extend SettingSource
+PropertySource source2 = store; // Stores extend PropertySource
```
-### <java-interface><a
href="/site/apidocs/org/apache/juneau/commons/settings/SettingStore.html"
target="_blank">SettingStore</a></java-interface>
+### <java-interface><a
href="/site/apidocs/org/apache/juneau/commons/settings/PropertyStore.html"
target="_blank">PropertyStore</a></java-interface>
Provides read/write access to property values.
```java
@@ -104,9 +104,11 @@ store.set("key", "value");
String value = store.get("key");
// Functional store
-<java-class><a
href="/site/apidocs/org/apache/juneau/commons/settings/FunctionalStore.html"
target="_blank">FunctionalStore</a></java-class> store2 = FunctionalStore.of(
- key -> getValue(key), // Getter
- (key, value) -> setValue(key, value) // Setter
+<java-class><a
href="/site/apidocs/org/apache/juneau/commons/settings/FunctionalPropertyStore.html"
target="_blank">FunctionalPropertyStore</a></java-class> store2 =
FunctionalPropertyStore.of(
+ key -> getValue(key), // Getter
+ (key, value) -> setValue(key, value), // Setter
+ key -> removeValue(key), // Unsetter
+ () -> clearAll() // Clear
);
```
@@ -167,7 +169,7 @@ configFile.set("app.version", "1.0.0");
Settings settings = Settings.create()
.addSource(configFile) // Check config file first
- .addSource(FunctionalSource.of(System::getProperty)) // Then system
properties
+ .addSource(FunctionalPropertySource.of(System::getProperty)) // Then
system properties
.build();
String appName = settings.get("app.name").get();
diff --git a/pages/topics/23.01.V9.5-migration-guide.md
b/pages/topics/23.01.V9.5-migration-guide.md
index 4ee792d140..f10d3eb007 100644
--- a/pages/topics/23.01.V9.5-migration-guide.md
+++ b/pages/topics/23.01.V9.5-migration-guide.md
@@ -43,6 +43,8 @@ teams jumping from 9.1 (or earlier) directly to 9.5 have a
single reference.
| `ManifestFile#getString(...)` / `getWithDefault(...)` / `containsKey(...)`
(and other `JsonMap` methods) | `ManifestFile#get(String).orElse(...)`,
`get(String section, String key)` | Convert callers to explicit `Optional`
handling and parsing. |
| `Microservice#getArgs()` / `Builder.args(Args)` / console command signatures
using old `Args` | Same methods/signatures but now typed to
`org.apache.juneau.commons.runtime.Args` | Most call sites only need import +
method rename updates (`getArg` -> `get(...).orElse(...)`). |
| `Microservice#getManifest()` / `Builder.manifest(Object)` consumers using
old `ManifestFile` API | Same methods/signatures but now typed to
`org.apache.juneau.commons.runtime.ManifestFile` | Replace
`getString()`/`containsKey()` patterns with `Optional`-based `get(...)`. |
+| `SettingSource` / `SettingStore` / `FunctionalSource` / `FunctionalStore` |
`PropertySource` / `PropertyStore` / `FunctionalPropertySource` /
`FunctionalPropertyStore` | SPI rename for settings/property source
composition. The old types have been removed (no compatibility shims); existing
`Settings` facade remains, migrate custom source/store implementations to the
renamed interfaces. |
+| Source-specific SVL lookups (`$S`, `$E`, `$A`, `$MF`, `$C`) as the only
option for property discovery | New unified resolver `$P{key[,default]}` | `$P`
walks the configured `Settings` source hierarchy. Keep source-specific vars
when strict source targeting is required. |
## Bean→Marshalled Renames
