Annotate nullability in org.junit.platform.engine

Author: marcphilipp

junit-platform-engine/src/main/java/org/junit/platform/engine/DefaultDiscoveryIssue.java

@@ -13,6 +13,7 @@
 import java.util.Objects;
 import java.util.Optional;
 
+import org.jspecify.annotations.Nullable;
 import org.junit.platform.commons.util.ToStringBuilder;
 
 /**
@@ -22,7 +23,11 @@ final class DefaultDiscoveryIssue implements DiscoveryIssue {
 
 	private final Severity severity;
 	private final String message;
+
+	@Nullable
 	private final TestSource source;
+
+	@Nullable
 	private final Throwable cause;
 
 	DefaultDiscoveryIssue(Builder builder) {
@@ -86,7 +91,11 @@ static class Builder implements DiscoveryIssue.Builder {
 
 		private final Severity severity;
 		private final String message;
+
+		@Nullable
 		private TestSource source;
+
+		@Nullable
 		public Throwable cause;
 
 		Builder(Severity severity, String message) {
@@ -95,13 +104,13 @@ static class Builder implements DiscoveryIssue.Builder {
 		}
 
 		@Override
-		public Builder source(TestSource source) {
+		public Builder source(@Nullable TestSource source) {
 			this.source = source;
 			return this;
 		}
 
 		@Override
-		public Builder cause(Throwable cause) {
+		public Builder cause(@Nullable Throwable cause) {
 			this.cause = cause;
 			return this;
 		}

junit-platform-engine/src/main/java/org/junit/platform/engine/DiscoveryIssue.java

@@ -16,6 +16,7 @@
 import java.util.function.UnaryOperator;
 
 import org.apiguardian.api.API;
+import org.jspecify.annotations.Nullable;
 import org.junit.platform.commons.util.Preconditions;
 
 /**
@@ -138,7 +139,7 @@ default Builder source(Optional<TestSource> source) {
 		 * @param source the {@link TestSource} for the {@code DiscoveryIssue};
 		 * may be {@code null}
 		 */
-		Builder source(TestSource source);
+		Builder source(@Nullable TestSource source);
 
 		/**
 		 * Set the {@link Throwable} that caused the {@code DiscoveryIssue}.
@@ -157,7 +158,7 @@ default Builder cause(Optional<Throwable> cause) {
 		 * @param cause the {@link Throwable} that caused the
 		 * {@code DiscoveryIssue}; may be {@code null}
 		 */
-		Builder cause(Throwable cause);
+		Builder cause(@Nullable Throwable cause);
 
 		/**
 		 * Build the {@code DiscoveryIssue}.

junit-platform-engine/src/main/java/org/junit/platform/engine/EngineDiscoveryRequest.java

@@ -46,7 +46,8 @@ public interface EngineDiscoveryRequest {
 	 * Get the {@link DiscoverySelector DiscoverySelectors} for this request,
 	 * filtered by a particular type.
 	 *
-	 * @param selectorType the type of {@link DiscoverySelector} to filter by
+	 * @param selectorType the type of {@link DiscoverySelector} to filter by;
+	 * never {@code null}
 	 * @return all selectors of this request that are instances of
 	 * {@code selectorType}; never {@code null} but potentially empty
 	 */
@@ -59,7 +60,8 @@ public interface EngineDiscoveryRequest {
 	 * <p>The returned filters are to be combined using AND semantics, i.e. all
 	 * of them have to include a resource for it to end up in the test plan.
 	 *
-	 * @param filterType the type of {@link DiscoveryFilter} to filter by
+	 * @param filterType the type of {@link DiscoveryFilter} to filter by;
+	 * never {@code null}
 	 * @return all filters of this request that are instances of
 	 * {@code filterType}; never {@code null} but potentially empty
 	 */

junit-platform-engine/src/main/java/org/junit/platform/engine/ExecutionRequest.java

@@ -16,6 +16,7 @@
 import static org.apiguardian.api.API.Status.STABLE;
 
 import org.apiguardian.api.API;
+import org.jspecify.annotations.Nullable;
 import org.junit.platform.commons.PreconditionViolationException;
 import org.junit.platform.commons.util.Preconditions;
 import org.junit.platform.engine.reporting.OutputDirectoryProvider;
@@ -41,7 +42,11 @@ public class ExecutionRequest {
 	private final TestDescriptor rootTestDescriptor;
 	private final EngineExecutionListener engineExecutionListener;
 	private final ConfigurationParameters configurationParameters;
+
+	@Nullable
 	private final OutputDirectoryProvider outputDirectoryProvider;
+
+	@Nullable
 	private final NamespacedHierarchicalStore<Namespace> requestLevelStore;
 
 	@Deprecated
@@ -52,8 +57,8 @@ public ExecutionRequest(TestDescriptor rootTestDescriptor, EngineExecutionListen
 	}
 
 	private ExecutionRequest(TestDescriptor rootTestDescriptor, EngineExecutionListener engineExecutionListener,
-			ConfigurationParameters configurationParameters, OutputDirectoryProvider outputDirectoryProvider,
-			NamespacedHierarchicalStore<Namespace> requestLevelStore) {
+			ConfigurationParameters configurationParameters, @Nullable OutputDirectoryProvider outputDirectoryProvider,
+			@Nullable NamespacedHierarchicalStore<Namespace> requestLevelStore) {
 		this.rootTestDescriptor = Preconditions.notNull(rootTestDescriptor, "rootTestDescriptor must not be null");
 		this.engineExecutionListener = Preconditions.notNull(engineExecutionListener,
 			"engineExecutionListener must not be null");

junit-platform-engine/src/main/java/org/junit/platform/engine/FilterResult.java

@@ -16,6 +16,7 @@
 import java.util.function.Supplier;
 
 import org.apiguardian.api.API;
+import org.jspecify.annotations.Nullable;
 import org.junit.platform.commons.util.ToStringBuilder;
 
 /**
@@ -32,7 +33,7 @@ public class FilterResult {
 	 * @param reason the reason why the filtered object was included
 	 * @return an included {@code FilterResult} with the given reason
 	 */
-	public static FilterResult included(String reason) {
+	public static FilterResult included(@Nullable String reason) {
 		return new FilterResult(true, reason);
 	}
 
@@ -42,14 +43,14 @@ public static FilterResult included(String reason) {
 	 * @param reason the reason why the filtered object was excluded
 	 * @return an excluded {@code FilterResult} with the given reason
 	 */
-	public static FilterResult excluded(String reason) {
+	public static FilterResult excluded(@Nullable String reason) {
 		return new FilterResult(false, reason);
 	}
 
 	/**
 	 * Factory for creating filter results based on the condition given.
 	 *
-	 * @param included whether or not the filtered object should be included
+	 * @param included whether the filtered object should be included
 	 * @return a valid {@code FilterResult} for the given condition
 	 */
 	public static FilterResult includedIf(boolean included) {
@@ -59,21 +60,21 @@ public static FilterResult includedIf(boolean included) {
 	/**
 	 * Factory for creating filter results based on the condition given.
 	 *
-	 * @param included whether or not the filtered object should be included
+	 * @param included whether the filtered object should be included
 	 * @param inclusionReasonSupplier supplier for the reason in case of inclusion
 	 * @param exclusionReasonSupplier supplier for the reason in case of exclusion
 	 * @return a valid {@code FilterResult} for the given condition
 	 */
-	public static FilterResult includedIf(boolean included, Supplier<String> inclusionReasonSupplier,
-			Supplier<String> exclusionReasonSupplier) {
+	public static FilterResult includedIf(boolean included, Supplier<@Nullable String> inclusionReasonSupplier,
+			Supplier<@Nullable String> exclusionReasonSupplier) {
 		return included ? included(inclusionReasonSupplier.get()) : excluded(exclusionReasonSupplier.get());
 	}
 
 	private final boolean included;
 
 	private final Optional<String> reason;
 
-	private FilterResult(boolean included, String reason) {
+	private FilterResult(boolean included, @Nullable String reason) {
 		this.included = included;
 		this.reason = Optional.ofNullable(reason);
 	}

junit-platform-engine/src/main/java/org/junit/platform/engine/SelectorResolutionResult.java

@@ -15,6 +15,7 @@
 import java.util.Optional;
 
 import org.apiguardian.api.API;
+import org.jspecify.annotations.Nullable;
 import org.junit.platform.commons.util.ToStringBuilder;
 
 /**
@@ -86,9 +87,11 @@ public static SelectorResolutionResult failed(Throwable throwable) {
 	}
 
 	private final Status status;
+
+	@Nullable
 	private final Throwable throwable;
 
-	private SelectorResolutionResult(Status status, Throwable throwable) {
+	private SelectorResolutionResult(Status status, @Nullable Throwable throwable) {
 		this.status = status;
 		this.throwable = throwable;
 	}

junit-platform-engine/src/main/java/org/junit/platform/engine/TestDescriptor.java

@@ -22,6 +22,7 @@
 import java.util.function.UnaryOperator;
 
 import org.apiguardian.api.API;
+import org.jspecify.annotations.Nullable;
 import org.junit.platform.commons.util.Preconditions;
 
 /**
@@ -99,7 +100,7 @@ default String getLegacyReportingName() {
 	 *
 	 * @param parent the new parent of this descriptor; may be {@code null}.
 	 */
-	void setParent(TestDescriptor parent);
+	void setParent(@Nullable TestDescriptor parent);
 
 	/**
 	 * Get the immutable set of <em>children</em> of this descriptor.

junit-platform-engine/src/main/java/org/junit/platform/engine/TestExecutionResult.java

@@ -18,6 +18,7 @@
 import java.util.Optional;
 
 import org.apiguardian.api.API;
+import org.jspecify.annotations.Nullable;
 import org.junit.platform.commons.util.Preconditions;
 import org.junit.platform.commons.util.ToStringBuilder;
 
@@ -94,9 +95,11 @@ public static TestExecutionResult failed(Throwable throwable) {
 	}
 
 	private final Status status;
+
+	@Nullable
 	private final Throwable throwable;
 
-	private TestExecutionResult(Status status, Throwable throwable) {
+	private TestExecutionResult(Status status, @Nullable Throwable throwable) {
 		this.status = Preconditions.notNull(status, "Status must not be null");
 		this.throwable = throwable;
 	}

junit-platform-engine/src/main/java/org/junit/platform/engine/TestTag.java

@@ -21,6 +21,7 @@
 import java.util.Set;
 
 import org.apiguardian.api.API;
+import org.jspecify.annotations.Nullable;
 import org.junit.platform.commons.PreconditionViolationException;
 import org.junit.platform.commons.util.Preconditions;
 import org.junit.platform.commons.util.StringUtils;
@@ -84,7 +85,7 @@ public final class TestTag implements Serializable {
 	 * @see #RESERVED_CHARACTERS
 	 * @see TestTag#create(String)
 	 */
-	public static boolean isValid(String name) {
+	public static boolean isValid(@Nullable String name) {
 		if (name == null) {
 			return false;
 		}

junit-platform-engine/src/main/java/org/junit/platform/engine/UniqueId.java

@@ -23,6 +23,7 @@
 import java.util.Optional;
 
 import org.apiguardian.api.API;
+import org.jspecify.annotations.Nullable;
 import org.junit.platform.commons.JUnitException;
 import org.junit.platform.commons.util.Preconditions;
 import org.junit.platform.commons.util.ToStringBuilder;
@@ -92,6 +93,7 @@ public static UniqueId root(String segmentType, String value) {
 	private transient int hashCode;
 
 	// lazily computed
+	@Nullable
 	private transient SoftReference<String> toString;
 
 	private UniqueId(UniqueIdFormat uniqueIdFormat, Segment segment) {