#63: added API-annotations for junit-engine-api, API now applicable to Constructor elements

Author: Matthias Merdes

junit-commons/src/main/java/org/junit/gen5/commons/meta/API.java

@@ -26,7 +26,7 @@
  * all public members of this type as well. A member is allowed to declare a
  * different {@link Usage} of lower stability.
  */
-@Target({ ElementType.TYPE, ElementType.METHOD })
+@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR })
 @Retention(RetentionPolicy.CLASS)
 @Documented
 @API(Internal)

junit-engine-api/src/main/java/org/junit/gen5/engine/DiscoveryFilter.java

@@ -11,11 +11,14 @@
 package org.junit.gen5.engine;
 
 import static java.util.Arrays.asList;
+import static org.junit.gen5.commons.meta.API.Usage.Experimental;
 import static org.junit.gen5.commons.util.CollectionUtils.getOnlyElement;
 import static org.junit.gen5.engine.CombinedDiscoveryFilter.alwaysIncluded;
 
 import java.util.Collection;
 
+import org.junit.gen5.commons.meta.API;
+
 /**
  * Filters particular tests during test discovery.
  *
@@ -26,6 +29,7 @@
  * @see EngineDiscoveryRequest
  * @see TestEngine
  */
+@API(Experimental)
 public interface DiscoveryFilter<T> extends Filter<T> {
 
 	/**

junit-engine-api/src/main/java/org/junit/gen5/engine/DiscoverySelector.java

@@ -10,11 +10,16 @@
 
 package org.junit.gen5.engine;
 
+import static org.junit.gen5.commons.meta.API.Usage.Experimental;
+
+import org.junit.gen5.commons.meta.API;
+
 /**
  * A selector defines location(s) a {@link TestEngine} should lookup tests at.
  *
  * @since 5.0
  * @see EngineDiscoveryRequest
  */
+@API(Experimental)
 public interface DiscoverySelector {
 }

junit-engine-api/src/main/java/org/junit/gen5/engine/EngineDiscoveryRequest.java

@@ -10,14 +10,19 @@
 
 package org.junit.gen5.engine;
 
+import static org.junit.gen5.commons.meta.API.Usage.Experimental;
+
 import java.util.List;
 
+import org.junit.gen5.commons.meta.API;
+
 /**
  * An {@code EngineDiscoveryRequest} gives {@link TestEngine}s
  * access to the information necessary to discover {@link TestDescriptor}s.
  *
  * @since 5.0
  */
+@API(Experimental)
 public interface EngineDiscoveryRequest {
 
 	List<DiscoverySelector> getSelectors();

junit-engine-api/src/main/java/org/junit/gen5/engine/EngineExecutionListener.java

@@ -10,6 +10,9 @@
 
 package org.junit.gen5.engine;
 
+import static org.junit.gen5.commons.meta.API.Usage.Experimental;
+
+import org.junit.gen5.commons.meta.API;
 import org.junit.gen5.engine.TestExecutionResult.Status;
 import org.junit.gen5.engine.reporting.ReportEntry;
 
@@ -25,6 +28,7 @@
  * @see TestEngine
  * @see ExecutionRequest
  */
+@API(Experimental)
 public interface EngineExecutionListener {
 
 	/**

junit-engine-api/src/main/java/org/junit/gen5/engine/ExecutionRequest.java

@@ -10,9 +10,15 @@
 
 package org.junit.gen5.engine;
 
+import static org.junit.gen5.commons.meta.API.Usage.Experimental;
+import static org.junit.gen5.commons.meta.API.Usage.Internal;
+
 import java.util.HashMap;
 import java.util.Map;
 
+import org.junit.gen5.commons.meta.API;
+
+@API(Experimental)
 public class ExecutionRequest {
 
 	private final TestDescriptor rootTestDescriptor;
@@ -21,6 +27,7 @@ public class ExecutionRequest {
 
 	private final Map<String, Object> attributes = new HashMap<>();
 
+	@API(Internal)
 	public ExecutionRequest(TestDescriptor rootTestDescriptor, EngineExecutionListener engineExecutionListener) {
 		this.rootTestDescriptor = rootTestDescriptor;
 		this.engineExecutionListener = engineExecutionListener;

junit-engine-api/src/main/java/org/junit/gen5/engine/Filter.java

@@ -10,8 +10,12 @@
 
 package org.junit.gen5.engine;
 
+import static org.junit.gen5.commons.meta.API.Usage.Internal;
+
 import java.util.function.Predicate;
 
+import org.junit.gen5.commons.meta.API;
+
 /**
  * Filters particular tests during/after test discovery.
  *
@@ -22,6 +26,7 @@
  * @see DiscoveryFilter
  */
 @FunctionalInterface
+@API(Internal)
 public interface Filter<T> {
 
 	FilterResult filter(T object);

junit-engine-api/src/main/java/org/junit/gen5/engine/FilterResult.java

@@ -10,16 +10,20 @@
 
 package org.junit.gen5.engine;
 
+import static org.junit.gen5.commons.meta.API.Usage.Experimental;
+
 import java.util.Optional;
 import java.util.function.Supplier;
 
+import org.junit.gen5.commons.meta.API;
 import org.junit.gen5.commons.util.ToStringBuilder;
 
 /**
  * The result of evaluating a {@link Filter}.
  *
  * @since 5.0
  */
+@API(Experimental)
 public class FilterResult {
 
 	/**

junit-engine-api/src/main/java/org/junit/gen5/engine/TestDescriptor.java

@@ -10,14 +10,19 @@
 
 package org.junit.gen5.engine;
 
+import static org.junit.gen5.commons.meta.API.Usage.Experimental;
+
 import java.util.LinkedHashSet;
 import java.util.Optional;
 import java.util.Set;
 import java.util.concurrent.atomic.AtomicLong;
 
+import org.junit.gen5.commons.meta.API;
+
 /**
  * @since 5.0
  */
+@API(Experimental)
 public interface TestDescriptor {
 	/**
 	 * Get the unique identifier (UID) for the described test.

junit-engine-api/src/main/java/org/junit/gen5/engine/TestEngine.java

@@ -10,9 +10,14 @@
 
 package org.junit.gen5.engine;
 
+import static org.junit.gen5.commons.meta.API.Usage.Experimental;
+
+import org.junit.gen5.commons.meta.API;
+
 /**
  * @since 5.0
  */
+@API(Experimental)
 public interface TestEngine {
 
 	default String getId() {