refactor(api): disallow null keys or values (#36)

* refactor: disallow null keys or values

* refactor: require non-null ICacheSpec provider

* chore(caffeine3): rename delegate class

* fix(expiringmap): ensure value is non null

* chore: prepare version for stable release

Author: iProdigy

api/src/main/java/io/github/xanthic/cache/api/Cache.java

@@ -13,7 +13,7 @@
  * This interface can be thought as a superset of {@link java.util.Map};
  * less functionality is required here to achieve greater compatibility.
  * <p>
- * There cannot be duplicate keys and null values are not necessarily supported.
+ * There cannot be duplicate keys, and null keys or values are not permitted.
  * <p>
  * Instances should be thread-safe, but no guarantee is made whether
  * this is achieved through fine-grained locking or blunt synchronization.
@@ -30,10 +30,10 @@ public interface Cache<K, V> {
 	 *
 	 * @param key the key whose mapped value should be queried
 	 * @return the value associated with the key in the cache, or null if no such mapping was found
-	 * @throws NullPointerException if the specified key is null and this implementation does not permit null keys
+	 * @throws NullPointerException if the specified key is null
 	 */
 	@Nullable
-	V get(K key);
+	V get(@NotNull K key);
 
 	/**
 	 * Associates the specified key with the specified value,
@@ -42,20 +42,20 @@ public interface Cache<K, V> {
 	 * @param key   the key whose mapping should be created or updated
 	 * @param value the value to be associated with the specified key
 	 * @return the previous value associated with the key, or null if no prior mapping existed
-	 * @throws NullPointerException if the specified key or value is null and this cache does not permit null keys or values
+	 * @throws NullPointerException if the specified key or value is null
 	 */
 	@Nullable
-	V put(K key, V value);
+	V put(@NotNull K key, @NotNull V value);
 
 	/**
 	 * Deletes any mapping that may exist for the specified key.
 	 *
 	 * @param key the key whose mapping should be deleted
 	 * @return the value in the removed mapping, or null if no mapping existed
-	 * @throws NullPointerException if the specified key is null and this cache does not permit null keys
+	 * @throws NullPointerException if the specified key is null
 	 */
 	@Nullable
-	V remove(K key);
+	V remove(@NotNull K key);
 
 	/**
 	 * Removes all entries from the cache.
@@ -73,11 +73,11 @@ public interface Cache<K, V> {
 	 * @param key         the key with which the specified value is to be associated
 	 * @param computeFunc the function to compute a value
 	 * @return the new value associated with the specified key, or null if none
-	 * @throws NullPointerException if the specified key is null and this cache does not support null keys, or the compute function is null
+	 * @throws NullPointerException if the specified key is null or the compute function is null
 	 * @implNote atomicity is dependent on provider characteristics
 	 */
 	@Nullable
-	V compute(K key, @NotNull BiFunction<? super K, ? super V, ? extends V> computeFunc);
+	V compute(@NotNull K key, @NotNull BiFunction<? super K, ? super V, ? extends V> computeFunc);
 
 	/**
 	 * Obtains the value currently associated with the specified key,
@@ -86,9 +86,9 @@ public interface Cache<K, V> {
 	 * @param key         the key whose mapping should be created or returned
 	 * @param computeFunc the value supplier for a given key, if no mapping already existed
 	 * @return the current (existing or computed) value associated with the key
-	 * @throws NullPointerException if the specified key is null and this cache does not permit null keys, or the compute function is null
+	 * @throws NullPointerException if the specified key is null or the compute function is null
 	 */
-	V computeIfAbsent(K key, @NotNull Function<K, V> computeFunc);
+	V computeIfAbsent(@NotNull K key, @NotNull Function<K, V> computeFunc);
 
 	/**
 	 * Computes a new value for a specific key, if a mapping already existed.
@@ -98,10 +98,10 @@ public interface Cache<K, V> {
 	 * @param key         the key whose mapping should be updated
 	 * @param computeFunc the function to compute the new value for an already existing mapping
 	 * @return the new value associated with the key, or null if none
-	 * @throws NullPointerException if the specified key is null and this cache does not support null keys, or the compute function is null
+	 * @throws NullPointerException if the specified key is null or the compute function is null
 	 */
 	@Nullable
-	V computeIfPresent(K key, @NotNull BiFunction<? super K, ? super V, ? extends V> computeFunc);
+	V computeIfPresent(@NotNull K key, @NotNull BiFunction<? super K, ? super V, ? extends V> computeFunc);
 
 	/**
 	 * Creates a mapping from the specified key to the specified value,
@@ -110,10 +110,10 @@ public interface Cache<K, V> {
 	 * @param key   the key whose mapping should be created or returned
 	 * @param value the value that should be associated with the key if no prior mapping exists
 	 * @return the previous value associated with the key, or null if no mapping already existed
-	 * @throws NullPointerException if the specified key or value is null and this cache does not permit null keys or values
+	 * @throws NullPointerException if the specified key or value is null
 	 */
 	@Nullable
-	V putIfAbsent(K key, V value);
+	V putIfAbsent(@NotNull K key, @NotNull V value);
 
 	/**
 	 * Associates the key with the specified value (or the result of the atomic merge function if a mapping already existed).
@@ -122,19 +122,19 @@ public interface Cache<K, V> {
 	 * @param value     the value to be associated with the key or merged with the existing mapped value
 	 * @param mergeFunc the function that takes the existing value and the new value to compute a merged value
 	 * @return the latest value associated with the specified key
-	 * @throws NullPointerException if the specified key is null and this cache does not support null keys or the value or mergeFunc is null
+	 * @throws NullPointerException if the specified key or the value or mergeFunc is null
 	 */
-	V merge(K key, V value, @NotNull BiFunction<V, V, V> mergeFunc);
+	V merge(@NotNull K key, @NotNull V value, @NotNull BiFunction<V, V, V> mergeFunc);
 
 	/**
 	 * Replaces the entry for the specified key only if it is currently mapped to some value.
 	 *
 	 * @param key   the key whose mapped value should be updated
 	 * @param value the value to be associated with the specified key
 	 * @return whether a replacement occurred (a prior mapping must have existed to return true)
-	 * @throws NullPointerException if the specified key or value is null, and this cache does not permit null keys or values
+	 * @throws NullPointerException if the specified key or value is null
 	 */
-	boolean replace(K key, V value);
+	boolean replace(@NotNull K key, @NotNull V value);
 
 	/**
 	 * Replaces the value for the specified key only if it is currently mapped to the specified old value.
@@ -143,15 +143,15 @@ public interface Cache<K, V> {
 	 * @param oldValue the value expected to be already associated with the specified key
 	 * @param newValue the value to be newly associated with the specified key
 	 * @return whether a replacement occurred
-	 * @throws NullPointerException if a specified key or newValue is null, and this cache does not permit null keys or values
+	 * @throws NullPointerException if a specified key or newValue is null
 	 */
-	boolean replace(K key, V oldValue, V newValue);
+	boolean replace(@NotNull K key, @NotNull V oldValue, @NotNull V newValue);
 
 	/**
 	 * Copies all of the mappings from the specified map to this cache.
 	 *
 	 * @param map the map whose entries should be added to this cache
-	 * @throws NullPointerException if the specified map is null, or if this cache does not permit null keys or values, and the specified map contains null keys or values
+	 * @throws NullPointerException if the map is null, or the specified map contains null keys or values
 	 * @implNote There is no behavior guarantee when there are concurrent updates to the map
 	 */
 	default void putAll(@NotNull Map<? extends K, ? extends V> map) {

api/src/main/java/io/github/xanthic/cache/api/ICacheSpec.java

@@ -1,6 +1,7 @@
 package io.github.xanthic.cache.api;
 
 import io.github.xanthic.cache.api.domain.ExpiryType;
+import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 import java.time.Duration;
@@ -21,7 +22,7 @@ public interface ICacheSpec<K, V> {
 	 *
 	 * @return the specific provider that should be used to fulfill the desired cache specification
 	 */
-	@Nullable
+	@NotNull
 	CacheProvider provider();
 
 	/**

build.gradle.kts

@@ -14,7 +14,7 @@ allprojects {
     }
 
     group = "io.github.xanthic.cache"
-    version = "1.0.0-SNAPSHOT"
+    version = "0.1.0"
 }
 
 subprojects {

core/src/main/java/io/github/xanthic/cache/core/AbstractCache.java

@@ -28,7 +28,7 @@
 public abstract class AbstractCache<K, V> implements Cache<K, V> {
 
 	@Override
-	public V computeIfAbsent(K key, @NotNull Function<K, V> computeFunc) {
+	public V computeIfAbsent(@NotNull K key, @NotNull Function<K, V> computeFunc) {
 		synchronized (getLock()) {
 			V old = this.get(key);
 			if (old != null) return old;
@@ -40,7 +40,7 @@ public V computeIfAbsent(K key, @NotNull Function<K, V> computeFunc) {
 
 	@Nullable
 	@Override
-	public V compute(K key, @NotNull BiFunction<? super K, ? super V, ? extends V> computeFunc) {
+	public V compute(@NotNull K key, @NotNull BiFunction<? super K, ? super V, ? extends V> computeFunc) {
 		synchronized (getLock()) {
 			V oldValue = this.get(key);
 			V newValue = computeFunc.apply(key, oldValue);
@@ -55,7 +55,7 @@ public V compute(K key, @NotNull BiFunction<? super K, ? super V, ? extends V> c
 	}
 
 	@Override
-	public V computeIfPresent(K key, @NotNull BiFunction<? super K, ? super V, ? extends V> computeFunc) {
+	public V computeIfPresent(@NotNull K key, @NotNull BiFunction<? super K, ? super V, ? extends V> computeFunc) {
 		synchronized (getLock()) {
 			V oldValue = this.get(key);
 			if (oldValue != null) {
@@ -72,7 +72,7 @@ public V computeIfPresent(K key, @NotNull BiFunction<? super K, ? super V, ? ext
 	}
 
 	@Override
-	public V putIfAbsent(K key, V value) {
+	public V putIfAbsent(@NotNull K key, @NotNull V value) {
 		synchronized (getLock()) {
 			V old = this.get(key);
 			if (old == null) {
@@ -83,7 +83,7 @@ public V putIfAbsent(K key, V value) {
 	}
 
 	@Override
-	public V merge(K key, V value, @NotNull BiFunction<V, V, V> mergeFunc) {
+	public V merge(@NotNull K key, @NotNull V value, @NotNull BiFunction<V, V, V> mergeFunc) {
 		synchronized (getLock()) {
 			V old = putIfAbsent(key, value);
 			if (old == null) return value;
@@ -94,7 +94,7 @@ public V merge(K key, V value, @NotNull BiFunction<V, V, V> mergeFunc) {
 	}
 
 	@Override
-	public boolean replace(K key, V value) {
+	public boolean replace(@NotNull K key, @NotNull V value) {
 		synchronized (getLock()) {
 			V old = this.get(key);
 			if (old == null) return false;
@@ -104,7 +104,8 @@ public boolean replace(K key, V value) {
 	}
 
 	@Override
-	public boolean replace(K key, V oldValue, V newValue) {
+	public boolean replace(@NotNull K key, @NotNull V oldValue, @NotNull V newValue) {
+		// noinspection ConstantConditions
 		if (oldValue == null) return false;
 		synchronized (getLock()) {
 			if (Objects.equals(oldValue, this.get(key))) {

core/src/main/java/io/github/xanthic/cache/core/CacheApiSpec.java

@@ -72,14 +72,16 @@ public void validate() {
 	 * @return CacheApiSpec
 	 * @throws NoDefaultCacheImplementationException if a provider is not specified and no default provider has been set
 	 * @throws MisconfiguredCacheException           if the cache settings are invalid (e.g., negative max size or expiry time)
+	 * @implNote During the building stage, the provider may not be initialized to a non-null value.
 	 */
 	@NotNull
 	public static <K, V> CacheApiSpec<K, V> process(@NotNull Consumer<CacheApiSpec<K, V>> spec) {
 		CacheApiSpec<K, V> data = new CacheApiSpec<>();
 		spec.accept(data);
 
-		// set / init default cache provider if nothing is set
+		// noinspection ConstantConditions
 		if (data.provider() == null) {
+			// set / init default cache provider if nothing is set
 			data.provider(CacheApiSettings.getInstance().getDefaultCacheProvider());
 			log.debug("No cache provider explicitly specified; cache defaults to {}!", data.provider.getClass().getCanonicalName());
 		}

core/src/main/java/io/github/xanthic/cache/core/delegate/GenericMapCacheDelegate.java

@@ -24,33 +24,33 @@ public class GenericMapCacheDelegate<K, V> implements Cache<K, V> {
 	private final Map<K, V> map;
 
 	@Override
-	public V get(K key) {
+	public V get(@NotNull K key) {
 		return map.get(key);
 	}
 
 	@Override
-	public V put(K key, V value) {
+	public V put(@NotNull K key, @NotNull V value) {
 		return map.put(key, value);
 	}
 
 	@Nullable
 	@Override
-	public V compute(K key, @NotNull BiFunction<? super K, ? super V, ? extends V> computeFunc) {
+	public V compute(@NotNull K key, @NotNull BiFunction<? super K, ? super V, ? extends V> computeFunc) {
 		return map.compute(key, computeFunc);
 	}
 
 	@Override
-	public V computeIfAbsent(K key, @NotNull Function<K, V> computeFunc) {
+	public V computeIfAbsent(@NotNull K key, @NotNull Function<K, V> computeFunc) {
 		return map.computeIfAbsent(key, computeFunc);
 	}
 
 	@Override
-	public V computeIfPresent(K key, @NotNull BiFunction<? super K, ? super V, ? extends V> computeFunc) {
+	public V computeIfPresent(@NotNull K key, @NotNull BiFunction<? super K, ? super V, ? extends V> computeFunc) {
 		return map.computeIfPresent(key, computeFunc);
 	}
 
 	@Override
-	public V remove(K key) {
+	public V remove(@NotNull K key) {
 		return map.remove(key);
 	}
 
@@ -65,22 +65,22 @@ public long size() {
 	}
 
 	@Override
-	public V putIfAbsent(K key, V value) {
+	public V putIfAbsent(@NotNull K key, @NotNull V value) {
 		return map.putIfAbsent(key, value);
 	}
 
 	@Override
-	public V merge(K key, V value, @NotNull BiFunction<V, V, V> mergeFunc) {
+	public V merge(@NotNull K key, @NotNull V value, @NotNull BiFunction<V, V, V> mergeFunc) {
 		return map.merge(key, value, mergeFunc);
 	}
 
 	@Override
-	public boolean replace(K key, V value) {
+	public boolean replace(@NotNull K key, @NotNull V value) {
 		return map.replace(key, value) != null;
 	}
 
 	@Override
-	public boolean replace(K key, V oldValue, V newValue) {
+	public boolean replace(@NotNull K key, @NotNull V oldValue, @NotNull V newValue) {
 		return map.replace(key, oldValue, newValue);
 	}
 

provider-androidx/src/main/java/io/github/xanthic/cache/provider/androidx/ExpiringLruDelegate.java

@@ -60,7 +60,7 @@ protected void entryRemoved(boolean evicted, @NotNull K key, @NotNull V oldValue
 	};
 
 	@Override
-	public V get(K key) {
+	public V get(@NotNull K key) {
 		synchronized (getLock()) {
 			V v = cache.get(key);
 			if (type == ExpiryType.POST_ACCESS) start(key, v);
@@ -69,7 +69,7 @@ public V get(K key) {
 	}
 
 	@Override
-	public V put(K key, V value) {
+	public V put(@NotNull K key, @NotNull V value) {
 		synchronized (getLock()) {
 			V prev = cache.put(key, value);
 			start(key, value);
@@ -80,7 +80,7 @@ public V put(K key, V value) {
 	}
 
 	@Override
-	public V remove(K key) {
+	public V remove(@NotNull K key) {
 		synchronized (getLock()) {
 			cancelIfRunning(key, cache.get(key)); // mapping is being removed already
 			return cache.remove(key);

provider-androidx/src/main/java/io/github/xanthic/cache/provider/androidx/LruDelegate.java

@@ -15,18 +15,18 @@ class LruDelegate<K, V> extends AbstractCache<K, V> {
 	LruCache<K, V> cache;
 
 	@Override
-	public V get(K key) {
+	public V get(@NotNull K key) {
 		// note: underlying operations are synchronized on same object
 		return cache.get(key);
 	}
 
 	@Override
-	public V put(K key, V value) {
+	public V put(@NotNull K key, @NotNull V value) {
 		return cache.put(key, value);
 	}
 
 	@Override
-	public V remove(K key) {
+	public V remove(@NotNull K key) {
 		return cache.remove(key);
 	}