diff options
| -rw-r--r-- | website2/templates/features/EqualsAndHashCode.html | 8 | ||||
| -rw-r--r-- | website2/templates/features/NonNull.html | 2 | ||||
| -rw-r--r-- | website2/templates/features/_features.html | 3 | ||||
| -rw-r--r-- | website2/templates/features/builder.html | 30 | ||||
| -rw-r--r-- | website2/templates/features/builderSingular.html | 5 | ||||
| -rw-r--r-- | website2/templates/features/configuration.html | 13 | ||||
| -rw-r--r-- | website2/templates/features/constructor.html | 4 | ||||
| -rw-r--r-- | website2/templates/features/data.html | 2 | ||||
| -rw-r--r-- | website2/templates/features/experimental/FieldDefaults.html | 12 | ||||
| -rw-r--r-- | website2/templates/features/experimental/UtilityClass.html | 4 | ||||
| -rw-r--r-- | website2/templates/features/experimental/index.html | 24 | ||||
| -rw-r--r-- | website2/templates/features/experimental/onX.html | 3 | ||||
| -rw-r--r-- | website2/templates/features/experimental/var.html | 37 | ||||
| -rw-r--r-- | website2/templates/features/index.html | 32 | ||||
| -rw-r--r-- | website2/templates/features/log.html | 10 | ||||
| -rw-r--r-- | website2/templates/features/val.html | 7 | ||||
| -rw-r--r-- | website2/templates/features/value.html | 4 |
17 files changed, 149 insertions, 51 deletions
diff --git a/website2/templates/features/EqualsAndHashCode.html b/website2/templates/features/EqualsAndHashCode.html index 91a9cb70..3c11367f 100644 --- a/website2/templates/features/EqualsAndHashCode.html +++ b/website2/templates/features/EqualsAndHashCode.html @@ -5,9 +5,9 @@ <p> Any class definition may be annotated with <code>@EqualsAndHashCode</code> to let lombok generate implementations of the <code>equals(Object other)</code> and <code>hashCode()</code> methods. By default, it'll use all non-static, non-transient fields, but you can exclude more fields by naming them in the optional <code>exclude</code> parameter to the annotation. Alternatively, you can specify exactly which fields you wish to be used by naming them in the <code>of</code> parameter. </p><p> - By setting <code>callSuper</code> to <em>true</em>, you can include the <code>equals</code> and <code>hashCode</code> methods of your superclass in the generated methods. For <code>hashCode</code>, the result of <code>super.hashCode()</code> is included in the hash algorithm, and for <code>equals</code>, the generated method will return false if the super implementation thinks it is not equal to the passed in object. Be aware that not all <code>equals</code> implementations handle this situation properly. However, lombok-generated <code>equals</code> implementations <strong>do</strong> handle this situation properly, so you can safely call your superclass equals if it, too, has a lombok-generated <code>equals</code> method.<br/> + If applying <code>@EqualsAndHashCode</code> to a class that extends another, this feature gets a bit trickier. Normally, auto-generating an <code>equals</code> and <code>hashCode</code> method for such classes is a bad idea, as the superclass also defines fields, which also need equals/hashCode code but this code will not be generated. By setting <code>callSuper</code> to <em>true</em>, you can include the <code>equals</code> and <code>hashCode</code> methods of your superclass in the generated methods. For <code>hashCode</code>, the result of <code>super.hashCode()</code> is included in the hash algorithm, and for<code>equals</code>, the generated method will return false if the super implementation thinks it is not equal to the passed in object. Be aware that not all <code>equals</code> implementations handle this situation properly. However, lombok-generated <code>equals</code> implementations <strong>do</strong> handle this situation properly, so you can safely call your superclass equals if it, too, has a lombok-generated <code>equals</code> method. If you have an explicit superclass you are forced to supply some value for <code>callSuper</code> to acknowledge that you've considered it; failure to do so results in a warning. </p><p> - Setting <code>callSuper</code> to <em>true</em> when you don't extend anything (you extend <code>java.lang.Object</code>) is a compile-time error, because it would turn the generated <code>equals()</code> and <code>hashCode()</code> implementations into having the same behaviour as simply inheriting these methods from <code>java.lang.Object</code>: only the same object will be equal to each other and will have the same hashCode. Not setting <code>callSuper</code> to <em>true</em> when you extend another class generates a warning, because unless the superclass has no (equality-important) fields, lombok cannot generate an implementation for you that takes into account the fields declared by your superclasses. You'll need to write your own implementations, or rely on the <code>callSuper</code> chaining facility. + Setting <code>callSuper</code> to <em>true</em> when you don't extend anything (you extend <code>java.lang.Object</code>) is a compile-time error, because it would turn the generated <code>equals()</code> and <code>hashCode()</code> implementations into having the same behaviour as simply inheriting these methods from <code>java.lang.Object</code>: only the same object will be equal to each other and will have the same hashCode. Not setting <code>callSuper</code> to <em>true</em> when you extend another class generates a warning, because unless the superclass has no (equality-important) fields, lombok cannot generate an implementation for you that takes into account the fields declared by your superclasses. You'll need to write your own implementations, or rely on the <code>callSuper</code> chaining facility. You can also use the <code>lombok.equalsAndHashCode.callSuper</code> config key. </p><p> <em>NEW in Lombok 0.10: </em>Unless your class is <code>final</code> and extends <code>java.lang.Object</code>, lombok generates a <code>canEqual</code> method which means JPA proxies can still be equal to their base class, but subclasses that add new state don't break the equals contract. The complicated reasons for why such a method is necessary are explained in this paper: <a href="https://www.artima.com/lejava/articles/equality.html">How to Write an Equality Method in Java</a>. If all classes in a hierarchy are a mix of scala case classes and classes with lombok-generated equals methods, all equality will 'just work'. If you need to write your own equals methods, you should always override <code>canEqual</code> if you change <code>equals</code> and <code>hashCode</code>. </p><p> @@ -23,6 +23,10 @@ </dt><dd> If set to <code>true</code>, lombok will access fields directly instead of using getters (if available) when generating <code>equals</code> and <code>hashCode</code> methods. The annotation parameter '<code>doNotUseGetters</code>', if explicitly specified, takes precedence over this setting. </dd><dt> + <code>lombok.equalsAndHashCode.callSuper</code> = [<code>call</code> | <code>skip</code> | <code>warn</code>] (default: warn) + </dt><dd> + If set to <code>call</code>, lombok will generate calls to the superclass implementation of <code>hashCode</code> and <code>equals</code> if your class extends something. If set to <code>skip</code> no such calls are generated. The default behaviour is like <code>skip</code>, with an additional warning. + </dd><dt> <code>lombok.equalsAndHashCode.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) </dt><dd> Lombok will flag any usage of <code>@EqualsAndHashCode</code> as a warning or error if configured. diff --git a/website2/templates/features/NonNull.html b/website2/templates/features/NonNull.html index 60879085..28d083d0 100644 --- a/website2/templates/features/NonNull.html +++ b/website2/templates/features/NonNull.html @@ -38,6 +38,8 @@ While <code>@Data</code> and other method-generating lombok annotations will trigger on any annotation named <code>@NonNull</code> regardless of casing or package name, this feature only triggers on lombok's own <code>@NonNull</code> annotation from the <code>lombok</code> package. </p><p> A <code>@NonNull</code> on a primitive parameter results in a warning. No null-check will be generated. + </p><p> + A <code>@NonNull</code> on a parameter of an abstract method used to generate a warning; starting with version 1.16.8, this is no longer the case, to acknowledge the notion that <code>@NonNull</code> also has a documentary role. For the same reason, you can annotate a method as <code>@NonNull</code>; this is allowed, generates no warning, and does not generate any code. </p> </@f.smallPrint> </@f.scaffold> diff --git a/website2/templates/features/_features.html b/website2/templates/features/_features.html index bcfdee63..d7c75761 100644 --- a/website2/templates/features/_features.html +++ b/website2/templates/features/_features.html @@ -64,8 +64,7 @@ </#macro> <#macro scaffold title logline load=[]> - <#assign load2=load + ["/js/history.js"]> - <@main.scaffold load2> + <@main.scaffold load> <div class="page-header top5" id="featureContent"> <div class="row text-center"> <div class="header-group"> diff --git a/website2/templates/features/builder.html b/website2/templates/features/builder.html index 6da47d15..238fada3 100644 --- a/website2/templates/features/builder.html +++ b/website2/templates/features/builder.html @@ -6,6 +6,8 @@ <code>@Builder</code> was introduced as experimental feature in lombok v0.12.0. </p><p> <code>@Builder</code> gained <code>@Singular</code> support and was promoted to the main <code>lombok</code> package since lombok v1.16.0. + </p><p> + <code>@Builder</code> with <code>@Singular</code> adds a clear method since lombok v1.16.8. </p> </@f.history> @@ -16,9 +18,9 @@ <code>@Builder</code> lets you automatically produce the code required to have your class be instantiable with code such as:<br /> <code>Person.builder().name("Adam Savage").city("San Francisco").job("Mythbusters").job("Unchained Reaction").build();</code> </p><p> - <code>@Builder</code> can be placed on a class, or on a constructor, or on a static method. While the "on a class" and "on a constructor" mode are the most common use-case, <code>@Builder</code> is most easily explained with the "static method" use-case. + <code>@Builder</code> 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, <code>@Builder</code> is most easily explained with the "method" use-case. </p><p> - A static method annotated with <code>@Builder</code> (from now on called the <em>target</em>) causes the following 7 things to be generated: + A method annotated with <code>@Builder</code> (from now on called the <em>target</em>) causes the following 7 things to be generated: <ul> <li> An inner static class named <code><em>Foo</em>Builder</code>, with the same type arguments as the static method (called the <em>builder</em>). @@ -29,7 +31,7 @@ </li><li> In the <em>builder</em>: A 'setter'-like method for each parameter of the <em>target</em>: It has the same type as that parameter and the same name. It returns the builder itself, so that the setter calls can be chained, as in the above example. </li><li> - In the <em>builder</em>: A <code>build()</code> method which calls the static method, passing in each field. It returns the same type that the <em>target</em> returns. + In the <em>builder</em>: A <code>build()</code> method which calls the method, passing in each field. It returns the same type that the <em>target</em> returns. </li><li> In the <em>builder</em>: A sensible <code>toString()</code> implementation. </li><li> @@ -40,11 +42,13 @@ </p><p> <code>@Builder</code> 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: <code>Person.builder().job("Mythbusters").job("Unchained Reaction").build();</code> would result in the <code>List<String> jobs</code> field to have 2 strings in it. To get this behaviour, the field/parameter needs to be annotated with <code>@Singular</code>. The feature has <a href="#singular">its own documentation</a>. </p><p> - Now that the "static method" mode is clear, putting a <code>@Builder</code> 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. + Now that the "method" mode is clear, putting a <code>@Builder</code> 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. </p><p> Finally, applying <code>@Builder</code> to a class is as if you added <code>@AllArgsConstructor(access = AccessLevel.PACKAGE)</code> to the class and applied the <code>@Builder</code> 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 <code>@Builder</code> annotation on the constructor instead of on the class. </p><p> - The name of the builder class is <code><em>Foobar</em>Builder</code>, where <em>Foobar</em> is the simplified, title-cased form of the return type of the <em>target</em> - that is, the name of your type for <code>@Builder</code> on constructors and types, and the name of the return type for <code>@Builder</code> on static methods. For example, if <code>@Builder</code> is applied to a class named <code>com.yoyodyne.FancyList<T></code>, then the builder name will be <code>FancyListBuilder<T></code>. If <code>@Builder</code> is applied to a static method that returns <code>void</code>, the builder will be named <code>VoidBuilder</code>. + If using <code>@Builder</code> to generate builders to produce instances of your own class (this is always the case unless adding <code>@Builder</code> to a method that doesn't return your own type), you can use <code>@Builder(toBuilder = true)</code> to also generate an instance method in your class called <code>toBuilder()</code>; it creates a new builder that starts out with all the values of this instance. You can put the <code>@Builder.ObtainVia</code> annotation on the parameters (in case of a constructor or method) or fields (in case of <code>@Builder</code> 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: <code>@Builder.ObtainVia(method = "calculateFoo")</code>. + </p><p> + The name of the builder class is <code><em>Foobar</em>Builder</code>, where <em>Foobar</em> is the simplified, title-cased form of the return type of the <em>target</em> - that is, the name of your type for <code>@Builder</code> on constructors and types, and the name of the return type for <code>@Builder</code> on methods. For example, if <code>@Builder</code> is applied to a class named <code>com.yoyodyne.FancyList<T></code>, then the builder name will be <code>FancyListBuilder<T></code>. If <code>@Builder</code> is applied to a method that returns <code>void</code>, the builder will be named <code>VoidBuilder</code>. </p><p> The configurable aspects of builder are: <ul> @@ -54,10 +58,12 @@ The <em>build()</em> method's name (default: <code>"build"</code>) </li><li> The <em>builder()</em> method's name (default: <code>"builder"</code>) + </li><li> + If you want <code>toBuilder()</code> (default: no) </li> </ul> Example usage where all options are changed from their defaults:<br /> - <code>@Builder(builderClassName = "HelloWorldBuilder", buildMethodName = "execute", builderMethodName = "helloWorld")</code><br /> + <code>@Builder(builderClassName = "HelloWorldBuilder", buildMethodName = "execute", builderMethodName = "helloWorld", toBuilder = true)</code><br /> </p> </@f.overview> @@ -65,12 +71,12 @@ <h3 id="singular"><a name="singular">@Singular</a></h3> <p> - By annotating one of the parameters (if annotating a static method or constructor with <code>@Builder</code>) or fields (if annotating a class with <code>@Builder</code>) with the <code>@Singular</code> 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. These 'singular' builders are very complicated in order to guarantee the following properties: + By annotating one of the parameters (if annotating a method or constructor with <code>@Builder</code>) or fields (if annotating a class with <code>@Builder</code>) with the <code>@Singular</code> 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: <ul> <li> When invoking <code>build()</code>, the produced collection will be immutable. </li><li> - Calling one of the 'adder' methods after invoking <code>build()</code> does not modify any already generated objects, and, if <code>build()</code> is later called again, another collection with all the elements added since the creation of the builder is generated. + Calling one of the 'adder' methods, or the 'clear' method, after invoking <code>build()</code> does not modify any already generated objects, and, if <code>build()</code> is later called again, another collection with all the elements added since the creation of the builder is generated. </li><li> The produced collection will be compacted to the smallest feasible format while remaining efficient. </li> @@ -79,7 +85,7 @@ <code>@Singular</code> can only be applied to collection types known to lombok. Currently, the supported types are: <ul> <li> - <a href="http://docs.oracle.com/javase/8/docs/api/java/util/package-summary.html"><code>java.util</code></a>: + <a href="https://docs.oracle.com/javase/8/docs/api/java/util/package-summary.html"><code>java.util</code></a>: <ul> <li> <code>Iterable</code>, <code>Collection</code>, and <code>List</code> (backed by a compacted unmodifiable <code>ArrayList</code> in the general case). @@ -98,6 +104,8 @@ <code>ImmutableSet</code> and <code>ImmutableSortedSet</code> (backed by the builder feature of those types). </li><li> <code>ImmutableMap</code>, <code>ImmutableBiMap</code>, and <code>ImmutableSortedMap</code> (backed by the builder feature of those types). + </li><li> + <code>ImmutableTable</code> (backed by the builder feature of <code>ImmutableTable</code>). </li> </ul> </li> @@ -106,7 +114,7 @@ If your identifiers are written in common english, lombok assumes that the name of any collection with <code>@Singular</code> 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 <code>statuses</code>, then the add-one method will automatically be called <code>status</code>. You can also specify the singular form of your identifier explictly by passing the singular form as argument to the annotation like so: <code>@Singular("axis") List<Line> axes;</code>.<br /> If lombok cannot singularize your identifier, or it is ambiguous, lombok will generate an error and force you to explicitly specify the singular name. </p><p> - The snippet below does not show what lombok generates for a <code>@Singular</code> field/parameter because it is rather complicated. You can view a snippet <a href="Singular-snippet.html">here</a>. + The snippet below does not show what lombok generates for a <code>@Singular</code> field/parameter because it is rather complicated. You can view a snippet <a href="builderSingular">here</a>. </p> </@f.featureSection> @@ -137,6 +145,8 @@ The sorted collections (java.util: <code>SortedSet</code>, <code>NavigableSet</code>, <code>SortedMap</code>, <code>NavigableMap</code> and guava: <code>ImmutableSortedSet</code>, <code>ImmutableSortedMap</code>) require that the type argument of the collection has natural order (implements <code>java.util.Comparable</code>). There is no way to pass an explicit <code>Comparator</code> to use in the builder. </p><p> An <code>ArrayList</code> is used to store added elements as call methods of a <code>@Singular</code> marked field, if the target collection is from the <code>java.util</code> package, <em>even if the collection is a set or map</em>. 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 <code>ArrayList</code> 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 <code>java.util</code> recipes for <code>@Singular @Builder</code>. + </p><p> + With <code>toBuilder = true</code> applied to methods, any type parameter of the annotated method itself must also show up in the return type. </p> </@f.smallPrint> </@f.scaffold> 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" /> +</@f.scaffold> diff --git a/website2/templates/features/configuration.html b/website2/templates/features/configuration.html index db3fc736..d33ae1c5 100644 --- a/website2/templates/features/configuration.html +++ b/website2/templates/features/configuration.html @@ -90,4 +90,17 @@ </div> </p> </@f.featureSection> + + <@f.featureSection> + <h3>Config keys that can affect any source file</h3> + + <p> + These config keys can make lombok affect source files even if they have 0 lombok annotations in them.<br /> + <div class="snippet example"> + <code>lombok.fieldDefaults.defaultPrivate = true</code><br /> + <code>lombok.fieldDefaults.defaultFinal = true</code> + </div> + Turning either of these options on means lombok will make <em>every</em> field in <em>every</em> source file final and/or private unless it has an explicit access modifier or annotation to suppress this. <a href="experimental/FieldDefaults">See the <code>@FieldDefaults</code> documentation for more</a>. + </p> + </@f.featureSection> </@f.scaffold> diff --git a/website2/templates/features/constructor.html b/website2/templates/features/constructor.html index 241926c0..fb331113 100644 --- a/website2/templates/features/constructor.html +++ b/website2/templates/features/constructor.html @@ -7,7 +7,7 @@ <p> This set of 3 annotations generate a constructor that will accept 1 parameter for certain fields, and simply assigns this parameter to the field. </p><p> - <code>@NoArgsConstructor</code> will generate a constructor with no parameters. If this is not possible (because of final fields), a compiler error will result instead. For fields with constraints, such as <code>@NonNull</code> fields, <em>no</em> check or assignment is generated, so be aware that these constraints may then not be fulfilled until those fields are properly initialized later. Certain java constructs, such as hibernate and the Service Provider Interface require a no-args constructor. This annotation is useful primarily in combination with either <code>@Data</code> or one of the other constructor generating annotations. + <code>@NoArgsConstructor</code> will generate a constructor with no parameters. If this is not possible (because of final fields), a compiler error will result instead, unless <code>@NoArgsConstructor(force = true</code> is used, then all final fields are initialized with <code>0</code> / <code>false</code> / <code>null</code>. For fields with constraints, such as <code>@NonNull</code> fields, <em>no</em> check is generated,so be aware that these constraints will generally not be fulfilled until those fields are properly initialized later. Certain java constructs, such as hibernate and the Service Provider Interface require a no-args constructor. This annotation is useful primarily in combination with either <code>@Data</code> or one of the other constructor generating annotations. </p><p> <code>@RequiredArgsConstructor</code> generates a constructor with 1 parameter for each field that requires special handling. All non-initialized <code>final</code> fields get a parameter, as well as any fields that are marked as <code>@NonNull</code> that aren't initialized where they are declared. For those fields marked with <code>@NonNull</code>, an explicit null check is also generated. The constructor will throw a <code>NullPointerException</code> if any of the parameters intended for the fields marked with <code>@NonNull</code> contain <code>null</code>. The order of the parameters match the order in which the fields appear in your class. </p><p> @@ -17,7 +17,7 @@ </p><p> To put annotations on the generated constructor, you can use <code>onConstructor=@__({@AnnotationsHere})</code>, but be careful; this is an experimental feature. For more details see the documentation on the <a href="/features/experimental/onX">onX</a> feature. </p><p> - Static fields are skipped by these annotations. Also, a <code>@java.beans.ConstructorProperties</code> annotation is added for all constructors with at least 1 argument, which allows bean editor tools to call the generated constructors. <code>@ConstructorProperties</code> is now in Java 1.6, which means that if your code is intended for compilation on Java 1.5, a compiler error will occur. <em>Running</em> on a JVM 1.5 should be no problem (the annotation will be ignored). To suppress the generation of the <code>@ConstructorProperties</code> annotation, add a parameter to your annotation: <code>@AllArgsConstructor(suppressConstructorProperties=true)</code>. However, as java 1.5, which has already been end-of-lifed, fades into obscurity, this parameter will eventually be removed. It has also been marked deprecated for this reason. + Static fields are skipped by these annotations. Also, a <code>@java.beans.ConstructorProperties</code> annotation is added for all constructors with at least 1 argument, which allows bean editor tools to call the generated constructors. <code>@ConstructorProperties</code> is new in Java 1.6, which means that if your code is intended for compilation on Java 1.5, a compiler error will occur. <em>Running</em> on a JVM 1.5 should be no problem (the annotation will be ignored). To suppress the generation of the <code>@ConstructorProperties</code> annotation, add a parameter to your annotation: <code>@AllArgsConstructor(suppressConstructorProperties=true)</code>. However, as java 1.5, which has already been end-of-lifed, fades into obscurity, this parameter will eventually be removed. It has also been marked deprecated for this reason. </p><p> Unlike most other lombok annotations, the existence of an explicit constructor does not stop these annotations from generating their own constructor. This means you can write your own specialized constructor, and let lombok generate the boilerplate ones as well. If a conflict arises (one of your constructors ends up with the same signature as one that lombok generates), a compiler error will occur. </p> diff --git a/website2/templates/features/data.html b/website2/templates/features/data.html index d018ae72..59370cc8 100644 --- a/website2/templates/features/data.html +++ b/website2/templates/features/data.html @@ -7,7 +7,7 @@ <p> <code>@Data</code> is a convenient shortcut annotation that bundles the features of <a href="/features/ToString"><code>@ToString</code></a>, <a href="/features/EqualsAndHashCode"><code>@EqualsAndHashCode</code></a>, <a href="/features/GetterSetter"><code>@Getter</code> / <code>@Setter</code></a> and <a href="/features/constructor"><code>@RequiredArgsConstructor</code></a> together: In other words, <code>@Data</code> generates <em>all</em> 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 <code>toString</code>, <code>equals</code> and <code>hashCode</code> 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 <code>@NonNull</code>, in order to ensure the field is never null. </p><p> - <code>@Data</code> is like having implicit <code>@Getter</code>, <code>@Setter</code>, <code>@ToString</code>, <code>@EqualsAndHashCode</code> and <code>@RequiredArgsConstructor</code> annotations on the class. However, the parameters of these annotations (such as <code>callSuper</code>, <code>includeFieldNames</code> and <code>exclude</code>) cannot be set with <code>@Data</code>. If you need to set non-default values for any of these parameters, just add those annotations explicitly; <code>@Data</code> is smart enough to defer to those annotations. + <code>@Data</code> is like having implicit <code>@Getter</code>, <code>@Setter</code>, <code>@ToString</code>, <code>@EqualsAndHashCode</code> and <code>@RequiredArgsConstructor</code> 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 <code>callSuper</code>, <code>includeFieldNames</code> and <code>exclude</code>) cannot be set with <code>@Data</code>. If you need to set non-default values for any of these parameters, just add those annotations explicitly; <code>@Data</code> is smart enough to defer to those annotations. </p><p> All generated getters and setters will be <code>public</code>. To override the access level, annotate the field or class with an explicit <code>@Setter</code> and/or <code>@Getter</code> annotation. You can also use this annotation (by combining it with <code>AccessLevel.NONE</code>) to suppress generating a getter and/or setter altogether. </p><p> diff --git a/website2/templates/features/experimental/FieldDefaults.html b/website2/templates/features/experimental/FieldDefaults.html index 77ed37b6..0d4cda9e 100644 --- a/website2/templates/features/experimental/FieldDefaults.html +++ b/website2/templates/features/experimental/FieldDefaults.html @@ -24,9 +24,9 @@ <p> The <code>@FieldDefaults</code> annotation can add an access modifier (<code>public</code>, <code>private</code>, or <code>protected</code>) to each field in the annotated class or enum. It can also add <code>final</code> to each field in the annotated class or enum. </p><p> - To add <code>final</code> to each field, use <code>@FieldDefaults(makeFinal=true)</code>. Any non-final field which must remain nonfinal can be annotated with <code>@NonFinal</code> (also in the <code>lombok.experimental</code> package). + To add <code>final</code> to each (instance) field, use <code>@FieldDefaults(makeFinal=true)</code>. Any non-final field which must remain nonfinal can be annotated with <code>@NonFinal</code> (also in the <code>lombok.experimental</code> package). </p><p> - To add an access modifier to each field, use <code>@FieldDefaults(level=AccessLevel.PRIVATE)</code>. 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 <code>@PackagePrivate</code> (also in the <code>lombok.experimental</code> package). + To add an access modifier to each (instance) field, use <code>@FieldDefaults(level=AccessLevel.PRIVATE)</code>. 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 <code>@PackagePrivate</code> (also in the <code>lombok.experimental</code> package). </p> </@f.overview> @@ -37,6 +37,14 @@ <code>lombok.fieldDefaults.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.fieldDefautls.defaultPrivate</code> = [<code>true</code> | <code>false</code>] (default: false) + </dt><dd> + (Since 1.16.8) If set to <code>true</code>, <em>every</em> field in <em>every</em> class or enum anywhere in the sources being compiled will be marked as <code>private</code> unless it has an explicit access modifier or the <code>@PackagePrivate</code> annotation, or an explicit <code>@FieldDefaults</code> annotation is present to override this config key. + </dd><dt> + <code>lombok.fieldDefaults.defaultFinal</code> = [<code>true</code> | <code>false</code>] (default: false) + </dt><dd> + (Since 1.16.8) If set to <code>true</code>, <em>every</em> field in <em>every</em> class or enum anywhere in the sources being compiled will be marked as <code>final</code> unless it has the <code>@NonFinal</code> annotation, or an explicit <code>@FieldDefaults</code> annotation is present to override this config key. </dd> </@f.confKeys> diff --git a/website2/templates/features/experimental/UtilityClass.html b/website2/templates/features/experimental/UtilityClass.html index 8145437a..4cee3657 100644 --- a/website2/templates/features/experimental/UtilityClass.html +++ b/website2/templates/features/experimental/UtilityClass.html @@ -9,7 +9,9 @@ <@f.experimental> <ul> - <li>Some debate as to whether its common enough to count as boilerplate.</li> + <li> + Some debate as to whether its common enough to count as boilerplate. + </li> </ul> Current status: <em>positive</em> - Currently we feel this feature may move out of experimental status with no or minor changes soon. </@f.experimental> diff --git a/website2/templates/features/experimental/index.html b/website2/templates/features/experimental/index.html index 257c0382..65cefd4c 100644 --- a/website2/templates/features/experimental/index.html +++ b/website2/templates/features/experimental/index.html @@ -25,35 +25,39 @@ </p> </div> <div class="row"> - <@main.feature title="@Accessors" code="/features/experimental/Accessors"> + <@main.feature title="var" href="var"> + Modifiable local variables with a type inferred by assigning value. + </@main.feature> + + <@main.feature title="@Accessors" href="Accessors"> A more fluent API for getters and setters. </@main.feature> - <@main.feature title="@ExtensionMethod" code="/features/experimental/ExtensionMethod"> + <@main.feature title="@ExtensionMethod" href="ExtensionMethod"> Annoying API? Fix it yourself: Add new methods to existing types! </@main.feature> - <@main.feature title="@FieldDefaults" code="/features/experimental/FieldDefaults"> + <@main.feature title="@FieldDefaults" href="FieldDefaults"> New default field modifiers for the 21st century. </@main.feature> - <@main.feature title="@Delegate" code="/features/experimental/Delegate"> + <@main.feature title="@Delegate" href="Delegate"> Don't lose your composition. </@main.feature> - <@main.feature title="@Wither" code="/features/experimental/Wither"> + <@main.feature title="@Wither" href="Wither"> Immutable 'setters' - methods that create a clone but with one changed field. </@main.feature> - <@main.feature title="onMethod= / onConstructor= / onParam=" code="/features/experimental/onX"> + <@main.feature title="onMethod= / onConstructor= / onParam=" href="onX"> Sup dawg, we heard you like annotations, so we put annotations in your annotations so you can annotate while you're annotating. </@main.feature> - <@main.feature title="@UtilityClass" code="/features/experimental/UtilityClass"> + <@main.feature title="@UtilityClass" href="UtilityClass"> Utility, metility, wetility! Utility classes for the masses. </@main.feature> - <@main.feature title="@Helper" code="/features/experimental/Helper"> + <@main.feature title="@Helper" href="Helper"> With a little help from my friends... Helper methods for java. </@main.feature> </div> @@ -69,10 +73,10 @@ <div class="row"> <h3 class="text-center">Putting the "Ex" in "Experimental": promoted or deleted experimental features.</h3> <div class="row"> - <@main.feature title="@Value: promoted" code="/features/Value"> + <@main.feature title="@Value: promoted" href="../Value"> <code>@Value</code> has proven its value and has been moved to the main package. </@main.feature> - <@main.feature title="@Builder: promoted" code="/features/Builder"> + <@main.feature title="@Builder: promoted" href="../Builder"> <code>@Builder</code> is a solid base to build APIs on, and has been moved to the main package. </@main.feature> </div> diff --git a/website2/templates/features/experimental/onX.html b/website2/templates/features/experimental/onX.html index 7398ce70..8e07f0ac 100644 --- a/website2/templates/features/experimental/onX.html +++ b/website2/templates/features/experimental/onX.html @@ -9,7 +9,8 @@ <@f.experimental> <ul> - <li>Ugly syntax. The syntax of this feature is not optimal, but it is the least convoluted syntax that could possibly work (for now!) + <li> + Ugly syntax. The syntax of this feature is not optimal, but it is the least convoluted syntax that could possibly work (for now!) </li><li> Possibly java 9 will offer (much) better ways of supporting this feature. </li><li> diff --git a/website2/templates/features/experimental/var.html b/website2/templates/features/experimental/var.html new file mode 100644 index 00000000..fa35ac5e --- /dev/null +++ b/website2/templates/features/experimental/var.html @@ -0,0 +1,37 @@ +<#import "../_features.html" as f> + +<@f.scaffold title="var" logline="Modifiable local variables with a type inferred by assigning value."> + <@f.history> + <p> + <code>var</code> was introduced in lombok 1.16.12 as experimental feature. + </p> + </@f.history> + + <@f.experimental> + <ul> + <li> + This feature is very controversial. + </li><li> + There is <a href="http://openjdk.java.net/jeps/286">JEP 286</a> that should make <code>var</code> obsolete. + </li> + </ul> + Current status: <em>uncertain</em> – Currently we feel this feature cannot move out of experimental status. + </@f.experimental> + + <@f.overview> + <p> + <code>var</code> works exactly like <a href="/features/val"><code>val</code></a>, except the local variable is <em>not</em> marked as <code>final</code>. + </p><p> + The type is still entirely derived from the mandatory initializer expression, and any further assignments, while now legal (because the variable is no longer <code>final</code>), aren't looked at to determine the appropriate type.<br /> + For example, <code>var x = "Hello"; x = Color.RED;</code> does <em>not</em> work; the type of x will be inferred to be <code>java.lang.String</code> and thus, the <code>x = Color.RED</code> assignment will fail. If the type of <code>x</code> was inferred to be <code>java.lang.Object</code> this code would have compiled, but that's not how<code>var</code> works. + </p> + </@f.overview> + + <@f.confKeys> + <dt> + <code>lombok.var.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) + </dt><dd> + Lombok will flag any usage of <code>var</code> as a warning or error if configured. + </dd> + </@f.confKeys> +</@f.scaffold> diff --git a/website2/templates/features/index.html b/website2/templates/features/index.html index 1dca7076..da3db634 100644 --- a/website2/templates/features/index.html +++ b/website2/templates/features/index.html @@ -6,64 +6,64 @@ <h1>Lombok features.</h1> </div> <div class="row"> - <@main.feature title="val" code="val"> + <@main.feature title="val" href="val"> Finally! Hassle-free final local variables. </@main.feature> - <@main.feature title="@NonNull" code="non-null"> + <@main.feature title="@NonNull" href="NonNull"> or: How I learned to stop worrying and love the NullPointerException. </@main.feature> - <@main.feature title="@Cleanup" code="cleanup"> + <@main.feature title="@Cleanup" href="Cleanup"> Automatic resource management: Call your <code>close()</code> methods safely with no hassle. </@main.feature> - <@main.feature title="@Getter/@Setter" code="getter-setter"> + <@main.feature title="@Getter/@Setter" href="GetterSetter"> Never write <code>public int getFoo() {return foo;}</code> again. </@main.feature> - <@main.feature title="@ToString" code="to-string"> + <@main.feature title="@ToString" href="ToString"> No need to start a debugger to see your fields: Just let lombok generate a <code>toString</code> for you! </@main.feature> - <@main.feature title="@EqualsAndHashCode" code="equals-and-hashcode"> + <@main.feature title="@EqualsAndHashCode" href="EqualsAndHashCode"> Equality made easy: Generates <code>hashCode</code> and <code>equals</code> implementations from the fields of your object.. </@main.feature> - <@main.feature title="@NoArgsConstructor, @RequiredArgsConstructor and @AllArgsConstructor" code="constructor"> + <@main.feature title="@NoArgsConstructor, @RequiredArgsConstructor and @AllArgsConstructor" href="constructor"> Constructors made to order: Generates constructors that take no arguments, one argument per final / non-nullfield, or one argument for every field. </@main.feature> - <@main.feature title="@Data" code="data"> + <@main.feature title="@Data" href="Data"> All together now: A shortcut for <code>@ToString</code>, <code>@EqualsAndHashCode</code>, <code>@Getter</code> on all fields, and <code>@Setter</code> on all non-final fields, and <code>@RequiredArgsConstructor</code>! </@main.feature> - <@main.feature title="@Value" code="value"> + <@main.feature title="@Value" href="Value"> Immutable classes made very easy. </@main.feature> - <@main.feature title="@Builder" code="builder"> + <@main.feature title="@Builder" href="Builder"> ... and Bob's your uncle: No-hassle fancy-pants APIs for object creation! </@main.feature> - <@main.feature title="@SneakyThrows" code="sneaky-throws"> + <@main.feature title="@SneakyThrows" href="SneakyThrows"> To boldly throw checked exceptions where no one has thrown them before! </@main.feature> - <@main.feature title="@Synchronized" code="sync"> + <@main.feature title="@Synchronized" href="Synchronized"> <code>synchronized</code> done right: Don't expose your locks. </@main.feature> - <@main.feature title="@Getter(lazy=true)" code="getter-lazy"> + <@main.feature title="@Getter(lazy=true)" href="GetterLazy"> Laziness is a virtue! </@main.feature> - <@main.feature title="@Log" code="log"> + <@main.feature title="@Log" href="log"> Captain's Log, stardate 24435.7: "What was that line again?" </@main.feature> </div> @@ -72,7 +72,7 @@ <h1>Configuration system</h1> <div class="text-center"> - Lombok, made to order: <a href="/feature/configuration">Configure lombok features</a> in one place for your entire project or even your workspace. + Lombok, made to order: <a href="configuration">Configure lombok features</a> in one place for your entire project or even your workspace. </div> </div> @@ -80,7 +80,7 @@ <h1 class="text-center">Running delombok</h1> <div> - Delombok copies your source files to another directory, replacing all lombok annotations with their desugared form. So, it'll turn <code>@Getter</code> back into the actual getter. It then removes the annotation. This is useful for all sorts of reasons; you can check out what's happening under the hood, if the unthinkable happens and you want to stop using lombok, you can easily remove all traces of it in your source, and you can use delombok to preprocess your source files for source-level tools such as javadoc and GWT. More information about how to run delombok, including instructions for build tools can be found at the <a href="/feature/api/delombok">delombok page</a>. + Delombok copies your source files to another directory, replacing all lombok annotations with their desugared form. So, it'll turn <code>@Getter</code> back into the actual getter. It then removes the annotation. This is useful for all sorts of reasons; you can check out what's happening under the hood, if the unthinkable happens and you want to stop using lombok, you can easily remove all traces of it in your source, and you can use delombok to preprocess your source files for source-level tools such as javadoc and GWT. More information about how to run delombok, including instructions for build tools can be found at the <a href="delombok">delombok page</a>. </div> </div> </div> diff --git a/website2/templates/features/log.html b/website2/templates/features/log.html index e27481b8..2854e896 100644 --- a/website2/templates/features/log.html +++ b/website2/templates/features/log.html @@ -13,13 +13,17 @@ <p> You put the variant of <code>@Log</code> on your class (whichever one applies to the logging system you use); you then have a static final <code>log</code> field, initialized to the name of your class, which you can then use to write log statements. </p><p> - There are six choices available:<br /> + There are several choices available:<br /> <dl> <dt> <code>@CommonsLog</code> </dt><dd> Creates <code><span class="keyword">private static final </span><a href="https://commons.apache.org/logging/apidocs/org/apache/commons/logging/Log.html">org.apache.commons.logging.Log</a> <span class="staticfield">log</span> = <a href="https://commons.apache.org/logging/apidocs/org/apache/commons/logging/LogFactory.html#getLog(java.lang.Class)">org.apache.commons.logging.LogFactory.getLog</a>(LogExample.<span class="keyword">class</span>);</code> </dd><dt> + <code>@JBossLog</code> + </dt><dd> + Creates <code><span class="keyword">private static final </span><a href="http://docs.jboss.org/jbosslogging/latest/org/jboss/logging/Logger.html">org.jboss.logging.Logger</a> <span class="staticfield">log</span> = <a href="http://docs.jboss.org/jbosslogging/latest/org/jboss/logging/Logger.html#getLogger(java.lang.Class)">org.jboss.logging.Logger.getLogger</a>(LogExample.<span class="keyword">class</span>);</code> + </dd><dt> <code>@Log</code> </dt><dd> Creates <code><span class="keyword">private static final </span><a href="http://download.oracle.com/javase/6/docs/api/java/util/logging/Logger.html">java.util.logging.Logger</a> <span class="staticfield">log</span> = <a href="http://download.oracle.com/javase/6/docs/api/java/util/logging/Logger.html#getLogger(java.lang.String)">java.util.logging.Logger.getLogger</a>(LogExample.<span class="keyword">class</span>.getName());</code> @@ -70,6 +74,10 @@ </dt><dd> Lombok will flag any usage of <code>@lombok.extern.java.Log</code> as a warning or error if configured. </dd><dt> + <code>lombok.log.jbosslog.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) + </dt><dd> + Lombok will flag any usage of <code>@lombok.extern.jbosslog.JBossLog</code> as a warning or error if configured. + </dd><dt> <code>lombok.log.log4j.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) </dt><dd> Lombok will flag any usage of <code>@lombok.extern.log4j.Log4j</code> as a warning or error if configured. diff --git a/website2/templates/features/val.html b/website2/templates/features/val.html index 34a3f187..32a8ffdf 100644 --- a/website2/templates/features/val.html +++ b/website2/templates/features/val.html @@ -1,9 +1,14 @@ <#import "_features.html" as f> <@f.scaffold title="val" logline="Finally! Hassle-free final local variables."> + <@f.history> + <p> + <code>val</code> was introduced in lombok 0.10. + </p> + </@f.history> <@f.overview> <p> - <em>NEW in Lombok 0.10: </em>You can use <code>val</code> as the type of a local variable declaration instead of actually writing the type. When you do this, the type will be inferred from the initializer expression. The local variable will also be made final. This feature works on local variables and on foreach loops only, not on fields. The initializer expression is required. + You can use <code>val</code> as the type of a local variable declaration instead of actually writing the type. When you do this, the type will be inferred from the initializer expression. The local variable will also be made final. This feature works on local variables and on foreach loops only, not on fields. The initializer expression is required. </p><p> <code>val</code> is actually a 'type' of sorts, and exists as a real class in the <code>lombok</code> package. You must import it for val to work (or use <code>lombok.val</code> as the type). The existence of this type on a local variable declaration triggers both the adding of the <code>final</code> keyword as well as copying the type of the initializing expression which overwrites the 'fake' <code>val</code> type. </p><p> diff --git a/website2/templates/features/value.html b/website2/templates/features/value.html index d9ea1ca7..fdad0e12 100644 --- a/website2/templates/features/value.html +++ b/website2/templates/features/value.html @@ -17,8 +17,8 @@ </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. You can mark any constructor or method with <code>@lombok.experimental.Tolerate</code> to hide them from lombok. </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. + 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 <code>@NonFinal</code> or <code>@PackagePrivate</code> annotations.<br /> + It is possible to override any default behavior for any of the 'parts' that make up <code>@Value</code> by explicitly using that annotation. </p> </@f.overview> |