Allow subclassing of AbstractRandomSampling outside the package (#49)

src/main/java/gr/james/sampling/AbstractRandomSampling.java

@@ -5,6 +5,12 @@
 /**
  * This class provides a skeletal implementation of the {@link RandomSampling} interface to minimize the effort required
  * to implement that interface.
+ * <p>
+ * This class requires the implementation of 2 methods:
+ * <ul>
+ *     <li>{@link #skipLength(long, int, Random)}</li>
+ *     <li>{@link #init(int, Random)}</li>
+ * </ul>
  *
  * @param <T> the item type
  * @author Giorgos Stamatelatos
@@ -50,7 +56,7 @@ public abstract class AbstractRandomSampling<T> implements RandomSampling<T> {
      * @throws NullPointerException     if {@code random} is {@code null}
      * @throws IllegalArgumentException if {@code sampleSize} is less than 1
      */
-    AbstractRandomSampling(int sampleSize, Random random) {
+    protected AbstractRandomSampling(int sampleSize, Random random) {
         if (random == null) {
             throw new NullPointerException("Random was null");
         }
@@ -172,14 +178,14 @@ public Collection<T> sample() {
     /**
      * Returns how many items should the algorithm skip given its state.
      * <p>
-     * The implementation of this method must only rely on the given arguments and not on the state of the instance.
+     * The implementation of this method relies on the given arguments and not on the state of the instance.
      *
      * @param streamSize how many items have been fed to the sampler
      * @param sampleSize expected sample size
      * @param random     the {@link Random} instance to use
      * @return how many items to skip
      */
-    abstract long skipLength(long streamSize, int sampleSize, Random random);
+    protected abstract long skipLength(long streamSize, int sampleSize, Random random);
 
     /**
      * Performs initialization logic.
@@ -189,6 +195,6 @@ public Collection<T> sample() {
      * @param sampleSize expected sample size
      * @param random     the {@link Random} instance assigned to this instance
      */
-    void init(int sampleSize, Random random) {
+    protected void init(int sampleSize, Random random) {
     }
 }

src/main/java/gr/james/sampling/LiLSampling.java

@@ -60,14 +60,28 @@ public static <E> RandomSamplingCollector<E> collector(int sampleSize, Random ra
         return new RandomSamplingCollector<>(() -> new LiLSampling<>(sampleSize, random));
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param sampleSize {@inheritDoc}
+     * @param random     {@inheritDoc}
+     */
     @Override
-    void init(int sampleSize, Random random) {
+    protected void init(int sampleSize, Random random) {
         // W = Math.exp(Math.log(RandomSamplingUtils.randomExclusive(random)) / sampleSize);
         W = Math.pow(RandomSamplingUtils.randomExclusive(random), 1.0 / sampleSize);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param streamSize {@inheritDoc}
+     * @param sampleSize {@inheritDoc}
+     * @param random     {@inheritDoc}
+     * @return {@inheritDoc}
+     */
     @Override
-    long skipLength(long streamSize, int sampleSize, Random random) {
+    protected long skipLength(long streamSize, int sampleSize, Random random) {
         final double random1 = RandomSamplingUtils.randomExclusive(random);
         final double random2 = RandomSamplingUtils.randomExclusive(random);
         long skip = (long) (Math.log(random1) / Math.log(1 - W));

src/main/java/gr/james/sampling/VitterXSampling.java

@@ -56,8 +56,16 @@ public static <E> RandomSamplingCollector<E> collector(int sampleSize, Random ra
         return new RandomSamplingCollector<>(() -> new VitterXSampling<>(sampleSize, random));
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param streamSize {@inheritDoc}
+     * @param sampleSize {@inheritDoc}
+     * @param random     {@inheritDoc}
+     * @return {@inheritDoc}
+     */
     @Override
-    long skipLength(long streamSize, int sampleSize, Random random) {
+    protected long skipLength(long streamSize, int sampleSize, Random random) {
         streamSize++;
 
         final double r = random.nextDouble();

src/main/java/gr/james/sampling/VitterZSampling.java

@@ -58,13 +58,27 @@ public static <E> RandomSamplingCollector<E> collector(int sampleSize, Random ra
         return new RandomSamplingCollector<>(() -> new VitterZSampling<>(sampleSize, random));
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param sampleSize {@inheritDoc}
+     * @param random     {@inheritDoc}
+     */
     @Override
-    void init(int sampleSize, Random random) {
+    protected void init(int sampleSize, Random random) {
         W = Math.pow(random.nextDouble(), -1.0 / sampleSize);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param streamSize {@inheritDoc}
+     * @param sampleSize {@inheritDoc}
+     * @param random     {@inheritDoc}
+     * @return {@inheritDoc}
+     */
     @Override
-    long skipLength(long streamSize, int sampleSize, Random random) {
+    protected long skipLength(long streamSize, int sampleSize, Random random) {
         double term = streamSize - sampleSize + 1;
         while (true) {
             // Generate U and X

src/main/java/gr/james/sampling/WatermanSampling.java

@@ -56,8 +56,16 @@ public static <E> RandomSamplingCollector<E> collector(int sampleSize, Random ra
         return new RandomSamplingCollector<>(() -> new WatermanSampling<>(sampleSize, random));
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param streamSize {@inheritDoc}
+     * @param sampleSize {@inheritDoc}
+     * @param random     {@inheritDoc}
+     * @return {@inheritDoc}
+     */
     @Override
-    long skipLength(long streamSize, int sampleSize, Random random) {
+    protected long skipLength(long streamSize, int sampleSize, Random random) {
         streamSize++;
         long skipCount = 0;
         while (random.nextDouble() * streamSize >= sampleSize && streamSize > 0) {