This strategy is used with the Builder AST transform to create a builder helper class for the fluent and type-safe creation of instances of a specified class. It is modelled roughly on the design outlined here: http://michid.wordpress.com/2008/08/13/type-safe-builder-pattern-in-java/ You define classes which use the type-safe initializer pattern as follows:

import groovy.transform.builder.*
import groovy.transform.*

@ToString
@Builder(builderStrategy=InitializerStrategy) class Person {
    String firstName
    String lastName
    int age
}

While it isn't required to do so, the benefit of this builder strategy comes in conjunction with static type-checking or static compilation. Typical usage is as follows:

@CompileStatic
def main() {
    println new Person(Person.createInitializer().firstName("John").lastName("Smith").age(21))
}

which prints:

Person(John, Smith, 21)

If you don't initialise some of the properties, your code won't compile, e.g. if the method body above was changed to this:

println new Person(Person.createInitializer().firstName("John").lastName("Smith"))

then the following compile-time error would result:

[Static type checking] - Cannot find matching method Person#<init>(Person$PersonInitializer <groovy.transform.builder.InitializerStrategy$SET, groovy.transform.builder.InitializerStrategy$SET, groovy.transform.builder.InitializerStrategy$UNSET>). Please check if the declared type is correct and if the method exists.

The message is a little cryptic, but it is basically the static compiler telling us that the third parameter, age in our case, is unset. You can also add this annotation to your predefined constructors. These will be made private and an initializer will be set up to call your constructor. Any parameters to your constructor become the properties expected by the initializer. If you use such a builder on a constructor as well as on the class or on more than one constructor, then it is up to you to define unique values for 'builderClassName' and 'builderMethodName' for each annotation.