diff --git a/src/main/java/gr/james/sampling/ChaoSampling.java b/src/main/java/gr/james/sampling/ChaoSampling.java index c79d0c6..231aa00 100644 --- a/src/main/java/gr/james/sampling/ChaoSampling.java +++ b/src/main/java/gr/james/sampling/ChaoSampling.java @@ -8,6 +8,9 @@ * According to this algorithm, the probability of an item to be in the final sample is proportional to its relative * weight. Weights are the range (0,+Inf), otherwise an {@link IllegalWeightException} is thrown. *

+ * This implementation throws {@link StreamOverflowException} if more than {@link Long#MAX_VALUE} are feeded or if the + * sum of the weights of the items feeded is {@link Double#POSITIVE_INFINITY}, whichever occurs first. + *

* The space complexity of this class is {@code O(k)}, where {@code k} is the sample size. * * @param the item type diff --git a/src/main/java/gr/james/sampling/EfraimidisSampling.java b/src/main/java/gr/james/sampling/EfraimidisSampling.java index 8d1eb13..859d341 100644 --- a/src/main/java/gr/james/sampling/EfraimidisSampling.java +++ b/src/main/java/gr/james/sampling/EfraimidisSampling.java @@ -9,6 +9,8 @@ * explicit or implicit item selections of the sampling procedure. Weights are the range (0,+Inf), otherwise an * {@link IllegalWeightException} is thrown. *

+ * This implementation never throws {@link StreamOverflowException}. + *

* The space complexity of this class is {@code O(k)}, where {@code k} is the sample size. * * @param the item type diff --git a/src/main/java/gr/james/sampling/RandomSampling.java b/src/main/java/gr/james/sampling/RandomSampling.java index 9592a7a..5dee594 100644 --- a/src/main/java/gr/james/sampling/RandomSampling.java +++ b/src/main/java/gr/james/sampling/RandomSampling.java @@ -21,6 +21,9 @@ * contain duplicate elements. Furthermore, elements need not be immutable and the sampling process does not rely on the * elements' {@code hashCode()} and {@code equals()} methods. *

+ * Implementations can throw {@link StreamOverflowException} if some overflow has occurred in the internal state of the + * algorithm that would otherwise prevent it from functioning properly, typically related to the stream size. + *

* Classes that implement this interface have a static method with signature *


  * public static <E> RandomSamplingCollector<E> collector(int sampleSize, Random random)
diff --git a/src/main/java/gr/james/sampling/VitterXSampling.java b/src/main/java/gr/james/sampling/VitterXSampling.java
index c279fa6..9c34303 100644
--- a/src/main/java/gr/james/sampling/VitterXSampling.java
+++ b/src/main/java/gr/james/sampling/VitterXSampling.java
@@ -10,6 +10,8 @@
  * algorithms to perform better by efficiently calculating the number of items that need to be skipped, while making
  * fewer calls to the RNG.
  * 

+ * This implementations throws {@link StreamOverflowException} if more than {@link Long#MAX_VALUE} items are feeded. + *

* The space complexity of this class is {@code O(k)}, where {@code k} is the sample size. * * @param the item type diff --git a/src/main/java/gr/james/sampling/VitterZSampling.java b/src/main/java/gr/james/sampling/VitterZSampling.java index 280509a..88a1983 100644 --- a/src/main/java/gr/james/sampling/VitterZSampling.java +++ b/src/main/java/gr/james/sampling/VitterZSampling.java @@ -10,6 +10,8 @@ * algorithms to perform better by efficiently calculating the number of items that need to be skipped, while making * fewer calls to the RNG. *

+ * This implementations throws {@link StreamOverflowException} if more than {@link Long#MAX_VALUE} items are feeded. + *

* The space complexity of this class is {@code O(k)}, where {@code k} is the sample size. * * @param the item type diff --git a/src/main/java/gr/james/sampling/WatermanSampling.java b/src/main/java/gr/james/sampling/WatermanSampling.java index c49c087..3460283 100644 --- a/src/main/java/gr/james/sampling/WatermanSampling.java +++ b/src/main/java/gr/james/sampling/WatermanSampling.java @@ -11,6 +11,8 @@ * {@link VitterXSampling} and {@link VitterZSampling} decide how many items to skip, rather than deciding whether or * not to skip an item each time it is feeded. *

+ * This implementations throws {@link StreamOverflowException} if more than {@link Long#MAX_VALUE} items are feeded. + *

* The space complexity of this class is {@code O(k)}, where {@code k} is the sample size. * * @param the item type diff --git a/src/main/java/gr/james/sampling/WeightedRandomSampling.java b/src/main/java/gr/james/sampling/WeightedRandomSampling.java index e46d38d..dd30cc3 100644 --- a/src/main/java/gr/james/sampling/WeightedRandomSampling.java +++ b/src/main/java/gr/james/sampling/WeightedRandomSampling.java @@ -28,6 +28,9 @@ * contain duplicate elements. Furthermore, elements need not be immutable and the sampling process does not rely on the * elements' {@code hashCode()} and {@code equals()} methods. *

+ * Implementations can throw {@link StreamOverflowException} if some overflow has occurred in the internal state of the + * algorithm that would otherwise prevent it from functioning properly, typically related to the stream size. + *

* Classes that implement this interface have a static method with signature *


  * public static <E> WeightedRandomSamplingCollector<E> weightedCollector(int sampleSize, Random random)