Builder (Groovy 2.4.5)
Date: 2015-09-17

groovy.transform.builder

## Annotation Type Builder

-     @Documented
      @Retention(value=RUNTIME)
      @Target(value={TYPE,CONSTRUCTOR,METHOD})
      public @interface Builder

  The `@Builder` AST transformation is used to help write classes that can be created using fluent api calls. The transform supports multiple building strategies to cover a range of cases and there are a number of configuration options to customize the building process. In addition, a number of annotation attributes let you customise the building process. Not all annotation attributes are supported by all strategies. See the individual strategy documentation for more details. If you're an AST hacker, you can also define your own strategy class. The following strategies are bundled with Groovy:
  - `SimpleStrategy` for creating chained setters
  - `ExternalStrategy` where you annotate an explicit builder class while leaving some buildee class being built untouched
  - `DefaultStrategy` which creates a nested helper class for instance creation
  - `InitializerStrategy` which creates a nested helper class for instance creation which when used with `@CompileStatic` allows type-safe object creation
  Note that Groovy provides other built-in mechanisms for easy creation of objects, e.g. the named-args constructor:

       new Person(firstName: "Robert", lastName: "Lewandowski", age: 21)

  or the with statement:

       new Person().with {
           firstName = "Robert"
           lastName = "Lewandowski"
           age = 21
       }

  so you might not find value in using the builder transform at all. But if you need Java integration or in some cases improved type safety, the `@Builder` transform might prove very useful.
  Author:
    Marcin Grzejszczak, Paul King
  See Also:
    `SimpleStrategy`, `ExternalStrategy`, `DefaultStrategy`, `InitializerStrategy`

- - ### Optional Element Summary

    Optional Elements
    Modifier and Type | Optional Element and Description
    --- | ---
    `String` | `builderClassName` For strategies which create a builder helper class, the class name to use for the helper class.
    `String` | `builderMethodName` The method name to use for a builder factory method in the source class for easy access of the builder helper class for strategies which create such a helper class.
    `Class<? extends BuilderASTTransformation.BuilderStrategy>` | `builderStrategy` A class capturing the builder strategy
    `String` | `buildMethodName` For strategies which create a builder helper class that creates the instance, the method name to call to create the instance.
    `String[]` | `excludes` List of field and/or property names to exclude from generated builder methods.
    `Class` | `forClass` A class for which builder methods should be created.
    `String[]` | `includes` List of field and/or property names to include within the generated builder methods.
    `String` | `prefix` The prefix to use when creating the setter methods.

- - ### Element Detail

    - #### forClass

          public abstract Class forClass

      A class for which builder methods should be created. It will be an error to leave this attribute with its default value for some strategies.
      Default:
        groovy.transform.Undefined.CLASS.class

    - #### builderStrategy

          public abstract Class<? extends BuilderASTTransformation.BuilderStrategy> builderStrategy

      A class capturing the builder strategy
      Default:
        groovy.transform.builder.DefaultStrategy.class

    - #### prefix

          public abstract String prefix

      The prefix to use when creating the setter methods. Default is determined by the strategy which might use "" or "set" but you can choose your own, e.g. "with". If non-empty the first letter of the property will be capitalized before being appended to the prefix.
      Default:
        "<DummyUndefinedMarkerString-DoNotUse>"

    - #### builderClassName

          public abstract String builderClassName

      For strategies which create a builder helper class, the class name to use for the helper class. Not used if using `forClass` since in such cases the builder class is explicitly supplied. Default is determined by the strategy, e.g. TargetClass + "Builder" or TargetClass + "Initializer".
      Default:
        "<DummyUndefinedMarkerString-DoNotUse>"

    - #### buildMethodName

          public abstract String buildMethodName

      For strategies which create a builder helper class that creates the instance, the method name to call to create the instance. Default is determined by the strategy, e.g. build or create.
      Default:
        "<DummyUndefinedMarkerString-DoNotUse>"

    - #### builderMethodName

          public abstract String builderMethodName

      The method name to use for a builder factory method in the source class for easy access of the builder helper class for strategies which create such a helper class. Must not be used if using `forClass`. Default is determined by the strategy, e.g. builder or createInitializer.
      Default:
        "<DummyUndefinedMarkerString-DoNotUse>"

    - #### excludes

          public abstract String[] excludes

      List of field and/or property names to exclude from generated builder methods. Must not be used if 'includes' is used. For convenience, a String with comma separated names can be used in addition to an array (using Groovy's literal list notation) of String values.
      Default:
        {}

    - #### includes

          public abstract String[] includes

      List of field and/or property names to include within the generated builder methods. Must not be used if 'excludes' is used. For convenience, a String with comma separated names can be used in addition to an array (using Groovy's literal list notation) of String values.
      Default:
        {}