lombok/website/templates/features/experimental/Jacksonized.html

<#import "../_features.html" as f>

<@f.scaffold title="@Jacksonized" logline="Bob, meet Jackson. Lets make sure you become fast friends.">
	<@f.history>
		<p>
			<code>@Jacksonized</code> was introduced as experimental feature for <code>@Builder</code> and <code>@SuperBuilder</code> in lombok v1.18.14.
		</p><p>
			Support for <code>@Accessors</code> was added in lombok v1.18.40.
		</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>, <a href="/features/experimental/SuperBuilder"><code>@SuperBuilder</code></a>, and <a href="/features/experimental/Accessors"><code>@Accessors</code></a>.
		</p><p>
			For <code>@Accessors(fluent = true)</code> on a type, it automatically configures Jackson to use the generated setters and getters for (de-)serialization by inserting <code>@JsonProperty</code> annotations.
			(Note that <code>@Jacksonized @Accessors</code> on fields are not supported.)<div class="snippet"><div class="java" align="left"><pre>
@Jacksonized @Accessors(fluent = true)
@Getter @Setter
public class AccessorsExample {
	private int age = 10;
}
		</pre></div></div>
		</p><p>
			For <code>@Builder</code> and <code>@SuperBuilder</code>, 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&lt;Foo&gt; foos;
}
</pre></div></div>
 		</p><p>
			This annotation does <em>not</em> 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.confKeys>
		<dt>
			<code>lombok.jacksonized.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set)
		</dt><dd>
			Lombok will flag any usage of <code>@Jacksonized</code> as a warning or error if configured.
		</dd><dt>
			<code>lombok.jacksonized.jacksonVersion</code> += <code>version</code> (default: 2 + generate warning)
		</dt><dd>
			(Since 1.18.44) Jackson now has 2 different major versions: Jackson2, and Jackson3. Specify which version of the jackson annotations to generate.<br />
			If no version is chosen, lombok will generate Jackson v2 annotations and emit a warning that you should add this config key to pick which jackson version you want.<br />
			If transitioning from Jackson2 to Jackson3, you can ask lombok to emit both variants. See: <a href="/features/configuration">Lombok configuration system</a>.
		</dd>
	</@f.confKeys>
	
	<@f.smallPrint>
 		<p>
			In particular, the annotation does the following for <code>@(Super)Builder</code>:
			<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, and <code>Impl</code> is added for <code>@SuperBuilder</code>).
					(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 <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>