Add nullability annotations to main API and extension points

core/pom.xml

@@ -42,6 +42,10 @@
             <groupId>org.slf4j</groupId>
             <artifactId>slf4j-api</artifactId>
         </dependency>
+        <dependency>
+            <groupId>com.google.code.findbugs</groupId>
+            <artifactId>jsr305</artifactId>
+        </dependency>
 
         <dependency>
             <groupId>org.hamcrest</groupId>

core/src/main/java/com/pholser/junit/quickcheck/generator/ComponentizedGenerator.java

@@ -31,6 +31,8 @@ a copy of this software and associated documentation files (the
 
 import org.javaruntype.type.TypeParameter;
 
+import javax.annotation.Nonnull;
+
 import static java.util.Collections.*;
 
 import static com.pholser.junit.quickcheck.internal.Reflection.*;
@@ -105,6 +107,7 @@ protected ComponentizedGenerator(Class<T> type) {
     /**
      * @return this generator's component generators
      */
+    @Nonnull
     protected List<Generator<?>> componentGenerators() {
         return unmodifiableList(components);
     }

core/src/main/java/com/pholser/junit/quickcheck/generator/Gen.java

@@ -37,6 +37,8 @@ a copy of this software and associated documentation files (the
 import com.pholser.junit.quickcheck.internal.Weighted;
 import com.pholser.junit.quickcheck.random.SourceOfRandomness;
 
+import javax.annotation.Nonnull;
+
 import static java.util.stream.Collectors.*;
 
 /**
@@ -57,7 +59,7 @@ public interface Gen<T> {
      * number of elements.
      * @return the generated value
      */
-    T generate(SourceOfRandomness random, GenerationStatus status);
+    T generate(@Nonnull SourceOfRandomness random, @Nonnull GenerationStatus status);
 
     /**
      * Gives a generation strategy that produces a random value by having this

core/src/main/java/com/pholser/junit/quickcheck/generator/GenerationStatus.java

@@ -25,6 +25,8 @@ a copy of this software and associated documentation files (the
 
 package com.pholser.junit.quickcheck.generator;
 
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 import java.util.Objects;
 import java.util.Optional;
 
@@ -65,6 +67,7 @@ default void semiAttempt() {
      * @param value the associated value
      * @return self, so that calls to this method can be chained
      */
+    @Nonnull
     <T> GenerationStatus setValue(Key<T> key, T value);
 
     /**
@@ -74,6 +77,7 @@ default void semiAttempt() {
      * @param key key to look up
      * @return the (optional) associated value
      */
+    @Nonnull
     <T> Optional<T> valueOf(Key<T> key);
 
     /**
@@ -96,6 +100,7 @@ public Key(String name, Class<T> type) {
             this.type = type;
         }
 
+        @Nullable
         public T cast(Object o) {
             return type.cast(o);
         }

core/src/main/java/com/pholser/junit/quickcheck/generator/Generator.java

@@ -42,6 +42,8 @@ a copy of this software and associated documentation files (the
 import org.javaruntype.type.Types;
 import org.javaruntype.type.WildcardTypeParameter;
 
+import javax.annotation.Nonnull;
+
 import static java.math.BigDecimal.*;
 import static java.util.Collections.*;
 import static java.util.stream.Collectors.*;
@@ -82,6 +84,7 @@ protected Generator(List<Class<T>> types) {
      * @return class tokens for the types of property parameters this generator
      * is applicable to
      */
+    @Nonnull
     public List<Class<T>> types() {
         return unmodifiableList(types);
     }
@@ -105,7 +108,8 @@ public boolean canRegisterAsType(Class<?> type) {
      * participate} in shrinking the given value, and if so, they
      * {@linkplain #doShrink(SourceOfRandomness, Object) produce shrinks}.</p>
      */
-    @Override public final List<T> shrink(SourceOfRandomness random, Object larger) {
+    @Nonnull
+    @Override public final List<T> shrink(@Nonnull SourceOfRandomness random, Object larger) {
         if (!canShrink(larger)) {
             throw new IllegalStateException(
                 getClass() + " not capable of shrinking " + larger);
@@ -141,7 +145,8 @@ public boolean canShrink(Object larger) {
      * @param larger the larger object
      * @return objects that are "smaller" than the larger object
      */
-    public List<T> doShrink(SourceOfRandomness random, T larger) {
+    @Nonnull
+    public List<T> doShrink(@Nonnull SourceOfRandomness random, T larger) {
         return emptyList();
     }
 
@@ -159,6 +164,7 @@ public List<T> doShrink(SourceOfRandomness random, T larger) {
      * @param value the value to assess
      * @return a measure of the given value's magnitude
      */
+    @Nonnull
     public BigDecimal magnitude(Object value) {
         return ONE;
     }
@@ -214,7 +220,7 @@ public int numberOfNeededComponents() {
      *
      * @param newComponents component generators to add
      */
-    public void addComponentGenerators(List<Generator<?>> newComponents) {
+    public void addComponentGenerators(@Nonnull List<Generator<?>> newComponents) {
         // do nothing by default
     }
 
@@ -224,7 +230,7 @@ public void addComponentGenerators(List<Generator<?>> newComponents) {
      * for property parameters that have the given type parameters in their
      * signatures
      */
-    public boolean canGenerateForParametersOfTypes(List<TypeParameter<?>> typeParameters) {
+    public boolean canGenerateForParametersOfTypes(@Nonnull List<TypeParameter<?>> typeParameters) {
         return true;
     }
 
@@ -254,14 +260,14 @@ public boolean canGenerateForParametersOfTypes(List<TypeParameter<?>> typeParame
      * "understand" one of the generation configuration annotations on
      * the annotated type
      */
-    public void configure(AnnotatedType annotatedType) {
+    public void configure(@Nonnull AnnotatedType annotatedType) {
         configureStrict(collectConfigurationAnnotations(annotatedType));
     }
 
     /**
      * @param element an annotated program element
      */
-    public void configure(AnnotatedElement element) {
+    public void configure(@Nonnull AnnotatedElement element) {
         configureLenient(collectConfigurationAnnotations(element));
     }
 
@@ -282,6 +288,7 @@ public void provide(Generators provided) {
      *
      * @return a copy of the receiver
      */
+    @Nonnull
     @SuppressWarnings("unchecked")
     public Generator<T> copy() {
         return (Generator<T>) instantiate(getClass());

core/src/main/java/com/pholser/junit/quickcheck/generator/Generators.java

@@ -30,6 +30,8 @@ a copy of this software and associated documentation files (the
 
 import com.pholser.junit.quickcheck.random.SourceOfRandomness;
 
+import javax.annotation.Nonnull;
+
 /**
  * An access point for available generators.
  */
@@ -47,6 +49,7 @@ public interface Generators {
      * @param rest other (related) types of generated values
      * @return generator that can produce values of the given types
      */
+    @Nonnull
     <T> Generator<T> oneOf(
         Class<? extends T> first,
         Class<? extends T>... rest);
@@ -63,6 +66,7 @@ <T> Generator<T> oneOf(
      * @param rest other generators
      * @return generator that can produce values using the given generators
      */
+    @Nonnull
     <T> Generator<T> oneOf(
         Generator<? extends T> first,
         Generator<? extends T>... rest);
@@ -79,6 +83,7 @@ <T> Generator<T> oneOf(
      * @param fieldName name of a field
      * @return generator that can produce values of the field's type
      */
+    @Nonnull
     Generator<?> field(Class<?> type, String fieldName);
 
     /**
@@ -97,6 +102,7 @@ <T> Generator<T> oneOf(
      * @param argumentTypes types of arguments to the constructor
      * @return generator that can produce values using the constructor
      */
+    @Nonnull
     <T> Generator<T> constructor(Class<T> type, Class<?>... argumentTypes);
 
     /**
@@ -114,6 +120,7 @@ <T> Generator<T> oneOf(
      * @param type a type
      * @return generator that can produce values of that type
      */
+    @Nonnull
     <T> Generator<T> fieldsOf(Class<T> type);
 
     /**
@@ -126,6 +133,7 @@ <T> Generator<T> oneOf(
      * @return generator that can produce values of that type
      * @see ComponentizedGenerator
      */
+    @Nonnull
     <T> Generator<T> type(Class<T> type, Class<?>... componentTypes);
 
     /**
@@ -139,6 +147,7 @@ <T> Generator<T> oneOf(
      * @param parameter a reflected method parameter
      * @return generator that can produce values of the parameter's type
      */
+    @Nonnull
     Generator<?> parameter(Parameter parameter);
 
     /**
@@ -152,6 +161,7 @@ <T> Generator<T> oneOf(
      * @param field a reflected field
      * @return generator that can produce values of the field's type
      */
+    @Nonnull
     Generator<?> field(Field field);
 
     /**
@@ -168,6 +178,7 @@ <T> Generator<T> oneOf(
      * @return a generator for producing values
      * @see ComponentizedGenerator
      */
+    @Nonnull
     <T extends Generator<?>> T make(
         Class<T> genType,
         Generator<?>... componentGenerators);
@@ -182,5 +193,6 @@ <T extends Generator<?>> T make(
      * @return a generator access point that has the source of randomness
      * available to it
      */
+    @Nonnull
     Generators withRandom(SourceOfRandomness random);
 }

core/src/main/java/com/pholser/junit/quickcheck/generator/Shrink.java

@@ -29,6 +29,8 @@ a copy of this software and associated documentation files (the
 
 import com.pholser.junit.quickcheck.random.SourceOfRandomness;
 
+import javax.annotation.Nonnull;
+
 /**
  * Represents a strategy for producing objects "smaller than" a given object.
  *
@@ -43,5 +45,6 @@ public interface Shrink<T> {
      * @param larger the larger object
      * @return objects that are "smaller" than the larger object
      */
-    List<T> shrink(SourceOfRandomness random, Object larger);
+    @Nonnull
+    List<T> shrink(@Nonnull SourceOfRandomness random, Object larger);
 }

core/src/main/java/com/pholser/junit/quickcheck/internal/generator/GeneratorRepository.java

@@ -54,6 +54,8 @@ a copy of this software and associated documentation files (the
 import org.javaruntype.type.TypeParameter;
 import org.javaruntype.type.Types;
 
+import javax.annotation.Nonnull;
+
 import static java.util.Arrays.*;
 import static java.util.Collections.*;
 import static java.util.stream.Collectors.*;
@@ -126,10 +128,12 @@ private void registerGeneratorForType(
         forType.add(generator);
     }
 
+    @Nonnull
     @Override public Generator<?> field(Class<?> type, String fieldName) {
         return field(findField(type, fieldName));
     }
 
+    @Nonnull
     @Override public <U> Generator<U> constructor(
         Class<U> type,
         Class<?>... argumentTypes) {
@@ -142,6 +146,7 @@ private void registerGeneratorForType(
         return ctor;
     }
 
+    @Nonnull
     @Override public <U> Generator<U> fieldsOf(Class<U> type) {
         Fields<U> fields = new Fields<>(type);
 
@@ -151,6 +156,7 @@ private void registerGeneratorForType(
         return fields;
     }
 
+    @Nonnull
     @SuppressWarnings("unchecked")
     @Override public <T> Generator<T> type(Class<T> type, Class<?>... componentTypes) {
         Generator<T> generator =
@@ -160,6 +166,7 @@ private void registerGeneratorForType(
         return generator;
     }
 
+    @Nonnull
     @Override public Generator<?> parameter(Parameter parameter) {
         return produceGenerator(
             new ParameterTypeContext(
@@ -169,6 +176,7 @@ private void registerGeneratorForType(
             ).annotate(parameter));
     }
 
+    @Nonnull
     @Override public Generator<?> field(Field field) {
         return produceGenerator(
             new ParameterTypeContext(
@@ -178,6 +186,7 @@ private void registerGeneratorForType(
             ).annotate(field));
     }
 
+    @Nonnull
     @SafeVarargs
     @SuppressWarnings("unchecked")
     @Override public final <T> Generator<T> oneOf(
@@ -191,6 +200,7 @@ private void registerGeneratorForType(
                 .toArray(Generator[]::new));
     }
 
+    @Nonnull
     @SafeVarargs
     @SuppressWarnings("unchecked")
     @Override public final <T> Generator<T> oneOf(
@@ -208,6 +218,7 @@ private void registerGeneratorForType(
         return (Generator<T>) new CompositeGenerator(weightings);
     }
 
+    @Nonnull
     @Override public final <T extends Generator<?>> T make(
         Class<T> genType,
         Generator<?>... components) {
@@ -220,6 +231,7 @@ private void registerGeneratorForType(
         return generator;
     }
 
+    @Nonnull
     @Override public final Generators withRandom(SourceOfRandomness other) {
         return new GeneratorRepository(other, this.generators);
     }

core/src/main/java/com/pholser/junit/quickcheck/random/SourceOfRandomness.java

@@ -38,6 +38,8 @@ a copy of this software and associated documentation files (the
 
 import com.pholser.junit.quickcheck.internal.Ranges;
 
+import javax.annotation.Nonnull;
+
 import static java.util.concurrent.TimeUnit.*;
 
 import static com.pholser.junit.quickcheck.internal.Ranges.*;
@@ -297,6 +299,7 @@ public short nextShort(short min, short max) {
      * @return a random {@code BigInteger}
      * @see BigInteger#BigInteger(int, java.util.Random)
      */
+    @Nonnull
     public BigInteger nextBigInteger(int numberOfBits) {
         return new BigInteger(numberOfBits, delegate);
     }
@@ -309,6 +312,7 @@ public BigInteger nextBigInteger(int numberOfBits) {
      * @param max upper bound of the desired interval
      * @return a random value
      */
+    @Nonnull
     public Instant nextInstant(Instant min, Instant max) {
         int comparison = checkRange(Ranges.Type.STRING, min, max);
         if (comparison == 0)
@@ -331,6 +335,7 @@ public Instant nextInstant(Instant min, Instant max) {
      * @param max upper bound of the desired interval
      * @return a random value
      */
+    @Nonnull
     public Duration nextDuration(Duration min, Duration max) {
         int comparison = checkRange(Ranges.Type.STRING, min, max);
         if (comparison == 0)