Add support for repeatable annotations for local extensions (#1118)

fixes #1030

Author: Vampire

docs/extensions.adoc

@@ -678,6 +678,14 @@ Your annotation can be applied to a specification, a feature method, a fixture m
 like helper methods or other places if the `@Target` is set accordingly, the annotation will be ignored and has no
 effect other than being visible in the source code.
 
+Since Spock 2.0 your annotation can also be defined as `@Repeatable` and applied multiple times to the same target.
+Spock will handle this appropriately and call your extension once for each annotation. If you want a repeatable
+annotation that is compatible with Spock before 2.0 you need to make the container annotation an extension annotation
+itself and handle all cases accordingly, but you need to make sure to only handle the container annotation if Spock
+version is before 2.0 or your annotations might be handled twice. Be aware that the repeatable annotation can be
+attached to the target directly, inside the container annotation or even both if the user added the container
+annotation manually and also attached one annotation directly.
+
 `IAnnotationDrivenExtension` has the following five methods, where in each you can prepare a specification with your
 extension magic, like attaching interceptors to various interception points as described in the chapter
 <<Interceptors>>:

docs/release_notes.adoc

@@ -5,6 +5,10 @@ include::include.adoc[]
 
 - Add a way to register `ConfigurationObject` globally without the need for a Global Extension
 
+- Annotations for local extensions can now be defined as `@Repeatable` and applied multiple times to the same target.
+  Spock will handle this appropriately and call the extension once for each annotation.
+
+
 == 2.0-M3 (2020-06-11)
 
 === Breaking Changes

spock-core/src/main/java/org/spockframework/compiler/AstNodeCache.java

@@ -18,6 +18,7 @@
 
 import org.codehaus.groovy.runtime.wrappers.PojoWrapper;
 import org.spockframework.runtime.*;
+import org.spockframework.runtime.extension.RepeatedExtensionAnnotations;
 import org.spockframework.runtime.model.*;
 import org.spockframework.util.Identifiers;
 import spock.lang.Specification;
@@ -68,6 +69,7 @@ public class AstNodeCache {
       ErrorCollector.getDeclaredMethods(org.spockframework.runtime.ErrorCollector.VALIDATE_COLLECTED_ERRORS).get(0);
 
   // annotations and annotation elements
+  public final ClassNode RepeatedExtensionAnnotations = ClassHelper.makeWithoutCaching(RepeatedExtensionAnnotations.class);
   public final ClassNode SpecMetadata = ClassHelper.makeWithoutCaching(SpecMetadata.class);
   public final ClassNode FieldMetadata = ClassHelper.makeWithoutCaching(FieldMetadata.class);
   public final ClassNode FeatureMetadata = ClassHelper.makeWithoutCaching(FeatureMetadata.class);

spock-core/src/main/java/org/spockframework/compiler/SpecAnnotator.java

@@ -17,13 +17,24 @@
 package org.spockframework.compiler;
 
 import org.spockframework.compiler.model.*;
+import org.spockframework.runtime.extension.ExtensionAnnotation;
+import org.spockframework.runtime.extension.RepeatedExtensionAnnotations;
 import org.spockframework.runtime.model.*;
 
 import java.io.File;
+import java.lang.annotation.Repeatable;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
 
 import org.codehaus.groovy.ast.*;
 import org.codehaus.groovy.ast.expr.*;
 
+import static java.util.stream.Collectors.*;
+import static org.spockframework.compiler.AstUtil.*;
+import static org.spockframework.util.ObjectUtil.asInstance;
+
 /**
  * Puts all spec information required at runtime into annotations
  * attached to class members.
@@ -41,6 +52,7 @@ public SpecAnnotator(AstNodeCache nodeCache) {
   @Override
   public void visitSpec(Spec spec) throws Exception {
     addSpecMetadata(spec);
+    addRepeatedExtensionAnnotations(spec.getAst());
   }
 
   private void addSpecMetadata(Spec spec) {
@@ -55,6 +67,7 @@ private void addSpecMetadata(Spec spec) {
   @Override
   public void visitField(Field field) throws Exception {
     addFieldMetadata(field);
+    addRepeatedExtensionAnnotations(field.getAst());
   }
 
   private void addFieldMetadata(Field field) {
@@ -70,6 +83,103 @@ private void addFieldMetadata(Field field) {
   public void visitMethod(Method method) throws Exception {
     if (method instanceof FeatureMethod)
       addFeatureMetadata((FeatureMethod)method);
+    if ((method instanceof FeatureMethod) || (method instanceof FixtureMethod))
+      addRepeatedExtensionAnnotations(method.getAst());
+  }
+
+  private void addRepeatedExtensionAnnotations(AnnotatedNode annotatedNode) {
+    ListExpression repeatedExtensionAnnotations = annotatedNode
+      // get all repeatable extension annotations flattened
+      .getAnnotations()
+      .stream()
+      .flatMap(this::flattenRepeatableExtensionAnnotationContainer)
+      .filter(this::isRepeatableExtensionAnnotation)
+      // find the annotations that occur multiple times
+      .collect(groupingBy(AnnotationNode::getClassNode))
+      .entrySet()
+      .stream()
+      .filter(entry -> entry.getValue().size() > 1)
+      // put them to a ListExpression
+      .map(Map.Entry::getKey)
+      .map(ClassExpression::new)
+      .collect(collectingAndThen(Collectors.<Expression>toList(), ListExpression::new));
+
+    // if any were found, put them to a RepeatedExtensionAnnotations annotation as runtime hint
+    if (repeatedExtensionAnnotations.getExpressions().size() != 0) {
+      AnnotationNode ann = new AnnotationNode(nodeCache.RepeatedExtensionAnnotations);
+      ann.setMember(RepeatedExtensionAnnotations.VALUE, repeatedExtensionAnnotations);
+      annotatedNode.addAnnotation(ann);
+    }
+  }
+
+  private Stream<? extends AnnotationNode> flattenRepeatableExtensionAnnotationContainer(AnnotationNode container) {
+    // supply the container itself, it could also be a valid extension annotation
+    Stream<? extends AnnotationNode> result = Stream.of(container);
+
+    Expression value = container.getMember("value");
+    if (value instanceof ListExpression) {
+      List<Expression> valueExpressions = asInstance(value, ListExpression.class).getExpressions();
+      switch (valueExpressions.size()) {
+        case 0:
+          // no value, nothing to do
+          break;
+
+        case 1:
+          result = handleSingleContainedAnnotation(container, result, valueExpressions.get(0));
+          break;
+
+        default:
+          result = handleMultipleContainedAnnotations(container, result, valueExpressions);
+          break;
+      }
+    } else if (value instanceof AnnotationConstantExpression) {
+      result = handleSingleContainedAnnotation(container, result, value);
+    }
+
+    return result;
+  }
+
+  private Stream<? extends AnnotationNode> handleSingleContainedAnnotation(AnnotationNode container,
+                                                                           Stream<? extends AnnotationNode> result,
+                                                                           Expression value) {
+    if (notRepeatedAnnotation(value, container)) {
+      return result;
+    }
+
+    AnnotationNode annotationNode = asInstance(
+      asInstance(value, AnnotationConstantExpression.class).getValue(),
+      AnnotationNode.class);
+    // supply annotation twice in case there is only the container annotation
+    // with one contained annotation and no annotation besides it
+    // in that case we also need the RepeatedExtensionAnnotations at runtime
+    // to unwrap the container
+    return Stream.concat(result, Stream.of(annotationNode, annotationNode));
+  }
+
+  private Stream<? extends AnnotationNode> handleMultipleContainedAnnotations(AnnotationNode container,
+                                                                              Stream<? extends AnnotationNode> result,
+                                                                              List<Expression> valueExpressions) {
+    if (notRepeatedAnnotation(valueExpressions.get(0), container)) {
+      return result;
+    }
+
+    return Stream.concat(result, valueExpressions
+      .stream()
+      .map(AnnotationConstantExpression.class::cast)
+      .map(AnnotationConstantExpression::getValue)
+      .map(AnnotationNode.class::cast));
+  }
+
+  private boolean notRepeatedAnnotation(Expression clazz, AnnotationNode container) {
+    AnnotationNode repeatableAnnotation = getAnnotation(clazz.getType(), Repeatable.class);
+    return (repeatableAnnotation == null) ||
+      !repeatableAnnotation.getMember("value").getType().equals(container.getClassNode());
+  }
+
+  private boolean isRepeatableExtensionAnnotation(AnnotationNode annotation) {
+    ClassNode annotationClass = annotation.getClassNode();
+    return hasAnnotation(annotationClass, ExtensionAnnotation.class) &&
+      hasAnnotation(annotationClass, Repeatable.class);
   }
 
   private void addFeatureMetadata(FeatureMethod feature) {

spock-core/src/main/java/org/spockframework/runtime/ExtensionRunner.java

@@ -81,9 +81,35 @@ private void doRunAnnotationDrivenExtensions(Iterable<MethodInfo> nodes) {
     }
   }
 
-  @SuppressWarnings("unchecked")
   private void doRunAnnotationDrivenExtensions(NodeInfo<?, ?> node) {
-    for (Annotation ann : node.getAnnotations()) {
+    RepeatedExtensionAnnotations repeatedExtensionAnnotations = node.getAnnotation(RepeatedExtensionAnnotations.class);
+
+    List<Annotation> annotations;
+    if (repeatedExtensionAnnotations == null) {
+      annotations = Arrays.asList(node.getAnnotations());
+    } else {
+      annotations = new ArrayList<>();
+      List<Class<? extends Annotation>> repeatedAnnotations = Arrays.asList(repeatedExtensionAnnotations.value());
+
+      // add all direct annotations except those marked as repeated
+      Arrays.stream(node.getAnnotations())
+        .filter(annotation -> repeatedAnnotations
+          .stream()
+          .noneMatch(repeatedAnnotation -> repeatedAnnotation.isInstance(annotation)))
+        .forEach(annotations::add);
+
+      // add all annotations marked as repeated
+      for (Class<? extends Annotation> repeatedAnnotation : repeatedAnnotations) {
+        annotations.addAll(Arrays.asList(node.getAnnotationsByType(repeatedAnnotation)));
+      }
+    }
+
+    doRunAnnotationDrivenExtensions(node, annotations);
+  }
+
+  @SuppressWarnings("unchecked")
+  private void doRunAnnotationDrivenExtensions(NodeInfo<?, ?> node, List<Annotation> annotations) {
+    for (Annotation ann : annotations) {
       ExtensionAnnotation extAnn = ann.annotationType().getAnnotation(ExtensionAnnotation.class);
       if (extAnn == null) continue;
       IAnnotationDrivenExtension extension = getOrCreateExtension(extAnn.value());

spock-core/src/main/java/org/spockframework/runtime/extension/RepeatedExtensionAnnotations.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2020 the original author or authors.
+ *
+ * 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 org.spockframework.runtime.extension;
+
+import org.spockframework.util.Beta;
+
+import java.lang.annotation.*;
+import java.lang.reflect.AnnotatedElement;
+
+/**
+ * This annotation carries the information which repeatable annotations are actually repeated from the
+ * AST transformation phase to the runtime phase. As repeated annotations are wrapped inside a container
+ * annotation and even can be wrapped in the container but also be once applied directly,
+ * you cannot simply use {@link AnnotatedElement#getAnnotations()} but also have to check each annotation
+ * whether it is a container annotation for a repeatable extension annotation and then use its {@code value}
+ * attribute. To save doing this effort at runtime using reflection, it is done during AST transformation,
+ * and the result carried over to runtime phase using this annotation.
+ *
+ * <p>This annotation is just for internal usage and should not be applied manually.
+ *
+ * @since 2.0
+ */
+@Beta
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD})
+public @interface RepeatedExtensionAnnotations {
+  String VALUE = "value";
+
+  Class<? extends Annotation>[] value();
+}

spock-core/src/main/java/org/spockframework/runtime/model/NodeInfo.java

@@ -82,6 +82,10 @@ public <T extends Annotation> T getAnnotation(Class<T> clazz) {
     return getReflection().getAnnotation(clazz);
   }
 
+  public <T extends Annotation> T[] getAnnotationsByType(Class<T> clazz) {
+    return getReflection().getAnnotationsByType(clazz);
+  }
+
   public boolean isAnnotationPresent(Class<? extends Annotation> clazz) {
     return getReflection().isAnnotationPresent(clazz);
   }