From 599b6aab677439ae1bdea2cdca3233d0b763fd3f Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Mon, 17 Oct 2016 23:09:21 +0200 Subject: Updated just about all of the pages to the template-based redesign. Added ajaxified loading for feature pages. --- .../templates/features/experimental/Accessors.html | 75 ++++++++++++++++++++ .../templates/features/experimental/Delegate.html | 59 ++++++++++++++++ .../features/experimental/ExtensionMethod.html | 67 ++++++++++++++++++ .../features/experimental/FieldDefaults.html | 48 +++++++++++++ .../templates/features/experimental/Helper.html | 52 ++++++++++++++ .../features/experimental/UtilityClass.html | 42 +++++++++++ .../templates/features/experimental/Wither.html | 66 ++++++++++++++++++ .../templates/features/experimental/index.html | 81 ++++++++++++++++++++++ website2/templates/features/experimental/onX.html | 57 +++++++++++++++ 9 files changed, 547 insertions(+) create mode 100644 website2/templates/features/experimental/Accessors.html create mode 100644 website2/templates/features/experimental/Delegate.html create mode 100644 website2/templates/features/experimental/ExtensionMethod.html create mode 100644 website2/templates/features/experimental/FieldDefaults.html create mode 100644 website2/templates/features/experimental/Helper.html create mode 100644 website2/templates/features/experimental/UtilityClass.html create mode 100644 website2/templates/features/experimental/Wither.html create mode 100644 website2/templates/features/experimental/index.html create mode 100644 website2/templates/features/experimental/onX.html (limited to 'website2/templates/features/experimental') diff --git a/website2/templates/features/experimental/Accessors.html b/website2/templates/features/experimental/Accessors.html new file mode 100644 index 00000000..97017dc6 --- /dev/null +++ b/website2/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> +

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

+ + + <@f.experimental> + + Current status: positive - Currently we feel this feature may move out of experimental status with no or minor changes soon. + + + <@f.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: +

+

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

+ + + <@f.snippets name="experimental/Accessors" /> + + <@f.confKeys> +
+ 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. +
+ + + <@f.smallPrint> +

+ 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/website2/templates/features/experimental/Delegate.html b/website2/templates/features/experimental/Delegate.html new file mode 100644 index 00000000..265c754a --- /dev/null +++ b/website2/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> +

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

+ + + <@f.experimental> + + 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. + + + <@f.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). +

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

+ 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/website2/templates/features/experimental/ExtensionMethod.html b/website2/templates/features/experimental/ExtensionMethod.html new file mode 100644 index 00000000..ca63bb2e --- /dev/null +++ b/website2/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> +

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

+ + + <@f.experimental> + + Current status: hold - 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.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! +

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

+ 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/website2/templates/features/experimental/FieldDefaults.html b/website2/templates/features/experimental/FieldDefaults.html new file mode 100644 index 00000000..77ed37b6 --- /dev/null +++ b/website2/templates/features/experimental/FieldDefaults.html @@ -0,0 +1,48 @@ +<#import "../_features.html" as f> + +<@f.scaffold title="@FieldDefaults" logline="New default field modifiers for the 21st century."> + <@f.history> +

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

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

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

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

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

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

+ 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/website2/templates/features/experimental/Helper.html b/website2/templates/features/experimental/Helper.html new file mode 100644 index 00000000..93b6e2b4 --- /dev/null +++ b/website2/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> +

+ @Helper was introduced as an experimental feature in lombok v1.16.6. +

+ + + <@f.experimental> + + Current status: unknown - We don't have enough experience with this feature to make predictions on its future. + + + <@f.overview> +

+ 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 @Helper comes in and helps you out! Annotate a method local class with @Helper 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. +

+ Normally you'd have to declare an instance of your helper, for example: HelperClass h = new HelperClass(); directly after declaring your helper class, and then call methods in your helper class with h.helperMethod();. With @Helper, 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 nameOfHelperInstance. +

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

+ @Helper requires that the helper class has a no-args constructor. A compiler error will be generated if this is not the case. +

+ Currently, the instance of your helper that's made under the hood is called $Foo, where Foo 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. +

+ Please don't rely on this making any sense in the helper method code. You can refer to the real 'this' by using the syntax NameOfMyClass.this. +

+ ANY unqualified method call in code that exists below 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. +

+ Unless you're using JDK8 or higher (which introduced the concept of 'effectively final'), you'll have to declare local variables and parameters as final if you wish to refer to them in your method local class. This is a java limitation, not something specific to lombok's @Helper. +

+ + diff --git a/website2/templates/features/experimental/UtilityClass.html b/website2/templates/features/experimental/UtilityClass.html new file mode 100644 index 00000000..8145437a --- /dev/null +++ b/website2/templates/features/experimental/UtilityClass.html @@ -0,0 +1,42 @@ +<#import "../_features.html" as f> + +<@f.scaffold title="@UtilityClass" logline="Utility, metility, wetility! Utility classes for the masses."> + <@f.history> +

+ @UtilityClass was introduced as an experimental feature in lombok v1.16.2. +

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

+ 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, java.lang.Math and java.util.Collections are well known utility classes. This annotation automatically turns the annotated class into one. +

+ A utility class cannot be instantiated. By marking your class with @UtilityClass, lombok will automatically generate a private constructor that throws an exception, flags as error any explicit constructors you add, and marks the class final. If the class is an inner class, the class is also marked static. +

+ All members of a utility class are automatically marked as static. Even fields and inner classes. +

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

+ 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, @UtilityClass cannot be used. +

+ + diff --git a/website2/templates/features/experimental/Wither.html b/website2/templates/features/experimental/Wither.html new file mode 100644 index 00000000..9642458b --- /dev/null +++ b/website2/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> +

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

+ + + <@f.experimental> + + Current status: neutral - More feedback requires on the items in the above list before promotion to the main package is warranted. + + + <@f.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). +

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

+ 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/website2/templates/features/experimental/index.html b/website2/templates/features/experimental/index.html new file mode 100644 index 00000000..257c0382 --- /dev/null +++ b/website2/templates/features/experimental/index.html @@ -0,0 +1,81 @@ +<#import "../../_scaffold.html" as main> +<#import "../_features.html" as f> + +<@main.scaffold> +
+
+

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 doesn't 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. +

+
+
+ <@main.feature title="@Accessors" code="/features/experimental/Accessors"> + A more fluent API for getters and setters. + + + <@main.feature title="@ExtensionMethod" code="/features/experimental/ExtensionMethod"> + Annoying API? Fix it yourself: Add new methods to existing types! + + + <@main.feature title="@FieldDefaults" code="/features/experimental/FieldDefaults"> + New default field modifiers for the 21st century. + + + <@main.feature title="@Delegate" code="/features/experimental/Delegate"> + Don't lose your composition. + + + <@main.feature title="@Wither" code="/features/experimental/Wither"> + Immutable 'setters' - methods that create a clone but with one changed field. + + + <@main.feature title="onMethod= / onConstructor= / onParam=" code="/features/experimental/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 title="@UtilityClass" code="/features/experimental/UtilityClass"> + Utility, metility, wetility! Utility classes for the masses. + + + <@main.feature title="@Helper" code="/features/experimental/Helper"> + With a little help from my friends... Helper methods for java. + +
+ + <@f.confKeys> +
+ 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.

+
+ <@main.feature title="@Value: promoted" code="/features/Value"> + @Value has proven its value and has been moved to the main package. + + <@main.feature title="@Builder: promoted" code="/features/Builder"> + @Builder is a solid base to build APIs on, and has been moved to the main package. + +
+
+
+ diff --git a/website2/templates/features/experimental/onX.html b/website2/templates/features/experimental/onX.html new file mode 100644 index 00000000..7398ce70 --- /dev/null +++ b/website2/templates/features/experimental/onX.html @@ -0,0 +1,57 @@ +<#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> +

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

+ + + <@f.experimental> + + Current status: uncertain - Currently we feel this feature cannot move out of experimental status. + + + <@f.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; 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. +

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

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

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

+ + -- cgit