You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ws.apache.org by ve...@apache.org on 2026/02/21 22:56:33 UTC
(ws-axiom) branch master updated: Refactor fluent builder design doc into ADR-0002
This is an automated email from the ASF dual-hosted git repository.
veithen pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ws-axiom.git
The following commit(s) were added to refs/heads/master by this push:
new 949be5c2d Refactor fluent builder design doc into ADR-0002
949be5c2d is described below
commit 949be5c2d6c6e3136c5bde2907f2f43b7e9ef435
Author: Andreas Veithen-Knowles <an...@gmail.com>
AuthorDate: Sat Feb 21 22:56:24 2026 +0000
Refactor fluent builder design doc into ADR-0002
---
.../0002-fluent-builder-conventions.md} | 24 ++++++++++++++--------
docs/design/README.md | 1 -
2 files changed, 16 insertions(+), 9 deletions(-)
diff --git a/docs/design/fluent-builder.md b/docs/adr/0002-fluent-builder-conventions.md
similarity index 75%
rename from docs/design/fluent-builder.md
rename to docs/adr/0002-fluent-builder-conventions.md
index 8e911981e..2ff6a0105 100644
--- a/docs/design/fluent-builder.md
+++ b/docs/adr/0002-fluent-builder-conventions.md
@@ -20,16 +20,12 @@
Fluent builder conventions
==========================
-Builders are mutable objects which create other (often immutable) objects.
-They are used as an alternative to public constructors in order to avoid
-constructors with long argument lists and classes with many different constructors.
-Builders generally use the fluent pattern so that method calls to the setters
-of the builder can be chained.
+## Decision
Axiom uses the following coding conventions for builders:
* A builder type is implemented as a public static final inner class of the class
- to be built. The name of the class is `Builder` and it's constructor must not be public.
+ to be built. The name of the class is `Builder` and its constructor must not be public.
* A builder instance is created using a static method named `builder` defined on the
type being built.
@@ -46,7 +42,19 @@ Axiom uses the following coding conventions for builders:
be used to create a new instance similar to an existing one, and the expectation is that
`someInstance.toBuilder().build()` would produce an instance that is equal (in the
relevant sense) to `someInstance`.
-
- If the build type has a `toBuilder` method, then the builder type may need additional
+
+ If the built type has a `toBuilder` method, then the builder type may need additional
methods allowing the caller to unset properties. In certain cases it may also be pertinent
to add getter methods to support complex state transitions.
+
+## Rationale
+
+* Builders are mutable objects which create other (often immutable) objects. They are used
+ as an alternative to public constructors in order to avoid constructors with long argument
+ lists and classes with many different constructors.
+
+* Builders generally use the fluent pattern so that method calls to the setters of the
+ builder can be chained, improving readability.
+
+* Having consistent conventions across the codebase makes the API predictable and easier
+ to use.
diff --git a/docs/design/README.md b/docs/design/README.md
index ef4681fe2..4308e0f3c 100644
--- a/docs/design/README.md
+++ b/docs/design/README.md
@@ -23,4 +23,3 @@ Design documents
| Title/link | Status |
| ---------- | ------ |
| [OSGi integration and separation between API and implementation](osgi-integration.md) | Implemented |
-| [Fluent builders](fluent-builder.md) | Implemented |