JSR-305 migrations (fixes #242)

Migrate removed usages of @nonnegative (prior commit) to @nonnegative.

Add generic type @nonnull where not excessively verbose.

caffeine/src/main/java/com/github/benmanes/caffeine/cache/AsyncCacheLoader.java

@@ -69,8 +69,8 @@ public interface AsyncCacheLoader<K, V> {
    *         that key; <b>may not contain null values</b>
    */
   @NonNull
-  default CompletableFuture<Map<K, V>> asyncLoadAll(
-      @NonNull Iterable<? extends K> keys, @NonNull Executor executor) {
+  default CompletableFuture<Map<@NonNull K, @NonNull V>> asyncLoadAll(
+      @NonNull Iterable<? extends @NonNull K> keys, @NonNull Executor executor) {
     throw new UnsupportedOperationException();
   }
 

caffeine/src/main/java/com/github/benmanes/caffeine/cache/AsyncLoadingCache.java

@@ -79,7 +79,7 @@ public interface AsyncLoadingCache<K, V> extends AsyncCache<K, V> {
    *         future, in which case the mapping is left unestablished
    */
   @NonNull
-  CompletableFuture<Map<K, V>> getAll(@NonNull Iterable<? extends K> keys);
+  CompletableFuture<Map<K, V>> getAll(@NonNull Iterable<? extends @NonNull K> keys);
 
   /**
    * Returns a view of the entries stored in this cache as a synchronous {@link LoadingCache}. A

caffeine/src/main/java/com/github/benmanes/caffeine/cache/Cache.java

@@ -19,6 +19,7 @@
 import java.util.concurrent.ConcurrentMap;
 import java.util.function.Function;
 
+import org.checkerframework.checker.index.qual.NonNegative;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
@@ -90,7 +91,7 @@ public interface Cache<K, V> {
    * @throws NullPointerException if the specified collection is null or contains a null element
    */
   @NonNull
-  Map<K, V> getAllPresent(@NonNull Iterable<?> keys);
+  Map<@NonNull K, @NonNull V> getAllPresent(@NonNull Iterable<@NonNull ?> keys);
 
   /**
    * Associates the {@code value} with the {@code key} in this cache. If the cache previously
@@ -116,7 +117,7 @@ public interface Cache<K, V> {
    * @throws NullPointerException if the specified map is null or the specified map contains null
    *         keys or values
    */
-  void putAll(@NonNull Map<? extends K,? extends V> map);
+  void putAll(@NonNull Map<? extends @NonNull K,? extends @NonNull V> map);
 
   /**
    * Discards any cached value for the {@code key}. The behavior of this operation is undefined for
@@ -150,6 +151,7 @@ public interface Cache<K, V> {
    *
    * @return the estimated number of mappings
    */
+  @NonNegative
   long estimatedSize();
 
   /**
@@ -175,7 +177,7 @@ public interface Cache<K, V> {
    * @return a thread-safe view of this cache supporting all of the optional {@link Map} operations
    */
   @NonNull
-  ConcurrentMap<K, V> asMap();
+  ConcurrentMap<@NonNull K, @NonNull V> asMap();
 
   /**
    * Performs any pending maintenance operations needed by the cache. Exactly which activities are

caffeine/src/main/java/com/github/benmanes/caffeine/cache/CacheLoader.java

@@ -83,7 +83,8 @@ public interface CacheLoader<K, V> extends AsyncCacheLoader<K, V> {
    *         caught, the thread's interrupt status is set
    */
   @NonNull
-  default Map<K, V> loadAll(@NonNull Iterable<? extends K> keys) throws Exception {
+  default Map<@NonNull K, @NonNull V> loadAll(
+      @NonNull Iterable<? extends @NonNull K> keys) throws Exception {
     throw new UnsupportedOperationException();
   }
 
@@ -128,7 +129,7 @@ default CompletableFuture<V> asyncLoad(@NonNull K key, @NonNull Executor executo
    *         that key; <b>may not contain null values</b>
    */
   @Override @NonNull
-  default CompletableFuture<Map<K, V>> asyncLoadAll(
+  default CompletableFuture<Map<@NonNull K, @NonNull V>> asyncLoadAll(
       @NonNull Iterable<? extends K> keys, @NonNull Executor executor) {
     requireNonNull(keys);
     requireNonNull(executor);

caffeine/src/main/java/com/github/benmanes/caffeine/cache/Caffeine.java

@@ -34,6 +34,7 @@
 import java.util.logging.Level;
 import java.util.logging.Logger;
 
+import org.checkerframework.checker.index.qual.NonNegative;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
@@ -243,7 +244,7 @@ public static Caffeine<Object, Object> from(String spec) {
    * @throws IllegalStateException if an initial capacity was already set
    */
   @NonNull
-  public Caffeine<K, V> initialCapacity(int initialCapacity) {
+  public Caffeine<K, V> initialCapacity(@NonNegative int initialCapacity) {
     requireState(this.initialCapacity == UNSET_INT,
         "initial capacity was already set to %s", this.initialCapacity);
     requireArgument(initialCapacity >= 0);
@@ -306,7 +307,7 @@ Executor getExecutor() {
    * @throws IllegalStateException if a maximum size or weight was already set
    */
   @NonNull
-  public Caffeine<K, V> maximumSize(long maximumSize) {
+  public Caffeine<K, V> maximumSize(@NonNegative long maximumSize) {
     requireState(this.maximumSize == UNSET_INT,
         "maximum size was already set to %s", this.maximumSize);
     requireState(this.maximumWeight == UNSET_INT,
@@ -342,7 +343,7 @@ public Caffeine<K, V> maximumSize(long maximumSize) {
    * @throws IllegalStateException if a maximum weight or size was already set
    */
   @NonNull
-  public Caffeine<K, V> maximumWeight(long maximumWeight) {
+  public Caffeine<K, V> maximumWeight(@NonNegative long maximumWeight) {
     requireState(this.maximumWeight == UNSET_INT,
         "maximum weight was already set to %s", this.maximumWeight);
     requireState(this.maximumSize == UNSET_INT,
@@ -546,7 +547,7 @@ public Caffeine<K, V> expireAfterWrite(@NonNull Duration duration) {
    * @throws IllegalStateException if the time to live or variable expiration was already set
    */
   @NonNull
-  public Caffeine<K, V> expireAfterWrite(long duration, @NonNull TimeUnit unit) {
+  public Caffeine<K, V> expireAfterWrite(@NonNegative long duration, @NonNull TimeUnit unit) {
     requireState(expireAfterWriteNanos == UNSET_INT,
         "expireAfterWrite was already set to %s ns", expireAfterWriteNanos);
     requireState(expiry == null, "expireAfterAccess may not be used with variable expiration");
@@ -605,7 +606,7 @@ public Caffeine<K, V> expireAfterAccess(@NonNull Duration duration) {
    * @throws IllegalStateException if the time to idle or variable expiration was already set
    */
   @NonNull
-  public Caffeine<K, V> expireAfterAccess(long duration, @NonNull TimeUnit unit) {
+  public Caffeine<K, V> expireAfterAccess(@NonNegative long duration, @NonNull TimeUnit unit) {
     requireState(expireAfterAccessNanos == UNSET_INT,
         "expireAfterAccess was already set to %s ns", expireAfterAccessNanos);
     requireState(expiry == null, "expireAfterAccess may not be used with variable expiration");
@@ -710,7 +711,7 @@ public Caffeine<K, V> refreshAfterWrite(@NonNull Duration duration) {
    * @throws IllegalStateException if the refresh interval was already set
    */
   @NonNull
-  public Caffeine<K, V> refreshAfterWrite(long duration, @NonNull TimeUnit unit) {
+  public Caffeine<K, V> refreshAfterWrite(@NonNegative long duration, @NonNull TimeUnit unit) {
     requireNonNull(unit);
     requireState(refreshNanos == UNSET_INT, "refresh was already set to %s ns", refreshNanos);
     requireArgument(duration > 0, "duration must be positive: %s %s", duration, unit);

caffeine/src/main/java/com/github/benmanes/caffeine/cache/CaffeineSpec.java

@@ -23,6 +23,7 @@
 import java.util.Objects;
 import java.util.concurrent.TimeUnit;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 import com.github.benmanes.caffeine.cache.Caffeine.Strength;
@@ -145,7 +146,7 @@ Caffeine<Object, Object> toBuilder() {
    * @return the parsed specification
    */
   @SuppressWarnings("StringSplitter")
-  public static CaffeineSpec parse(String specification) {
+  public static @NonNull CaffeineSpec parse(@NonNull String specification) {
     CaffeineSpec spec = new CaffeineSpec(specification);
     for (String option : specification.split(SPLIT_OPTIONS)) {
       spec.parseOption(option.trim());

caffeine/src/main/java/com/github/benmanes/caffeine/cache/Expiry.java

@@ -15,6 +15,7 @@
  */
 package com.github.benmanes.caffeine.cache;
 
+import org.checkerframework.checker.index.qual.NonNegative;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
@@ -57,7 +58,8 @@ public interface Expiry<K, V> {
    * @param currentDuration the current duration, in nanoseconds
    * @return the length of time before the entry expires, in nanoseconds
    */
-  long expireAfterUpdate(@NonNull K key, @NonNull V value, long currentTime, long currentDuration);
+  long expireAfterUpdate(@NonNull K key, @NonNull V value,
+      long currentTime, @NonNegative long currentDuration);
 
   /**
    * Specifies that the entry should be automatically removed from the cache once the duration has
@@ -75,5 +77,6 @@ public interface Expiry<K, V> {
    * @param currentDuration the current duration, in nanoseconds
    * @return the length of time before the entry expires, in nanoseconds
    */
-  long expireAfterRead(@NonNull K key, @NonNull V value, long currentTime, long currentDuration);
+  long expireAfterRead(@NonNull K key, @NonNull V value,
+      long currentTime, @NonNegative long currentDuration);
 }

caffeine/src/main/java/com/github/benmanes/caffeine/cache/FrequencySketch.java

@@ -19,6 +19,7 @@
 
 import java.util.concurrent.ThreadLocalRandom;
 
+import org.checkerframework.checker.index.qual.NonNegative;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
@@ -87,7 +88,7 @@ public FrequencySketch() {
    *
    * @param maximumSize the maximum size of the cache
    */
-  public void ensureCapacity(long maximumSize) {
+  public void ensureCapacity(@NonNegative long maximumSize) {
     requireArgument(maximumSize >= 0);
     int maximum = (int) Math.min(maximumSize, Integer.MAX_VALUE >>> 1);
     if ((table != null) && (table.length >= maximum)) {
@@ -117,6 +118,7 @@ public boolean isNotInitialized() {
    * @param e the element to count occurrences of
    * @return the estimated number of occurrences of the element; possibly zero but never negative
    */
+  @NonNegative
   public int frequency(@NonNull E e) {
     if (isNotInitialized()) {
       return 0;

caffeine/src/main/java/com/github/benmanes/caffeine/cache/LoadingCache.java

@@ -89,7 +89,7 @@ public interface LoadingCache<K, V> extends Cache<K, V> {
    *         is left unestablished
    */
   @NonNull
-  Map<K, V> getAll(@NonNull Iterable<? extends K> keys);
+  Map<@NonNull K, @NonNull V> getAll(@NonNull Iterable<? extends @NonNull K> keys);
 
   /**
    * Loads a new value for the {@code key}, asynchronously. While the new value is loading the

caffeine/src/main/java/com/github/benmanes/caffeine/cache/Node.java

@@ -17,6 +17,7 @@
 
 import java.lang.ref.ReferenceQueue;
 
+import org.checkerframework.checker.index.qual.NonNegative;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
@@ -69,24 +70,26 @@ abstract class Node<K, V> implements AccessOrder<Node<K, V>>, WriteOrder<Node<K,
   public abstract boolean containsValue(@NonNull Object value);
 
   /** Returns the weight of this entry from the entry's perspective. */
+  @NonNegative
   @GuardedBy("this")
   public int getWeight() {
     return 1;
   }
 
   /** Sets the weight from the entry's perspective. */
   @GuardedBy("this")
-  public void setWeight(int weight) {}
+  public void setWeight(@NonNegative int weight) {}
 
   /** Returns the weight of this entry from the policy's perspective. */
+  @NonNegative
   @GuardedBy("evictionLock")
   public int getPolicyWeight() {
     return 1;
   }
 
   /** Sets the weight from the policy's perspective. */
   @GuardedBy("evictionLock")
-  public void setPolicyWeight(int weight) {}
+  public void setPolicyWeight(@NonNegative int weight) {}
 
   /* ---------------- Health -------------- */
 

caffeine/src/main/java/com/github/benmanes/caffeine/cache/Policy.java

@@ -22,6 +22,7 @@
 import java.util.OptionalLong;
 import java.util.concurrent.TimeUnit;
 
+import org.checkerframework.checker.index.qual.NonNegative;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
@@ -148,6 +149,7 @@ default OptionalInt weightOf(@NonNull K key) {
      *
      * @return the maximum size bounding, which may be either weighted or unweighted
      */
+    @NonNegative
     long getMaximum();
 
     /**
@@ -163,7 +165,7 @@ default OptionalInt weightOf(@NonNull K key) {
      *        cache was constructed
      * @throws IllegalArgumentException if the maximum size specified is negative
      */
-    void setMaximum(long maximum);
+    void setMaximum(@NonNegative long maximum);
 
     /**
      * Returns an unmodifiable snapshot {@link Map} view of the cache with ordered traversal. The
@@ -180,7 +182,7 @@ default OptionalInt weightOf(@NonNull K key) {
      * @return a snapshot view of the cache from coldest entry to the hottest
      */
     @NonNull
-    Map<K, V> coldest(int limit);
+    Map<@NonNull K, @NonNull V> coldest(@NonNegative int limit);
 
     /**
      * Returns an unmodifiable snapshot {@link Map} view of the cache with ordered traversal. The
@@ -197,7 +199,7 @@ default OptionalInt weightOf(@NonNull K key) {
      * @return a snapshot view of the cache from hottest entry to the coldest
      */
     @NonNull
-    Map<K, V> hottest(int limit);
+    Map<@NonNull K, @NonNull V> hottest(@NonNegative int limit);
   }
 
   /** The low-level operations for a cache with a fixed expiration policy. */
@@ -251,6 +253,7 @@ default Optional<Duration> ageOf(@NonNull K key) {
      * @param unit the unit that duration is expressed in
      * @return the length of time after which an entry should be automatically removed
      */
+    @NonNegative
     long getExpiresAfter(@NonNull TimeUnit unit);
 
     /**
@@ -277,7 +280,7 @@ default Duration getExpiresAfter() {
      * @param unit the unit that {@code duration} is expressed in
      * @throws IllegalArgumentException if {@code duration} is negative
      */
-    void setExpiresAfter(long duration, @NonNull TimeUnit unit);
+    void setExpiresAfter(@NonNegative long duration, @NonNull TimeUnit unit);
 
     /**
      * Specifies that each entry should be automatically removed from the cache once a fixed
@@ -306,7 +309,7 @@ default void setExpiresAfter(@NonNull Duration duration) {
      * @return a snapshot view of the cache from oldest entry to the youngest
      */
     @NonNull
-    Map<K, V> oldest(int limit);
+    Map<@NonNull K, @NonNull V> oldest(@NonNegative int limit);
 
     /**
      * Returns an unmodifiable snapshot {@link Map} view of the cache with ordered traversal. The
@@ -323,7 +326,7 @@ default void setExpiresAfter(@NonNull Duration duration) {
      * @return a snapshot view of the cache from youngest entry to the oldest
      */
     @NonNull
-    Map<K, V> youngest(int limit);
+    Map<@NonNull K, @NonNull V> youngest(@NonNegative int limit);
   }
 
   /** The low-level operations for a cache with a variable expiration policy. */
@@ -368,7 +371,7 @@ default Optional<Duration> getExpiresAfter(@NonNull K key) {
      * @throws IllegalArgumentException if {@code duration} is negative
      * @throws NullPointerException if the unit is null
      */
-    void setExpiresAfter(@NonNull K key, long duration, @NonNull TimeUnit unit);
+    void setExpiresAfter(@NonNull K key, @NonNegative long duration, @NonNull TimeUnit unit);
 
     /**
      * Specifies that the entry should be automatically removed from the cache once the duration has
@@ -399,7 +402,7 @@ default void setExpiresAfter(@NonNull K key, @NonNull Duration duration) {
      * @throws IllegalArgumentException if {@code duration} is negative
      */
     default boolean putIfAbsent(@NonNull K key, @NonNull V value,
-        long duration, @NonNull TimeUnit unit) {
+        @NonNegative long duration, @NonNull TimeUnit unit) {
       // This method was added & implemented in version 2.6.0
       throw new UnsupportedOperationException();
     }
@@ -436,7 +439,8 @@ default boolean putIfAbsent(@NonNull K key, @NonNull V value, @NonNull Duration
      * @throws IllegalArgumentException if {@code duration} is negative
      * @throws NullPointerException if the specified key or value is null
      */
-    default void put(@NonNull K key, @NonNull V value, long duration, @NonNull TimeUnit unit) {
+    default void put(@NonNull K key, @NonNull V value,
+        @NonNegative long duration, @NonNull TimeUnit unit) {
       // This method was added & implemented in version 2.6.0
       throw new UnsupportedOperationException();
     }
@@ -472,7 +476,7 @@ default void put(@NonNull K key, @NonNull V value, @NonNull Duration duration) {
      * @return a snapshot view of the cache from oldest entry to the youngest
      */
     @NonNull
-    Map<K, V> oldest(int limit);
+    Map<@NonNull K, @NonNull V> oldest(@NonNegative int limit);
 
     /**
      * Returns an unmodifiable snapshot {@link Map} view of the cache with ordered traversal. The
@@ -489,6 +493,6 @@ default void put(@NonNull K key, @NonNull V value, @NonNull Duration duration) {
      * @return a snapshot view of the cache from youngest entry to the oldest
      */
     @NonNull
-    Map<K, V> youngest(int limit);
+    Map<@NonNull K, @NonNull V> youngest(@NonNegative int limit);
   }
 }