Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8294727

Add @throws and @implNote clauses to BigInteger::isProblablePrime and BigInteger::nextProblablePrime

XMLWordPrintable

    • Icon: CSR CSR
    • Resolution: Approved
    • Icon: P4 P4
    • 20
    • core-libs
    • None
    • minimal
    • It's extremely improbable that anyone would successfully perform a primality test on really huge targets.
    • Java API
    • SE

      Summary

      BigInteger::isProbablePrime should specify that it throws an ArithmeticException on large targets.

      Problem

      https://bugs.openjdk.org/browse/JDK-8294593 adds a check on the size of the target of BigInteger::isProbablePrime. The check throws an ArithmeticException on large targets, similarly to what is specificed on BigInteger::nextProbablePrime. The spec, however, lacks a @throws clause.

      Solution

      Add a @throws clause to the spec. Also, add some rationale for the check itself as @implNotes, both on BigInteger::isProbablePrime and BigInteger::nextProbablePrime.

      Specification

      diff --git a/src/java.base/share/classes/java/math/BigInteger.java b/src/java.base/share/classes/java/math/BigInteger.java
      index 4ba044b4284..63f0210b147 100644
      --- a/src/java.base/share/classes/java/math/BigInteger.java
      +++ b/src/java.base/share/classes/java/math/BigInteger.java
      @@ -868,6 +868,10 @@ public class BigInteger extends Number implements Comparable<BigInteger> {
           * @return the first integer greater than this {@code BigInteger} that
           *         is probably prime.
           * @throws ArithmeticException {@code this < 0} or {@code this} is too large.
      +    * @implNote Due to the nature of the underlying algorithm,
      +    *          and depending on the size of {@code this},
      +    *          this method could consume a large amount of memory, up to
      +    *          exhaustion of available heap space, or could run for a long time.
           * @since 1.5
           */
           public BigInteger nextProbablePrime() {
      @@ -3880,6 +3884,11 @@ public class BigInteger extends Number implements Comparable<BigInteger> {
            *         this method is proportional to the value of this parameter.
            * @return {@code true} if this BigInteger is probably prime,
            *         {@code false} if it's definitely composite.
      +     * @throws ArithmeticException {@code this} is too large.
      +     * @implNote Due to the nature of the underlying primality test algorithm,
      +     *          and depending on the size of {@code this} and {@code certainty},
      +     *          this method could consume a large amount of memory, up to
      +     *          exhaustion of available heap space, or could run for a long time.
            */
           public boolean isProbablePrime(int certainty) {
               if (certainty <= 0)

            rgiulietti Raffaello Giulietti
            rgiulietti Raffaello Giulietti
            Brian Burkhalter
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Created:
              Updated:
              Resolved: