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

XMLWordPrintable

#### Details

• CSR
• Resolution: Approved
• P4
• 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 `@implNote`s, 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)``````

#### People

Raffaello Giulietti
Raffaello Giulietti
Brian Burkhalter