Summary

Document existing exception for the javax.crypto.Mac.update(ByteBuffer input) javax.crypto.MacSpi.engineUpdate(ByteBuffer input) methods when input parameter is null.

Problem

See Summary (above).

Solution

Add @throws to indicate that an IllegalArgumentException may be thrown for javax.crypto.Mac.update(ByteBuffer input) and NullPointerException may be thrown for javax.crypto.MacSpi.engineUpdate(ByteBuffer input). Also replaced existing @exception to @throws for both classes.

Specification

1) javax.crypto.Mac class:

@@ -421,11 +421,11 @@
     /**
      * Initializes this {@code Mac} object with the given key.
      *
      * @param key the key.
      *
-     * @exception InvalidKeyException if the given key is inappropriate for
+     * @throws InvalidKeyException if the given key is inappropriate for
      * initializing this MAC.
      */
     public final void init(Key key) throws InvalidKeyException {
         try {
             if (spi != null) {
@@ -449,13 +449,13 @@
      * algorithm parameters.
      *
      * @param key the key.
      * @param params the algorithm parameters.
      *
-     * @exception InvalidKeyException if the given key is inappropriate for
+     * @throws InvalidKeyException if the given key is inappropriate for
      * initializing this MAC.
-     * @exception InvalidAlgorithmParameterException if the given algorithm
+     * @throws InvalidAlgorithmParameterException if the given algorithm
      * parameters are inappropriate for this MAC.
      */
     public final void init(Key key, AlgorithmParameterSpec params)
             throws InvalidKeyException, InvalidAlgorithmParameterException {
         if (spi != null) {
@@ -474,11 +474,11 @@
     /**
      * Processes the given byte.
      *
      * @param input the input byte to be processed.
      *
-     * @exception IllegalStateException if this {@code Mac} has not been
+     * @throws IllegalStateException if this {@code Mac} has not been
      * initialized.
      */
     public final void update(byte input) throws IllegalStateException {
         chooseFirstProvider();
         if (!initialized) {
@@ -490,11 +490,11 @@
     /**
      * Processes the given array of bytes.
      *
      * @param input the array of bytes to be processed.
      *
-     * @exception IllegalStateException if this {@code Mac} has not been
+     * @throws IllegalStateException if this {@code Mac} has not been
      * initialized.
      */
     public final void update(byte[] input) throws IllegalStateException {
         chooseFirstProvider();
         if (!initialized) {
@@ -511,11 +511,11 @@
      *
      * @param input the input buffer.
      * @param offset the offset in {@code input} where the input starts.
      * @param len the number of bytes to process.
      *
-     * @exception IllegalStateException if this {@code Mac} has not been
+     * @throws IllegalStateException if this {@code Mac} has not been
      * initialized.
      */
     public final void update(byte[] input, int offset, int len)
             throws IllegalStateException {
         chooseFirstProvider();
@@ -536,12 +536,13 @@
      * Upon return, the buffer's position will be equal to its limit;
      * its limit will not have changed.
      *
      * @param input the ByteBuffer
      *
-     * @exception IllegalStateException if this {@code Mac} has not been
+     * @throws IllegalStateException if this {@code Mac} has not been
      * initialized.
+     * @throws IllegalArgumentException if {@code input} is null
      * @since 1.5
      */
     public final void update(ByteBuffer input) {
         chooseFirstProvider();
         if (!initialized) {
@@ -567,11 +568,11 @@
      * it must be reinitialized via a call to {@code init(Key)} or
      * {@code init(Key, AlgorithmParameterSpec)}.
      *
      * @return the MAC result.
      *
-     * @exception IllegalStateException if this {@code Mac} has not been
+     * @throws IllegalStateException if this {@code Mac} has not been
      * initialized.
      */
     public final byte[] doFinal() throws IllegalStateException {
         chooseFirstProvider();
         if (!initialized) {
@@ -601,13 +602,13 @@
      *
      * @param output the buffer where the MAC result is stored
      * @param outOffset the offset in {@code output} where the MAC is
      * stored
      *
-     * @exception ShortBufferException if the given output buffer is too small
+     * @throws ShortBufferException if the given output buffer is too small
      * to hold the result
-     * @exception IllegalStateException if this {@code Mac} has not been
+     * @throws IllegalStateException if this {@code Mac} has not been
      * initialized.
      */
     public final void doFinal(byte[] output, int outOffset)
         throws ShortBufferException, IllegalStateException
     {
@@ -639,11 +640,11 @@
      * {@code init(Key, AlgorithmParameterSpec)}.
      *
      * @param input data in bytes
      * @return the MAC result.
      *
-     * @exception IllegalStateException if this {@code Mac} has not been
+     * @throws IllegalStateException if this {@code Mac} has not been
      * initialized.
      */
     public final byte[] doFinal(byte[] input) throws IllegalStateException
     {
         chooseFirstProvider();
@@ -676,11 +677,11 @@
     /**
      * Returns a clone if the provider implementation is cloneable.
      *
      * @return a clone if the provider implementation is cloneable.
      *
-     * @exception CloneNotSupportedException if this is called on a
+     * @throws CloneNotSupportedException if this is called on a
      * delegate that does not support {@code Cloneable}.
      */
     public final Object clone() throws CloneNotSupportedException {
         chooseFirstProvider();
         Mac that = (Mac)super.clone();

2) javax.crypto.MacSpi class:

@@ -63,13 +63,13 @@
      * parameters.
      *
      * @param key the (secret) key.
      * @param params the algorithm parameters.
      *
-     * @exception InvalidKeyException if the given key is inappropriate for
+     * @throws InvalidKeyException if the given key is inappropriate for
      * initializing this MAC.
-     * @exception InvalidAlgorithmParameterException if the given algorithm
+     * @throws InvalidAlgorithmParameterException if the given algorithm
      * parameters are inappropriate for this MAC.
      */
     protected abstract void engineInit(Key key,
                                        AlgorithmParameterSpec params)
         throws InvalidKeyException, InvalidAlgorithmParameterException ;
@@ -99,10 +99,13 @@
      *
      * <p>Subclasses should consider overriding this method if they can
      * process ByteBuffers more efficiently than byte arrays.
      *
      * @param input the ByteBuffer
+     *
+     * @throws NullPointerException if {@code input} is null
+     *
      * @since 1.5
      */
     protected void engineUpdate(ByteBuffer input) {
         if (!input.hasRemaining()) {
             return;
@@ -143,11 +146,11 @@
     /**
      * Returns a clone if the implementation is cloneable.
      *
      * @return a clone if the implementation is cloneable.
      *
-     * @exception CloneNotSupportedException if this is called
+     * @throws CloneNotSupportedException if this is called
      * on an implementation that does not support {@code Cloneable}.
      */
     public Object clone() throws CloneNotSupportedException {
         if (this instanceof Cloneable) {
             return super.clone();