|
| 1 | +--- |
| 2 | +nav_order: 54 |
| 3 | +parent: Decision Records |
| 4 | +--- |
| 5 | +# Use Jilt staged builders for complex test configurations |
| 6 | + |
| 7 | +## Context and Problem Statement |
| 8 | + |
| 9 | +For tests around linked files we frequently need `BibTestConfiguration` instances with multiple required and optional parameters: |
| 10 | + |
| 11 | +```java |
| 12 | +@Builder(style = BuilderStyle.STAGED_PRESERVING_ORDER) |
| 13 | +BibTestConfiguration( |
| 14 | + String bibDir, |
| 15 | + @Opt String librarySpecificFileDir, |
| 16 | + @Opt String userSpecificFileDir, |
| 17 | + String pdfFileDir, |
| 18 | + FileTestConfiguration.TestFileLinkMode fileLinkMode, |
| 19 | + Path tempDir |
| 20 | +) throws IOException { |
| 21 | +} |
| 22 | +``` |
| 23 | + |
| 24 | +Usage in tests currently follows a staged builder style: |
| 25 | + |
| 26 | +```java |
| 27 | +BibTestConfigurationBuilder |
| 28 | + .bibTestConfiguration() |
| 29 | + .bibDir("source-dir") |
| 30 | + .pdfFileDir("source-dir") |
| 31 | + .fileLinkMode(TestFileLinkMode.RELATIVE_TO_BIB"); |
| 32 | +
|
| 33 | +// later in the code |
| 34 | +
|
| 35 | +BibTestConfiguration sourceBibTestConfiguration = |
| 36 | + sourceBibTestConfigurationBuilder.tempDir(tempDir).build(); |
| 37 | +``` |
| 38 | +
|
| 39 | +We want a clear, type-safe, and readable way to construct such configurations. |
| 40 | +Especially important is the ordering of the "setters" to increase code readability. |
| 41 | +
|
| 42 | +## Decision Drivers |
| 43 | +
|
| 44 | +* Make test setup code more readable and explicit. |
| 45 | +* Enforce required vs. optional parameters at compile time. |
| 46 | +* Keep the order of builder calls aligned with the parameter declaration order. |
| 47 | +* Avoid handwritten builder boilerplate and its maintenance. |
| 48 | +* Provide a reusable template for future configuration/value classes. |
| 49 | +
|
| 50 | +## Considered Options |
| 51 | +
|
| 52 | +* Jilt staged builder (`@Builder(style = BuilderStyle.STAGED_PRESERVING_ORDER)`). |
| 53 | +* Plain constructors (direct `new BibTestConfiguration(…)`), setters, and `initialize()` method. |
| 54 | +* Handwritten classic builder. |
| 55 | +* Lombok’s `@Builder`. |
| 56 | +
|
| 57 | +## Decision Outcome |
| 58 | +
|
| 59 | +Chosen option: "Jilt staged builder (`@Builder(style = BuilderStyle.STAGED_PRESERVING_ORDER)`)", because it gives us: |
| 60 | +
|
| 61 | +* type-safe staged construction, |
| 62 | +* stable call order matching parameter order, |
| 63 | +* clear distinction between required and optional parameters, |
| 64 | +* no handwritten builder code. |
| 65 | +
|
| 66 | +### Consequences |
| 67 | +
|
| 68 | +* Good, because **test code is more readable** – parameter names are visible at the call site instead of a long constructor argument list. |
| 69 | +* Good, because **required parameters are enforced by the compiler**; tests cannot accidentally omit them. |
| 70 | +* Good, because **builder invocation order matches declaration order**, which makes it easier to compare code and constructor signature. |
| 71 | +* Good, because **no runtime dependency** is introduced; Jilt is an annotation processor only. |
| 72 | +* Bad, because **another annotation processor** is in the toolchain, which slightly increases build complexity and can interact with other processors. |
| 73 | +* Bad, because **developers must learn the Jilt conventions**, especially staged builders and generated builder class naming. |
| 74 | +
|
| 75 | +### Confirmation |
| 76 | +
|
| 77 | +* `BibTestConfigurationBuilder` and similar builders are generated successfully during the build. |
| 78 | +* Tests compile only if all required fields are set via the staged builder. |
| 79 | +
|
| 80 | +## Pros and Cons of the Options |
| 81 | +
|
| 82 | +### Jilt staged builder (`@Builder(style = BuilderStyle.STAGED_PRESERVING_ORDER)`) |
| 83 | +
|
| 84 | +Homepage: <https://github.com/skinny85/jilt> |
| 85 | +
|
| 86 | +* Good, because it generates **staged** builders with clear required/optional semantics. |
| 87 | +* Good, because `BuilderStyle.STAGED_PRESERVING_ORDER` keeps **builder call order aligned with parameter order**. |
| 88 | +* Good, because no runtime dependency; Jilt is compile-time only. |
| 89 | +* Good, because it is compatible with new Java releases. |
| 90 | +* Good, because it integrates with existing Java code without changing runtime behavior. |
| 91 | +* Bad, because adding an annotation processor requires **IDE/build configuration** and developer knowledge. |
| 92 | +* Bad, because navigating to generated code can be less convenient, depending on IDE support. |
| 93 | +
|
| 94 | +### Plain constructors (direct `new BibTestConfiguration(…)`), setters, and `initialize()` method |
| 95 | +
|
| 96 | +* Good, because useful for very small classes. |
| 97 | +* Good, because no extra dependency. |
| 98 | +* Good, because IDEs understand plain constructors well. |
| 99 | +* Bad, because more complicated calling code - and unusual calling code. |
| 100 | +* Bad, because call sites with many parameters are hard to read and fragile. |
| 101 | +* Bad, because no compile-time enforcement of “required vs. optional” beyond primitive defaults and `null`. |
| 102 | +* Bad, because changing constructor parameter order can silently break call sites. |
| 103 | +
|
| 104 | +### Handwritten classic builder |
| 105 | +
|
| 106 | +* Good, because familiar builder pattern; no extra tools. |
| 107 | +* Good, because call sites are readable and explicit. |
| 108 | +* Bad, because builder code is boilerplate and must be maintained manually. |
| 109 | +* Bad, because easy to introduce inconsistencies between builder and target class. |
| 110 | +* Bad, because type-safety of required/optional parameters might be weaker than staged builders. |
| 111 | +
|
| 112 | +### Lombok’s `@Builder` |
| 113 | +
|
| 114 | +* Good, because concise annotation, common in many Java projects. |
| 115 | +* Good, because builder usage is clear at call sites. |
| 116 | +* Bad, because Lombok adds its own ecosystem and tooling constraints. |
| 117 | +* Bad, because Lombok is not always compatible with the most recent Java versions. |
| 118 | +* Bad, because staged/type-safe builders for required/optional distinction are less explicit than with Jilt. |
| 119 | +* Bad, because we avoid additional Lombok usage where possible. |
0 commit comments