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 <[email protected]>
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 |
