aboutsummaryrefslogtreecommitdiff
path: root/website/templates/features/experimental/FieldNameConstants.html
blob: 283ebe55cc81b75ea870a123353f2eefbd4af67d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
<#import "../_features.html" as f>

<@f.scaffold title="@FieldNameConstants" logline="Name... that... field! String constants for your field's names.">
	<@f.history>
		<p>
			@FieldNameConstants was introduced as experimental feature in lombok v1.16.22.
		</p><p>
			@FieldNameConstants was redesigned in lombok v1.18.4.
		</p>
	</@f.history>

	<@f.experimental>
		<ul>
			<li>
				New feature; unsure if this busts enough boilerplate.
			</li>
		</ul>
		Current status: <em>neutral</em> - As a just-introduced feature we're still gathering feedback.
	</@f.experimental>

	<@f.overview>
		<p>
			The <code>@FieldNameConstants</code> annotation generates an inner type which contains 1 constant for each field in your class; either string constants (fields marked <code>public static final</code>, of type <code>java.lang.String</code>) or if you prefer, an enum type with 1 value for each field. <code>@FieldNameConstants</code> is useful for various marshalling and serialization frameworks. The constant field (whether enum value or string constant) always has the exact same name as the field, capitalization and all.
		</p><p>
			The generated inner type is by default called <code>Fields</code> and is <code>public</code>. You can modify this via <code>@FieldNameConstants(innerTypeName = "FieldNames", access = AccessLevel.PACKAGE)</code> for example. The default inner type name can also be modified via configuration key <code>lombok.fieldNameConstants.innerTypeName</code>. The generated fields are always <code>public</code>.
		</p><p>
			Must be applied to classes (or enums, though you'd rarely want to do that). By default includes all non-transient, non-static fields. You can use <code>@FieldNameConstants.Include</code> in fields + <code>@FieldNameConstants(onlyExplicitlyIncluded = true)</code>, or <code>@FieldNameConstants.Exclude</code> for more fine-grained control.
		</p>
	</@f.overview>

	<@f.snippets name="experimental/FieldNameConstants" />

	<@f.confKeys>
		<dt>
			<code>lombok.fieldNameConstants.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set)
		</dt><dd>
			Lombok will flag any usage of <code>@FieldDefaults</code> as a warning or error if configured.
		</dd><dt>
			<code>lombok.fieldNameConstants.innerTypeName</code> = <em>a string</em> (default: 'Fields')
		</dt><dd>
			The name of the inner type generated by lombok can be controlled with this configuration key.
		</dd>
	</@f.confKeys>

	<@f.smallPrint>
		<p>
			Starting with lombok v1.18.5, lombok will silently skip generating anything that already exists. You can define the inner <code>Fields</code> enum/class yourself,
			in which case lombok will add all the enum constants / public static final fields you haven't written yourself.
		</p><p>
			From lombok v1.16.22 to lombok v1.18.2, this feature generated constants inside the type directly; the name of these fields would for example turn field <code>exampleFieldName</code> into <code>public static final String FIELD_EXAMPLE_FIELD_NAME = "exampleFieldName";</code>. The prefix and suffix (here, <code>FIELD_</code>, and the empty string) were configurable. Starting with lombok v1.18.4 this feature has been redesigned into generating an inner type as described above.
		</p><p>
			Any parameters of lombok annotations that take strings need to be supplied actual string literals; you cannot have references to constants like those generated by <code>@FieldNameConstants</code>. If you'd like to use <code>@FieldNameConstants</code> to for example fill in the <code>of</code> and/or <code>exclude</code> parameters of <code>@ToString</code> and similar lombok annotations, use the <code>@ToString.Include</code> / <code>@ToString.Exclude</code> etc system instead; these are described at the feature pages for those features.
		</p><p>
			Like other lombok handlers that touch fields, any field whose name starts with a dollar (<code>$</code>) symbol is skipped entirely. Such a field will not be modified at all. Static fields are also skipped.
		</p>
	</@f.smallPrint>
</@f.scaffold>