diff options
Diffstat (limited to 'website/templates/features/experimental')
| -rw-r--r-- | website/templates/features/experimental/Jacksonized.html | 53 | ||||
| -rw-r--r-- | website/templates/features/experimental/index.html | 4 |
2 files changed, 57 insertions, 0 deletions
diff --git a/website/templates/features/experimental/Jacksonized.html b/website/templates/features/experimental/Jacksonized.html new file mode 100644 index 00000000..fd2bfe68 --- /dev/null +++ b/website/templates/features/experimental/Jacksonized.html @@ -0,0 +1,53 @@ +<#import "../_features.html" as f> + +<@f.scaffold title="@Jacksonized" logline="Make Jackson use your builders."> + <@f.history> + <p> + <code>@Jacksonized</code> was introduced as experimental feature in lombok v1.18.14. + </p> + </@f.history> + + <@f.overview> + <p> + The <code>@Jacksonized</code> annotation is an add-on annotation for <a href="/features/Builder"><code>@Builder</code></a> and <a href="/features/experimental/SuperBuilder"><code>@SuperBuilder</code></a>. + It automatically configures the generated builder class to be used by <a href="https://github.com/FasterXML/jackson">Jackson</a>'s deserialization. + It only has an effect if present at a context where there is also a <code>@Builder</code> or a <code>@SuperBuilder</code>; a warning is emitted otherwise. + </p><p> + Without <code>@Jacksonized</code>, you would have to customize your builder class(es). + With <code>@Jacksonized</code>, you can simply write something like this to let Jackson use the generated builder:<div class="snippet"><div class="java" align="left"><pre> +@Jacksonized @Builder +@JsonIgnoreProperties(ignoreUnknown = true) +public class JacksonExample { + private List<Foo> foos; +} +</pre></div></div> + </p><p> + This annotation is especially useful when deserializing into immutable (sub-)classes that only use <code>@SuperBuilder</code> to create instances. + With <code>@Jacksonized</code>, you do not have to put the complex <code>@SuperBuilder</code> class header into your code just to configure it for Jackson. + </p><p> + This annotation does <i>not</i> change the behavior of the generated builder. + A <code>@Jacksonized</code> <code>@SuperBuilder</code> remains fully compatible to regular <code>@SuperBuilder</code>s. + </p> + </@f.overview> + + <@f.smallPrint> + <p> + In particular, the annotation does the following: + <ul> + <li> + Configure Jackson to use the builder for deserialization using <code>@JsonDeserialize(builder=<em>Foobar</em>.<em>Foobar</em>Builder[Impl].class))</code> on the class (where <em>Foobar</em> is the name of the annotated class). + (An error is emitted if such an annotation already exists.) + </li><li> + Copy Jackson-related configuration annotations (like <code>@JsonIgnoreProperties</code>) from the class to the builder class. + This is necessary so that Jackson recognizes them when using the builder. + </li><li> + Insert <code>@JsonPOJOBuilder(withPrefix="")</code> on the generated builder class to override Jackson's default prefix "with". + If you configured a different prefix in lombok using <code>setterPrefix</code>, this value is used. + If you changed the name of the <code>build()</code> method using using <code>buildMethodName</code>, this is also made known to Jackson. + </li><li> + For <code>@SuperBuilder</code>, make the builder implementation class package-private. + </li> + </ul> + </p> + </@f.smallPrint> +</@f.scaffold> diff --git a/website/templates/features/experimental/index.html b/website/templates/features/experimental/index.html index b158d381..dc7870cf 100644 --- a/website/templates/features/experimental/index.html +++ b/website/templates/features/experimental/index.html @@ -71,6 +71,10 @@ <@main.feature title="@Tolerate" href="Tolerate"> Skip, jump, and forget! Make lombok disregard an existing method or constructor. </@main.feature> + + <@main.feature title="@Jacksonized" href="Jacksonized"> + Make Jackson use your builders. + </@main.feature> </div> <@f.confKeys> |