Date: Mon, 13 Aug 2012 00:11:02 +0200 Subject: Documentation for @Value, @FieldDefaults, @Wither --- website/features/experimental/ExtensionMethod.html | 2 +- website/features/experimental/FieldDefaults.html | 84 +++++++++++++++++ website/features/experimental/Value.html | 87 ++++++++++++++++++ website/features/experimental/Wither.html | 100 +++++++++++++++++++++ website/features/experimental/index.html | 6 ++ 5 files changed, 278 insertions(+), 1 deletion(-) create mode 100644 website/features/experimental/FieldDefaults.html create mode 100644 website/features/experimental/Value.html create mode 100644 website/features/experimental/Wither.html (limited to 'website/features/experimental') diff --git a/website/features/experimental/ExtensionMethod.html b/website/features/experimental/ExtensionMethod.html index 773904bb..0025d795 100644 --- a/website/features/experimental/ExtensionMethod.html +++ b/website/features/experimental/ExtensionMethod.html @@ -90,7 +90,7 @@ System.out.println(x.or("Hello, World!"));

diff --git a/website/features/experimental/FieldDefaults.html b/website/features/experimental/FieldDefaults.html new file mode 100644 index 00000000..94c23a27 --- /dev/null +++ b/website/features/experimental/FieldDefaults.html @@ -0,0 +1,84 @@ + + + + + + + + EXPERIMENTAL - @FieldDefaults +

+ +

@FieldDefaults

New default field modifiers for the 21st century.

Since

+ @FieldDefaults was introduced as experimental feature in lombok v0.11.4. +

Experimental

+ Experimental because: +

New feature; unsure if this busts enough boilerplate
Would be nice if you could stick this on the package-info.java package to set the default for all classes in that package
Part of the work on @Value, which is experimental

+ Current status: positive - Currently we feel this feature may move out of experimental status with no or minor changes soon. +

Overview

+ The @FieldDefaults annotation can add an access modifier (public, private, or protected) + to each field in the annotated class or enum. It can also add final to each field in the annotated class or enum. +

+ To add final to each field, use @FieldDefaults(makeFinal=true). Any non-final field which must remain nonfinal + can be annotated with @NonFinal (also in the lombok.experimental package). +

+ To add an access modifier to each field, use @FieldDefaults(level=AccessLevel.PRIVATE). Any field that does not already have an + access modifier (i.e. any field that looks like package private access) is changed to have the appropriate access modifier. Any package private + field which must remain package private can be annotated with @PackagePrivate (also in the lombok.experimental package). +

With Lombok

@HTML_PRE@

Vanilla Java

@HTML_POST@

Small print

+ Like other lombok handlers that touch fields, any field whose name starts with a dollar ($) symbol is skipped entirely. + Such a field will not be modified at all. +

+ +

+ + + diff --git a/website/features/experimental/Value.html b/website/features/experimental/Value.html new file mode 100644 index 00000000..464f0966 --- /dev/null +++ b/website/features/experimental/Value.html @@ -0,0 +1,87 @@ + + + + + + + + EXPERIMENTAL - @ExtensionMethod +

+ +

@Value

Immutable classes made very easy.

Since

+ @Value was introduced as experimental feature in lombok v0.11.4. +

Experimental

+ Experimental because: +

Various choices still have to be vetted as being the correct 'least surprise' choice: Should the class be made final by default, etc.
Dependent on @Wither which is experimental.

+ Current status: positive - Currently we feel this feature may move out of experimental status with no or minor changes soon. +

Overview

+ @Value is the immutable variant of @Data; all fields are made private and final by default, and instead of setters, each field gets a so-called 'wither', + which is a method that produces a clone with each field having the same value, except for the field you want a new value for. The class itself is also made final by default, because immutability is not something that can + be forced onto a subclass. Like @Data, useful toString(), equals() and hashCode() methods are also generated, each field gets a getter method, and a constructor that covers every + argument (except final fields that are initialized in the field declaration) is also generated. +

+ In practice, @Value is shorthand for: final @ToString @EqualsAndHashCode @AllArgsConstructor @FieldDefaults(makeFinal = true, level = AccessLevel.PRIVATE) @Getter @Wither. +

+ 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 @NonFinal or @PackagePrivate annotations.
+ It is possible to override any default behaviour for any of the 'parts' that make up @Value by explicitly using that annotation. +

With Lombok

@HTML_PRE@

Vanilla Java

@HTML_POST@

Small print

+ Look for the documentation on the 'parts' of @Value: @ToString, @EqualsAndHashCode, + @AllArgsConstructor, @FieldDefaults, @Getter, + @Wither. +

+ 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 @AllArgsConstructor annotation, there's also the @Value(staticConstructor="of") feature, which will make the generated all-arguments constructor + private, and generates a public static method named of which is a wrapper around this private constructor. +

+ +

+ + + diff --git a/website/features/experimental/Wither.html b/website/features/experimental/Wither.html new file mode 100644 index 00000000..34d6d0d9 --- /dev/null +++ b/website/features/experimental/Wither.html @@ -0,0 +1,100 @@ + + + + + + + + EXPERIMENTAL - @ExtensionMethod +

+ +

@Wither

Immutable 'setters' - methods that create a clone but with one changed field.

Since

+ @Wither was introduced as experimental feature in lombok v0.11.4. +

Experimental

+ Experimental because: +

Still not sure that @Wither is an appropriate name for this feature.
Should there be an option to supply a way of cloning the input somehow?
Should the way that the clone is created by configurable?
Should we replace @Wither entirely with a builder class?

+ Current status: neutral - More feedback requires on the items in the above list before promotion to the main package is warranted. +

Overview

+ The next best alternative to a setter for an immutable property is to construct a clone of the object, but with a new value for this one field. + A method to generate this clone is precisely what @Wither generates: a withFieldName(newValue) method which produces a clone + except for the new value for the associated field. +

+ For example, if you create public class Point { private final int x, y; }, setters make no sense because the fields + are final. @Wither can generate a withX(int newXValue) method for you which will return a new point with the supplied + value for x and the same value for y. +

+ Like @Setter, you can specify an access level in case you want the generated wither to be something other than public:
+ @Wither(level = AccessLevel.PROTECTED). Also like @Setter, you can also put a @Wither annotation on a type, which means + a 'wither' is generated for each field (even non-final fields). +

With Lombok

@HTML_PRE@

Vanilla Java

@HTML_POST@

Small print

+ Withers cannot be generated for static fields because that makes no sense. +

+ When applying @Wither to a type, static fields and fields whose name start with a $ are skipped. +

+ For generating the method names, the first character of the field, if it is a lowercase character, is title-cased, otherwise, it is left unmodified. + Then, with is prefixed. +

+ No method is generated if any method already exists with the same name (case insensitive) and same parameter count. For example, withX(int x) + will not be generated if there's already a method withX(String... x) even though it is technically possible to make the method. This caveat + exists to prevent confusion. If the generation of a method is skipped for this reason, a warning is emitted instead. Varargs count as 0 to N parameters. +

+ For boolean fields that start with is immediately followed by a title-case letter, nothing is prefixed to generate the wither name. +

+ Any annotations named @NonNull (case insensitive) on the field are interpreted as: This field must not ever hold + null. Therefore, these annotations result in an explicit null check in the generated wither. Also, these + annotations (as well as any annotation named @Nullable or @CheckForNull) are copied to wither parameter. +

+ +

+ + + diff --git a/website/features/experimental/index.html b/website/features/experimental/index.html index 9b25d710..6f180065 100644 --- a/website/features/experimental/index.html +++ b/website/features/experimental/index.html @@ -26,6 +26,12 @@

A more fluent API for getters and setters.

@ExtensionMethod

Annoying API? Fix it yourself: Add new methods to existing types!

@FieldDefaults

New default field modifiers for the 21st century.

@Wither

Immutable 'setters' - methods that create a clone but with one changed field.

@Value

Immutable classes made very easy.