From 34ce0add03dc666b7c9f5d6c499c7efd6479f523 Mon Sep 17 00:00:00 2001
From: Oliver Drotbohm <oliver.drotbohm@broadcom.com>
Date: Tue, 29 Oct 2024 15:20:10 +0100
Subject: [PATCH] GH-919 - Add @CheckReturnValue and use it in Scenario API.

---
 .../modulith/core/util/CheckReturnValue.java  | 38 +++++++++++++++++++
 .../modulith/test/Scenario.java               |  7 ++++
 2 files changed, 45 insertions(+)
 create mode 100644 spring-modulith-core/src/main/java/org/springframework/modulith/core/util/CheckReturnValue.java

diff --git a/spring-modulith-core/src/main/java/org/springframework/modulith/core/util/CheckReturnValue.java b/spring-modulith-core/src/main/java/org/springframework/modulith/core/util/CheckReturnValue.java
new file mode 100644
index 00000000..ea8c8f29
--- /dev/null
+++ b/spring-modulith-core/src/main/java/org/springframework/modulith/core/util/CheckReturnValue.java
@@ -0,0 +1,38 @@
+/*
+ * Copyright 2024 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
+ *
+ *      https://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.springframework.modulith.core.util;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Findbugs and IDEA handle any annotation with name "CheckReturnValue" in return value check.
+ *
+ * @see <a href=
+ *      "https://github.com/findbugsproject/findbugs/blob/264ae7baf890d2b347d91805c90057062b5dcb1e/findbugs/src/java/edu/umd/cs/findbugs/detect/BuildCheckReturnAnnotationDatabase.java#L120">Findbugs
+ *      source code</a>
+ * @since 1.3
+ */
+@Target({
+		ElementType.CONSTRUCTOR,
+		ElementType.METHOD,
+		ElementType.PACKAGE,
+		ElementType.TYPE,
+})
+@Retention(RetentionPolicy.CLASS)
+public @interface CheckReturnValue {}
diff --git a/spring-modulith-test/src/main/java/org/springframework/modulith/test/Scenario.java b/spring-modulith-test/src/main/java/org/springframework/modulith/test/Scenario.java
index 2bbc0a1c..e47298dc 100644
--- a/spring-modulith-test/src/main/java/org/springframework/modulith/test/Scenario.java
+++ b/spring-modulith-test/src/main/java/org/springframework/modulith/test/Scenario.java
@@ -31,6 +31,7 @@ import org.awaitility.Awaitility;
 import org.awaitility.core.ConditionFactory;
 import org.springframework.context.ApplicationEventPublisher;
 import org.springframework.lang.Nullable;
+import org.springframework.modulith.core.util.CheckReturnValue;
 import org.springframework.modulith.test.PublishedEvents.TypedPublishedEvents;
 import org.springframework.modulith.test.PublishedEventsAssert.PublishedEventAssert;
 import org.springframework.modulith.test.Scenario.When.EventResult;
@@ -53,6 +54,7 @@ import org.springframework.util.Assert;
  * @author Oliver Drotbohm
  * @see ApplicationModuleTest
  */
+@CheckReturnValue
 public class Scenario {
 
 	private static final Predicate<Object> DEFAULT_ACCEPTANCE = it -> {
@@ -216,6 +218,7 @@ public class Scenario {
 		return this;
 	}
 
+	@CheckReturnValue
 	public class When<T> {
 
 		private final BiFunction<TransactionOperations, ApplicationEventPublisher, T> stimulus;
@@ -460,6 +463,7 @@ public class Scenario {
 			 * @param eventType must not be {@literal null}.
 			 * @return will never be {@literal null}.
 			 */
+			@CheckReturnValue
 			public <E> EventResult<E> andExpect(Class<E> eventType) {
 				return new EventResult<>(eventType, Function.identity(), result);
 			}
@@ -501,6 +505,7 @@ public class Scenario {
 			 * @param filter must not be {@literal null}.
 			 * @return will never be {@literal null}.
 			 */
+			@CheckReturnValue
 			public EventResult<E> matching(Predicate<? super E> filter) {
 
 				Assert.notNull(filter, "Filter must not be null!");
@@ -517,6 +522,7 @@ public class Scenario {
 			 * @param filter must not be {@literal null}.
 			 * @return will never be {@literal null}.
 			 */
+			@CheckReturnValue
 			public <S> EventResult<E> matchingMapped(Function<E, S> extractor, Predicate<? super S> filter) {
 				return new EventResult<E>(type, createOrAdd(it -> it.matching(extractor, filter)), previousResult);
 			}
@@ -529,6 +535,7 @@ public class Scenario {
 			 * @param value can be {@literal null}.
 			 * @return will never be {@literal null}.
 			 */
+			@CheckReturnValue
 			public <S> EventResult<E> matchingMappedValue(Function<E, S> extractor, @Nullable S value) {
 				return new EventResult<E>(type, createOrAdd(it -> it.matching(extractor, value)), previousResult);
 			}