Split API and engine

core-api/pom.xml

@@ -0,0 +1,78 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>com.pholser</groupId>
+        <artifactId>junit-quickcheck</artifactId>
+        <version>0.10-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>junit-quickcheck-core-api</artifactId>
+    <version>0.10-SNAPSHOT</version>
+    <packaging>jar</packaging>
+    <name>junit-quickcheck-core-api</name>
+    <description>Property-based testing, JUnit-style: core functionality</description>
+    <url>http://github.com/pholser/junit-quickcheck</url>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.javaruntype</groupId>
+            <artifactId>javaruntype</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.hamcrest</groupId>
+            <artifactId>hamcrest-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.hamcrest</groupId>
+            <artifactId>hamcrest-library</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-all</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>ch.qos.logback</groupId>
+            <artifactId>logback-classic</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-release-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.jacoco</groupId>
+                <artifactId>jacoco-maven-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-checkstyle-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-pmd-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>findbugs-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+</project>

core/src/main/java/com/pholser/junit/quickcheck/From.java → core-api/src/main/java/com/pholser/junit/quickcheck/From.java

@@ -29,11 +29,11 @@ a copy of this software and associated documentation files (the
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import com.pholser.junit.quickcheck.generator.Generator;
-
 import static java.lang.annotation.ElementType.*;
 import static java.lang.annotation.RetentionPolicy.*;
 
+import com.pholser.junit.quickcheck.generator.Generator;
+
 /**
  * <p>Mark a parameter of a {@link Property} method with this annotation to
  * have random values supplied to it via the specified

core/src/main/java/com/pholser/junit/quickcheck/Mode.java → core-api/src/main/java/com/pholser/junit/quickcheck/Mode.java

@@ -25,10 +25,6 @@ a copy of this software and associated documentation files (the
 
 package com.pholser.junit.quickcheck;
 
-import com.pholser.junit.quickcheck.internal.ParameterSampler;
-import com.pholser.junit.quickcheck.internal.sampling.ExhaustiveParameterSampler;
-import com.pholser.junit.quickcheck.internal.sampling.TupleParameterSampler;
-
 /**
  * Represents different modes of execution of property-based tests.
  *
@@ -40,23 +36,13 @@ public enum Mode {
      * Verify {@link Property#trials()} tuples of arguments for a property's
      * parameters.
      */
-    SAMPLING {
-        @Override ParameterSampler sampler(int defaultSampleSize) {
-            return new TupleParameterSampler(defaultSampleSize);
-        }
-    },
+    SAMPLING,
 
     /**
      * Generate {@link Property#trials()} arguments for each parameter
      * property, and verify the cross-products of those sets of arguments.
      * This behavior mirrors that of the JUnit
      * {@link org.junit.experimental.theories.Theories} runner.
      */
-    EXHAUSTIVE {
-        @Override ParameterSampler sampler(int defaultSampleSize) {
-            return new ExhaustiveParameterSampler(defaultSampleSize);
-        }
-    };
-
-    abstract ParameterSampler sampler(int defaultSampleSize);
+    EXHAUSTIVE;
 }

core/src/main/java/com/pholser/junit/quickcheck/Pair.java → core-api/src/main/java/com/pholser/junit/quickcheck/Pair.java

@@ -25,14 +25,16 @@ a copy of this software and associated documentation files (the
 
 package com.pholser.junit.quickcheck;
 
+import com.pholser.junit.quickcheck.generator.Gen;
+
 import java.util.Objects;
 
 /**
  * Typed pair of elements.
  *
  * @param <F> type of first element of pair
  * @param <S> type of second element of pair
- * @see com.pholser.junit.quickcheck.generator.Gen#frequency(Pair, Pair[])
+ * @see Gen#frequency(Pair, Pair[])
  */
 public final class Pair<F, S> {
     public final F first;

core/src/main/java/com/pholser/junit/quickcheck/Produced.java → core-api/src/main/java/com/pholser/junit/quickcheck/Produced.java

@@ -31,10 +31,12 @@ a copy of this software and associated documentation files (the
 import static java.lang.annotation.ElementType.*;
 import static java.lang.annotation.RetentionPolicy.*;
 
+import com.pholser.junit.quickcheck.generator.Generator;
+
 /**
  * <p>Mark a parameter of a {@link Property} method with this annotation to
  * have random values supplied to it via one of the
- * {@link com.pholser.junit.quickcheck.generator.Generator}s specified by the
+ * {@link Generator}s specified by the
  * aggregated {@link From} annotations.</p>
  *
  * <p>Alternatively, you can specify many generators via many repetitions of

core/src/main/java/com/pholser/junit/quickcheck/internal/generator/NullAllowed.java → core-api/src/main/java/com/pholser/junit/quickcheck/generator/NullAllowed.java

@@ -1,4 +1,4 @@
-package com.pholser.junit.quickcheck.internal.generator;
+package com.pholser.junit.quickcheck.generator;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;

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

@@ -0,0 +1,222 @@
+package com.pholser.junit.quickcheck.random;
+
+import com.pholser.junit.quickcheck.generator.Generator;
+
+import java.math.BigInteger;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.Collection;
+import java.util.Random;
+
+/**
+ * A source of randomness, fed to
+ * {@linkplain Generator generators}
+ * so they can produce random values for property parameters.
+ */
+public interface SourceOfRandomness {
+    /**
+     * <p>Gives a JDK source of randomness, with the same internal state as
+     * this source of randomness.</p>
+     *
+     * @return a JDK "clone" of self
+     */
+    Random toJDKRandom();
+
+    /**
+     * @return a uniformly distributed boolean value
+     * @see Random#nextBoolean()
+     */
+    boolean nextBoolean();
+
+    /**
+     * @param bytes a byte array to fill with random values
+     * @see Random#nextBytes(byte[])
+     */
+    void nextBytes(byte[] bytes);
+
+    /**
+     * Gives an array of a given length containing random bytes.
+     *
+     * @param count the desired length of the random byte array
+     * @return random bytes
+     * @see Random#nextBytes(byte[])
+     */
+    byte[] nextBytes(int count);
+
+    /**
+     * @return a uniformly distributed random {@code double} value in the
+     * interval {@code [0.0, 1.0)}
+     * @see Random#nextDouble()
+     */
+    double nextDouble();
+
+    /**
+     * @return a uniformly distributed random {@code float} value in the
+     * interval {@code [0.0, 1.0)}
+     * @see Random#nextFloat()
+     */
+    float nextFloat();
+
+    /**
+     * @return a Gaussian-distributed random double value
+     * @see Random#nextGaussian()
+     */
+    double nextGaussian();
+
+    /**
+     * @return a uniformly distributed random {@code int} value
+     * @see Random#nextInt()
+     */
+    int nextInt();
+
+    /**
+     * @param n upper bound
+     * @return a uniformly distributed random {@code int} value in the interval
+     * {@code [0, n)}
+     * @see Random#nextInt(int)
+     */
+    int nextInt(int n);
+
+    /**
+     * @return a uniformly distributed random {@code long} value
+     * @see Random#nextLong()
+     */
+    long nextLong();
+
+    /**
+     * @param seed value with which to seed this source of randomness
+     * @see Random#setSeed(long)
+     */
+    void setSeed(long seed);
+
+    /**
+     * @return the value used to initially seed this source of randomness
+     */
+    long seed();
+
+    /**
+     * Gives a random {@code byte} value, uniformly distributed across the
+     * interval {@code [min, max]}.
+     *
+     * @param min lower bound of the desired interval
+     * @param max upper bound of the desired interval
+     * @return a random value
+     */
+    byte nextByte(byte min, byte max);
+
+    /**
+     * Gives a random {@code char} value, uniformly distributed across the
+     * interval {@code [min, max]}.
+     *
+     * @param min lower bound of the desired interval
+     * @param max upper bound of the desired interval
+     * @return a random value
+     */
+    char nextChar(char min, char max);
+
+    /**
+     * <p>Gives a random {@code double} value in the interval
+     * {@code [min, max)}.</p>
+     *
+     * <p>This naive implementation takes a random {@code double} value from
+     * {@link Random#nextDouble()} and scales/shifts the value into the desired
+     * interval. This may give surprising results for large ranges.</p>
+     *
+     * @param min lower bound of the desired interval
+     * @param max upper bound of the desired interval
+     * @return a random value
+     */
+    double nextDouble(double min, double max);
+
+    /**
+     * <p>Gives a random {@code float} value in the interval
+     * {@code [min, max)}.</p>
+     *
+     * <p>This naive implementation takes a random {@code float} value from
+     * {@link Random#nextFloat()} and scales/shifts the value into the desired
+     * interval. This may give surprising results for large ranges.</p>
+     *
+     * @param min lower bound of the desired interval
+     * @param max upper bound of the desired interval
+     * @return a random value
+     */
+    float nextFloat(float min, float max);
+
+    /**
+     * Gives a random {@code int} value, uniformly distributed across the
+     * interval {@code [min, max]}.
+     *
+     * @param min lower bound of the desired interval
+     * @param max upper bound of the desired interval
+     * @return a random value
+     */
+    int nextInt(int min, int max);
+
+    /**
+     * Gives a random {@code long} value, uniformly distributed across the
+     * interval {@code [min, max]}.
+     *
+     * @param min lower bound of the desired interval
+     * @param max upper bound of the desired interval
+     * @return a random value
+     */
+    long nextLong(long min, long max);
+
+    /**
+     * Gives a random {@code short} value, uniformly distributed across the
+     * interval {@code [min, max]}.
+     *
+     * @param min lower bound of the desired interval
+     * @param max upper bound of the desired interval
+     * @return a random value
+     */
+    short nextShort(short min, short max);
+
+    /**
+     * Gives a random {@code BigInteger} representable by the given number
+     * of bits.
+     *
+     * @param numberOfBits the desired number of bits
+     * @return a random {@code BigInteger}
+     * @see BigInteger#BigInteger(int, Random)
+     */
+    BigInteger nextBigInteger(int numberOfBits);
+
+    /**
+     * Gives a random {@code Instant} value, uniformly distributed across the
+     * interval {@code [min, max]}.
+     *
+     * @param min lower bound of the desired interval
+     * @param max upper bound of the desired interval
+     * @return a random value
+     */
+    Instant nextInstant(Instant min, Instant max);
+
+    /**
+     * Gives a random {@code Duration} value, uniformly distributed across the
+     * interval {@code [min, max]}.
+     *
+     * @param min lower bound of the desired interval
+     * @param max upper bound of the desired interval
+     * @return a random value
+     */
+    Duration nextDuration(Duration min, Duration max);
+
+    /**
+     * Gives a random element of the given collection.
+     *
+     * @param <T> type of items in the collection
+     * @param items a collection
+     * @return a randomly chosen element from the collection
+     */
+    <T> T choose(Collection<T> items);
+
+    /**
+     * Gives a random element of the given array.
+     *
+     * @param <T> type of items in the array
+     * @param items an array
+     * @return a randomly chosen element from the array
+     */
+    <T> T choose(T[] items);
+}