From 6f39b962f02348b4ffd3f45589bab5f2c7b87e2b Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Mon, 8 May 2017 21:02:49 +0200 Subject: [trivial] fixing file casing. --- website2/templates/features/Builder.html | 152 +++++++++++++++++++++++ website2/templates/features/BuilderSingular.html | 5 + website2/templates/features/Cleanup.html | 35 ++++++ website2/templates/features/Data.html | 41 ++++++ website2/templates/features/Value.html | 50 ++++++++ website2/templates/features/builder.html | 152 ----------------------- website2/templates/features/builderSingular.html | 5 - website2/templates/features/cleanup.html | 35 ------ website2/templates/features/data.html | 41 ------ website2/templates/features/value.html | 50 -------- 10 files changed, 283 insertions(+), 283 deletions(-) create mode 100644 website2/templates/features/Builder.html create mode 100644 website2/templates/features/BuilderSingular.html create mode 100644 website2/templates/features/Cleanup.html create mode 100644 website2/templates/features/Data.html create mode 100644 website2/templates/features/Value.html delete mode 100644 website2/templates/features/builder.html delete mode 100644 website2/templates/features/builderSingular.html delete mode 100644 website2/templates/features/cleanup.html delete mode 100644 website2/templates/features/data.html delete mode 100644 website2/templates/features/value.html (limited to 'website2/templates/features') diff --git a/website2/templates/features/Builder.html b/website2/templates/features/Builder.html new file mode 100644 index 00000000..238fada3 --- /dev/null +++ b/website2/templates/features/Builder.html @@ -0,0 +1,152 @@ +<#import "_features.html" as f> + +<@f.scaffold title="@Builder" logline="... and Bob's your uncle: No-hassle fancy-pants APIs for object creation!"> + <@f.history> +

+ @Builder was introduced as experimental feature in lombok v0.12.0. +

+ @Builder gained @Singular support and was promoted to the main lombok package since lombok v1.16.0. +

+ @Builder with @Singular adds a clear method since lombok v1.16.8. +

+ + + <@f.overview> +

+ The @Builder annotation produces complex builder APIs for your classes. +

+ @Builder lets you automatically produce the code required to have your class be instantiable with code such as:
+ Person.builder().name("Adam Savage").city("San Francisco").job("Mythbusters").job("Unchained Reaction").build(); +

+ @Builder can be placed on a class, or on a constructor, or on a method. While the "on a class" and "on a constructor" mode are the most common use-case, @Builder is most easily explained with the "method" use-case. +

+ A method annotated with @Builder (from now on called the target) causes the following 7 things to be generated: +

+ Each listed generated element will be silently skipped if that element already exists (disregarding parameter counts and looking only at names). This includes the builder itself: If that class already exists, lombok will simply start injecting fields and methods inside this already existing class, unless of course the fields / methods to be injected already exist. You may not put any other method (or constructor) generating lombok annotation on a builder class though; for example, you can not put @EqualsAndHashCode on the builder class. +

+ @Builder can generate so-called 'singular' methods for collection parameters/fields. These take 1 element instead of an entire list, and add the element to the list. For example: Person.builder().job("Mythbusters").job("Unchained Reaction").build(); would result in the List<String> jobs field to have 2 strings in it. To get this behaviour, the field/parameter needs to be annotated with @Singular. The feature has its own documentation. +

+ Now that the "method" mode is clear, putting a @Builder annotation on a constructor functions similarly; effectively, constructors are just static methods that have a special syntax to invoke them: Their 'return type' is the class they construct, and their type parameters are the same as the type parameters of the class itself. +

+ Finally, applying @Builder to a class is as if you added @AllArgsConstructor(access = AccessLevel.PACKAGE) to the class and applied the @Builder annotation to this all-args-constructor. This only works if you haven't written any explicit constructors yourself. If you do have an explicit constructor, put the @Builder annotation on the constructor instead of on the class. +

+ If using @Builder to generate builders to produce instances of your own class (this is always the case unless adding @Builder to a method that doesn't return your own type), you can use @Builder(toBuilder = true) to also generate an instance method in your class called toBuilder(); it creates a new builder that starts out with all the values of this instance. You can put the @Builder.ObtainVia annotation on the parameters (in case of a constructor or method) or fields (in case of @Builder on a type) to indicate alternative means by which the value for that field/parameter is obtained from this instance. For example, you can specify a method to be invoked: @Builder.ObtainVia(method = "calculateFoo"). +

+ The name of the builder class is FoobarBuilder, where Foobar is the simplified, title-cased form of the return type of the target - that is, the name of your type for @Builder on constructors and types, and the name of the return type for @Builder on methods. For example, if @Builder is applied to a class named com.yoyodyne.FancyList<T>, then the builder name will be FancyListBuilder<T>. If @Builder is applied to a method that returns void, the builder will be named VoidBuilder. +

+ The configurable aspects of builder are: +

+ Example usage where all options are changed from their defaults:
+ @Builder(builderClassName = "HelloWorldBuilder", buildMethodName = "execute", builderMethodName = "helloWorld", toBuilder = true)
+

+ + + <@f.featureSection> +

@Singular

+ +

+ By annotating one of the parameters (if annotating a method or constructor with @Builder) or fields (if annotating a class with @Builder) with the @Singular annotation, lombok will treat that builder node as a collection, and it generates 2 'adder' methods instead of a 'setter' method. One which adds a single element to the collection, and one which adds all elements of another collection to the collection. No setter to just set the collection (replacing whatever was already added) will be generated. A 'clear' method is also generated. These 'singular' builders are very complicated in order to guarantee the following properties: +

+

+ @Singular can only be applied to collection types known to lombok. Currently, the supported types are: +

+

+ If your identifiers are written in common english, lombok assumes that the name of any collection with @Singular on it is an english plural and will attempt to automatically singularize that name. If this is possible, the add-one method will use this name. For example, if your collection is called statuses, then the add-one method will automatically be called status. You can also specify the singular form of your identifier explictly by passing the singular form as argument to the annotation like so: @Singular("axis") List<Line> axes;.
+ If lombok cannot singularize your identifier, or it is ambiguous, lombok will generate an error and force you to explicitly specify the singular name. +

+ The snippet below does not show what lombok generates for a @Singular field/parameter because it is rather complicated. You can view a snippet here. +

+ + + <@f.snippets name="Builder" /> + + <@f.confKeys> +
+ lombok.builder.flagUsage = [warning | error] (default: not set) +
+ Lombok will flag any usage of @Builder as a warning or error if configured. +
+ lombok.singular.useGuava = [true | false] (default: false) +
+ If true, lombok will use guava's ImmutableXxx builders and types to implement java.util collection interfaces, instead of creating implementations based on Collections.unmodifiableXxx. You must ensure that guava is actually available on the classpath and buildpath if you use this setting. Guava is used automatically if your field/parameter has one of the guava ImmutableXxx types. +
+ lombok.singular.auto = [true | false] (default: true) +
+ If true (which is the default), lombok automatically tries to singularize your identifier name by assuming that it is a common english plural. If false, you must always explicitly specify the singular name, and lombok will generate an error if you don't (useful if you write your code in a language other than english). +
+ + + <@f.smallPrint> +

+ @Singular support for java.util.NavigableMap/Set only works if you are compiling with JDK1.8 or higher. +

+ You cannot manually provide some or all parts of a @Singular node; the code lombok generates is too complex for this. If you want to manually control (part of) the builder code associated with some field or parameter, don't use @Singular and add everything you need manually. +

+ The sorted collections (java.util: SortedSet, NavigableSet, SortedMap, NavigableMap and guava: ImmutableSortedSet, ImmutableSortedMap) require that the type argument of the collection has natural order (implements java.util.Comparable). There is no way to pass an explicit Comparator to use in the builder. +

+ An ArrayList is used to store added elements as call methods of a @Singular marked field, if the target collection is from the java.util package, even if the collection is a set or map. Because lombok ensures that generated collections are compacted, a new backing instance of a set or map must be constructed anyway, and storing the data as an ArrayList during the build process is more efficient that storing it as a map or set. This behaviour is not externally visible, an implementation detail of the current implementation of the java.util recipes for @Singular @Builder. +

+ With toBuilder = true applied to methods, any type parameter of the annotated method itself must also show up in the return type. +

+ + diff --git a/website2/templates/features/BuilderSingular.html b/website2/templates/features/BuilderSingular.html new file mode 100644 index 00000000..10253365 --- /dev/null +++ b/website2/templates/features/BuilderSingular.html @@ -0,0 +1,5 @@ +<#import "_features.html" as f> + +<@f.scaffold title="@Builder @Singular" logline="... and Bob's your uncle: No-hassle fancy-pants APIs for object creation!"> + <@f.snippets name="Singular-snippet" /> + diff --git a/website2/templates/features/Cleanup.html b/website2/templates/features/Cleanup.html new file mode 100644 index 00000000..e868c40d --- /dev/null +++ b/website2/templates/features/Cleanup.html @@ -0,0 +1,35 @@ +<#import "_features.html" as f> + +<@f.scaffold title="@Cleanup" logline="Automatic resource management: Call your close() methods safely with no hassle."> + <@f.overview> +

+ You can use @Cleanup to ensure a given resource is automatically cleaned up before the code execution path exits your current scope. You do this by annotating any local variable declaration with the @Cleanup annotation like so:
+ @Cleanup InputStream in = new FileInputStream("some/file");
+ As a result, at the end of the scope you're in, in.close() is called. This call is guaranteed to run by way of a try/finally construct. Look at the example below to see how this works. +

+ If the type of object you'd like to cleanup does not have a close() method, but some other no-argument method, you can specify the name of this method like so:
+ @Cleanup("dispose") org.eclipse.swt.widgets.CoolBar bar = new CoolBar(parent, 0);
+ By default, the cleanup method is presumed to be close(). A cleanup method that takes 1 or more arguments cannot be called via @Cleanup. +

+ + + <@f.snippets name="Cleanup" /> + + <@f.confKeys> +
+ lombok.cleanup.flagUsage = [warning | error] (default: not set) +
+ Lombok will flag any usage of @Cleanup as a warning or error if configured. + + + + <@f.smallPrint> +

+ In the finally block, the cleanup method is only called if the given resource is not null. However, if you use delombok on the code, a call to lombok.Lombok.preventNullAnalysis(Object o) is inserted to prevent warnings if static code analysis could determine that a null-check would not be needed. Compilation with lombok.jar on the classpath removes that method call, so there is no runtime dependency. +

+ If your code throws an exception, and the cleanup method call that is then triggered also throws an exception, then the original exception is hidden by the exception thrown by the cleanup call. You should not rely on this 'feature'. Preferably, lombok would like to generate code so that, if the main body has thrown an exception, any exception thrown by the close call is silently swallowed (but if the main body exited in any other way, exceptions by the close call will not be swallowed). The authors of lombok do not currently know of a feasible way to implement this scheme, but if java updates allow it, or we find a way, we'll fix it. +

+ You do still need to handle any exception that the cleanup method can generate! +

+ + diff --git a/website2/templates/features/Data.html b/website2/templates/features/Data.html new file mode 100644 index 00000000..59370cc8 --- /dev/null +++ b/website2/templates/features/Data.html @@ -0,0 +1,41 @@ +<#import "_features.html" as f> + +<@f.scaffold title="@Data" + logline="All together now: A shortcut for @ToString, @EqualsAndHashCode, @Getter on all fields, @Setter on all non-final fields, and @RequiredArgsConstructor!"> + + <@f.overview> +

+ @Data is a convenient shortcut annotation that bundles the features of @ToString, @EqualsAndHashCode, @Getter / @Setter and @RequiredArgsConstructor together: In other words, @Data generates all the boilerplate that is normally associated with simple POJOs (Plain Old Java Objects) and beans: getters for all fields, setters for all non-final fields, and appropriate toString, equals and hashCode implementations that involve the fields of the class, and a constructor that initializes all final fields, as well as all non-final fields with no initializer that have been marked with @NonNull, in order to ensure the field is never null. +

+ @Data is like having implicit @Getter, @Setter, @ToString, @EqualsAndHashCode and @RequiredArgsConstructor annotations on the class (except that no constructor will be generated if any explicitly written constructors already exist). However, the parameters of these annotations (such as callSuper, includeFieldNames and exclude) cannot be set with @Data. If you need to set non-default values for any of these parameters, just add those annotations explicitly; @Data is smart enough to defer to those annotations. +

+ All generated getters and setters will be public. To override the access level, annotate the field or class with an explicit @Setter and/or @Getter annotation. You can also use this annotation (by combining it with AccessLevel.NONE) to suppress generating a getter and/or setter altogether. +

+ All fields marked as transient will not be considered for hashCode and equals. All static fields will be skipped entirely (not considered for any of the generated methods, and no setter/getter will be made for them). +

+ If the class already contains a method with the same name and parameter count as any method that would normally be generated, that method is not generated, and no warning or error is emitted. For example, if you already have a method with signature equals(AnyType param), no equals method will be generated, even though technically it might be an entirely different method due to having different parameter types. The same rule applies to the constructor (any explicit constructor will prevent @Data from generating one), as well as toString, equals, and all getters and setters. You can mark any constructor or method with @lombok.experimental.Tolerate to hide them from lombok. +

+ @Data can handle generics parameters for fields just fine. In order to reduce the boilerplate when constructing objects for classes with generics, you can use the staticConstructor parameter to generate a private constructor, as well as a static method that returns a new instance. This way, javac will infer the variable name. Thus, by declaring like so: @Data(staticConstructor="of") class Foo<T> { private T x;} you can create new instances of Foo by writing: Foo.of(5); instead of having to write: new Foo<Integer>(5);. +

+ + + <@f.snippets name="Data" /> + + <@f.confKeys> +
+ lombok.data.flagUsage = [warning | error] (default: not set) +
+ Lombok will flag any usage of @Data as a warning or error if configured. +
+ + + <@f.smallPrint> +

+ See the small print of @ToString, @EqualsAndHashCode, @Getter / @Setter and @RequiredArgsConstructor. +

+ Any annotations named @NonNull (case insensitive) on a field are interpreted as: This field must not ever hold null. Therefore, these annotations result in an explicit null check in the generated constructor for the provided field. Also, these annotations (as well as any annotation named @Nullable) are copied to the constructor parameter, in both the true constructor and any static constructor. The same principle applies to generated getters and setters (see the documentation for @Getter / @Setter) +

+ By default, any variables that start with a $ symbol are excluded automatically. You can include them by specifying an explicit annotation (@Getter or @ToString, for example) and using the 'of' parameter. +

+ + diff --git a/website2/templates/features/Value.html b/website2/templates/features/Value.html new file mode 100644 index 00000000..fdad0e12 --- /dev/null +++ b/website2/templates/features/Value.html @@ -0,0 +1,50 @@ +<#import "_features.html" as f> + +<@f.scaffold title="@Value" logline="Immutable classes made very easy."> + <@f.history> +

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

+ @Value no longer implies @Wither since lombok v0.11.8. +

+ @Value promoted to the main lombok package since lombok v0.12.0. +

+ + + <@f.overview> +

+ @Value is the immutable variant of @Data; all fields are made private and final by default, and setters are not generated. 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, 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 toString, no error occurs, and lombok will not generate a toString. Also, any 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 @AllArgsConstructor to the class. You can mark any constructor or method with @lombok.experimental.Tolerate to hide them from lombok. +

+ It is possible to override the final-by-default and private-by-default behavior using either an explicit access level on a field, or by using the @NonFinal or @PackagePrivate annotations.
+ It is possible to override any default behavior for any of the 'parts' that make up @Value by explicitly using that annotation. +

+ + + <@f.snippets name="Value" /> + + <@f.confKeys> +
+ lombok.value.flagUsage = [warning | error] (default: not set) +
+ Lombok will flag any usage of @Value as a warning or error if configured. +
+ lombok.val.flagUsage = [warning | error] (default: not set) +
+ Lombok will flag any usage of val as a warning or error if configured. +
+ + + <@f.smallPrint> +

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

+ 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(staticConstructor="of") 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. +

+ @Value was an experimental feature from v0.11.4 to v0.11.9 (as @lombok.experimental.Value). 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. +

+ It is not possible to use @FieldDefaults to 'undo' the private-by-default and final-by-default aspect of fields in the annotated class. Use @NonFinal and @PackagePrivate on the fields in the class to override this behaviour. +

+ + diff --git a/website2/templates/features/builder.html b/website2/templates/features/builder.html deleted file mode 100644 index 238fada3..00000000 --- a/website2/templates/features/builder.html +++ /dev/null @@ -1,152 +0,0 @@ -<#import "_features.html" as f> - -<@f.scaffold title="@Builder" logline="... and Bob's your uncle: No-hassle fancy-pants APIs for object creation!"> - <@f.history> -

- @Builder was introduced as experimental feature in lombok v0.12.0. -

- @Builder gained @Singular support and was promoted to the main lombok package since lombok v1.16.0. -

- @Builder with @Singular adds a clear method since lombok v1.16.8. -

- - - <@f.overview> -

- The @Builder annotation produces complex builder APIs for your classes. -

- @Builder lets you automatically produce the code required to have your class be instantiable with code such as:
- Person.builder().name("Adam Savage").city("San Francisco").job("Mythbusters").job("Unchained Reaction").build(); -

- @Builder can be placed on a class, or on a constructor, or on a method. While the "on a class" and "on a constructor" mode are the most common use-case, @Builder is most easily explained with the "method" use-case. -

- A method annotated with @Builder (from now on called the target) causes the following 7 things to be generated: -

- Each listed generated element will be silently skipped if that element already exists (disregarding parameter counts and looking only at names). This includes the builder itself: If that class already exists, lombok will simply start injecting fields and methods inside this already existing class, unless of course the fields / methods to be injected already exist. You may not put any other method (or constructor) generating lombok annotation on a builder class though; for example, you can not put @EqualsAndHashCode on the builder class. -

- @Builder can generate so-called 'singular' methods for collection parameters/fields. These take 1 element instead of an entire list, and add the element to the list. For example: Person.builder().job("Mythbusters").job("Unchained Reaction").build(); would result in the List<String> jobs field to have 2 strings in it. To get this behaviour, the field/parameter needs to be annotated with @Singular. The feature has its own documentation. -

- Now that the "method" mode is clear, putting a @Builder annotation on a constructor functions similarly; effectively, constructors are just static methods that have a special syntax to invoke them: Their 'return type' is the class they construct, and their type parameters are the same as the type parameters of the class itself. -

- Finally, applying @Builder to a class is as if you added @AllArgsConstructor(access = AccessLevel.PACKAGE) to the class and applied the @Builder annotation to this all-args-constructor. This only works if you haven't written any explicit constructors yourself. If you do have an explicit constructor, put the @Builder annotation on the constructor instead of on the class. -

- If using @Builder to generate builders to produce instances of your own class (this is always the case unless adding @Builder to a method that doesn't return your own type), you can use @Builder(toBuilder = true) to also generate an instance method in your class called toBuilder(); it creates a new builder that starts out with all the values of this instance. You can put the @Builder.ObtainVia annotation on the parameters (in case of a constructor or method) or fields (in case of @Builder on a type) to indicate alternative means by which the value for that field/parameter is obtained from this instance. For example, you can specify a method to be invoked: @Builder.ObtainVia(method = "calculateFoo"). -

- The name of the builder class is FoobarBuilder, where Foobar is the simplified, title-cased form of the return type of the target - that is, the name of your type for @Builder on constructors and types, and the name of the return type for @Builder on methods. For example, if @Builder is applied to a class named com.yoyodyne.FancyList<T>, then the builder name will be FancyListBuilder<T>. If @Builder is applied to a method that returns void, the builder will be named VoidBuilder. -

- The configurable aspects of builder are: -

- Example usage where all options are changed from their defaults:
- @Builder(builderClassName = "HelloWorldBuilder", buildMethodName = "execute", builderMethodName = "helloWorld", toBuilder = true)
-

- - - <@f.featureSection> -

@Singular

- -

- By annotating one of the parameters (if annotating a method or constructor with @Builder) or fields (if annotating a class with @Builder) with the @Singular annotation, lombok will treat that builder node as a collection, and it generates 2 'adder' methods instead of a 'setter' method. One which adds a single element to the collection, and one which adds all elements of another collection to the collection. No setter to just set the collection (replacing whatever was already added) will be generated. A 'clear' method is also generated. These 'singular' builders are very complicated in order to guarantee the following properties: -

-

- @Singular can only be applied to collection types known to lombok. Currently, the supported types are: -

-

- If your identifiers are written in common english, lombok assumes that the name of any collection with @Singular on it is an english plural and will attempt to automatically singularize that name. If this is possible, the add-one method will use this name. For example, if your collection is called statuses, then the add-one method will automatically be called status. You can also specify the singular form of your identifier explictly by passing the singular form as argument to the annotation like so: @Singular("axis") List<Line> axes;.
- If lombok cannot singularize your identifier, or it is ambiguous, lombok will generate an error and force you to explicitly specify the singular name. -

- The snippet below does not show what lombok generates for a @Singular field/parameter because it is rather complicated. You can view a snippet here. -

- - - <@f.snippets name="Builder" /> - - <@f.confKeys> -
- lombok.builder.flagUsage = [warning | error] (default: not set) -
- Lombok will flag any usage of @Builder as a warning or error if configured. -
- lombok.singular.useGuava = [true | false] (default: false) -
- If true, lombok will use guava's ImmutableXxx builders and types to implement java.util collection interfaces, instead of creating implementations based on Collections.unmodifiableXxx. You must ensure that guava is actually available on the classpath and buildpath if you use this setting. Guava is used automatically if your field/parameter has one of the guava ImmutableXxx types. -
- lombok.singular.auto = [true | false] (default: true) -
- If true (which is the default), lombok automatically tries to singularize your identifier name by assuming that it is a common english plural. If false, you must always explicitly specify the singular name, and lombok will generate an error if you don't (useful if you write your code in a language other than english). -
- - - <@f.smallPrint> -

- @Singular support for java.util.NavigableMap/Set only works if you are compiling with JDK1.8 or higher. -

- You cannot manually provide some or all parts of a @Singular node; the code lombok generates is too complex for this. If you want to manually control (part of) the builder code associated with some field or parameter, don't use @Singular and add everything you need manually. -

- The sorted collections (java.util: SortedSet, NavigableSet, SortedMap, NavigableMap and guava: ImmutableSortedSet, ImmutableSortedMap) require that the type argument of the collection has natural order (implements java.util.Comparable). There is no way to pass an explicit Comparator to use in the builder. -

- An ArrayList is used to store added elements as call methods of a @Singular marked field, if the target collection is from the java.util package, even if the collection is a set or map. Because lombok ensures that generated collections are compacted, a new backing instance of a set or map must be constructed anyway, and storing the data as an ArrayList during the build process is more efficient that storing it as a map or set. This behaviour is not externally visible, an implementation detail of the current implementation of the java.util recipes for @Singular @Builder. -

- With toBuilder = true applied to methods, any type parameter of the annotated method itself must also show up in the return type. -

- - diff --git a/website2/templates/features/builderSingular.html b/website2/templates/features/builderSingular.html deleted file mode 100644 index 10253365..00000000 --- a/website2/templates/features/builderSingular.html +++ /dev/null @@ -1,5 +0,0 @@ -<#import "_features.html" as f> - -<@f.scaffold title="@Builder @Singular" logline="... and Bob's your uncle: No-hassle fancy-pants APIs for object creation!"> - <@f.snippets name="Singular-snippet" /> - diff --git a/website2/templates/features/cleanup.html b/website2/templates/features/cleanup.html deleted file mode 100644 index e868c40d..00000000 --- a/website2/templates/features/cleanup.html +++ /dev/null @@ -1,35 +0,0 @@ -<#import "_features.html" as f> - -<@f.scaffold title="@Cleanup" logline="Automatic resource management: Call your close() methods safely with no hassle."> - <@f.overview> -

- You can use @Cleanup to ensure a given resource is automatically cleaned up before the code execution path exits your current scope. You do this by annotating any local variable declaration with the @Cleanup annotation like so:
- @Cleanup InputStream in = new FileInputStream("some/file");
- As a result, at the end of the scope you're in, in.close() is called. This call is guaranteed to run by way of a try/finally construct. Look at the example below to see how this works. -

- If the type of object you'd like to cleanup does not have a close() method, but some other no-argument method, you can specify the name of this method like so:
- @Cleanup("dispose") org.eclipse.swt.widgets.CoolBar bar = new CoolBar(parent, 0);
- By default, the cleanup method is presumed to be close(). A cleanup method that takes 1 or more arguments cannot be called via @Cleanup. -

- - - <@f.snippets name="Cleanup" /> - - <@f.confKeys> -
- lombok.cleanup.flagUsage = [warning | error] (default: not set) -
- Lombok will flag any usage of @Cleanup as a warning or error if configured. - - - - <@f.smallPrint> -

- In the finally block, the cleanup method is only called if the given resource is not null. However, if you use delombok on the code, a call to lombok.Lombok.preventNullAnalysis(Object o) is inserted to prevent warnings if static code analysis could determine that a null-check would not be needed. Compilation with lombok.jar on the classpath removes that method call, so there is no runtime dependency. -

- If your code throws an exception, and the cleanup method call that is then triggered also throws an exception, then the original exception is hidden by the exception thrown by the cleanup call. You should not rely on this 'feature'. Preferably, lombok would like to generate code so that, if the main body has thrown an exception, any exception thrown by the close call is silently swallowed (but if the main body exited in any other way, exceptions by the close call will not be swallowed). The authors of lombok do not currently know of a feasible way to implement this scheme, but if java updates allow it, or we find a way, we'll fix it. -

- You do still need to handle any exception that the cleanup method can generate! -

- - diff --git a/website2/templates/features/data.html b/website2/templates/features/data.html deleted file mode 100644 index 59370cc8..00000000 --- a/website2/templates/features/data.html +++ /dev/null @@ -1,41 +0,0 @@ -<#import "_features.html" as f> - -<@f.scaffold title="@Data" - logline="All together now: A shortcut for @ToString, @EqualsAndHashCode, @Getter on all fields, @Setter on all non-final fields, and @RequiredArgsConstructor!"> - - <@f.overview> -

- @Data is a convenient shortcut annotation that bundles the features of @ToString, @EqualsAndHashCode, @Getter / @Setter and @RequiredArgsConstructor together: In other words, @Data generates all the boilerplate that is normally associated with simple POJOs (Plain Old Java Objects) and beans: getters for all fields, setters for all non-final fields, and appropriate toString, equals and hashCode implementations that involve the fields of the class, and a constructor that initializes all final fields, as well as all non-final fields with no initializer that have been marked with @NonNull, in order to ensure the field is never null. -

- @Data is like having implicit @Getter, @Setter, @ToString, @EqualsAndHashCode and @RequiredArgsConstructor annotations on the class (except that no constructor will be generated if any explicitly written constructors already exist). However, the parameters of these annotations (such as callSuper, includeFieldNames and exclude) cannot be set with @Data. If you need to set non-default values for any of these parameters, just add those annotations explicitly; @Data is smart enough to defer to those annotations. -

- All generated getters and setters will be public. To override the access level, annotate the field or class with an explicit @Setter and/or @Getter annotation. You can also use this annotation (by combining it with AccessLevel.NONE) to suppress generating a getter and/or setter altogether. -

- All fields marked as transient will not be considered for hashCode and equals. All static fields will be skipped entirely (not considered for any of the generated methods, and no setter/getter will be made for them). -

- If the class already contains a method with the same name and parameter count as any method that would normally be generated, that method is not generated, and no warning or error is emitted. For example, if you already have a method with signature equals(AnyType param), no equals method will be generated, even though technically it might be an entirely different method due to having different parameter types. The same rule applies to the constructor (any explicit constructor will prevent @Data from generating one), as well as toString, equals, and all getters and setters. You can mark any constructor or method with @lombok.experimental.Tolerate to hide them from lombok. -

- @Data can handle generics parameters for fields just fine. In order to reduce the boilerplate when constructing objects for classes with generics, you can use the staticConstructor parameter to generate a private constructor, as well as a static method that returns a new instance. This way, javac will infer the variable name. Thus, by declaring like so: @Data(staticConstructor="of") class Foo<T> { private T x;} you can create new instances of Foo by writing: Foo.of(5); instead of having to write: new Foo<Integer>(5);. -

- - - <@f.snippets name="Data" /> - - <@f.confKeys> -
- lombok.data.flagUsage = [warning | error] (default: not set) -
- Lombok will flag any usage of @Data as a warning or error if configured. -
- - - <@f.smallPrint> -

- See the small print of @ToString, @EqualsAndHashCode, @Getter / @Setter and @RequiredArgsConstructor. -

- Any annotations named @NonNull (case insensitive) on a field are interpreted as: This field must not ever hold null. Therefore, these annotations result in an explicit null check in the generated constructor for the provided field. Also, these annotations (as well as any annotation named @Nullable) are copied to the constructor parameter, in both the true constructor and any static constructor. The same principle applies to generated getters and setters (see the documentation for @Getter / @Setter) -

- By default, any variables that start with a $ symbol are excluded automatically. You can include them by specifying an explicit annotation (@Getter or @ToString, for example) and using the 'of' parameter. -

- - diff --git a/website2/templates/features/value.html b/website2/templates/features/value.html deleted file mode 100644 index fdad0e12..00000000 --- a/website2/templates/features/value.html +++ /dev/null @@ -1,50 +0,0 @@ -<#import "_features.html" as f> - -<@f.scaffold title="@Value" logline="Immutable classes made very easy."> - <@f.history> -

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

- @Value no longer implies @Wither since lombok v0.11.8. -

- @Value promoted to the main lombok package since lombok v0.12.0. -

- - - <@f.overview> -

- @Value is the immutable variant of @Data; all fields are made private and final by default, and setters are not generated. 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, 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 toString, no error occurs, and lombok will not generate a toString. Also, any 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 @AllArgsConstructor to the class. You can mark any constructor or method with @lombok.experimental.Tolerate to hide them from lombok. -

- It is possible to override the final-by-default and private-by-default behavior using either an explicit access level on a field, or by using the @NonFinal or @PackagePrivate annotations.
- It is possible to override any default behavior for any of the 'parts' that make up @Value by explicitly using that annotation. -

- - - <@f.snippets name="Value" /> - - <@f.confKeys> -
- lombok.value.flagUsage = [warning | error] (default: not set) -
- Lombok will flag any usage of @Value as a warning or error if configured. -
- lombok.val.flagUsage = [warning | error] (default: not set) -
- Lombok will flag any usage of val as a warning or error if configured. -
- - - <@f.smallPrint> -

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

- 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(staticConstructor="of") 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. -

- @Value was an experimental feature from v0.11.4 to v0.11.9 (as @lombok.experimental.Value). 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. -

- It is not possible to use @FieldDefaults to 'undo' the private-by-default and final-by-default aspect of fields in the annotated class. Use @NonFinal and @PackagePrivate on the fields in the class to override this behaviour. -

- - -- cgit