diff options
Diffstat (limited to 'website/templates/features/experimental')
10 files changed, 603 insertions, 0 deletions
diff --git a/website/templates/features/experimental/Accessors.html b/website/templates/features/experimental/Accessors.html new file mode 100644 index 00000000..97017dc6 --- /dev/null +++ b/website/templates/features/experimental/Accessors.html @@ -0,0 +1,75 @@ +<#import "../_features.html" as f> + +<@f.scaffold title="@Accessors" logline="A more fluent API for getters and setters."> + <@f.history> + <p> + <code>@Accessors</code> was introduced as experimental feature in lombok v0.11.0. + </p> + </@f.history> + + <@f.experimental> + <ul> + <li> + We may want to roll these features into a more complete property support concept. + </li><li> + New feature – community feedback requested. + </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> + + <@f.overview> + <p> + The <code>@Accessors</code> annotation is used to configure how lombok generates and looks for getters and setters. + </p><p> + By default, lombok follows the <em>bean specification</em> for getters and setters: The getter for a field named <code>pepper</code> is <code>getPepper</code> for example. However, some might like to break with the <em>bean specification</em> in order to end up with nicer looking APIs. <code>@Accessors</code> lets you do this. + </p><p> + Some programmers like to use a prefix for their fields, i.e. they write <code>fPepper</code> instead of <code>pepper</code>. We <em>strongly</em> discourage doing this, as you can't unit test the validity of your prefixes, and refactor scripts may turn fields into local variables or method names. Furthermore, your tools (such as your editor) can take care of rendering the identifier in a certain way if you want this information to be instantly visible. Nevertheless, you can list the prefixes that your project uses via <code>@Accessors</code> as well. + </p><p> + <code>@Accessors</code> therefore has 3 options: + <ul> + <li> + <code>fluent</code> – A boolean. If <em>true</em>, the getter for <code>pepper</code> is just <code>pepper()</code>, and the setter is <code>pepper(T newValue)</code>. Furthermore, unless specified, <code>chain</code> defaults to <em>true</em>. <br /> + Default: <em>false</em>. + </li><li> + <code>chain</code> – A boolean. If <em>true</em>, generated setters return <code>this</code> instead of <code>void</code>.<br /> + Default: <em>false</em>, unless <code>fluent=true</code>, then Default: <em>true</em>. + </li><li> + <code>prefix</code> – A list of strings. If present, fields must be prefixed with any of these prefixes. Each field name is compared to each prefix in the list in turn, and if a match is found, the prefix is stripped out to create the base name for the field. It is legal to include an empty string in the list, which will always match. For characters which are letters, the character following the prefix must not be a lowercase letter, i.e. <code>pepper</code> is not a match even to prefix <code>p</code>, but <code>pEpper</code> would be (and would mean the base name of this field is <code>epper</code>). + </li> + </ul> + <p><p> + The <code>@Accessors</code> annotation is legal on types and fields; the annotation that applies is the one on the field if present, otherwise the one on the class. When a <code>@Accessors</code> annotation on a field is present, any <code>@Accessors</code> annotation also present on that field's type is ignored. + </p> + </@f.overview> + + <@f.snippets name="experimental/Accessors" /> + + <@f.confKeys> + <dt> + <code>lombok.accessors.chain</code> = [<code>true</code> | <code>false</code>] (default: false) + </dt><dd> + If set to <code>true</code>, any class that either doesn't have an <code>@Accessors</code> annotation, or it does, but that annotation does not have an explicit value for the <code>chain</code> parameter, will act as if <code>@Accessors(chain = true)</code> is present. + </dd><dt> + <code>lombok.accessors.fluent</code> = [<code>true</code> | <code>false</code>] (default: false) + </dt><dd> + If set to <code>true</code>, any class that either doesn't have an <code>@Accessors</code> annotation, or it does, but that annotation does not have an explicit value for the <code>fluent</code> parameter, will act as if <code>@Accessors(fluent = true)</code> is present. + </dd><dt> + <code>lombok.accessors.prefix</code> += <em>a field prefix</em> (default: empty list) + </dt><dd> + This is a list property; entries can be added with the <code>+=</code> operator. Inherited prefixes from parent config files can be removed with the <code>-=</code> operator. Any class that either doesn't have an <code>@Accessors</code> annotation, or it does, but that annotation does not have an explicit value for the <code>prefix</code> parameter, will act as if <code>@Accessors(prefix = {<em>prefixes listed in configuration</em>})</code> is present. + </dd><dt> + <code>lombok.accessors.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) + </dt><dd> + Lombok will flag any usage of <code>@Accessors</code> as a warning or error if configured. + </dd> + </@f.confKeys> + + <@f.smallPrint> + <p> + The nearest <code>@Accessors</code> annotation is also used for the various methods in lombok that look for getters, such as <code>@EqualsAndHashCode</code>. + </p><p> + If a prefix list is provided and a field does not start with one of them, that field is skipped entirely by lombok, and a warning will be generated. + </p> + </@f.smallPrint> +</@f.scaffold> diff --git a/website/templates/features/experimental/Delegate.html b/website/templates/features/experimental/Delegate.html new file mode 100644 index 00000000..265c754a --- /dev/null +++ b/website/templates/features/experimental/Delegate.html @@ -0,0 +1,59 @@ +<#import "../_features.html" as f> + +<@f.scaffold title="@Delegate" logline="Don't lose your composition."> + <@f.history> + <p> + <code>@Delegate</code> was introduced as feature in lombok v0.10 (the experimental package did not exist yet).<br /> + It was moved to the experimental package in lombok v1.14; the old version from the main lombok package is now deprecated. + </p> + </@f.history> + + <@f.experimental> + <ul> + <li> + Not used that much. + </li><li> + Difficult to support for edge cases, such as recursive delegation. + </li><li> + API is rather unfriendly; it would be a lot nicer if you can simply implement some methods and let <code>@Delegate</code> generate delegates for whatever you didn't manually implement, but due to issues with generics erasure this also can't be made to work without caveats. + </li> + </ul> + Current status: <em>negative</em> - Currently we feel this feature will not move out of experimental status anytime soon, and support for this feature may be dropped if future versions of javac or ecj make it difficult to continue to maintain the feature. + </@f.experimental> + + <@f.overview> + <p> + Any field or no-argument method can be annotated with <code>@Delegate</code> to let lombok generate delegate methods that forward the call to this field (or the result of invoking this method). + </p><p> + Lombok delegates all <code>public</code> methods of the field's type (or method's return type), as well as those of its supertypes except for all methods declared in <code>java.lang.Object</code>. + </p><p> + You can pass any number of classes into the <code>@Delegate</code> annotation's <code>types</code> parameter. If you do that, then lombok will delegate all <code>public</code> methods in those types (and their supertypes, except <code>java.lang.Object</code>) instead of looking at the field/method's type. + </p><p> + All public non-<code>Object</code> methods that are part of the calculated type(s) are copied, whether or not you also wrote implementations for those methods. That would thus result in duplicate method errors. You can avoid these by using the <code>@Delegate(excludes=SomeType.class)</code> parameter to exclude all public methods in the excluded type(s), and their supertypes. + </p><p> + To have very precise control over what is delegated and what isn't, write private inner interfaces with method signatures, then specify these private inner interfaces as types in <code>@Delegate(types=PrivateInnerInterfaceWithIncludesList.class, excludes=SameForExcludes.class)</code>. + </p> + </@f.overview> + + <@f.snippets name="experimental/Delegate" /> + + <@f.confKeys> + <dt> + <code>lombok.delegate.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) + </dt><dd> + Lombok will flag any usage of <code>@Delegate</code> as a warning or error if configured. + </dd> + </@f.confKeys> + + <@f.smallPrint> + <p> + When passing classes to the annotation's <code>types</code> or <code>excludes</code> parameter, you cannot include generics. This is a limitation of java. Use private inner interfaces or classes that extend the intended type including the generics parameter to work around this problem. + </p><p> + When passing classes to the annotation, these classes do not need to be supertypes of the field. See the example. + </p><p> + <code>@Delegate</code> cannot be used on static fields or methods. + </p><p> + <code>@Delegate</code> cannot be used when the calculated type(s) to delegate / exclude themselves contain <code>@Delegate</code> annotations; in other words, <code>@Delegate</code> will error if you attempt to use it recursively. + </p> + </@f.smallPrint> +</@f.scaffold> diff --git a/website/templates/features/experimental/ExtensionMethod.html b/website/templates/features/experimental/ExtensionMethod.html new file mode 100644 index 00000000..ca63bb2e --- /dev/null +++ b/website/templates/features/experimental/ExtensionMethod.html @@ -0,0 +1,67 @@ +<#import "../_features.html" as f> + +<@f.scaffold title="@ExtensionMethod" logline="Annoying API? Fix it yourself: Add new methods to existing types!"> + <@f.history> + <p> + <code>@ExtensionMethod</code> was introduced as experimental feature in lombok v0.11.2. + </p> + </@f.history> + + <@f.experimental> + <ul> + <li> + High-impact on code style. + </li><li> + Really would like to ship with utility methods to expand common classes, but so far lombok doesn't have a good distribution method for such runtime dependencies. + </li><li> + Affects quite a bit of eclipse, and auto-complete e.d. do not work yet in netbeans. + </li><li> + Should @ExtensionMethod be legal on methods? Should it be legal on packages? + </li><li> + This feature has more bugs associated with it than we would like, and it is a large maintenance burden. + </li> + </ul> + Current status: <em>hold</em> - Currently we feel this feature will not move out of experimental status anytime soon, but it will not significantly change and support for it is unlikely to be removed in future versions of lombok either. + </@f.experimental> + + <@f.overview> + <p> + You can make a class containing a bunch of <code>public</code>, <code>static</code> methods which all take at least 1 parameter. These methods will extend the type of the first parameter, as if they were instance methods, using the <code>@ExtensionMethod</code> feature. + </p><p> + For example, if you create <code>public static String toTitleCase(String in) { ... }</code>, you can use the <code>@ExtensionMethod</code> feature to make it look like the <code>java.lang.String</code> class has a method named <code>toTitleCase</code>, which has no arguments. The first argument of the static method fills the role of <code>this</code> in instance methods. + </p><p> + All methods that are <code>public</code>, <code>static</code>, and have at least 1 argument whose type is not primitive, are considered extension methods, and each will be injected into the namespace of the type of the first parameter as if they were instance methods. As in the above example, a call that looks like: <code>foo.toTitleCase()</code> is replaced with <code>ClassContainingYourExtensionMethod.toTitleCase(foo);</code>. Note that it is actually not an instant <code>NullPointerException</code> if <code>foo</code> is null - it is passed like any other parameter. + </p><p> + You can pass any number of classes to the <code>@ExtensionMethod</code> annotation; they will all be searched for extension methods. These extension methods apply for any code that is in the annotated class. + </p><p> + Lombok does not (currently) have any runtime dependencies which means lombok does not (currently) ship with any useful extension methods so you'll have to make your own. However, here's one that might spark your imagination: <br /> + <pre>public class ObjectExtensions { + public static <T> or(T object, T ifNull) { + return object != null ? object : ifNull; + } +}</pre><br /> + With the above class, if you add <code>@ExtensionMethod(ObjectExtensions.class)</code> to your class definition, you can write:<br /> + <pre>String x = null; +System.out.println(x.or("Hello, World!"));</pre><br /> + The above code will not fail with a <code>NullPointerException</code>; it will actually output <code>Hello, World!</code> + </p> + </@f.overview> + + <@f.snippets name="experimental/ExtensionMethod" /> + + <@f.confKeys> + <dt> + <code>lombok.extensionMethod.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) + </dt><dd> + Lombok will flag any usage of <code>@ExtensionMethod</code> as a warning or error if configured. + </dd> + </@f.confKeys> + + <@f.smallPrint> + <p> + Calls are rewritten to a call to the extension method; the static method itself is not inlined. Therefore, the extension method must be present both at compile and at runtime. + </p><p> + Generics is fully applied to figure out extension methods. i.e. if the first parameter of your extension method is <code>List<? extends String></code>, then any expression that is compatible with that will have your extension method, but other kinds of lists won't. So, a <code>List<Object></code> won't get it, but a <code>List<String></code> will. + </p> + </@f.smallPrint> +</@f.scaffold> diff --git a/website/templates/features/experimental/FieldDefaults.html b/website/templates/features/experimental/FieldDefaults.html new file mode 100644 index 00000000..0d4cda9e --- /dev/null +++ b/website/templates/features/experimental/FieldDefaults.html @@ -0,0 +1,56 @@ +<#import "../_features.html" as f> + +<@f.scaffold title="@FieldDefaults" logline="New default field modifiers for the 21st century."> + <@f.history> + <p> + @FieldDefaults was introduced as experimental feature in lombok v0.11.4. + </p> + </@f.history> + + <@f.experimental> + <ul> + <li> + New feature; unsure if this busts enough boilerplate. + </li><li> + Would be nice if you could stick this on the package-info.java package to set the default for all classes in that package. + </li><li> + Part of the work on @Value, which is experimental. + </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> + + <@f.overview> + <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 (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 (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> + + <@f.snippets name="experimental/FieldDefaults" /> + + <@f.confKeys> + <dt> + <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> + + <@f.smallPrint> + <p> + Like other lombok handlers that touch fields, any field whose name starts with a dollar (<code>$</code>) symbol is skipped entirely. Such a field will not be modified at all. + </p> + </@f.smallPrint> +</@f.scaffold> diff --git a/website/templates/features/experimental/Helper.html b/website/templates/features/experimental/Helper.html new file mode 100644 index 00000000..93b6e2b4 --- /dev/null +++ b/website/templates/features/experimental/Helper.html @@ -0,0 +1,52 @@ +<#import "../_features.html" as f> + +<@f.scaffold title="@Helper" logline="With a little help from my friends... Helper methods for java."> + <@f.history> + <p> + <code>@Helper</code> was introduced as an experimental feature in lombok v1.16.6. + </p> + </@f.history> + + <@f.experimental> + <ul> + <li> + Lambdas with general function types offer an alternative strategy. + </li><li> + Perhaps a way to make helper methods with less boilerplate is possible, making this feature obsolete. + </li> + </ul> + Current status: <em>unknown</em> - We don't have enough experience with this feature to make predictions on its future. + </@f.experimental> + + <@f.overview> + <p> + This annotation lets you put methods in methods. You might not know this, but you can declare classes inside methods, and the methods in this class can access any (effectively) final local variable or parameter defined and set before the declaration. Unfortunately, to actually call any methods you'd have to make an instance of this method local class first, but that's where <code>@Helper</code> comes in and helps you out! Annotate a method local class with <code>@Helper</code> and it's as if all the methods in that helper class are methods that you can call directly, just as if java had allowed methods to exist inside methods. + </p><p> + Normally you'd have to declare an instance of your helper, for example: <code>HelperClass h = new HelperClass();</code> directly after declaring your helper class, and then call methods in your helper class with <code>h.helperMethod();</code>. With <code>@Helper</code>, both of these things are no longer needed: You do not need to waste a line of code declaring an instance of the helper, and you don't need to prefix all your calls to helper methods with <code>nameOfHelperInstance.</code> + </p> + </@f.overview> + + <@f.snippets name="experimental/Helper" /> + + <@f.confKeys> + <dt> + <code>lombok.helper.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) + </dt><dd> + Lombok will flag any usage of <code>@Helper</code> as a warning or error if configured. + </dd> + </@f.confKeys> + + <@f.smallPrint> + <p> + <code>@Helper</code> requires that the helper class has a no-args constructor. A compiler error will be generated if this is not the case. + </p><p> + Currently, the instance of your helper that's made under the hood is called <code>$Foo</code>, where <code>Foo</code> is the name of your helper. We might change this in the future; please don't rely on this variable existing. We might even replace this later with a sibling method instead. + </p><p> + Please don't rely on <code>this</code> making any sense in the helper method code. You can refer to the real 'this' by using the syntax <code>NameOfMyClass.this</code>. + </p><p> + <em>ANY</em> unqualified method call in code that exists <em>below</em> the declaration of the helper method with the same name as any method in the helper is assumed to be a call to the helper. If the arguments don't end up being compatible, you get a compiler error. + </p><p> + Unless you're using JDK8 or higher (which introduced the concept of 'effectively final'), you'll have to declare local variables and parameters as <code>final</code> if you wish to refer to them in your method local class. This is a java limitation, not something specific to lombok's <code>@Helper</code>. + </p> + </@f.smallPrint> +</@f.scaffold> diff --git a/website/templates/features/experimental/UtilityClass.html b/website/templates/features/experimental/UtilityClass.html new file mode 100644 index 00000000..4cee3657 --- /dev/null +++ b/website/templates/features/experimental/UtilityClass.html @@ -0,0 +1,44 @@ +<#import "../_features.html" as f> + +<@f.scaffold title="@UtilityClass" logline="Utility, metility, wetility! Utility classes for the masses."> + <@f.history> + <p> + <code>@UtilityClass</code> was introduced as an experimental feature in lombok v1.16.2. + </p> + </@f.history> + + <@f.experimental> + <ul> + <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> + + <@f.overview> + <p> + A utility class is a class that is just a namespace for functions. No instances of it can exist, and all its members are static. For example, <code>java.lang.Math</code> and <code>java.util.Collections</code> are well known utility classes. This annotation automatically turns the annotated class into one. + </p><p> + A utility class cannot be instantiated. By marking your class with <code>@UtilityClass</code>, lombok will automatically generate a private constructor that throws an exception, flags as error any explicit constructors you add, and marks the class <code>final</code>. If the class is an inner class, the class is also marked <code>static</code>. + </p><p> + <em>All</em> members of a utility class are automatically marked as <code>static</code>. Even fields and inner classes. + </p> + </@f.overview> + + <@f.snippets name="experimental/UtilityClass" /> + + <@f.confKeys> + <dt> + <code>lombok.utilityClass.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) + </dt><dd> + Lombok will flag any usage of <code>@UtilityClass</code> as a warning or error if configured. + </dd> + </@f.confKeys> + + <@f.smallPrint> + <p> + There isn't currently any way to create non-static members, or to define your own constructor. If you want to instantiate the utility class, even only as an internal implementation detail, <code>@UtilityClass</code> cannot be used. + </p> + </@f.smallPrint> +</@f.scaffold> diff --git a/website/templates/features/experimental/Wither.html b/website/templates/features/experimental/Wither.html new file mode 100644 index 00000000..9642458b --- /dev/null +++ b/website/templates/features/experimental/Wither.html @@ -0,0 +1,66 @@ +<#import "../_features.html" as f> + +<@f.scaffold title="@Wither" logline="Immutable 'setters' - methods that create a clone but with one changed field."> + <@f.history> + <p> + @Wither was introduced as experimental feature in lombok v0.11.4. + </p> + </@f.history> + + <@f.experimental> + <ul> + <li> + Still not sure that <code>@Wither</code> is an appropriate name for this feature. + </li><li> + Should there be an option to supply a way of cloning the input somehow? + </li><li> + Should the way that the clone is created by configurable? + </li><li> + Should we replace @Wither entirely with a builder class? + </li> + </ul> + Current status: <em>neutral</em> - More feedback requires on the items in the above list before promotion to the main package is warranted. + </@f.experimental> + + <@f.overview> + <p> + The next best alternative to a setter for an immutable property is to construct a clone of the object, but with a new value for this one field. A method to generate this clone is precisely what <code>@Wither</code> generates: a <code>withFieldName(newValue)</code> method which produces a clone except for the new value for the associated field. + </p><p> + For example, if you create <code>public class Point { private final int x, y; }</code>, setters make no sense because the fields are final. <code>@Wither</code> can generate a <code>withX(int newXValue)</code> method for you which will return a new point with the supplied value for <code>x</code> and the same value for <code>y</code>. + </p><p> + Like <a href="/features/GetterSetter"><code>@Setter</code></a>, you can specify an access level in case you want the generated wither to be something other than <code>public</code>:<br /> <code>@Wither(level = AccessLevel.PROTECTED)</code>. Also like <a href="/features/GetterSetter"><code>@Setter</code></a>, you can also put a <code>@Wither</code> annotation on a type, which means a 'wither' is generated for each field (even non-final fields). + </p><p> + To put annotations on the generated method, you can use <code>onMethod=@__({@AnnotationsHere})</code>; to put annotations on the only parameter of a generated wither method, you can use <code>onParam=@__({@AnnotationsHere})</code>. Be careful though! This is an experimental feature. For more details see the documentation on the <a href="/features/experimental/onX">onX</a> feature. + </p><p> + <em>NEW in lombok v1.12.0:</em> javadoc on the field will now be copied to generated withers. Normally, all text is copied, and <code>@param</code> is <em>moved</em> to the wither, whilst <code>@return</code> lines are stripped from the wither's javadoc. Moved means: Deleted from the field's javadoc. It is also possible to define unique text for the wither's javadoc. To do that, you create a 'section' named <code>WITHER</code>. A section is a line in your javadoc containing 2 or more dashes, then the text 'WITHER', followed by 2 or more dashes, and nothing else on the line. If you use sections, <code>@return</code> and <code>@param</code> stripping / copying for that section is no longer done (move the <code>@param</code> line into the section). + </p> + </@f.overview> + + <@f.snippets name="experimental/Wither" /> + + <@f.confKeys> + <dt> + <code>lombok.wither.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) + </dt><dd> + Lombok will flag any usage of <code>@Wither</code> as a warning or error if configured. + </dd> + </@f.confKeys> + + <@f.smallPrint> + <p> + Withers cannot be generated for static fields because that makes no sense. + </p><p> + Withers can be generated for abstract classes, but this generates an abstract method with the appropriate signature. + </p><p> + When applying <code>@Wither</code> to a type, static fields and fields whose name start with a $ are skipped. + </p><p> + For generating the method names, the first character of the field, if it is a lowercase character, is title-cased, otherwise, it is left unmodified. Then, <code>with</code> is prefixed. + </p><p> + No method is generated if any method already exists with the same name (case insensitive) and same parameter count. For example, <code>withX(int x)</code> will not be generated if there's already a method <code>withX(String... x)</code> even though it is technically possible to make the method. This caveat exists to prevent confusion. If the generation of a method is skipped for this reason, a warning is emitted instead. Varargs count as 0 to N parameters. + </p><p> + For <code>boolean</code> fields that start with <code>is</code> immediately followed by a title-case letter, nothing is prefixed to generate the wither name. + </p><p> + Any annotations named <code>@NonNull</code> (case insensitive) on the field are interpreted as: This field must not ever hold <em>null</em>. Therefore, these annotations result in an explicit null check in the generated wither. Also, these annotations (as well as any annotation named <code>@Nullable</code> or <code>@CheckForNull</code>) are copied to wither parameter. + </p> + </@f.smallPrint> +</@f.scaffold> diff --git a/website/templates/features/experimental/index.html b/website/templates/features/experimental/index.html new file mode 100644 index 00000000..11d48485 --- /dev/null +++ b/website/templates/features/experimental/index.html @@ -0,0 +1,85 @@ +<#import "../../_scaffold.html" as main> +<#import "../_features.html" as f> + +<@main.scaffold> + <div class="page-header top5"> + <div class="row text-center"> + <h1>Lombok experimental features</h1> + </div> + <div class="row"> + <p> + Experimental features are available in your normal lombok installation, but are not as robustly supported as lombok's main features. In particular, experimental features: + <ul> + <li> + Are not tested as well as the core features. + </li><li> + Do not get bugs fixed as quickly as core features. + </li><li> + May have APIs that will change, possibly drastically if we find a different, better way to solve the same problem. + </li><li> + May disappear entirely if the feature is too difficult to support or doesn't bust enough boilerplate. + </li> + </ul> + </p><p> + Features that receive positive community feedback and which seem to produce clean, flexible code will eventually become accepted as a core feature and move out of the experimental package. + </p> + </div> + <div class="row"> + <@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" href="ExtensionMethod"> + Annoying API? Fix it yourself: Add new methods to existing types! + </@main.feature> + + <@main.feature title="@FieldDefaults" href="FieldDefaults"> + New default field modifiers for the 21st century. + </@main.feature> + + <@main.feature title="@Delegate" href="Delegate"> + Don't lose your composition. + </@main.feature> + + <@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=" 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" href="UtilityClass"> + Utility, metility, wetility! Utility classes for the masses. + </@main.feature> + + <@main.feature title="@Helper" href="Helper"> + With a little help from my friends... Helper methods for java. + </@main.feature> + </div> + + <@f.confKeys> + <dt> + <code>lombok.experimental.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) + </dt><dd> + Lombok will flag any usage of any of the features listed here as a warning or error if configured. + </dd> + </@f.confKeys> + + <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" href="/features/Value"> + <code>@Value</code> has proven its value and has been moved to the main package. + </@main.feature> + <@main.feature title="@Builder: promoted" href="/features/Builder"> + <code>@Builder</code> is a solid base to build APIs on, and has been moved to the main package. + </@main.feature> + </div> + </div> + </div> +</@main.scaffold> diff --git a/website/templates/features/experimental/onX.html b/website/templates/features/experimental/onX.html new file mode 100644 index 00000000..fd2e7b58 --- /dev/null +++ b/website/templates/features/experimental/onX.html @@ -0,0 +1,62 @@ +<#import "../_features.html" as f> + +<@f.scaffold title="onX" logline="Sup dawg, we heard you like annotations, so we put annotations in your annotations so you can annotate while you're annotating."> + <@f.history> + <p> + onX was introduced as experimental feature in lombok v0.11.8. + </p> + </@f.history> + + <@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><li> + Possibly java 9 will offer (much) better ways of supporting this feature. + </li><li> + Uncertainty: Future versions of javac may break this feature, and we may not be able to restore it. + </li> + </ul> + Current status: <em>uncertain</em> - Currently we feel this feature cannot move out of experimental status. + </@f.experimental> + + <@f.overview> + <p> + <strong>This feature is considered 'workaround status' - it exists in order to allow users of lombok that cannot work without this feature to have access to it anyway. If we find a better way to implement this feature, or some future java version introduces an alternative strategy, this feature can disappear without a reasonable deprecation period. Also, this feature may not work in future versions of javac. Use at your own discretion.</strong> + </p><p> + Most annotations that make lombok generate methods or constructors can be configured to also make lombok put custom annotations on elements in the generated code. + </p><p> + <code>@Getter</code>, <code>@Setter</code>, and <code>@Wither</code> support the <code>onMethod</code> option, which will put the listed annotations on the generated method. + </p><p> + <code>@AllArgsConstructor</code>, <code>@NoArgsConstructor</code>, and <code>@RequiredArgsConstructor</code> support the <code>onConstructor</code> option which will put the listed annotations on the generated constructor. + </p><p> + <code>@Setter</code> and <code>@Wither</code> support <code>onParam</code> in addition to <code>onMethod</code>; annotations listed will be put on the only parameter that the generated method has. <code>@EqualsAndHashCode</code> also supports <code>onParam</code>; the listed annotation(s) will be placed on the single parameter of the generated <code>equals</code> method, as well as any generated <code>canEqual</code> method. + </p><p> + The syntax is a little strange and depends on the javac you are using.<br /> + On javac7, to use any of the 3 <code>onX</code> features, you must wrap the annotations to be applied to the constructor / method / parameter in <code>@__(@AnnotationGoesHere)</code>. To apply multiple annotations, use <code>@__({@Annotation1, @Annotation2})</code>. The annotations can themselves obviously have parameters as well.<br /> + On javac8 and up, you add an underscore after <code>onMethod</code>, <code>onParam</code>, or <code>onConstructor</code>. + </p> + </@f.overview> + + <@f.snippets name="experimental/onX" /> + + <@f.confKeys> + <dt> + <code>lombok.onX.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) + </dt><dd> + Lombok will flag any usage of <code>onX</code> as a warning or error if configured. + </dd> + </@f.confKeys> + + <@f.smallPrint> + <p> + The reason of the weird syntax is to make this feature work in javac 7 compilers; the <code>@__</code> type is an annotation reference to the annotation type <code>__</code> (double underscore) which doesn't actually exist; this makes javac 7 delay aborting the compilation process due to an error because it is possible an annotation processor will later create the <code>__</code> type. Instead, lombok applies the annotations and removes the references so that the error will never actually occur. The point is: The <code>__</code> type <em>must not exist</em>, otherwise the feature does not work. In the rare case that the <code>__</code> type does exist (and is imported or in the package), you can simply add more underscores. Technically any non-existent type would work, but to maintain consistency and readability and catch erroneous use, lombok considers it an error if the 'wrapper' annotation is anything but a series of underscores. + </p><p> + In javac8, the above feature should work but due to a bug in javac8 it does not. However, starting in javac8, if the parameter name does not exist in the annotation type, compilation proceeds to a phase where lombok can fix it. + </p><p> + To reiterate: This feature can disappear at any time; if you use this feature, be prepared to adjust your code when we find a nicer way of implementing this feature, or, if a future version of javac forces us to remove this feature entirely with no alternative. + </p><p> + The <code>onX</code> parameter is not legal on any type-wide variant. For example, a <code>@Getter</code> annotation on a class does not support <code>onMethod</code>. + </p> + </@f.smallPrint> +</@f.scaffold> diff --git a/website/templates/features/experimental/var.html b/website/templates/features/experimental/var.html new file mode 100644 index 00000000..fa35ac5e --- /dev/null +++ b/website/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> |