RFR: 4964430: (spec) missing IllegalStateException exception requirement for javax.crypto.Cipher.doFinal [v4]

[Sean Mullan]

On Wed, 4 Oct 2023 22:36:57 GMT, Ben Perez <duke at openjdk.org> wrote:

>> Updated IllegalStateException exception requirements for `update`, `doFinal`, `wrap`, and `unwrap`
>
> Ben Perez has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Updated docs for NullCipher to indicate it will not throw and IllegalStateException when calling Cipher methods in bad state

Changes requested by mullan (Reviewer).

src/java.base/share/classes/javax/crypto/Cipher.java line 1855:

> 1853:      * @throws IllegalStateException if this {@code Cipher} object is in a
> 1854:      * wrong state (e.g., has not been initialized, or is not
> 1855:      * in ENCRYPT_MODE or DECRYPT_MODE)

Use code format when referencing the modes, ex: change this line to:

`* in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})`

Same comment applies to all other applicable lines below.

src/java.base/share/classes/javax/crypto/NullCipher.java line 35:

> 33:  * byte.  Unlike other ciphers, the {@code NullCipher} will not throw an
> 34:  * {@code IllegalStateException} when calling {@code Cipher} methods
> 35:  * in an incorrect state.

Suggest rewording last part as "... when {@code Cipher} methods are called in an incorrect state." I also think we should say a NullCipher has no state. So how about:

"Unlike other ciphers, the {@code NullCipher} has no state, and will not throw an {@code IllegalStateException} when {@code Cipher} methods are called in an incorrect state."

-------------

PR Review: https://git.openjdk.org/jdk/pull/15727#pullrequestreview-1660017070
PR Review Comment: https://git.openjdk.org/jdk/pull/15727#discussion_r1347514833
PR Review Comment: https://git.openjdk.org/jdk/pull/15727#discussion_r1347520301