#320 Custom functional interfaces

Allow users to change the functional interface used in map/mutate methods with an override.

Author: alicederyn

README.md

@@ -26,6 +26,7 @@ _Automatic generation of the Builder pattern for Java 1.6+_
   - [Collections and Maps](#collections-and-maps)
   - [Nested buildable types](#nested-buildable-types)
   - [Custom toString method](#custom-tostring-method)
+  - [Custom functional interfaces](#custom-functional-interfaces)
   - [Builder construction](#builder-construction)
   - [Partials](#partials)
   - [Jackson](#jackson)
@@ -460,6 +461,22 @@ It is rarely a good idea to redefine equality on a value type, as it makes testi
 For instance, `assertEquals` in JUnit relies on equality; it will not know to check individual fields, and as a result, tests may be failing to catch bugs that, on the face of it, they looks like they should be.
 If you are only testing a subset of your fields for equality, consider separating your class in two, as you may have accidentally combined the key and the value of a map into a single object, and you may find your code becomes healthier after the separation.
 
+### Custom functional interfaces
+
+FreeBuilder's generated map and mutate methods take [UnaryOperator] or [Consumer] functional interfaces. If you need to use a different functional interface, you can override the generated methods in your Builder and change the parameter type. FreeBuilder will spot the incompatible override and change the code it generates to match:
+
+```java
+public interface MyType {
+  String property();
+
+  class Builder extends MyType_Builder {
+    @Override public Builder mapProperty(
+        com.google.common.base.Function<Integer, Integer> mapper) {
+      return super.mapProperty(mapper);
+    }
+  }
+}
+
 ### Builder construction
 
 <em>Effective Java</em> recommends passing required parameters in to the Builder

src/main/java/org/inferred/freebuilder/processor/BuildableProperty.java

@@ -24,6 +24,8 @@
 import static org.inferred.freebuilder.processor.BuilderMethods.mutator;
 import static org.inferred.freebuilder.processor.BuilderMethods.setter;
 import static org.inferred.freebuilder.processor.util.Block.methodBody;
+import static org.inferred.freebuilder.processor.util.FunctionalType.consumer;
+import static org.inferred.freebuilder.processor.util.FunctionalType.functionalTypeAcceptedByMethod;
 import static org.inferred.freebuilder.processor.util.ModelUtils.asElement;
 import static org.inferred.freebuilder.processor.util.ModelUtils.findAnnotationMirror;
 import static org.inferred.freebuilder.processor.util.ModelUtils.maybeDeclared;
@@ -37,6 +39,7 @@
 import org.inferred.freebuilder.processor.util.Block;
 import org.inferred.freebuilder.processor.util.Excerpt;
 import org.inferred.freebuilder.processor.util.Excerpts;
+import org.inferred.freebuilder.processor.util.FunctionalType;
 import org.inferred.freebuilder.processor.util.ModelUtils;
 import org.inferred.freebuilder.processor.util.ParameterizedType;
 import org.inferred.freebuilder.processor.util.PreconditionExcerpts;
@@ -161,18 +164,28 @@ public Optional<BuildableProperty> create(Config config) {
         partialToBuilderMethod = PartialToBuilderMethod.MERGE_DIRECTLY;
       }
 
+      // Find any mutate method override
+      FunctionalType mutatorType = functionalTypeAcceptedByMethod(
+          config.getBuilder(),
+          mutator(config.getProperty()),
+          consumer(builder.get().asType()),
+          config.getElements(),
+          config.getTypes());
+
       return Optional.of(new BuildableProperty(
           config.getMetadata(),
           config.getProperty(),
           ParameterizedType.from(builder.get()),
           builderFactory.get(),
+          mutatorType,
           mergeFromBuilderMethod,
           partialToBuilderMethod));
     }
   }
 
   private final ParameterizedType builderType;
   private final BuilderFactory builderFactory;
+  private final FunctionalType mutatorType;
   private final MergeBuilderMethod mergeFromBuilderMethod;
   private final PartialToBuilderMethod partialToBuilderMethod;
   private final Excerpt suppressUnchecked;
@@ -182,11 +195,13 @@ private BuildableProperty(
       Property property,
       ParameterizedType builderType,
       BuilderFactory builderFactory,
+      FunctionalType mutatorType,
       MergeBuilderMethod mergeFromBuilderMethod,
       PartialToBuilderMethod partialToBuilderMethod) {
     super(metadata, property);
     this.builderType = builderType;
     this.builderFactory = builderFactory;
+    this.mutatorType = mutatorType;
     this.mergeFromBuilderMethod = mergeFromBuilderMethod;
     this.partialToBuilderMethod = partialToBuilderMethod;
     if (ModelUtils.needsSafeVarargs(property.getType())) {
@@ -259,8 +274,7 @@ private void addSetterTakingBuilder(SourceBuilder code, Metadata metadata) {
   }
 
   private void addMutate(SourceBuilder code, Metadata metadata) {
-    ParameterizedType consumer = code.feature(FUNCTION_PACKAGE).consumer().orNull();
-    if (consumer == null) {
+    if (!code.feature(FUNCTION_PACKAGE).consumer().isPresent()) {
       return;
     }
     code.addLine("")
@@ -275,13 +289,12 @@ private void addMutate(SourceBuilder code, Metadata metadata) {
         .addLine(" * @return this {@code %s} object", metadata.getBuilder().getSimpleName())
         .addLine(" * @throws NullPointerException if {@code mutator} is null")
         .addLine(" */")
-        .addLine("public %s %s(%s<%s> mutator) {",
+        .addLine("public %s %s(%s mutator) {",
             metadata.getBuilder(),
             mutator(property),
-            consumer.getQualifiedName(),
-            builderType)
+            mutatorType.getFunctionalInterface())
         .add(methodBody(code, "mutator")
-            .addLine("  mutator.accept(%s());", getBuilderMethod(property))
+            .addLine("  mutator.%s(%s());", mutatorType.getMethodName(), getBuilderMethod(property))
             .addLine("  return (%s) this;", metadata.getBuilder()))
         .addLine("}");
   }

src/main/java/org/inferred/freebuilder/processor/DefaultProperty.java

@@ -21,6 +21,8 @@
 import static org.inferred.freebuilder.processor.BuilderMethods.setter;
 import static org.inferred.freebuilder.processor.CodeGenerator.UNSET_PROPERTIES;
 import static org.inferred.freebuilder.processor.util.Block.methodBody;
+import static org.inferred.freebuilder.processor.util.FunctionalType.functionalTypeAcceptedByMethod;
+import static org.inferred.freebuilder.processor.util.FunctionalType.unaryOperator;
 import static org.inferred.freebuilder.processor.util.ObjectsExcerpts.Nullability.NOT_NULLABLE;
 import static org.inferred.freebuilder.processor.util.PreconditionExcerpts.checkNotNullInline;
 import static org.inferred.freebuilder.processor.util.PreconditionExcerpts.checkNotNullPreamble;
@@ -33,13 +35,12 @@
 import org.inferred.freebuilder.processor.util.Excerpt;
 import org.inferred.freebuilder.processor.util.Excerpts;
 import org.inferred.freebuilder.processor.util.FieldAccess;
+import org.inferred.freebuilder.processor.util.FunctionalType;
 import org.inferred.freebuilder.processor.util.ObjectsExcerpts;
-import org.inferred.freebuilder.processor.util.ParameterizedType;
 import org.inferred.freebuilder.processor.util.PreconditionExcerpts;
 import org.inferred.freebuilder.processor.util.SourceBuilder;
 
 import javax.lang.model.type.TypeKind;
-import javax.lang.model.type.TypeMirror;
 
 /** Default {@link PropertyCodeGenerator}, providing reference semantics for any type. */
 class DefaultProperty extends PropertyCodeGenerator {
@@ -51,16 +52,29 @@ public Optional<DefaultProperty> create(Config config) {
       Property property = config.getProperty();
       boolean hasDefault = config.getMethodsInvokedInBuilderConstructor()
           .contains(setter(property));
-      return Optional.of(new DefaultProperty(config.getMetadata(), property, hasDefault));
+      FunctionalType mapperType = functionalTypeAcceptedByMethod(
+          config.getBuilder(),
+          mapper(property),
+          unaryOperator(firstNonNull(property.getBoxedType(), property.getType())),
+          config.getElements(),
+          config.getTypes());
+      return Optional.of(new DefaultProperty(
+          config.getMetadata(), property, hasDefault, mapperType));
     }
   }
 
   private final boolean hasDefault;
+  private final FunctionalType mapperType;
   private final TypeKind kind;
 
-  DefaultProperty(Metadata metadata, Property property, boolean hasDefault) {
+  DefaultProperty(
+      Metadata metadata,
+      Property property,
+      boolean hasDefault,
+      FunctionalType mapperType) {
     super(metadata, property);
     this.hasDefault = hasDefault;
+    this.mapperType = mapperType;
     this.kind = property.getType().getKind();
   }
 
@@ -116,8 +130,7 @@ private void addSetter(SourceBuilder code, final Metadata metadata) {
   }
 
   private void addMapper(SourceBuilder code, final Metadata metadata) {
-    ParameterizedType unaryOperator = code.feature(FUNCTION_PACKAGE).unaryOperator().orNull();
-    if (unaryOperator == null) {
+    if (!code.feature(FUNCTION_PACKAGE).unaryOperator().isPresent()) {
       return;
     }
     code.addLine("")
@@ -127,21 +140,23 @@ private void addMapper(SourceBuilder code, final Metadata metadata) {
         .addLine(" * by applying {@code mapper} to it and using the result.")
         .addLine(" *")
         .addLine(" * @return this {@code %s} object", metadata.getBuilder().getSimpleName())
-        .addLine(" * @throws NullPointerException if {@code mapper} is null"
-        + " or returns null");
+        .addLine(" * @throws NullPointerException if {@code mapper} is null");
+    if (mapperType.canReturnNull()) {
+      code.addLine(" * or returns null");
+    }
     if (!hasDefault) {
       code.addLine(" * @throws IllegalStateException if the field has not been set");
     }
-    TypeMirror typeParam = firstNonNull(property.getBoxedType(), property.getType());
     code.addLine(" */")
         .add("public %s %s(%s mapper) {",
             metadata.getBuilder(),
             mapper(property),
-            unaryOperator.withParameters(typeParam));
+            mapperType.getFunctionalInterface());
     if (!hasDefault) {
       code.add(PreconditionExcerpts.checkNotNull("mapper"));
     }
-    code.addLine("  return %s(mapper.apply(%s()));", setter(property), getter(property))
+    code.addLine("  return %s(mapper.%s(%s()));",
+            setter(property), mapperType.getMethodName(), getter(property))
         .addLine("}");
   }
 

src/main/java/org/inferred/freebuilder/processor/ListMultimapProperty.java

@@ -25,6 +25,8 @@
 import static org.inferred.freebuilder.processor.Util.erasesToAnyOf;
 import static org.inferred.freebuilder.processor.Util.upperBound;
 import static org.inferred.freebuilder.processor.util.Block.methodBody;
+import static org.inferred.freebuilder.processor.util.FunctionalType.consumer;
+import static org.inferred.freebuilder.processor.util.FunctionalType.functionalTypeAcceptedByMethod;
 import static org.inferred.freebuilder.processor.util.ModelUtils.maybeDeclared;
 import static org.inferred.freebuilder.processor.util.ModelUtils.maybeUnbox;
 import static org.inferred.freebuilder.processor.util.ModelUtils.overrides;
@@ -43,14 +45,17 @@
 import org.inferred.freebuilder.processor.excerpt.CheckedListMultimap;
 import org.inferred.freebuilder.processor.util.Block;
 import org.inferred.freebuilder.processor.util.Excerpt;
-import org.inferred.freebuilder.processor.util.ParameterizedType;
+import org.inferred.freebuilder.processor.util.FunctionalType;
 import org.inferred.freebuilder.processor.util.SourceBuilder;
 
 import java.util.Collection;
 import java.util.Map.Entry;
 
+import javax.lang.model.element.TypeElement;
 import javax.lang.model.type.DeclaredType;
 import javax.lang.model.type.TypeMirror;
+import javax.lang.model.util.Elements;
+import javax.lang.model.util.Types;
 
 /**
  * {@link PropertyCodeGenerator} providing fluent methods for {@link ListMultimap} properties.
@@ -61,7 +66,8 @@ static class Factory implements PropertyCodeGenerator.Factory {
 
     @Override
     public Optional<ListMultimapProperty> create(Config config) {
-      DeclaredType type = maybeDeclared(config.getProperty().getType()).orNull();
+      Property property = config.getProperty();
+      DeclaredType type = maybeDeclared(property.getType()).orNull();
       if (type == null) {
         return Optional.absent();
       }
@@ -79,14 +85,23 @@ public Optional<ListMultimapProperty> create(Config config) {
       Optional<TypeMirror> unboxedValueType = maybeUnbox(valueType, config.getTypes());
       boolean overridesPutMethod =
           hasPutMethodOverride(config, unboxedKeyType.or(keyType), unboxedValueType.or(valueType));
+
+      FunctionalType mutatorType = functionalTypeAcceptedByMethod(
+          config.getBuilder(),
+          mutator(property),
+          consumer(listMultimap(keyType, valueType, config.getElements(), config.getTypes())),
+          config.getElements(),
+          config.getTypes());
+
       return Optional.of(new ListMultimapProperty(
           config.getMetadata(),
-          config.getProperty(),
+          property,
           overridesPutMethod,
           keyType,
           unboxedKeyType,
           valueType,
-          unboxedValueType));
+          unboxedValueType,
+          mutatorType));
     }
 
     private static boolean hasPutMethodOverride(
@@ -98,13 +113,23 @@ private static boolean hasPutMethodOverride(
           keyType,
           valueType);
     }
+
+    private static TypeMirror listMultimap(
+        TypeMirror keyType,
+        TypeMirror valueType,
+        Elements elements,
+        Types types) {
+      TypeElement listMultimapType = elements.getTypeElement(ListMultimap.class.getName());
+      return types.getDeclaredType(listMultimapType, keyType, valueType);
+    }
   }
 
   private final boolean overridesPutMethod;
   private final TypeMirror keyType;
   private final Optional<TypeMirror> unboxedKeyType;
   private final TypeMirror valueType;
   private final Optional<TypeMirror> unboxedValueType;
+  private final FunctionalType mutatorType;
 
   ListMultimapProperty(
       Metadata metadata,
@@ -113,13 +138,15 @@ private static boolean hasPutMethodOverride(
       TypeMirror keyType,
       Optional<TypeMirror> unboxedKeyType,
       TypeMirror valueType,
-      Optional<TypeMirror> unboxedValueType) {
+      Optional<TypeMirror> unboxedValueType,
+      FunctionalType mutatorType) {
     super(metadata, property);
     this.overridesPutMethod = overridesPutMethod;
     this.keyType = keyType;
     this.unboxedKeyType = unboxedKeyType;
     this.valueType = valueType;
     this.unboxedValueType = unboxedValueType;
+    this.mutatorType = mutatorType;
   }
 
   @Override
@@ -301,8 +328,7 @@ private void addRemoveAll(SourceBuilder code, Metadata metadata) {
   }
 
   private void addMutate(SourceBuilder code, Metadata metadata) {
-    ParameterizedType consumer = code.feature(FUNCTION_PACKAGE).consumer().orNull();
-    if (consumer == null) {
+    if (!code.feature(FUNCTION_PACKAGE).consumer().isPresent()) {
       return;
     }
     code.addLine("")
@@ -316,21 +342,21 @@ private void addMutate(SourceBuilder code, Metadata metadata) {
         .addLine(" * @return this {@code Builder} object")
         .addLine(" * @throws NullPointerException if {@code mutator} is null")
         .addLine(" */")
-        .addLine("public %s %s(%s<%s<%s, %s>> mutator) {",
+        .addLine("public %s %s(%s mutator) {",
             metadata.getBuilder(),
             mutator(property),
-            consumer.getQualifiedName(),
-            ListMultimap.class,
-            keyType,
-            valueType);
+            mutatorType.getFunctionalInterface());
     Block body = methodBody(code, "mutator");
     if (overridesPutMethod) {
-      body.addLine("  mutator.accept(new %s<>(%s, this::%s));",
-          CheckedListMultimap.TYPE, property.getField(), putMethod(property));
+      body.addLine("  mutator.%s(new %s<>(%s, this::%s));",
+          mutatorType.getMethodName(),
+          CheckedListMultimap.TYPE,
+          property.getField(),
+          putMethod(property));
     } else {
       body.addLine("  // If %s is overridden, this method will be updated to delegate to it",
               putMethod(property))
-          .addLine("  mutator.accept(%s);", property.getField());
+          .addLine("  mutator.%s(%s);", mutatorType.getMethodName(), property.getField());
     }
     body.addLine("  return (%s) this;", metadata.getBuilder());
     code.add(body)