aboutsummaryrefslogtreecommitdiff
path: root/website/features/Value.html
blob: 07e1e949bc32582cfcda9f7cac66f054cdac06e4 (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
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
<!DOCTYPE html>
<html><head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	<link rel="stylesheet" type="text/css" href="../logi/reset.css" />
	<link rel="stylesheet" type="text/css" href="features.css" />
	<link rel="shortcut icon" href="../favicon.ico" type="image/x-icon" />
	<meta name="description" content="Spice up your java" />
	<title>@ExtensionMethod</title>
</head><body><div id="pepper">
	<div class="minimumHeight"></div>
	<div class="meat">
		<div class="header"><a href="../index.html">Project Lombok</a></div>
		<h1>@Value</h1>
		<div class="byline">Immutable classes made very easy.</div>
		<div class="since">
			<h3>Since</h3>
			<p>
				<code>@Value</code> was introduced as experimental feature in lombok v0.11.4.
			</p><p>
				<code>@Value</code> no longer implies <code>@Wither</code> since lombok v0.11.8.
			</p><p>
				<code>@Value</code> promoted to the main <code>lombok</code> package since lombok v0.12.0.
		</div>
		<div class="overview">
			<h3>Overview</h3>
			<p>
				<code>@Value</code> is the immutable variant of <a href="Data.html"><code>@Data</code></a>; all fields are made <code>private</code> and <code>final</code> by default, and setters are not generated. The class itself is also made <code>final</code> by default, because immutability is not something that can be forced onto a subclass. Like <code>@Data</code>, useful <code>toString()</code>, <code>equals()</code> and <code>hashCode()</code> methods are also generated, each field gets a getter method, and a constructor that covers every
				argument (except <code>final</code> fields that are initialized in the field declaration) is also generated.
			</p><p>
				In practice, <code>@Value</code> is shorthand for: <code>final @ToString @EqualsAndHashCode @AllArgsConstructor @FieldDefaults(makeFinal = true, level = AccessLevel.PRIVATE) @Getter</code>, except that explicitly including an implementation of any of the relevant methods simply means that part won't be generated and no warning will be emitted. For example, if you write your own <code>toString</code>, no error occurs, and lombok will not generate a <code>toString</code>. Also, <em>any</em> explicit constructor, no matter the arguments list, implies lombok will not generate a constructor. If you do want lombok to generate the all-args constructor, add <code>@AllArgsConstructor</code> to the class.
			</p><p>
				It is possible to override the final-by-default and private-by-default behaviour using either an explicit access level on a field, or by using the <code>@NonFinal</code> or <code>@PackagePrivate</code> annotations.<br />
				It is possible to override any default behaviour for any of the 'parts' that make up <code>@Value</code> by explicitly using that annotation.
				</p>
		</div>
		<div class="snippets">
			<div class="pre">
				<h3>With Lombok</h3>
				<div class="snippet">@HTML_PRE@</div>
			</div>
			<div class="sep"></div>
			<div class="post">
				<h3>Vanilla Java</h3>
				<div class="snippet">@HTML_POST@</div>
			</div>
		</div>
		<div style="clear: left;"></div>
		<div class="overview">
			<h3>Small print</h3><div class="smallprint">
				<p>
					Look for the documentation on the 'parts' of <code>@Value</code>: <a href="ToString.html"><code>@ToString</code></a>, <a href="EqualsAndHashCode.html"><code>@EqualsAndHashCode</code></a>, <a href="Constructor.html"><code>@AllArgsConstructor</code></a>, <a href="experimental/FieldDefaults.html"><code>@FieldDefaults</code></a>, and <a href="GetterSetter.html"><code>@Getter</code></a>.
				</p><p>
					For classes with generics, it's useful to have a static method which serves as a constructor, because inference of generic parameters via static methods works in java6 and avoids having to use the diamond operator. While you can force this by applying an explicit <code>@AllArgsConstructor(staticConstructor="of")</code> annotation, there's also the <code>@Value(staticConstructor="of")</code> feature, which will make the generated all-arguments constructor private, and generates a public static method named <code>of</code> which is a wrapper around this private constructor.
				</p><p>
					<code>@Value</code> was an experimental feature from v0.11.4 to v0.11.9 (as <code>@lombok.experimental.Value</code>). It has since been moved into the core package. The old annotation is still
					around (and is an alias). It will eventually be removed in a future version, though.
				</p><p>
					It is not possible to use <code>@FieldDefaults</code> to 'undo' the private-by-default and final-by-default aspect of fields in the annotated class. Use <code>@NonFinal</code> and <code>@PackagePrivate</code> on the fields in the class to override this behaviour.
				</p>
			</div>
		</div>
		<div class="footer">
			<a href="index.html">Back to features</a> | <a href="Data.html">Previous feature (@Data)</a> | <a href="SneakyThrows.html">Next feature (@SneakyThrows)</a><br />
			<a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright &copy; 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span>
		</div>
		<div style="clear: both;"></div>
	</div>
</div>
<script type="text/javascript">
	var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
	document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
	try {
		var pageTracker = _gat._getTracker("UA-9884254-1");
		pageTracker._trackPageview();
	} catch(err) {}
</script>
</body></html>