Date: Mon, 8 May 2017 21:28:02 +0200 Subject: The great rename: the old ‘website’ is now ‘website-old’, and ‘website2’ is now ‘website’. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- website-old/features/experimental/Accessors.html | 116 +++++++++++++++++++++ website-old/features/experimental/Builder.html | 36 +++++++ website-old/features/experimental/Delegate.html | 100 ++++++++++++++++++ .../features/experimental/ExtensionMethod.html | 116 +++++++++++++++++++++ .../features/experimental/FieldDefaults.html | 95 +++++++++++++++++ website-old/features/experimental/Value.html | 36 +++++++ website-old/features/experimental/Wither.html | 113 ++++++++++++++++++++ website-old/features/experimental/index.html | 77 ++++++++++++++ website-old/features/experimental/onX.html | 92 ++++++++++++++++ website-old/features/experimental/var.html | 83 +++++++++++++++ 10 files changed, 864 insertions(+) create mode 100644 website-old/features/experimental/Accessors.html create mode 100644 website-old/features/experimental/Builder.html create mode 100644 website-old/features/experimental/Delegate.html create mode 100644 website-old/features/experimental/ExtensionMethod.html create mode 100644 website-old/features/experimental/FieldDefaults.html create mode 100644 website-old/features/experimental/Value.html create mode 100644 website-old/features/experimental/Wither.html create mode 100644 website-old/features/experimental/index.html create mode 100644 website-old/features/experimental/onX.html create mode 100644 website-old/features/experimental/var.html (limited to 'website-old/features/experimental') diff --git a/website-old/features/experimental/Accessors.html b/website-old/features/experimental/Accessors.html new file mode 100644 index 00000000..909c0873 --- /dev/null +++ b/website-old/features/experimental/Accessors.html @@ -0,0 +1,116 @@ + + + + + + + + EXPERIMENTAL – @Accessors +

+ +

@Accessors

A more fluent API for getters and setters.

Since

+ @Accessors was introduced as experimental feature in lombok v0.11.0. +

Experimental

+ Experimental because: +

We may want to roll these features into a more complete property support concept.
New feature - community feedback requested.

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

Overview

+ The @Accessors annotation is used to configure how lombok generates and looks for getters and setters. +

+ By default, lombok follows the bean specification for getters and setters: The getter for a field named pepper + is getPepper for example. However, some might like to break with the bean specification in order to end up with + nicer looking APIs. @Accessors lets you do this. +

+ Some programmers like to use a prefix for their fields, i.e. they write fPepper instead of pepper. + We strongly 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 + @Accessors as well. +

+ @Accessors therefore has 3 options:

fluent - A boolean. If true, the getter for pepper is just pepper(), and the + setter is pepper(T newValue). Furthermore, unless specified, chain defaults to true.
+ Default: false.
chain - A boolean. If true, generated setters return this instead of void.
+ Default: false, unless fluent=true, then Default: true.
prefix - 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. pepper is not a match even to prefix p, + but pEpper would be (and would mean the base name of this field is epper).

+ The @Accessors 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 @Accessors annotation on a field is present, any @Accessors annotation + also present on that field's type is ignored. +

With Lombok

@HTML_PRE@

Vanilla Java

@HTML_POST@

Supported configuration keys:

lombok.accessors.chain = [true | false] (default: false): If set to true, any class that either doesn't have an @Accessors annotation, or it does, but that annotation does not have an explicit value for the chain parameter, will act as if @Accessors(chain = true) is present.
lombok.accessors.fluent = [true | false] (default: false): If set to true, any class that either doesn't have an @Accessors annotation, or it does, but that annotation does not have an explicit value for the fluent parameter, will act as if @Accessors(fluent = true) is present.
lombok.accessors.prefix += a field prefix (default: empty list): This is a list property; entries can be added with the += operator. Inherited prefixes from parent config files can be removed with the -= operator. Any class that either doesn't have an @Accessors annotation, or it does, but that annotation does not have an explicit value for the prefix parameter, will act as if @Accessors(prefix = {prefixes listed in configuration}) is present.
lombok.accessors.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @Accessors as a warning or error if configured.

Small print

+ The nearest @Accessors annotation is also used for the various methods in lombok that look for getters, such as + @EqualsAndHashCode. +

+ 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. +

+ +

+ + + diff --git a/website-old/features/experimental/Builder.html b/website-old/features/experimental/Builder.html new file mode 100644 index 00000000..e1c545fc --- /dev/null +++ b/website-old/features/experimental/Builder.html @@ -0,0 +1,36 @@ + + + + + + + + @Builder +

+ +

@Builder

... and Bob's your uncle: No-hassle fancy-pants APIs for object creation!

+ @Builder has been promoted to the core package in lombok release v1.16.0.
+ The documentation has been moved here: @lombok.Builder. +

+ +

+ + + diff --git a/website-old/features/experimental/Delegate.html b/website-old/features/experimental/Delegate.html new file mode 100644 index 00000000..5173376d --- /dev/null +++ b/website-old/features/experimental/Delegate.html @@ -0,0 +1,100 @@ + + + + + + + + EXPERIMENTAL – @Delegate +

+ +

@Delegate

Don't lose your composition.

Since

+ @Delegate was introduced as feature in lombok v0.10. It was moved to the experimental package in lombok v1.14; the old version from the main lombok package is now deprecated. +

Experimental

+ Experimental because: +

Not used that much
Difficult to support for edge cases, such as recursive delegation.
API is rather unfriendly; it would be a lot nicer if you can simply implement some methods and let @Delegate 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. +

+ Current status: negative - 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. +

Overview

+ Any field or no-argument method can be annotated with @Delegate to let lombok generate delegate methods that forward the call to this field (or the result of invoking this method). +

+ Lombok delegates all public methods of the field's type (or method's return type), as well as those of its supertypes except for all + methods declared in java.lang.Object. +

+ You can pass any number of classes into the @Delegate annotation's types parameter. + If you do that, then lombok will delegate all public methods in those types (and their supertypes, except java.lang.Object) instead of looking at the field/method's type. +

+ All public non-Object 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 @Delegate(excludes=SomeType.class) parameter to exclude all public methods in the excluded type(s), and their supertypes. +

+ 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 @Delegate(types=PrivateInnerInterfaceWithIncludesList.class, excludes=SameForExcludes.class). +

With Lombok

@HTML_PRE@

Vanilla Java

@HTML_POST@

Supported configuration keys:

lombok.delegate.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @Delegate as a warning or error if configured.

Small print

+ When passing classes to the annotation's types or excludes 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. +

+ When passing classes to the annotation, these classes do not need to be supertypes of the field. See the example. +

+ @Delegate cannot be used on static fields or methods. +

+ @Delegate cannot be used when the calculated type(s) to delegate / exclude themselves contain @Delegate annotations; in other words, @Delegate will error if you attempt to use it recursively. +

+ +

+ + + diff --git a/website-old/features/experimental/ExtensionMethod.html b/website-old/features/experimental/ExtensionMethod.html new file mode 100644 index 00000000..7090fd19 --- /dev/null +++ b/website-old/features/experimental/ExtensionMethod.html @@ -0,0 +1,116 @@ + + + + + + + + EXPERIMENTAL – @ExtensionMethod +

+ +

@ExtensionMethod

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

Since

+ @ExtensionMethod was introduced as experimental feature in lombok v0.11.2. +

Experimental

+ Experimental because: +

High-impact on code style
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
Affects quite a bit of eclipse, and auto-complete e.d. do not work yet in netbeans
Should @ExtensionMethod be legal on methods? Should it be legal on packages?

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

Overview

+ You can make a class containing a bunch of public, static 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 + @ExtensionMethod feature. +

+ For example, if you create public static String toTitleCase(String in) { ... }, you can use the + @ExtensionMethod feature to make it look like the java.lang.String class has a method named + toTitleCase, which has no arguments. The first argument of the static method fills the role of this + in instance methods. +

+ All methods that are public, static, 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: foo.toTitleCase() is replaced with + ClassContainingYourExtensionMethod.toTitleCase(foo);. Note that it is actually not an instant + NullPointerException if foo is null - it is passed like any other parameter. +

+ You can pass any number of classes to the @ExtensionMethod annotation; they will all be searched for + extension methods. These extension methods apply for any code that is in the annotated class. +

+ 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: +

public class ObjectExtensions {
+	public static <T> or(T object, T ifNull) {
+		return object != null ? object : ifNull;
+	}
+}

+ With the above class, if you add @ExtensionMethod(ObjectExtensions.class) to your class definition, you can write: +

String x = null;
+System.out.println(x.or("Hello, World!"));

+ The above code will not fail with a NullPointerException; it will actually output Hello, World! +

With Lombok

@HTML_PRE@

Vanilla Java

@HTML_POST@

Supported configuration keys:

lombok.extensionMethod.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @ExtensionMethod as a warning or error if configured.

Small print

+ 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. +

+ Generics is fully applied to figure out extension methods. i.e. if the first parameter of your extension method is + List<? extends String>, then any expression that is compatible with that will have your extension method, + but other kinds of lists won't. So, a List<Object> won't get it, but a List<String> will. +

+ +

+ + + diff --git a/website-old/features/experimental/FieldDefaults.html b/website-old/features/experimental/FieldDefaults.html new file mode 100644 index 00000000..a253198b --- /dev/null +++ b/website-old/features/experimental/FieldDefaults.html @@ -0,0 +1,95 @@ + + + + + + + + EXPERIMENTAL – @FieldDefaults +

+ +

@FieldDefaults

New default field modifiers for the 21st century.

Since

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

Experimental

+ Experimental because: +

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

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

Overview

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

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

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

With Lombok

@HTML_PRE@

Vanilla Java

@HTML_POST@

Supported configuration keys:

lombok.fieldDefaults.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @FieldDefaults as a warning or error if configured.
lombok.fieldDefaults.defaultPrivate = [true | false] (default: false): (Since 1.16.8) If set to true, every field in every class or enum anywhere in the sources being compiled will be marked as private unless it has an explicit access modifier or the @PackagePrivate annotation, or an explicit @FieldDefaults annotation is present to override this config key.
lombok.fieldDefaults.defaultFinal = [true | false] (default: false): (Since 1.16.8) If set to true, every field in every class or enum anywhere in the sources being compiled will be marked as final unless it has the @NonFinal annotation, or an explicit @FieldDefaults annotation is present to override this config key.

Small print

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

+ +

+ + + diff --git a/website-old/features/experimental/Value.html b/website-old/features/experimental/Value.html new file mode 100644 index 00000000..ec0ff9e4 --- /dev/null +++ b/website-old/features/experimental/Value.html @@ -0,0 +1,36 @@ + + + + + + + + EXPERIMENTAL – @Value +

+ +

@Value

Immutable classes made very easy.

+ @Value has been promoted to the core package in lombok release v1.12.0.
+ The documentation has been moved here: @lombok.Value. +

+ +

+ + + diff --git a/website-old/features/experimental/Wither.html b/website-old/features/experimental/Wither.html new file mode 100644 index 00000000..c8030bd9 --- /dev/null +++ b/website-old/features/experimental/Wither.html @@ -0,0 +1,113 @@ + + + + + + + + EXPERIMENTAL – @Wither +

+ +

@Wither

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

Since

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

Experimental

+ Experimental because: +

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

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

Overview

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

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

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

+ To put annotations on the generated method, you can use onMethod=@__({@AnnotationsHere}); to put annotations on the only parameter of a generated wither method, you can use onParam=@__({@AnnotationsHere}). Be careful though! This is an experimental feature. For more details see the documentation on the onX feature. +

+ NEW in lombok v1.12.0: javadoc on the field will now be copied to generated withers. Normally, all text is copied, and @param is moved to the wither, whilst @return 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 WITHER. 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, @return and @param stripping / copying for that section is no longer done (move the @param line into the section). +

With Lombok

@HTML_PRE@

Vanilla Java

@HTML_POST@

Supported configuration keys:

lombok.wither.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @Wither as a warning or error if configured.

Small print

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

+ Withers can be generated for abstract classes, but this generates an abstract method with the appropriate signature. +

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

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

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

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

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

+ +

+ + + diff --git a/website-old/features/experimental/index.html b/website-old/features/experimental/index.html new file mode 100644 index 00000000..4a6d12bb --- /dev/null +++ b/website-old/features/experimental/index.html @@ -0,0 +1,77 @@ + + + + + + + + Lombok feature overview +

+ +

Lombok experimental features

+ Experimental features are available in your normal lombok installation, but are not as robustly supported as lombok's main features. + In particular, experimental features:

Are not tested as well as the core features.
Do not get bugs fixed as quickly as core features.
May have APIs that will change, possibly drastically if we find a different, better way to solve the same problem.
May disappear entirely if the feature is too difficult to support or does bust enough boilerplate.

+ 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. +

@var: The same as @val but modifiable.
@Accessors: A more fluent API for getters and setters.
@ExtensionMethod: Annoying API? Fix it yourself: Add new methods to existing types!
@FieldDefaults: New default field modifiers for the 21st century.
@Delegate: Don't lose your composition.
@Wither: Immutable 'setters' - methods that create a clone but with one changed field.
onMethod= / onConstructor= / onParam=: Sup dawg, we heard you like annotations, so we put annotations in your annotations so you can annotate while you're annotating.
@UtilityClass: Utility, metility, wetility! Utility classes for the masses.
@Helper: With a little help from my friends... Helper methods for java.

Supported configuration keys:

lombok.experimental.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of any of the features listed here as a warning or error if configured.

Putting the "Ex" in "Experimental": promoted or deleted experimental features.

@Value: Promoted: @Value has proven its value and has been moved to the main package. +
@Builder: Promoted: @Builder is a solid base to build APIs on, and has been moved to the main package. +

+ +

+ + + diff --git a/website-old/features/experimental/onX.html b/website-old/features/experimental/onX.html new file mode 100644 index 00000000..39faa1bf --- /dev/null +++ b/website-old/features/experimental/onX.html @@ -0,0 +1,92 @@ + + + + + + + + EXPERIMENTAL – onX +

+ +

onX

Sup dawg, we heard you like annotations, so we put annotations in your annotations so you can annotate while you're annotating.

Since

+ onX was introduced as experimental feature in lombok v0.11.8. +

Experimental

+ Experimental because: +

Ugly syntax. The syntax of this feature is not optimal, but it is the least convoluted syntax that could possibly work (for now!)
Possibly java 9 will offer (much) better ways of supporting this feature.
Uncertainty: Future versions of javac may break this feature, and we may not be able to restore it.

+ Current status: uncertain - Currently we feel this feature cannot move out of experimental status. +

Overview

+ 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. +

+ 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. +

+ @Getter, @Setter, and @Wither support the onMethod option, which will put the listed annotations on the generated method. +

+ @AllArgsConstructor, @NoArgsConstructor, and @RequiredArgsConstructor support the onConstructor option which will put the listed annotations on the generated constructor. +

+ @Setter and @Wither support onParam in addition to onMethod; annotations listed will be put on the only parameter that the generated method has. @EqualsAndHashCode also supports onParam; the listed annotation(s) will be placed on the single parameter of the generated equals method, as well as any generated canEqual method. +

+ The syntax is a little strange and depends on the javac you are using.
+ On javac7, to use any of the 3 onX features, you must wrap the annotations to be applied to the constructor / method / parameter in @__(@AnnotationGoesHere). To apply multiple annotations, use @__({@Annotation1, @Annotation2}). The annotations can themselves obviously have parameters as well.
+ On javac8 and up, you add an underscore after onMethod, onParam, or onConstructor. +

With Lombok

@HTML_PRE@

Vanilla Java

@HTML_POST@

Small print

+ The reason of the weird syntax is to make this feature work in javac 7 compilers; the @__ type is an annotation reference to the annotation type __ (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 __ type. Instead, lombok applies the annotations and removes the references so that the error will never actually occur. The point is: The __ type must not exist, otherwise the feature does not work. In the rare case that the __ 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. +

+ 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. +

+ 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. +

+ The onX parameter is not legal on any type-wide variant. For example, a @Getter annotation on a class does not support onMethod. +

+ +

+ + + diff --git a/website-old/features/experimental/var.html b/website-old/features/experimental/var.html new file mode 100644 index 00000000..dde9c35e --- /dev/null +++ b/website-old/features/experimental/var.html @@ -0,0 +1,83 @@ + + + + + + + + EXPERIMENTAL – @var +

+ +

@var

Modifiable local variables with a type inferred by assigning value.

Since

+ @var was introduced as experimental feature in lombok v1.16.12. +

Experimental

+ Experimental because: +

This feature is very controversial.
There is JEP 286 that should make the @var obsolete.

Current status: uncertain - Currently we feel this feature cannot move out of experimental status. +

Overview

+ The @var has the same mission as the @val annotation but modifable. +

With Lombok

@HTML_PRE@

Vanilla Java

@HTML_POST@

Supported configuration keys:

lombok.val.flagUsage = [allow] (default: not set): Lombok will flag any usage of var as an error if not configured.

Small print

+ For compound types, the most common superclass is inferred, not any shared interfaces. For example, bool ? new HashSet() : new ArrayList() + is an expression with a compound type: The result is both AbstractCollection as well as Serializable. The type inferred will be + AbstractCollection, as that is a class, whereas Serializable is an interface. +

+ In ambiguous cases, java.lang.Object is inferred. +

+ +

+ + + -- cgit