Summary

Update the javadoc of the static getInstance(...) methods, i.e. getInstance(String), getInstance(String, String) and getInstance(String, Provider) methods of javax.crypto.Cipher class to clarify when NoSuchAlgorithmException, NoSuchPaddingException will be thrown.

Problem

When the specified cipher transformation string contains an unsupported padding scheme, it may lead to either NoSuchAlgorithmException or NoSuchPaddingException depending on how the provider register its implementations. This is not obvious by the current javadoc.

Solution

Clarifying the javadoc description for the static getInstance(...) methods regarding java.security.NoSuchAlgorithmException and javax.crypto.NoSuchPaddingException.

Specification

Modify the javadoc of the following methods of javax.crypto.Cipher class
1) getInstance(String transformation):

      * @throws NoSuchAlgorithmException if {@code transformation}
      *         is {@code null}, empty, in an invalid format,
-     *         or if no provider supports a {@code CipherSpi}
-     *         implementation for the specified algorithm
+     *         or if a {@code CipherSpi} implementation is not found, or
+     *         is found but does not support the mode
      *
-     * @throws NoSuchPaddingException if {@code transformation}
-     *         contains a padding scheme that is not available
+     * @throws NoSuchPaddingException if a {@code CipherSpi} implementation
+     *         is found but does not support the padding scheme
      *

1) getInstance(String transformation, String provider):

      * @throws NoSuchAlgorithmException if {@code transformation}
      *         is {@code null}, empty, in an invalid format,
-     *         or if a {@code CipherSpi} implementation for the
-     *         specified algorithm is not available from the specified
-     *         provider
+     *         or if a {@code CipherSpi} implementation from the specified
+     *         {@code provider} is not found, or is found but does not support
+     *         the mode
      *
-     * @throws NoSuchPaddingException if {@code transformation}
-     *         contains a padding scheme that is not available
+     * @throws NoSuchPaddingException if a {@code CipherSpi} implementation
+     *         from the specified {@code provider} is found but it does not
+     *         support the padding scheme
      *

2) getInstance(String transformation, Provider provider):

      * @throws NoSuchAlgorithmException if {@code transformation}
      *         is {@code null}, empty, in an invalid format,
-     *         or if a {@code CipherSpi} implementation for the
-     *         specified algorithm is not available from the specified
-     *         {@code provider} object
+     *         or if a {@code CipherSpi} implementation from the specified
+     *         {@code provider} is not found, or is found but does not support
+     *         the mode
      *
-     * @throws NoSuchPaddingException if {@code transformation}
-     *         contains a padding scheme that is not available
+     * @throws NoSuchPaddingException if a {@code CipherSpi} implementation
+     *         from the specified {@code provider} is found but it does not
+     *         support the padding scheme