Enable batch-processing for repeatable annotations (#1198)

Author: Vampire

docs/extensions.adoc

@@ -665,46 +665,66 @@ methods in the interface, so that only the needed ones need to be overridden.
 
 === Annotation Driven Local Extensions
 
-To create an annotation driven local extension you need to create a class that implements the interface
-`IAnnotationDrivenExtension`. As type argument to the interface you need to supply an annotation class that has
-`@Retention` set to `RUNTIME`, `@Target` set to one or more of `FIELD`, `METHOD` and `TYPE` - depending on where you
+To create an annotation driven local extension you need to create a class implementing the interface
+`IAnnotationDrivenExtension`. As type argument to the interface you need to supply an annotation class having
+`@Retention` set to `RUNTIME`, `@Target` set to one or more of `FIELD`, `METHOD`, and `TYPE` - depending on where you
 want your annotation to be applicable - and `@ExtensionAnnotation` applied, with the `IAnnotationDrivenExtension` class
 as argument. Of course the annotation class can have some attributes with which the user can further configure the
-behaviour of the extension for each annotation application. For convenience there is also the class
-`AbstractAnnotationDrivenExtension`, which provides empty implementations for all methods in the interface, so that only
-the needed ones need to be overridden.
+behaviour of the extension for each annotation application.
 
 Your annotation can be applied to a specification, a feature method, a fixture method or a field. On all other places
 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.
+effect other than being visible in the source code, except you check its existence in other places yourself.
 
 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
+`IAnnotationDrivenExtension` has `visit...Annotations` methods that are called by Spock with all annotations of the
+extension applied to the same target. Their default implementations will then call the respective singular
+`visit...Annotation` method 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 nine 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>>:
 
+`visitSpecAnnotations(List<T> annotations, SpecInfo spec)`::
+  This is called once for each specification where the annotation is applied one or multiple times
+  with the annotation instances as first parameter and the specification info object as second parameter.
+  The default implementation calls `visitSpecAnnotation` once for each given annotation.
+
 `visitSpecAnnotation(T annotation, SpecInfo spec)`::
-  This is called once for each specification where the annotation is applied with the annotation instance as first
-  parameter and the specification info object as second parameter.
+  This is used as singular delegate for `visitSpecAnnotations` and is otherwise not called by Spock directly.
+  The default implementation throws an exception.
 
-`visitFeatureAnnotation(T annotation, FeatureInfo feature)`::
-  This is called once for each feature method where the annotation is applied with the annotation instance as first
-  parameter and the feature info object as second parameter.
+`visitFieldAnnotations(List<T> annotations, FieldInfo field)`::
+  This is called once for each field where the annotation is applied one or multiple times
+  with the annotation instances as first parameter and the field info object as second parameter.
+  The default implementation calls `visitFieldAnnotation` once for each given annotation.
+
+`visitFieldAnnotation(T annotation, FieldInfo field)`::
+  This is used as singular delegate for `visitFieldAnnotations` and is otherwise not called by Spock directly.
+  The default implementation throws an exception.
+
+`visitFixtureAnnotations(List<T> annotations, MethodInfo fixtureMethod)`::
+  This is called once for each fixture method where the annotation is applied one or multiple times
+  with the annotation instances as first parameter and the fixture method info object as second parameter.
+  The default implementation calls `visitFixtureAnnotation` once for each given annotation.
 
 `visitFixtureAnnotation(T annotation, MethodInfo fixtureMethod)`::
-  This is called once for each fixture method where the annotation is applied with the annotation instance as first
-  parameter and the fixture method info object as second parameter.
+  This is used as singular delegate for `visitFixtureAnnotations` and is otherwise not called by Spock directly.
+  The default implementation throws an exception.
 
-`visitFieldAnnotation(T annotation, FieldInfo field)`::
-  This is called once for each field where the annotation is applied with the annotation instance as first parameter and
-  the field info object as second parameter.
+`visitFeatureAnnotations(List<T> annotations, FeatureInfo feature)`::
+  This is called once for each feature method where the annotation is applied one or multiple times
+  with the annotation instances as first parameter and the feature info object as second parameter.
+  The default implementation calls `visitFeatureAnnotation` once for each given annotation.
+
+`visitFeatureAnnotation(T annotation, FeatureInfo feature)`::
+  This is used as singular delegate for `visitFeatureAnnotations` and is otherwise not called by Spock directly.
+  The default implementation throws an exception.
 
 `visitSpec(SpecInfo spec)`::
   This is called once for each specification within which the annotation is applied to at least one of the supported

docs/release_notes.adoc

@@ -3,10 +3,14 @@ include::include.adoc[]
 
 == 2.0-M4 (tbd)
 
-- Add a way to register `ConfigurationObject` globally without the need for a Global Extension
+- 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.
+  Spock will handle this appropriately and call the extensions `visitSpecAnnotations` method with all annotations.
+  If these methods are not overwritten, they forward to the usual `visitSpecAnnotation` methods once for each annotation.
+
+- `AbstractAnnotationDrivenExtension` is now deprecated and its logic was moved to `default` methods of
+  `IAnnotationDrivenExtension` which should be implemented directly now instead of extending the abstract class.
 
 
 == 2.0-M3 (2020-06-11)

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

@@ -19,6 +19,9 @@
 
 import java.lang.annotation.Annotation;
 import java.util.*;
+import java.util.stream.Collectors;
+
+import static java.util.stream.Collectors.toList;
 
 /**
  * Runs global and local extensions for a spec.
@@ -84,9 +87,12 @@ private void doRunAnnotationDrivenExtensions(Iterable<MethodInfo> nodes) {
   private void doRunAnnotationDrivenExtensions(NodeInfo<?, ?> node) {
     RepeatedExtensionAnnotations repeatedExtensionAnnotations = node.getAnnotation(RepeatedExtensionAnnotations.class);
 
-    List<Annotation> annotations;
+    List<List<Annotation>> annotations;
     if (repeatedExtensionAnnotations == null) {
-      annotations = Arrays.asList(node.getAnnotations());
+      annotations = Arrays
+        .stream(node.getAnnotations())
+        .map(Collections::singletonList)
+        .collect(toList());
     } else {
       annotations = new ArrayList<>();
       List<Class<? extends Annotation>> repeatedAnnotations = Arrays.asList(repeatedExtensionAnnotations.value());
@@ -96,34 +102,35 @@ private void doRunAnnotationDrivenExtensions(NodeInfo<?, ?> node) {
         .filter(annotation -> repeatedAnnotations
           .stream()
           .noneMatch(repeatedAnnotation -> repeatedAnnotation.isInstance(annotation)))
+        .map(Collections::singletonList)
         .forEach(annotations::add);
 
       // add all annotations marked as repeated
       for (Class<? extends Annotation> repeatedAnnotation : repeatedAnnotations) {
-        annotations.addAll(Arrays.asList(node.getAnnotationsByType(repeatedAnnotation)));
+        annotations.add(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);
+  private void doRunAnnotationDrivenExtensions(NodeInfo<?, ?> node, List<List<Annotation>> annotations) {
+    for (List<Annotation> ann : annotations) {
+      ExtensionAnnotation extAnn = ann.get(0).annotationType().getAnnotation(ExtensionAnnotation.class);
       if (extAnn == null) continue;
       IAnnotationDrivenExtension extension = getOrCreateExtension(extAnn.value());
       if (node instanceof SpecInfo) {
-        extension.visitSpecAnnotation(ann, (SpecInfo) node);
+        extension.visitSpecAnnotations(ann, (SpecInfo) node);
       } else if (node instanceof MethodInfo) {
         MethodInfo method = (MethodInfo) node;
         if (method.getKind() == MethodKind.FEATURE) {
-          extension.visitFeatureAnnotation(ann, method.getFeature());
+          extension.visitFeatureAnnotations(ann, method.getFeature());
         } else {
-          extension.visitFixtureAnnotation(ann, method);
+          extension.visitFixtureAnnotations(ann, method);
         }
       } else {
-        extension.visitFieldAnnotation(ann, (FieldInfo) node);
+        extension.visitFieldAnnotations(ann, (FieldInfo) node);
       }
     }
   }

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

@@ -16,40 +16,14 @@
 
 package org.spockframework.runtime.extension;
 
-import org.spockframework.runtime.InvalidSpecException;
-import org.spockframework.runtime.model.*;
-
 import java.lang.annotation.Annotation;
 
 /**
  *
  * @author Peter Niederwieser
+ * @deprecated The logic of this class has moved to default methods in {@link IAnnotationDrivenExtension},
+ *             implement that interface directly instead of extending this class
  */
+@Deprecated
 public abstract class AbstractAnnotationDrivenExtension<T extends Annotation> implements IAnnotationDrivenExtension<T> {
-  @Override
-  public void visitSpecAnnotation(T annotation, SpecInfo spec) {
-    throw new InvalidSpecException("@%s may not be applied to Specs")
-        .withArgs(annotation.annotationType().getSimpleName());
-  }
-
-  @Override
-  public void visitFeatureAnnotation(T annotation, FeatureInfo feature) {
-    throw new InvalidSpecException("@%s may not be applied to feature methods")
-        .withArgs(annotation.annotationType().getSimpleName());
-  }
-
-  @Override
-  public void visitFixtureAnnotation(T annotation, MethodInfo fixtureMethod) {
-    throw new InvalidSpecException("@%s may not be applied to fixture methods")
-        .withArgs(annotation.annotationType().getSimpleName());
-  }
-
-  @Override
-  public void visitFieldAnnotation(T annotation, FieldInfo field) {
-    throw new InvalidSpecException("@%s may not be applied to fields")
-        .withArgs(annotation.annotationType().getSimpleName());
-  }
-
-  @Override
-  public void visitSpec(SpecInfo spec) {} // do nothing
 }

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

@@ -17,17 +17,143 @@
 package org.spockframework.runtime.extension;
 
 import java.lang.annotation.Annotation;
+import java.util.List;
 
+import org.spockframework.runtime.InvalidSpecException;
 import org.spockframework.runtime.model.*;
 
 /**
- *
  * @author Peter Niederwieser
  */
 public interface IAnnotationDrivenExtension<T extends Annotation> {
-  void visitSpecAnnotation(T annotation, SpecInfo spec);
-  void visitFeatureAnnotation(T annotation, FeatureInfo feature);
-  void visitFixtureAnnotation(T annotation, MethodInfo fixtureMethod);
-  void visitFieldAnnotation(T annotation, FieldInfo field);
-  void visitSpec(SpecInfo spec);
+  /**
+   * Handles the annotation when applied to a specification one or multiple times.
+   * The default implementation of this method calls {@link #visitSpecAnnotation(Annotation, SpecInfo)}
+   * once for each given annotation.
+   *
+   * @since 2.0
+   * @param annotations the annotations found on the specification
+   * @param spec        the annotated specification
+   */
+  default void visitSpecAnnotations(List<T> annotations, SpecInfo spec) {
+    for (T annotation : annotations) {
+      visitSpecAnnotation(annotation, spec);
+    }
+  }
+
+  /**
+   * Handles the annotation when applied to a specification.
+   * The default implementation of this method throws an {@link InvalidSpecException}.
+   * This method is not called by Spock directly, but only by the default implementation of
+   * {@link #visitSpecAnnotations(List, SpecInfo)}, so if you have overwritten that method,
+   * there is no need to overwrite this one too except if you want to call it yourself.
+   *
+   * @param annotation the annotation found on the specification
+   * @param spec       the annotated specification
+   */
+  default void visitSpecAnnotation(T annotation, SpecInfo spec) {
+    throw new InvalidSpecException("@%s may not be applied to Specs")
+      .withArgs(annotation.annotationType().getSimpleName());
+  }
+
+  /**
+   * Handles the annotation when applied to a field of a specification one or multiple times.
+   * The default implementation of this method calls {@link #visitFieldAnnotation(Annotation, FieldInfo)}
+   * once for each given annotation.
+   *
+   * @since 2.0
+   * @param annotations the annotations found on the field
+   * @param field       the annotated field
+   */
+  default void visitFieldAnnotations(List<T> annotations, FieldInfo field) {
+    for (T annotation : annotations) {
+      visitFieldAnnotation(annotation, field);
+    }
+  }
+
+  /**
+   * Handles the annotation when applied to a field of a specification.
+   * The default implementation of this method throws an {@link InvalidSpecException}.
+   * This method is not called by Spock directly, but only by the default implementation of
+   * {@link #visitFieldAnnotations(List, FieldInfo)}, so if you have overwritten that method,
+   * there is no need to overwrite this one too except if you want to call it yourself.
+   *
+   * @param annotation the annotation found on the field
+   * @param field      the annotated field
+   */
+  default void visitFieldAnnotation(T annotation, FieldInfo field) {
+    throw new InvalidSpecException("@%s may not be applied to fields")
+      .withArgs(annotation.annotationType().getSimpleName());
+  }
+
+  /**
+   * Handles the annotation when applied to a fixture method of a specification one or multiple times.
+   * The default implementation of this method calls {@link #visitFixtureAnnotation(Annotation, MethodInfo)}
+   * once for each given annotation.
+   *
+   * @since 2.0
+   * @param annotations   the annotations found on the fixture method
+   * @param fixtureMethod the annotated fixture method
+   */
+  default void visitFixtureAnnotations(List<T> annotations, MethodInfo fixtureMethod) {
+    for (T annotation : annotations) {
+      visitFixtureAnnotation(annotation, fixtureMethod);
+    }
+  }
+
+  /**
+   * Handles the annotation when applied to a fixture method of a specification.
+   * The default implementation of this method throws an {@link InvalidSpecException}.
+   * This method is not called by Spock directly, but only by the default implementation of
+   * {@link #visitFixtureAnnotations(List, MethodInfo)}, so if you have overwritten that method,
+   * there is no need to overwrite this one too except if you want to call it yourself.
+   *
+   * @param annotation    the annotation found on the fixture method
+   * @param fixtureMethod the annotated fixture method
+   */
+  default void visitFixtureAnnotation(T annotation, MethodInfo fixtureMethod) {
+    throw new InvalidSpecException("@%s may not be applied to fixture methods")
+      .withArgs(annotation.annotationType().getSimpleName());
+  }
+
+  /**
+   * Handles the annotation when applied to a feature method of a specification one or multiple times.
+   * The default implementation of this method calls {@link #visitFeatureAnnotation(Annotation, FeatureInfo)}
+   * once for each given annotation.
+   *
+   * @since 2.0
+   * @param annotations the annotations found on the feature method
+   * @param feature     the annotated feature method
+   */
+  default void visitFeatureAnnotations(List<T> annotations, FeatureInfo feature) {
+    for (T annotation : annotations) {
+      visitFeatureAnnotation(annotation, feature);
+    }
+  }
+
+  /**
+   * Handles the annotation when applied to a feature method of a specification.
+   * The default implementation of this method throws an {@link InvalidSpecException}.
+   * This method is not called by Spock directly, but only by the default implementation of
+   * {@link #visitFeatureAnnotations(List, FeatureInfo)}, so if you have overwritten that method,
+   * there is no need to overwrite this one too except if you want to call it yourself.
+   *
+   * @param annotation the annotation found on the feature method
+   * @param feature    the annotated feature method
+   */
+  default void visitFeatureAnnotation(T annotation, FeatureInfo feature) {
+    throw new InvalidSpecException("@%s may not be applied to feature methods")
+      .withArgs(annotation.annotationType().getSimpleName());
+  }
+
+  /**
+   * Does concluding actions after the single annotations were handled.
+   * This method is called after all the other {@code visit...} methods of this interface to do any concluding
+   * or combining actions that are necessary. It is called once for each extension that has at least one
+   * of its annotation somewhere on the given specification.
+   *
+   * @param spec the annotated specification
+   */
+  default void visitSpec(SpecInfo spec) {
+  }
 }

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

@@ -14,7 +14,7 @@
 
 package org.spockframework.runtime.extension.builtin;
 
-import org.spockframework.runtime.extension.AbstractAnnotationDrivenExtension;
+import org.spockframework.runtime.extension.IAnnotationDrivenExtension;
 import org.spockframework.runtime.model.FieldInfo;
 import org.spockframework.runtime.model.SpecInfo;
 
@@ -23,7 +23,7 @@
 /**
  * @author Peter Niederwieser
  */
-public class AutoCleanupExtension extends AbstractAnnotationDrivenExtension<AutoCleanup> {
+public class AutoCleanupExtension implements IAnnotationDrivenExtension<AutoCleanup> {
   private final AutoCleanupInterceptor sharedFieldInterceptor = new AutoCleanupInterceptor();
   private final AutoCleanupInterceptor instanceFieldInterceptor = new AutoCleanupInterceptor();