diff --git a/src/core/lombok/experimental/Accessors.java b/src/core/lombok/experimental/Accessors.java new file mode 100644 index 00000000..5b454273 --- /dev/null +++ b/src/core/lombok/experimental/Accessors.java @@ -0,0 +1,56 @@ +/* + * Copyright (C) 2012 The Project Lombok Authors. + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package lombok.experimental; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * A container for settings for the generation of getters and setters. + * Using this annotation does nothing by itself; an annotation that makes lombok generate getters and setters, + * such as {@link lombok.Setter} or {@link lombok.Data} is also required. + */ +@Target({ElementType.TYPE, ElementType.FIELD}) +@Retention(RetentionPolicy.SOURCE) +public @interface Accessors { + /** + * If true, accessors will be named after the field and not include a get or set + * prefix. If true and chain is omitted, chain defaults to true. + * default: false + */ + boolean fluent() default false; + + /** + * If true, setters return this instead of void. + * default: false, unless fluent=true, then default: true + */ + boolean chain() default false; + + /** + * If present, only fields with any of the stated prefixes are given the getter/setter treatment. + * Note that a prefix only counts if the next character is NOT a lowercase character. If multiple fields + * all turn into the same name when the prefix is stripped, an error will be generated. + */ + String[] prefix() default {}; +} diff --git a/website/features/experimental/Accessors.html b/website/features/experimental/Accessors.html new file mode 100644 index 00000000..bbcd80bb --- /dev/null +++ b/website/features/experimental/Accessors.html @@ -0,0 +1,103 @@ + + + + + + + + EXPERIMENTAL - @Accessors +
+
+
+
Project Lombok
+

@Accessors

+
A more fluent API for getters and setters.
+
+

Since

+

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

+
+
+

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

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

+
+
+
+ Back to experimental features | Previous feature | Next feature
+ credits | Copyright © 2009-2012 The Project Lombok Authors, licensed under the MIT license. +
+
+
+
+ + + diff --git a/website/features/experimental/index.html b/website/features/experimental/index.html new file mode 100644 index 00000000..e4e90c41 --- /dev/null +++ b/website/features/experimental/index.html @@ -0,0 +1,45 @@ + + + + + + + + Lombok feature overview +
+
+
+
Project Lombok
+

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. +
+
@Accessors
+
A more fluent API for getters and setters.
+
+
+
+ credits | Copyright © 2009-2012 The Project Lombok Authors, licensed under the MIT license. +
+
+
+
+ + + diff --git a/website/features/index.html b/website/features/index.html index 1a4531f4..00669bb5 100644 --- a/website/features/index.html +++ b/website/features/index.html @@ -38,6 +38,8 @@
Finally! Hassle-free final local variables.
@Delegate
Don't lose your composition.
+
experimental features
+
Here be dragons: Extra features which aren't quite ready for prime time yet.