diff options
Diffstat (limited to 'website')
22 files changed, 258 insertions, 37 deletions
diff --git a/website/extra/htaccess b/website/extra/htaccess index db3393af..2d5b6b2a 100644 --- a/website/extra/htaccess +++ b/website/extra/htaccess @@ -22,8 +22,6 @@ RewriteRule ^all-versions$ /all-versions.html [L,END] RewriteRule ^all-versions(\.html)?$ /all-versions [NC,R=301] RewriteRule ^disable-checked-exceptions$ /disable-checked-exceptions.html [L,END] RewriteRule ^disable-checked-exceptions(\.html)?$ /disable-checked-exceptions [NC,R=301] -RewriteRule ^contributing$ /contributing.html [L,END] -RewriteRule ^contributing(\.html)?$ /contributing [NC,R=301] RewriteRule ^supporters$ /supporters.html [L,END] RewriteRule ^supporters(.html)?$ /supporters [NC,R=301] RewriteRule ^order-license-info$ /order-license-info.html [L,END] @@ -31,6 +29,14 @@ RewriteRule ^order-?license-?info(.html)?$ /order-license-info [NC,R=301] RewriteRule ^order-license$ /order-license.html [L,END] RewriteRule ^order-?license(.html)?$ /order-license [NC,R=301] +RewriteRule ^contributing/index$ /contributing/index.html [L,END] +RewriteRule ^contributing(\.html)?$ /contributing/index [NC,R=301] +RewriteRule ^contributing/index(\.html)?$ /contributing/index [NC,R=301] +RewriteRule ^contributing/contributing$ /contributing/contributing.html [L,END] +RewriteRule ^contributing/contributing(\.html)?$ /contributing/contributing [NC,R=301] +RewriteRule ^contributing/lombok-execution-path$ /contributing/lombok-execution-path.html [L,END] +RewriteRule ^contributing/lombok-execution-path(\.html)?$ /contributing/lombok-execution-path [NC,R=301] + <#list setupPages as pg> RewriteRule ^setup/${pg?no_esc}$ /setup/${pg?no_esc}.html [L,END] RewriteRule ^setup/${pg?no_esc}(\.html)?$ /setup/${pg?no_esc} [NC,R=301] diff --git a/website/resources/js/supporters.js b/website/resources/js/supporters.js index 07319226..58db28cc 100644 --- a/website/resources/js/supporters.js +++ b/website/resources/js/supporters.js @@ -26,7 +26,7 @@ function toDate(s) { var x = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s); - if (x) return new Date(parseInt(x[1]), parseInt(x[2]), parseInt(x[3])); + if (x) return new Date(parseInt(x[1]), parseInt(x[2]) - 1, parseInt(x[3])); return null; } diff --git a/website/templates/_scaffold.html b/website/templates/_scaffold.html index 8bb22635..7acfb6b6 100644 --- a/website/templates/_scaffold.html +++ b/website/templates/_scaffold.html @@ -43,10 +43,12 @@ <title>${title}</title> - <script src="//cdnjs.cloudflare.com/ajax/libs/modernizr/2.8.3/modernizr.min.js"></script> + <script src="//cdnjs.cloudflare.com/ajax/libs/modernizr/2.8.3/modernizr.min.js" + integrity="sha384-bPV3mA2eo3edoq56VzcPBmG1N1QVUfjYMxVIJPPzyFJyFZ8GFfN7Npt06Zr23qts" crossorigin="anonymous"></script> <link href="/css/bootstrap.css" rel="stylesheet" /> - <link href="//maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css" rel="stylesheet" /> + <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css" + integrity="sha384-CmLV3WR+cw/TcN50vJSYAs2EAzhDD77tQvGcmoZ1KEzxtpl2K5xkrpFz9N2H9ClN" crossorigin="anonymous"> <link href="/css/custom.css" rel="stylesheet" /> @@ -55,8 +57,10 @@ <link href="${ld?url_path}" rel="stylesheet" /> </#if> </#list> - <script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script> - <script src="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.2.0/js/bootstrap.min.js"></script> + <script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js" + integrity="sha384-Pn+PczAsODRZ2PiGg0IheRROpP7lXO1NTIjiPo6cca8TliBvaeil42fobhzvZd74" crossorigin="anonymous"></script> + <script src="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.2.0/js/bootstrap.min.js" + integrity="sha384-VI5+XuguQ/l3kUhh4knz7Hxptx47wpQbVRDnp8v7Vvuhzwn1PEYb/uvtH6KLxv6d" crossorigin="anonymous"></script> <script src="/js/history.js"></script> <script src="/js/main.js"></script> @@ -98,7 +102,7 @@ ga('send', 'pageview'); <ul class="dropdown-menu" aria-labelledby="themes"> <li><a href="https://groups.google.com/group/project-lombok" rel="noopener">Discuss / Help</a></li> <li><a href="https://github.com/rzwitserloot/lombok/issues" rel="noopener">Issues</a></li> - <li><a href="/contributing">Contribute</a></li> + <li><a href="/contributing/index">Documentation for contributors</a></li> </ul> </li> <li> diff --git a/website/templates/contributing.html b/website/templates/contributing/contributing.html index 16d68f32..8da9b827 100644 --- a/website/templates/contributing.html +++ b/website/templates/contributing/contributing.html @@ -1,4 +1,4 @@ -<#import "/_scaffold.html" as main> +<#import "../_scaffold.html" as main> <@main.scaffold title="Contribute"> <div class="page-header top5"> diff --git a/website/templates/contributing/index.html b/website/templates/contributing/index.html new file mode 100644 index 00000000..4f6a1bca --- /dev/null +++ b/website/templates/contributing/index.html @@ -0,0 +1,17 @@ +<#import "../_scaffold.html" as main> + +<@main.scaffold title="Documentation for being a lombok developer"> + <div class="page-header top5"> + <div class="row text-center"> + <@main.h1 title="Documentation for lombok developers" /> + </div> + <div class="row"> + <@main.feature title="contributing" href="contributing"> + Want to contribute to Project Lombok? Start by reading this introduction. + </@main.feature> + <@main.feature title="execution path" href="lombok-execution-path"> + Discusses how lombok ends up being invoked, and how it gets around to transforming code being compiled / edited. + </@main.feature> + </div> + </div> +</@main.scaffold> diff --git a/website/templates/contributing/lombok-execution-path.html b/website/templates/contributing/lombok-execution-path.html new file mode 100644 index 00000000..1fa2f697 --- /dev/null +++ b/website/templates/contributing/lombok-execution-path.html @@ -0,0 +1,45 @@ +<#import "../_scaffold.html" as main> + +<@main.scaffold title="Lombok Execution Path"> + <div class="page-header top5"> + <div class="row text-center"> + <@main.h1 title="Lombok Execution Path" /> + </div><div class="row text-center"> + <@main.h1 title="Javac: Launching as annotation processor" /> + </div><div class="row"> + <p> + With <code>javac</code> (and netbeans, maven, gradle, and most other build systems), lombok runs as an annotation processor. + </p><p> + Lombok is on the classpath, and <code>javac</code> will load every <code>META-INF/services/javax.annotation.processing.Processor</code> file on the classpath it can find, reading each line and loading that class, then executing it as an annotation processor. <code>lombok.jar</code> has this file, it lists <code>lombok.launch.AnnotationProcessorHider$AnnotationProcessor</code> as entry. + </p><p> + This class is not actually visible (it is public, but its outer class (<code>AnnotationProcessorHider</code>) is package private, making it invisible to java-the-language), however, it is considered visible for the purposes of java-the-VM and therefore it will run. This convoluted trick is used to ensure that anybody who develops with lombok on the classpath doesn't get lombok's classes or lombok's dependencies injected into their 'namespace' (for example, if you add lombok to your project, your IDE will <em>not</em> start suggesting lombok classes for auto-complete dialogs). + </p><p> + The <code>lombok.launch.AnnotationProcessorHider$AnnotationProcessor</code> class is loaded by <code>javac</code>, instantiated, and <code>init()</code> is called on it. This class starts lombok's <code>ShadowClassLoader</code>; it finds the jar file it is in, then will start loading classes from this jar file. It looks not for files ending in <code>.class</code> like normal loaders, it looks for files ending in <code>.SCL.lombok</code> instead (this too is for the purpose of hiding lombok's classes from IDEs and such). Via this classloader, the <em>real</em> annotation processor is launched, which is class <code>lombok.core.AnnotationProcessor</code>. + </p><p> + The <code>lombok.core.AnnotationProcessor</code> is also a delegating processor. It can delegate to one of 2 sub-processors based on the environment lombok finds itself in: If it's javac, class <code>lombok.javac.apt.LombokProcessor</code> is used (and if the plexus compiler framework is used, which can be the case when compiling with javac, some extra code runs to patch lombok into its modular classloading architecture). If it's ecj (eclipse's compiler, which means we're either running inside eclipse itself, or being invoked as annotation processor for ecj, the standalone eclipse compiler), errors/warnings are injected into the compilation process to tell the user they should use different parameters to <a href="/setup/ecj">use lombok in eclipse/ecj</a>. + </p><p> + <code>lombok.javac.apt.LombokProcessor</code> is the 'real' annotation processor that does the work of transforming your code. + </p><p> + code transformation is fundamentally a cyclic concept: To generate some code you want to know about the code (which annotations are in it, for example), but when you generate new code, interpreting it means we start over. The same applies to lombok itself: Some of lombok's transformations add methods which then have an effect on other lombok transformations. Because of that, lombok divides up the handlers into 'levels'. All handlers at the highest level are executed, then a new annotation round is forced (which integrates generated stuff into the symbol tables and such), and then the handlers at the next level are executed. These levels are indicated via the <code>@HandlerPriority</code> annotation. You force javac to run another round by generating a file. We don't actually want to generate any files, so we generate a dummy file and patch the javac <em>filer</em> to not actually save lombok-generated dummy files anywhere. The various <code>HandleX</code> classes, which apply the actual lombok transformations, are stored in <code>HandlerLibrary</code> which uses SPI to discover the handle classes. + </p> + </div><div class="row text-center"> + <@main.h1 title="Eclipse/ECJ: Launching as agent" /> + </div><div class="row"> + <p> + With <code>ecj</code> and <code>eclipse</code>, lombok starts as an 'agent'. That's a bit like a debugger: It lets lombok inspect raw class bytecode <em>before</em> the JVM actually loads these classes, and lombok will modify this code in order to ensure that ecj/eclipse involves lombok in the compilation process. + </p><p> + The patching of classes is done by the code in the <code>src/eclipseAgent</code> sourcedir. Note that the patching code has to patch equinox, the eclipse module system, to ensure lombok and the java compilation module (The 'JDT' module, in eclipse parlance) can see each other. + </p><p> + A bunch of ad-hoc fixes to issues (such as the eclipse format-my-code feature needing a few tactical bytecode patches to ensure it doesn't mess up formatting source) are applied, but the main 'run lombok as part of the compilation process' hook injected into ecj/eclipse leads to the <code>lombok.eclipse.TransformEclipseAST</code> class, which can be considered the entrypoint. Unless you want to mess with how lombok is loaded into eclipse/ecj, start there. + </p><p> + Each <code>HandleX</code> class is discovered via SPI and lombok will invoke the handle classes as needed. Handle classes find lombok annotations and apply the desired transformations. The handlers are in the <code>lombok.eclipse.handlers</code> package from the <code>src/core</code> sourcedir. + </p> + </div><div class="row text-center"> + <@main.h1 title="VSCode and IntelliJ: Launching as a plugin" /> + </div><div class="row"> + <p> + Lombok support in these two IDEs is taken care of by plugins for these IDEs. + </p> + </div> + </div> +</@main.scaffold> diff --git a/website/templates/features/EqualsAndHashCode.html b/website/templates/features/EqualsAndHashCode.html index 3c11367f..5a7b8166 100644 --- a/website/templates/features/EqualsAndHashCode.html +++ b/website/templates/features/EqualsAndHashCode.html @@ -3,7 +3,7 @@ <@f.scaffold title="@EqualsAndHashCode" logline="Equality made easy: Generates <code>hashCode</code> and <code>equals</code> implementations from the fields of your object."> <@f.overview> <p> - Any class definition may be annotated with <code>@EqualsAndHashCode</code> to let lombok generate implementations of the <code>equals(Object other)</code> and <code>hashCode()</code> methods. By default, it'll use all non-static, non-transient fields, but you can exclude more fields by naming them in the optional <code>exclude</code> parameter to the annotation. Alternatively, you can specify exactly which fields you wish to be used by naming them in the <code>of</code> parameter. + Any class definition may be annotated with <code>@EqualsAndHashCode</code> to let lombok generate implementations of the <code>equals(Object other)</code> and <code>hashCode()</code> methods. By default, it'll use all non-static, non-transient fields, but you can modify which fields are used (and even specify that the output of various methods is to be used) by marking type members with <code>@EqualsAndHashCode.Include</code> or <code>@EqualsAndHashCode.Exclude</code>. Alternatively, you can specify exactly which fields or methods you wish to be used by marking them with <code>@EqualsAndHashCode.Include</code> and using <code>@EqualsAndHashCode(onlyExplicitlyIncluded = true)</code>. </p><p> If applying <code>@EqualsAndHashCode</code> to a class that extends another, this feature gets a bit trickier. Normally, auto-generating an <code>equals</code> and <code>hashCode</code> method for such classes is a bad idea, as the superclass also defines fields, which also need equals/hashCode code but this code will not be generated. By setting <code>callSuper</code> to <em>true</em>, you can include the <code>equals</code> and <code>hashCode</code> methods of your superclass in the generated methods. For <code>hashCode</code>, the result of <code>super.hashCode()</code> is included in the hash algorithm, and for<code>equals</code>, the generated method will return false if the super implementation thinks it is not equal to the passed in object. Be aware that not all <code>equals</code> implementations handle this situation properly. However, lombok-generated <code>equals</code> implementations <strong>do</strong> handle this situation properly, so you can safely call your superclass equals if it, too, has a lombok-generated <code>equals</code> method. If you have an explicit superclass you are forced to supply some value for <code>callSuper</code> to acknowledge that you've considered it; failure to do so results in a warning. </p><p> @@ -43,11 +43,13 @@ </p><p> If there is <em>any</em> method named either <code>hashCode</code> or <code>equals</code>, regardless of return type, no methods will be generated, and a warning is emitted instead. These 2 methods need to be in sync with each other, which lombok cannot guarantee unless it generates all the methods, hence you always get a warning if one <em>or</em> both of the methods already exist. You can mark any method with <code>@lombok.experimental.Tolerate</code> to hide them from lombok. </p><p> - Attempting to exclude fields that don't exist or would have been excluded anyway (because they are static or transient) results in warnings on the named fields. You therefore don't have to worry about typos. + Attempting to exclude fields that don't exist or would have been excluded anyway (because they are static or transient) results in warnings on the named fields. </p><p> - Having both <code>exclude</code> and <code>of</code> generates a warning; the <code>exclude</code> parameter will be ignored in that case. + If a method is marked for inclusion and it has the same name as a field, it replaces the field (the method is included, the field is excluded). </p><p> - By default, any variables that start with a $ symbol are excluded automatically. You can onlyinclude them by using the 'of' parameter. + Prior to lombok 1.16.22, inclusion/exclusion could be done with the <code>of</code> and <code>exclude</code> parameters of the <code>@EqualsAndHashCode</code> annotation. This old-style inclusion mechanism is still supported but will be deprecated in the future. + </p><p> + By default, any variables that start with a $ symbol are excluded automatically. You can only include them by marking them with <code>@EqualsAndHashCode.Include</code>. </p><p> If a getter exists for a field to be included, it is called instead of using a direct field reference. This behaviour can be suppressed:<br /> <code>@EqualsAndHashCode(doNotUseGetters = true)</code> diff --git a/website/templates/features/NonNull.html b/website/templates/features/NonNull.html index 28d083d0..3d99a3c7 100644 --- a/website/templates/features/NonNull.html +++ b/website/templates/features/NonNull.html @@ -11,7 +11,7 @@ </p><p> Lombok has always treated any annotation named <code>@NonNull</code> on a field as a signal to generate a null-check if lombok generates an entire method or constructor for you, via for example <a href="/features/Data"><code>@Data</code></a>. Now, however, using lombok's own <code>@lombok.NonNull</code> on a parameter results in the insertion of just the null-check statement inside your own method or constructor. </p><p> - The null-check looks like <code>if (param == null) throw new NullPointerException("param");</code> and will be inserted at the very top of your method. For constructors, the null-check will be inserted immediately following any explicit <code>this()</code> or <code>super()</code> calls. + The null-check looks like <code>if (param == null) throw new NullPointerException("param is marked @NonNull but is null");</code> and will be inserted at the very top of your method. For constructors, the null-check will be inserted immediately following any explicit <code>this()</code> or <code>super()</code> calls. </p><p> If a null-check is already present at the top, no additional null-check will be generated. </p> @@ -23,7 +23,7 @@ <dt> <code>lombok.nonNull.exceptionType</code> = [<code>NullPointerException</code> | <code>IllegalArgumentException</code>] (default: <code>NullPointerException</code>). </dt><dd> - When lombok generates a null-check <code>if</code> statement, by default, a <code>java.lang.NullPointerException</code> will be thrown with the field name as the exception message. However, you can use <code>IllegalArgumentException</code> in this configuration key to have lombok throw that exception, with '<em>fieldName</em> is null' as exception message. + When lombok generates a null-check <code>if</code> statement, by default, a <code>java.lang.NullPointerException</code> will be thrown with '<em>field name</em> is marked @NonNull but is null' as the exception message. However, you can use <code>IllegalArgumentException</code> in this configuration key to have lombok throw that exception with this message instead. </dd><dt> <code>lombok.nonNull.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) </dt><dd> diff --git a/website/templates/features/ToString.html b/website/templates/features/ToString.html index 6f230561..d31cf35d 100644 --- a/website/templates/features/ToString.html +++ b/website/templates/features/ToString.html @@ -7,9 +7,13 @@ </p><p> By setting the <code>includeFieldNames</code> parameter to <em>true</em> you can add some clarity (but also quite some length) to the output of the <code>toString()</code> method. </p><p> - By default, all non-static fields will be printed. If you want to skip some fields, you can name them in the <code>exclude</code> parameter; each named field will not be printed at all. Alternatively, you can specify exactly which fields you wish to be used by naming them in the <code>of</code> parameter. + By default, all non-static fields will be printed. If you want to skip some fields, you can annotate these fields with <code>@ToString.Exclude</code>. Alternatively, you can specify exactly which fields you wish to be used by using <code>@ToString(onlyExplicitlyIncluded = true)</code>, then marking each field you want to include with <code>@ToString.Include</code>. </p><p> By setting <code>callSuper</code> to <em>true</em>, you can include the output of the superclass implementation of <code>toString</code> to the output. Be aware that the default implementation of <code>toString()</code> in <code>java.lang.Object</code> is pretty much meaningless, so you probably don't want to do this unless you are extending another class. + </p><p> + You can also include the output of a method call in your <code>toString</code>. Only instance (non-static) methods that take no arguments can be included. To do so, mark the method with <code>@ToString.Include</code>. + </p><p> + You can change the name used to identify the member with <code>@ToString.Include(name = "some other name")</code>, and you can change the order in which the members are printed via <code>@ToString.Include(rank = -1)</code>. Members without a rank are considered to have rank 0, members of a higher rank are printed first, and members of the same rank are printed in the same order they appear in the source file. </p> </@f.overview> @@ -37,13 +41,15 @@ </p><p> Arrays are printed via <code>Arrays.deepToString</code>, which means that arrays that contain themselves will result in <code>StackOverflowError</code>s. However, this behaviour is no different from e.g. <code>ArrayList</code>. </p><p> - Attempting to exclude fields that don't exist or would have been excluded anyway (because they are static) results in warnings on the named fields. You therefore don't have to worry about typos. + If a method is marked for inclusion and it has the same name as a field, it replaces the toString output for that field (the method is included, the field is excluded, and the method's output is printed in the place the field would be printed). + </p><p> + Prior to lombok 1.16.22, inclusion/exclusion could be done with the <code>of</code> and <code>exclude</code> parameters of the <code>@ToString</code> annotation. This old-style inclusion mechanism is still supported but will be deprecated in the future. </p><p> - Having both <code>exclude</code> and <code>of</code> generates a warning; the <code>exclude</code> parameter will be ignored in that case. + Having both <code>@ToString.Exclude</code> and <code>@ToString.Include</code> on a member generates a warning; the member will be excluded in this case. </p><p> We don't promise to keep the output of the generated <code>toString()</code> methods the same between lombok versions. You should never design your API so that other code is forced to parse your <code>toString()</code> output anyway! </p><p> - By default, any variables that start with a $ symbol are excluded automatically. You can only include them by using the 'of' parameter. + By default, any variables that start with a $ symbol are excluded automatically. You can only include them by using the <code>@ToString.Include</code> annotation. </p><p> If a getter exists for a field to be included, it is called instead of using a direct field reference. This behaviour can be suppressed:<br /> <code>@ToString(doNotUseGetters = true)</code> diff --git a/website/templates/features/experimental/FieldNameConstants.html b/website/templates/features/experimental/FieldNameConstants.html new file mode 100644 index 00000000..c5e57195 --- /dev/null +++ b/website/templates/features/experimental/FieldNameConstants.html @@ -0,0 +1,54 @@ +<#import "../_features.html" as f> + +<@f.scaffold title="@FieldNameConstants" logline="Name... that... field! String constants for your field's names."> + <@f.history> + <p> + @FieldNameConstants was introduced as experimental feature in lombok v1.16.22. + </p> + </@f.history> + + <@f.experimental> + <ul> + <li> + New feature; unsure if this busts enough boilerplate. + </li> + </ul> + Current status: <em>neutral</em> - As a just-introduced feature we're still gathering feedback. + </@f.experimental> + + <@f.overview> + <p> + The <code>@FieldNameConstants</code> annotation generates string constants (fields marked <code>public static final</code>, of type <code>java.lang.String</code>) containing the field's name, as a string. This is useful for various marshalling and serialization frameworks. The constant field by default is named <code>FIELD_<em>NAME_OF_FIELD</em></code>, where <em>NAME_OF_FIELD</em> is the same name as the field it represents, except with all uppercase letters, with underscores in front of the uppercase letters in the original field. The prefix (and suffix) is configurable on the <code>@FieldNameConstants</code> annotation. + </p><p> + The <code>public</code> access modifier can be changed via the parameter <code>level = AccessLevel.PACKAGE</code> for example. You can force a field to be skipped by supplying <code>level = AccessLevel.NONE</code>. + </p><p> + Can be applied to classes (in which case every field gets a constant), or to an individual field. + </p> + </@f.overview> + + <@f.snippets name="experimental/FieldNameConstants" /> + + <@f.confKeys> + <dt> + <code>lombok.fieldNameConstants.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.fieldNameConstants.prefix</code> = <em>a string</em> (default: 'PREFIX_') + </dt><dd> + Lombok will generate the name for each fieldconstant by constant-casing the field name and then prefixing this string to the result. + </dd><dt> + <code>lombok.fieldNameConstants.suffix</code> = <em>a string</em> (default: '' - the blank string) + </dt><dd> + Lombok will generate the name for each fieldconstant by constant-casing the field name and then suffixing this string to the result. + </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. Static fields are also skipped. + </p><p> + The annotation can itself be used to set prefix/suffix. If you do so, it overrides the <code>lombok.fieldNameConstants.prefix/suffix</code> config key. Example: <code>@FieldNameConstants(prefix = "")</code>: This would generate for field <code>helloWorld</code> a constant named <code>HELLO_WORLD</code> instead of the default <code>FIELD_HELLO_WORLD</code>. + </p> + </@f.smallPrint> +</@f.scaffold> diff --git a/website/templates/features/experimental/index.html b/website/templates/features/experimental/index.html index 988a7154..ba830ab5 100644 --- a/website/templates/features/experimental/index.html +++ b/website/templates/features/experimental/index.html @@ -63,6 +63,10 @@ With a little help from my friends... Helper methods for java. </@main.feature> + <@main.feature title="@FieldNameConstants" href="FieldNameConstants"> + Name... that... field! String constants for your field's names. + </@main.feature> + <@main.feature title="@SuperBuilder" href="SuperBuilder"> Bob now knows his ancestors: Builders with fields from superclasses, too. </@main.feature> diff --git a/website/templates/features/log.html b/website/templates/features/log.html index 2854e896..1de26836 100644 --- a/website/templates/features/log.html +++ b/website/templates/features/log.html @@ -6,6 +6,8 @@ The various <code>@Log</code> variants were added in lombok v0.10. <em>NEW in lombok 0.10: </em>You can annotate any class with a log annotation to let lombok generate a logger field.<br/> The logger is named <code>log</code> and the field's type depends on which logger you have selected. + </p><p> + <em>NEW in lombok v1.16.24: </em>Addition of google's FluentLogger (flogger). </p> </@f.history> @@ -20,13 +22,17 @@ </dt><dd> Creates <code><span class="keyword">private static final </span><a href="https://commons.apache.org/logging/apidocs/org/apache/commons/logging/Log.html">org.apache.commons.logging.Log</a> <span class="staticfield">log</span> = <a href="https://commons.apache.org/logging/apidocs/org/apache/commons/logging/LogFactory.html#getLog(java.lang.Class)">org.apache.commons.logging.LogFactory.getLog</a>(LogExample.<span class="keyword">class</span>);</code> </dd><dt> + <code>@Flogger</code> + </dt><dd> + Creates <code><span class="keyword">private static final </span><a href="https://google.github.io/flogger/">com.google.common.flogger.FluentLogger</a> <span class="staticfield">log</span> = com.google.common.flogger.FluentLogger.forEnclosingClass();</code> + </dd><dt> <code>@JBossLog</code> </dt><dd> - Creates <code><span class="keyword">private static final </span><a href="http://docs.jboss.org/jbosslogging/latest/org/jboss/logging/Logger.html">org.jboss.logging.Logger</a> <span class="staticfield">log</span> = <a href="http://docs.jboss.org/jbosslogging/latest/org/jboss/logging/Logger.html#getLogger(java.lang.Class)">org.jboss.logging.Logger.getLogger</a>(LogExample.<span class="keyword">class</span>);</code> + Creates <code><span class="keyword">private static final </span><a href="https://docs.jboss.org/jbosslogging/latest/org/jboss/logging/Logger.html">org.jboss.logging.Logger</a> <span class="staticfield">log</span> = <a href="https://docs.jboss.org/jbosslogging/latest/org/jboss/logging/Logger.html#getLogger(java.lang.Class)">org.jboss.logging.Logger.getLogger</a>(LogExample.<span class="keyword">class</span>);</code> </dd><dt> <code>@Log</code> </dt><dd> - Creates <code><span class="keyword">private static final </span><a href="http://download.oracle.com/javase/6/docs/api/java/util/logging/Logger.html">java.util.logging.Logger</a> <span class="staticfield">log</span> = <a href="http://download.oracle.com/javase/6/docs/api/java/util/logging/Logger.html#getLogger(java.lang.String)">java.util.logging.Logger.getLogger</a>(LogExample.<span class="keyword">class</span>.getName());</code> + Creates <code><span class="keyword">private static final </span><a href="https://docs.oracle.com/javase/6/docs/api/java/util/logging/Logger.html">java.util.logging.Logger</a> <span class="staticfield">log</span> = <a href="https://docs.oracle.com/javase/6/docs/api/java/util/logging/Logger.html#getLogger(java.lang.String)">java.util.logging.Logger.getLogger</a>(LogExample.<span class="keyword">class</span>.getName());</code> </dd><dt> <code>@Log4j</code> </dt><dd> @@ -38,11 +44,11 @@ </dd><dt> <code>@Slf4j</code> </dt><dd> - Creates <code><span class="keyword">private static final </span><a href="http://www.slf4j.org/api/org/slf4j/Logger.html">org.slf4j.Logger</a> <span class="staticfield">log</span> = <a href="http://www.slf4j.org/apidocs/org/slf4j/LoggerFactory.html#getLogger(java.lang.Class)">org.slf4j.LoggerFactory.getLogger</a>(LogExample.<span class="keyword">class</span>);</code> + Creates <code><span class="keyword">private static final </span><a href="https://www.slf4j.org/api/org/slf4j/Logger.html">org.slf4j.Logger</a> <span class="staticfield">log</span> = <a href="https://www.slf4j.org/api/org/slf4j/LoggerFactory.html#getLogger(java.lang.Class)">org.slf4j.LoggerFactory.getLogger</a>(LogExample.<span class="keyword">class</span>);</code> </dd><dt> <code>@XSlf4j</code> </dt><dd> - Creates <code><span class="keyword">private static final </span><a href="http://www.slf4j.org/api/org/slf4j/ext/XLogger.html">org.slf4j.ext.XLogger</a> <span class="staticfield">log</span> = <a href="http://www.slf4j.org/apidocs/org/slf4j/ext/XLoggerFactory.html#getXLogger(java.lang.Class)">org.slf4j.ext.XLoggerFactory.getXLogger</a>(LogExample.<span class="keyword">class</span>);</code> + Creates <code><span class="keyword">private static final </span><a href="https://www.slf4j.org/api/org/slf4j/ext/XLogger.html">org.slf4j.ext.XLogger</a> <span class="staticfield">log</span> = <a href="https://www.slf4j.org/api/org/slf4j/ext/XLoggerFactory.html#getXLogger(java.lang.Class)">org.slf4j.ext.XLoggerFactory.getXLogger</a>(LogExample.<span class="keyword">class</span>);</code> </dd> </dl> </p><p> @@ -70,14 +76,18 @@ </dt><dd> Lombok will flag any usage of <code>@lombok.extern.apachecommons.CommonsLog</code> as a warning or error if configured. </dd><dt> - <code>lombok.log.javaUtilLogging.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) + <code>lombok.log.flogger.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) </dt><dd> - Lombok will flag any usage of <code>@lombok.extern.java.Log</code> as a warning or error if configured. + Lombok will flag any usage of <code>@lombok.extern.flogger.Flogger</code> as a warning or error if configured. </dd><dt> <code>lombok.log.jbosslog.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) </dt><dd> Lombok will flag any usage of <code>@lombok.extern.jbosslog.JBossLog</code> as a warning or error if configured. </dd><dt> + <code>lombok.log.javaUtilLogging.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) + </dt><dd> + Lombok will flag any usage of <code>@lombok.extern.java.Log</code> as a warning or error if configured. + </dd><dt> <code>lombok.log.log4j.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) </dt><dd> Lombok will flag any usage of <code>@lombok.extern.log4j.Log4j</code> as a warning or error if configured. diff --git a/website/usageExamples/BuilderExample_post.jpage b/website/usageExamples/BuilderExample_post.jpage index 54b064d7..24d326b3 100644 --- a/website/usageExamples/BuilderExample_post.jpage +++ b/website/usageExamples/BuilderExample_post.jpage @@ -1,6 +1,7 @@ import java.util.Set; public class BuilderExample { + private long created; private String name; private int age; private Set<String> occupations; @@ -11,11 +12,17 @@ public class BuilderExample { this.occupations = occupations; } + private static long $default$created() { + return System.currentTimeMillis(); + } + public static BuilderExampleBuilder builder() { return new BuilderExampleBuilder(); } public static class BuilderExampleBuilder { + private long created; + private boolean created$set; private String name; private int age; private java.util.ArrayList<String> occupations; @@ -23,6 +30,12 @@ public class BuilderExample { BuilderExampleBuilder() { } + public BuilderExampleBuilder created(long created) { + this.created = created; + this.created$set = true; + return this; + } + public BuilderExampleBuilder name(String name) { this.name = name; return this; @@ -61,14 +74,13 @@ public class BuilderExample { public BuilderExample build() { // complicated switch statement to produce a compact properly sized immutable set omitted. - // go to https://projectlombok.org/features/Singular-snippet.html to see it. Set<String> occupations = ...; - return new BuilderExample(name, age, occupations); + return new BuilderExample(created$set ? created : BuilderExample.$default$created(), name, age, occupations); } @java.lang.Override public String toString() { - return "BuilderExample.BuilderExampleBuilder(name = " + this.name + ", age = " + this.age + ", occupations = " + this.occupations + ")"; + return "BuilderExample.BuilderExampleBuilder(created = " + this.created + ", name = " + this.name + ", age = " + this.age + ", occupations = " + this.occupations + ")"; } } }
\ No newline at end of file diff --git a/website/usageExamples/BuilderExample_pre.jpage b/website/usageExamples/BuilderExample_pre.jpage index 1557fff4..3b1b0df2 100644 --- a/website/usageExamples/BuilderExample_pre.jpage +++ b/website/usageExamples/BuilderExample_pre.jpage @@ -4,6 +4,7 @@ import java.util.Set; @Builder public class BuilderExample { + @Builder.Default private long created = System.currentTimeMillis(); private String name; private int age; @Singular private Set<String> occupations; diff --git a/website/usageExamples/EqualsAndHashCodeExample_pre.jpage b/website/usageExamples/EqualsAndHashCodeExample_pre.jpage index 64faf59f..cf235917 100644 --- a/website/usageExamples/EqualsAndHashCodeExample_pre.jpage +++ b/website/usageExamples/EqualsAndHashCodeExample_pre.jpage @@ -1,13 +1,13 @@ import lombok.EqualsAndHashCode; -@EqualsAndHashCode(exclude={"id", "shape"}) +@EqualsAndHashCode public class EqualsAndHashCodeExample { private transient int transientVar = 10; private String name; private double score; - private Shape shape = new Square(5, 10); + @EqualsAndHashCode.Exclude private Shape shape = new Square(5, 10); private String[] tags; - private int id; + @EqualsAndHashCode.Exclude private int id; public String getName() { return this.name; diff --git a/website/usageExamples/NonNullExample_post.jpage b/website/usageExamples/NonNullExample_post.jpage index 24175e06..bb67b3f6 100644 --- a/website/usageExamples/NonNullExample_post.jpage +++ b/website/usageExamples/NonNullExample_post.jpage @@ -6,7 +6,7 @@ public class NonNullExample extends Something { public NonNullExample(@NonNull Person person) { super("Hello"); if (person == null) { - throw new NullPointerException("person"); + throw new NullPointerException("person is marked @NonNull but is null"); } this.name = person.getName(); } diff --git a/website/usageExamples/ToStringExample_pre.jpage b/website/usageExamples/ToStringExample_pre.jpage index a15fb944..1b6b58e0 100644 --- a/website/usageExamples/ToStringExample_pre.jpage +++ b/website/usageExamples/ToStringExample_pre.jpage @@ -1,15 +1,15 @@ import lombok.ToString; -@ToString(exclude="id") +@ToString public class ToStringExample { private static final int STATIC_VAR = 10; private String name; private Shape shape = new Square(5, 10); private String[] tags; - private int id; + @ToString.Exclude private int id; public String getName() { - return this.getName(); + return this.name; } @ToString(callSuper=true, includeFieldNames=true) diff --git a/website/usageExamples/experimental/FieldNameConstantsExample_post.jpage b/website/usageExamples/experimental/FieldNameConstantsExample_post.jpage new file mode 100644 index 00000000..67d89891 --- /dev/null +++ b/website/usageExamples/experimental/FieldNameConstantsExample_post.jpage @@ -0,0 +1,7 @@ +public class FieldNameConstantsExample { + public static final String FIELD_I_AM_A_FIELD = "iAmAField"; + static final String FIELD_AND_SO_AM_I = "andSoAmI"; + + private final String iAmAField; + private final int andSoAmI; +} diff --git a/website/usageExamples/experimental/FieldNameConstantsExample_pre.jpage b/website/usageExamples/experimental/FieldNameConstantsExample_pre.jpage new file mode 100644 index 00000000..dc6376eb --- /dev/null +++ b/website/usageExamples/experimental/FieldNameConstantsExample_pre.jpage @@ -0,0 +1,9 @@ +import lombok.experimental.FieldNameConstants; +import lombok.AccessLevel; + +@FieldNameConstants +public class FieldNameConstantsExample { + private final String iAmAField; + @FieldNameConstants(level = AccessLevel.PACKAGE) + private final int andSoAmI; +} diff --git a/website/usageExamples/experimental/onXExample_pre.jpage b/website/usageExamples/experimental/onXExample_pre.jpage index f8fcb435..e54371ae 100644 --- a/website/usageExamples/experimental/onXExample_pre.jpage +++ b/website/usageExamples/experimental/onXExample_pre.jpage @@ -9,7 +9,9 @@ import javax.validation.constraints.Max; @AllArgsConstructor(onConstructor=@__(@Inject)) public class OnXExample { - @Getter(onMethod=@__({@Id, @Column(name="unique-id")})) - @Setter(onParam=@__(@Max(10000))) +// @Getter(onMethod=@__({@Id, @Column(name="unique-id")})) //JDK7 +// @Setter(onParam=@__(@Max(10000))) //JDK7 + @Getter(onMethod_={@Id, @Column(name="unique-id")}) //JDK8 + @Setter(onParam_=@Max(10000)) //JDK8 private long unid; } diff --git a/website/usageExamples/experimental/varExample_post.jpage b/website/usageExamples/experimental/varExample_post.jpage new file mode 100644 index 00000000..d0a7c124 --- /dev/null +++ b/website/usageExamples/experimental/varExample_post.jpage @@ -0,0 +1,21 @@ +import java.util.ArrayList; +import lombok.var; + +public class VarExample { + public String example() { + ArrayList<String> example = new ArrayList<String>(); + example.add("Hello, World!"); + final String foo = example.get(0); + return foo.toLowerCase(); + } + + public void example2() { + ArrayList<String> list = new ArrayList<String>(); + list.add("zero"); + list.add("one"); + list.add("two"); + for(int i = 0; i < list.size(); ++i) { + System.out.printf("%d: %s\n", i, list.get(i)); + } + } +} diff --git a/website/usageExamples/experimental/varExample_pre.jpage b/website/usageExamples/experimental/varExample_pre.jpage new file mode 100644 index 00000000..e58c4c0d --- /dev/null +++ b/website/usageExamples/experimental/varExample_pre.jpage @@ -0,0 +1,21 @@ +import java.util.ArrayList; +import lombok.var; + +public class VarExample { + public String example() { + var example = new ArrayList<String>(); + example.add("Hello, World!"); + final var foo = example.get(0); + return foo.toLowerCase(); + } + + public void example2() { + var list = new ArrayList<String>(); + list.add("zero"); + list.add("one"); + list.add("two"); + for(var i = 0; i < list.size(); ++i) { + System.out.printf("%d: %s\n", i, list.get(i)); + } + } +} |