add jspecify/spotbugs annotations

Author: Sebastian Hoß

memoization-core/pom.xml

@@ -31,4 +31,19 @@
     <!-- https://maven.apache.org/pom.html#More_Project_Information -->
     <name>memoization.java :: Core</name>
 
+    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+    <!--                                DEPENDENCIES                             -->
+    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+    <!-- https://maven.apache.org/pom.html#Dependencies -->
+    <dependencies>
+        <dependency>
+            <groupId>com.github.spotbugs</groupId>
+            <artifactId>spotbugs-annotations</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.jspecify</groupId>
+            <artifactId>jspecify</artifactId>
+        </dependency>
+    </dependencies>
+
 </project>

memoization-core/src/main/java/module-info.java

@@ -5,8 +5,12 @@
 /**
  * The core module contains the core interfaces and utilities of memoization.java
  */
+@org.jspecify.nullness.NullMarked
 module wtf.metio.memoization.core {
 
+    requires com.github.spotbugs.annotations;
+    requires org.jspecify;
+
     exports wtf.metio.memoization.core;
 
 }

memoization-core/src/main/java/wtf/metio/memoization/core/AbstractMemoizer.java

@@ -4,6 +4,8 @@
  */
 package wtf.metio.memoization.core;
 
+import edu.umd.cs.findbugs.annotations.CheckReturnValue;
+
 import java.util.concurrent.ConcurrentMap;
 import java.util.function.Function;
 
@@ -12,9 +14,10 @@ public abstract class AbstractMemoizer<KEY, VALUE> {
     private final ConcurrentMap<KEY, VALUE> cache;
 
     protected AbstractMemoizer(final ConcurrentMap<KEY, VALUE> cache) {
-        this.cache = ConcurrentMaps.nullsafe(cache);
+        this.cache = cache;
     }
 
+    @CheckReturnValue
     protected final VALUE computeIfAbsent(final KEY key, final Function<KEY, VALUE> mappingFunction) {
         return cache.computeIfAbsent(key, mappingFunction);
     }

memoization-core/src/main/java/wtf/metio/memoization/core/ConcurrentMaps.java

@@ -4,27 +4,37 @@
  */
 package wtf.metio.memoization.core;
 
+import edu.umd.cs.findbugs.annotations.CheckReturnValue;
+
 import java.util.Map;
+import java.util.Objects;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentMap;
 
-import static java.util.Objects.requireNonNull;
-
+/**
+ * Utility class that helps with handling {@link ConcurrentMap}s.
+ */
 public final class ConcurrentMaps {
 
     private ConcurrentMaps() {
         // utility class
     }
 
+    /**
+     * Converts a given {@link Map} to a {@link ConcurrentMap}.
+     *
+     * @param map The given map.
+     * @return The converted map which may be the given one if it is already a {@link ConcurrentMap}.
+     * @param <KEY> The key type of the map.
+     * @param <VALUE> The value type of the map.
+     */
+    @CheckReturnValue
     public static <KEY, VALUE> ConcurrentMap<KEY, VALUE> asConcurrentMap(final Map<KEY, VALUE> map) {
+        Objects.requireNonNull(map, "Provide a non-null map or remove your custom cache entirely");
         if (ConcurrentMap.class.isAssignableFrom(map.getClass())) {
-            return (ConcurrentMap<KEY, VALUE>) nullsafe(map);
+            return (ConcurrentMap<KEY, VALUE>) map;
         }
-        return new ConcurrentHashMap<>(nullsafe(map));
-    }
-
-    public static <MAP extends Map<?, ?>> MAP nullsafe(final MAP map) {
-        return requireNonNull(map, "Provide an empty map instead of NULL.");
+        return new ConcurrentHashMap<>(map);
     }
 
 }

memoization-core/src/main/java/wtf/metio/memoization/core/MemoizationDefaults.java

@@ -4,6 +4,8 @@
  */
 package wtf.metio.memoization.core;
 
+import edu.umd.cs.findbugs.annotations.CheckReturnValue;
+
 import java.util.Arrays;
 import java.util.function.Supplier;
 
@@ -21,6 +23,7 @@ private MemoizationDefaults() {
      *
      * @return The default key supplier used throughout the library.
      */
+    @CheckReturnValue
     public static Supplier<Integer> staticKey() {
         return () -> 1;
     }
@@ -31,6 +34,7 @@ public static Supplier<Integer> staticKey() {
      * @param values The values to use.
      * @return The constructed cache key.
      */
+    @CheckReturnValue
     public static int hashCodes(final Object... values) {
         return Arrays.hashCode(values);
     }

memoization-core/src/main/java/wtf/metio/memoization/core/WrappedException.java

@@ -5,6 +5,8 @@
 
 package wtf.metio.memoization.core;
 
+import edu.umd.cs.findbugs.annotations.CheckReturnValue;
+
 import java.io.Serial;
 
 public final class WrappedException extends RuntimeException {
@@ -18,6 +20,7 @@ public WrappedException(final Exception wrappedException) {
         this.wrappedException = wrappedException;
     }
 
+    @CheckReturnValue
     public Exception wrappedException() {
         return wrappedException;
     }

memoization-core/src/main/java/wtf/metio/memoization/core/WrappedThrowable.java

@@ -5,6 +5,8 @@
 
 package wtf.metio.memoization.core;
 
+import edu.umd.cs.findbugs.annotations.CheckReturnValue;
+
 import java.io.Serial;
 
 public final class WrappedThrowable extends RuntimeException {
@@ -18,6 +20,7 @@ public WrappedThrowable(final Throwable wrappedThrowable) {
         this.wrappedThrowable = wrappedThrowable;
     }
 
+    @CheckReturnValue
     public Throwable wrappedThrowable() {
         return wrappedThrowable;
     }

memoization-core/src/main/java/wtf/metio/memoization/core/package-info.java

@@ -4,7 +4,5 @@
  */
 /**
  * Core interfaces and utilities.
- *
- * @see wtf.metio.memoization.core.MemoizationDefaults
  */
 package wtf.metio.memoization.core;

memoization-jdk/pom.xml

@@ -49,6 +49,10 @@
             <groupId>com.github.spotbugs</groupId>
             <artifactId>spotbugs-annotations</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.jspecify</groupId>
+            <artifactId>jspecify</artifactId>
+        </dependency>
         <dependency>
             <groupId>org.mockito</groupId>
             <artifactId>mockito-core</artifactId>

memoization-jdk/src/main/java/module-info.java

@@ -5,10 +5,12 @@
 /**
  * The JDK module contains the implementation covering JDK interfaces.
  */
+@org.jspecify.nullness.NullMarked
 module wtf.metio.memoization.jdk {
 
     requires wtf.metio.memoization.core;
     requires com.github.spotbugs.annotations;
+    requires org.jspecify;
 
     exports wtf.metio.memoization.jdk;