lombok.experimental

Annotation Type WithBy

@Target(value={FIELD,TYPE})
 @Retention(value=SOURCE)
public @interface WithBy

Put on any field to make lombok build a 'withBy' - a withFieldNameBy method which produces a clone of this object (except for 1 field which gets a new value).

Complete documentation is found at the project lombok features page for @WithBy.

Example:

     private @WithBy final int foo;
     private @WithBy final String bar;
 

will generate:

     public SELF_TYPE withFooBy(@lombok.NonNull IntUnaryOperator operator) {
         int foo = operator.apply(this.foo);
         return this.foo == foo ? this : new SELF_TYPE(foo, bar);
     }
     public SELF_TYPE withBarBy(@lombok.NonNull Function<? super String, ? extends String> operator) {
         String bar = operator.apply(this.bar);
         return this.bar == bar ? this : new SELF_TYPE(foo, bar);
     }
 

This annotation can also be applied to a class, in which case it'll be as if all non-static fields that don't already have a WithBy annotation have the annotation.

This annotation is primarily useful for hierarchical immutable data structures. For example:

     class Movie {
         @WithBy private final Director director;
     }
     
     class Director {
         @WithBy private final LocalDate birthDate;
     }
 

Using plain old @With, to increment a movie's director's birth date by one, you would write:

     movie = movie.withDirector(movie.getDirector().withBirthDate(movie.getDirector().getBirthDate().plusDays(1)));
 

but with @WithBy, you'd write:

     movie = movie.withDirectorBy(d -> d.withBirthDateBy(bd -> bd.plusDays(1)));
 

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
WithBy.AnyAnnotation[]	onMethod Any annotations listed here are put on the generated method.
AccessLevel	value If you want your with method to be non-public, you can specify an alternate access level here.

Element Detail

value

public abstract AccessLevel value

If you want your with method to be non-public, you can specify an alternate access level here.

Returns:

The method will be generated with this access modifier.

Default:

lombok.AccessLevel.PUBLIC

onMethod

public abstract WithBy.AnyAnnotation[] onMethod

Any annotations listed here are put on the generated method. The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).
up to JDK7:
@With(onMethod=@__({@AnnotationsGoHere}))
from JDK8:
@With(onMethod_={@AnnotationsGohere}) // note the underscore after onMethod.

Returns:

List of annotations to apply to the generated method.

Default:

{}