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 9c515608b9 Add fluent Config.entry(key) builder as an additive
alternative to the 6-arg set() (TODO-350 B-config-2)
9c515608b9 is described below
commit 9c515608b9c77900aade44c109975ec5c4473456
Author: James Bognar <[email protected]>
AuthorDate: Thu Aug 13 15:58:24 2026 -0400
Add fluent Config.entry(key) builder as an additive alternative to the
6-arg set() (TODO-350 B-config-2)
Introduces org.apache.juneau.config.EntryBuilder, reached via
Config.entry(String key), replacing the 6-arg
Config.set(key,value,serializer,modifiers,comment,preLines)'s three sentinel
conventions (null=leave untouched, blank=clear comment, empty list=clear
pre-lines) with explicit .comment/.preLines/.serializer/.modifiers setters plus
.clearComment()/.clearPreLines() and terminal .set(value). "Leave untouched" is
simply not calling a facet method; clearing is explicit. Delegates to t [...]
---
pages/topics/06.06.00.SettingValues.md | 32 ++++++++++++++++++++++++++++++++
1 file changed, 32 insertions(+)
diff --git a/pages/topics/06.06.00.SettingValues.md
b/pages/topics/06.06.00.SettingValues.md
index f9228c2e5a..5eebde2b3f 100644
--- a/pages/topics/06.06.00.SettingValues.md
+++ b/pages/topics/06.06.00.SettingValues.md
@@ -56,6 +56,38 @@ To unset the same-line comment, you should pass in a blank
string.
To remove pre-lines, you should pass in an empty list.
+### Fluent entry builder
+
+Because the 6-argument `set(...)` overload packs several different
"leave-unchanged versus clear" sentinel conventions into one call (a `null`
comment leaves the existing comment untouched while a blank comment clears it;
a `null` pre-lines list leaves the existing pre-lines untouched while an empty
list clears them), the recommended ergonomic alternative is the fluent entry
builder returned by <a
href="/site/apidocs/org/apache/juneau/config/Config.html#entry(java.lang.String)"
target="_ [...]
+
+Each facet is expressed explicitly, so no sentinels are needed:
+
+- **Not calling** a facet method leaves that facet untouched.
+- An explicit setter (`comment(String)`, `preLines(List)`,
`serializer(Serializer)`, `modifiers(String)`) sets that facet.
+- An explicit clear (`clearComment()`, `clearPreLines()`) intentionally clears
that facet.
+- A terminal `set(Object)` (or `value(Object).set()`) performs the write.
+
+```java
+// Equivalent to the 6-arg set(...) call above.
+config.entry("key1")
+ .modifiers("*")
+ .comment("Same-line comment")
+ .preLines(List.of("# Comment 1", "", "# Comment 2"))
+ .set(1);
+
+// Update only the comment on an existing entry, leaving the value and
pre-lines untouched.
+config.entry("key1")
+ .comment("Updated comment")
+ .set();
+
+// Explicitly clear the comment (rather than passing a magic blank string).
+config.entry("key1")
+ .clearComment()
+ .set();
+```
+
+The fluent path produces a result identical to the equivalent <a
href="/site/apidocs/org/apache/juneau/config/Config.html#set(java.lang.String,java.lang.Object)"
target="_blank">Config.set(String,Object,Serializer,String,String,List)</a>
call, and the legacy `set(...)` overloads remain available.
+
Sections can be added with optional pre-lines using the `setSection` methods:
```java
