JAVA-2279: Add logs to the generated mapper code

manual/mapper/README.md

@@ -152,3 +152,22 @@ From the mapper, you can then obtain a DAO instance and execute queries:
 ProductDao dao = inventoryMapper.productDao(CqlIdentifier.fromCql("inventory"));
 dao.save(new Product(UUID.randomUUID(), "Mechanical keyboard"));
 ```
+
+### Logging
+
+The code generated by the mapper includes logs. They are issued with SLF4J, and can be configured
+the same way as the [core driver logs](../core/logging/).
+
+They can help you figure out which queries the mapper is generating under the hood, for example:
+
+```
+DEBUG ProductDaoImpl__MapperGenerated - [s0] Initializing new instance for keyspace = ks_0 and table = null
+DEBUG ProductHelper__MapperGenerated - [s0] Entity Product will be mapped to ks_0.product
+DEBUG ProductDaoImpl__MapperGenerated - [s0] Preparing query
+      `SELECT id,description,dimensions FROM ks_0.product WHERE id=:id`
+      for method findById(java.util.UUID)
+```
+
+You can decide which logs to enable using the standard SLF4J mechanisms (categories and levels). In
+addition, if you want no logs at all, it's possible to entirely remove them from the generated code
+with the Java compiler option `-Acom.datastax.oss.driver.mapper.logs.enabled=false`.

mapper-processor/src/main/java/com/datastax/oss/driver/internal/mapper/processor/DefaultProcessorContext.java

@@ -18,6 +18,7 @@
 import com.datastax.oss.driver.internal.core.context.DefaultDriverContext;
 import com.datastax.oss.driver.internal.core.util.concurrent.CycleDetector;
 import com.datastax.oss.driver.internal.core.util.concurrent.LazyReference;
+import com.datastax.oss.driver.internal.mapper.processor.dao.LoggingGenerator;
 import com.datastax.oss.driver.internal.mapper.processor.entity.DefaultEntityFactory;
 import com.datastax.oss.driver.internal.mapper.processor.entity.EntityFactory;
 import com.datastax.oss.driver.internal.mapper.processor.util.Classes;
@@ -40,20 +41,24 @@ public class DefaultProcessorContext implements ProcessorContext {
   private final DecoratedMessager messager;
   private final Types typeUtils;
   private final Elements elementUtils;
+  private boolean logsEnabled;
   private final Classes classUtils;
   private final JavaPoetFiler filer;
+  private final LoggingGenerator loggingGenerator;
 
   public DefaultProcessorContext(
       DecoratedMessager messager,
       Types typeUtils,
       Elements elementUtils,
       Filer filer,
-      String indent) {
+      String indent,
+      boolean logsEnabled) {
     this.messager = messager;
     this.typeUtils = typeUtils;
     this.elementUtils = elementUtils;
     this.classUtils = new Classes(typeUtils, elementUtils);
     this.filer = new JavaPoetFiler(filer, indent);
+    this.loggingGenerator = new LoggingGenerator(logsEnabled);
   }
 
   protected CodeGeneratorFactory buildCodeGeneratorFactory() {
@@ -98,4 +103,9 @@ public CodeGeneratorFactory getCodeGeneratorFactory() {
   public EntityFactory getEntityFactory() {
     return entityFactoryRef.get();
   }
+
+  @Override
+  public LoggingGenerator getLoggingGenerator() {
+    return loggingGenerator;
+  }
 }

mapper-processor/src/main/java/com/datastax/oss/driver/internal/mapper/processor/MapperProcessor.java

@@ -40,16 +40,20 @@
 
 @AutoService(Processor.class)
 public class MapperProcessor extends AbstractProcessor {
+  private static final boolean DEFAULT_MAPPER_LOGS_ENABLED = true;
 
   private static final String INDENT_AMOUNT_OPTION = "com.datastax.oss.driver.mapper.indent";
   private static final String INDENT_WITH_TABS_OPTION =
       "com.datastax.oss.driver.mapper.indentWithTabs";
+  private static final String MAPPER_LOGS_ENABLED_OPTION =
+      "com.datastax.oss.driver.mapper.logs.enabled";
 
   private DecoratedMessager messager;
   private Types typeUtils;
   private Elements elementUtils;
   private Filer filer;
   private String indent;
+  private boolean logsEnabled;
 
   @Override
   public synchronized void init(ProcessingEnvironment processingEnvironment) {
@@ -59,12 +63,22 @@ public synchronized void init(ProcessingEnvironment processingEnvironment) {
     elementUtils = processingEnvironment.getElementUtils();
     filer = processingEnvironment.getFiler();
     indent = computeIndent(processingEnvironment.getOptions());
+    logsEnabled = isLogsEnabled(processingEnvironment.getOptions());
+  }
+
+  private boolean isLogsEnabled(Map<String, String> options) {
+    String mapperLogsEnabled = options.get(MAPPER_LOGS_ENABLED_OPTION);
+    if (mapperLogsEnabled != null) {
+      return Boolean.parseBoolean(mapperLogsEnabled);
+    }
+    return DEFAULT_MAPPER_LOGS_ENABLED;
   }
 
   @Override
   public boolean process(
       Set<? extends TypeElement> annotations, RoundEnvironment roundEnvironment) {
-    ProcessorContext context = buildContext(messager, typeUtils, elementUtils, filer, indent);
+    ProcessorContext context =
+        buildContext(messager, typeUtils, elementUtils, filer, indent, logsEnabled);
 
     CodeGeneratorFactory generatorFactory = context.getCodeGeneratorFactory();
     processAnnotatedTypes(
@@ -81,8 +95,10 @@ protected ProcessorContext buildContext(
       Types typeUtils,
       Elements elementUtils,
       Filer filer,
-      String indent) {
-    return new DefaultProcessorContext(messager, typeUtils, elementUtils, filer, indent);
+      String indent,
+      boolean logsEnabled) {
+    return new DefaultProcessorContext(
+        messager, typeUtils, elementUtils, filer, indent, logsEnabled);
   }
 
   protected void processAnnotatedTypes(
@@ -119,7 +135,8 @@ public Set<String> getSupportedAnnotationTypes() {
 
   @Override
   public Set<String> getSupportedOptions() {
-    return ImmutableSet.of(INDENT_AMOUNT_OPTION, INDENT_WITH_TABS_OPTION);
+    return ImmutableSet.of(
+        INDENT_AMOUNT_OPTION, INDENT_WITH_TABS_OPTION, MAPPER_LOGS_ENABLED_OPTION);
   }
 
   @Override

mapper-processor/src/main/java/com/datastax/oss/driver/internal/mapper/processor/ProcessorContext.java

@@ -15,6 +15,7 @@
  */
 package com.datastax.oss.driver.internal.mapper.processor;
 
+import com.datastax.oss.driver.internal.mapper.processor.dao.LoggingGenerator;
 import com.datastax.oss.driver.internal.mapper.processor.entity.EntityFactory;
 import com.datastax.oss.driver.internal.mapper.processor.util.Classes;
 import javax.lang.model.util.Elements;
@@ -36,4 +37,6 @@ public interface ProcessorContext {
   CodeGeneratorFactory getCodeGeneratorFactory();
 
   EntityFactory getEntityFactory();
+
+  LoggingGenerator getLoggingGenerator();
 }

mapper-processor/src/main/java/com/datastax/oss/driver/internal/mapper/processor/dao/DaoImplementationGenerator.java

@@ -340,6 +340,8 @@ protected JavaFile.Builder getContents() {
             .addParameter(MapperContext.class, "context")
             .addStatement("super(context)");
 
+    context.getLoggingGenerator().addLoggerField(classBuilder, implementationName);
+
     // For each entity helper that was requested by a method generator, create a field for it and
     // add a constructor parameter for it (the instance gets created in initAsync).
     for (Map.Entry<ClassName, String> entry : entityHelperFields.entrySet()) {
@@ -401,6 +403,14 @@ private MethodSpec.Builder getInitAsyncContents() {
             .addModifiers(Modifier.PUBLIC, Modifier.STATIC)
             .addParameter(MapperContext.class, "context");
 
+    LoggingGenerator loggingGenerator = context.getLoggingGenerator();
+    loggingGenerator.debug(
+        initAsyncBuilder,
+        "[{}] Initializing new instance for keyspace = {} and table = {}",
+        CodeBlock.of("context.getSession().getName()"),
+        CodeBlock.of("context.getKeyspaceId()"),
+        CodeBlock.of("context.getTableId()"));
+
     generateProtocolVersionCheck(initAsyncBuilder);
 
     initAsyncBuilder.beginControlFlow("try");
@@ -431,6 +441,13 @@ private MethodSpec.Builder getInitAsyncContents() {
       String simpleStatementName = preparedStatement.fieldName + "_simple";
       preparedStatement.simpleStatementGenerator.accept(initAsyncBuilder, simpleStatementName);
       // - prepare it asynchronously, store all CompletionStages in a list
+      loggingGenerator.debug(
+          initAsyncBuilder,
+          String.format(
+              "[{}] Preparing query `{}` for method %s",
+              preparedStatement.methodElement.toString()),
+          CodeBlock.of("context.getSession().getName()"),
+          CodeBlock.of("$L.getQuery()", simpleStatementName));
       initAsyncBuilder
           .addStatement(
               "$T $L = prepare($L, context)",

mapper-processor/src/main/java/com/datastax/oss/driver/internal/mapper/processor/dao/LoggingGenerator.java

@@ -0,0 +1,81 @@
+/*
+ * Copyright DataStax, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.datastax.oss.driver.internal.mapper.processor.dao;
+
+import com.squareup.javapoet.ClassName;
+import com.squareup.javapoet.CodeBlock;
+import com.squareup.javapoet.FieldSpec;
+import com.squareup.javapoet.MethodSpec;
+import com.squareup.javapoet.TypeSpec;
+import javax.lang.model.element.Modifier;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class LoggingGenerator {
+  private final boolean logsEnabled;
+
+  public LoggingGenerator(boolean logsEnabled) {
+    this.logsEnabled = logsEnabled;
+  }
+
+  /**
+   * Generates a logger in a constant, such as:
+   *
+   * <pre>
+   *   private static final Logger LOG = LoggerFactory.getLogger(Foobar.class);
+   * </pre>
+   *
+   * @param classBuilder where to generate.
+   * @param className the name of the class ({@code Foobar}).
+   */
+  public void addLoggerField(TypeSpec.Builder classBuilder, ClassName className) {
+    if (logsEnabled) {
+      classBuilder.addField(
+          FieldSpec.builder(
+                  ClassName.get(Logger.class),
+                  "LOG",
+                  Modifier.PRIVATE,
+                  Modifier.FINAL,
+                  Modifier.STATIC)
+              .initializer("$T.getLogger($T.class)", LoggerFactory.class, className)
+              .build());
+    }
+  }
+
+  /**
+   * Generates a debug log statement, such as:
+   *
+   * <pre>
+   *   LOG.debug("setting {} = {}", key, value);
+   * </pre>
+   *
+   * <p>This assumes that {@link #addLoggerField(TypeSpec.Builder, ClassName)} has already been
+   * called for the class where this is generated.
+   *
+   * @param builder where to generate.
+   * @param template the message ({@code "setting {} = {}"}).
+   * @param arguments the arguments ({@code key} and {@code value}).
+   */
+  public void debug(MethodSpec.Builder builder, String template, CodeBlock... arguments) {
+    if (logsEnabled) {
+      builder.addCode("$[LOG.debug($S", template);
+      for (CodeBlock argument : arguments) {
+        builder.addCode(",\n$L", argument);
+      }
+      builder.addCode(");$]\n");
+    }
+  }
+}

mapper-processor/src/main/java/com/datastax/oss/driver/internal/mapper/processor/entity/EntityHelperGenerator.java

@@ -26,6 +26,7 @@
 import com.datastax.oss.driver.internal.mapper.processor.util.generation.GenericTypeConstantGenerator;
 import com.datastax.oss.driver.shaded.guava.common.collect.ImmutableList;
 import com.squareup.javapoet.ClassName;
+import com.squareup.javapoet.CodeBlock;
 import com.squareup.javapoet.FieldSpec;
 import com.squareup.javapoet.JavaFile;
 import com.squareup.javapoet.MethodSpec;
@@ -90,6 +91,8 @@ protected JavaFile.Builder getContents() {
                 ParameterizedTypeName.get(
                     ClassName.get(EntityHelperBase.class), ClassName.get(classElement)));
 
+    context.getLoggingGenerator().addLoggerField(classContents, helperName);
+
     classContents.addMethod(
         MethodSpec.methodBuilder("getEntityClass")
             .addModifiers(Modifier.PUBLIC)
@@ -126,6 +129,16 @@ protected JavaFile.Builder getContents() {
           entityDefinition.getDefaultKeyspace(),
           entityDefinition.getCqlName());
     }
+    context
+        .getLoggingGenerator()
+        .debug(
+            constructorContents,
+            String.format(
+                "[{}] Entity %s will be mapped to {}{}",
+                entityDefinition.getClassName().simpleName()),
+            CodeBlock.of("context.getSession().getName()"),
+            CodeBlock.of("getKeyspaceId() == null ? \"\" : getKeyspaceId() + \".\""),
+            CodeBlock.of("getTableId()"));
 
     genericTypeConstantGenerator.generate(classContents);
 

mapper-processor/src/test/java/com/datastax/oss/driver/internal/mapper/processor/MapperProcessorTest.java

@@ -22,6 +22,7 @@
 import com.squareup.javapoet.JavaFile;
 import com.squareup.javapoet.TypeSpec;
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
 import javax.tools.JavaFileObject;
 
@@ -32,14 +33,30 @@ public abstract class MapperProcessorTest {
    *
    * @param packageName the package of the types to process. Note that it is currently not possible
    *     to process multiple packages (and it's unlikely to be needed in unit tests).
+   * @param options the compiler options (use to pass -A options to the processor).
    * @param typeSpecs the contents of the classes or interfaces to process.
    */
-  protected Compilation compileWithMapperProcessor(String packageName, TypeSpec... typeSpecs) {
+  protected Compilation compileWithMapperProcessor(
+      String packageName, Iterable<?> options, TypeSpec... typeSpecs) {
     List<JavaFileObject> files = new ArrayList<>();
     for (TypeSpec typeSpec : typeSpecs) {
       files.add(JavaFile.builder(packageName, typeSpec).build().toJavaFileObject());
     }
-    return Compiler.javac().withProcessors(new MapperProcessor()).compile(files);
+    return Compiler.javac()
+        .withProcessors(new MapperProcessor())
+        .withOptions(options)
+        .compile(files);
+  }
+
+  /**
+   * Launches an in-process execution of javac with {@link MapperProcessor} enabled.
+   *
+   * @param packageName the package of the types to process. Note that it is currently not possible
+   *     to process multiple packages (and it's unlikely to be needed in unit tests).
+   * @param typeSpecs the contents of the classes or interfaces to process.
+   */
+  protected Compilation compileWithMapperProcessor(String packageName, TypeSpec... typeSpecs) {
+    return compileWithMapperProcessor(packageName, Collections.emptyList(), typeSpecs);
   }
 
   protected void should_fail_with_expected_error(
@@ -55,7 +72,8 @@ protected void should_succeed_with_expected_warning(
   }
 
   protected void should_succeed_without_warnings(String packageName, TypeSpec... typeSpecs) {
-    Compilation compilation = compileWithMapperProcessor(packageName, typeSpecs);
+    Compilation compilation =
+        compileWithMapperProcessor(packageName, Collections.emptyList(), typeSpecs);
     assertThat(compilation).succeededWithoutWarnings();
   }
 }