Summary

Update the javadoc of the static 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 both methods with existing behaviors.

Specification

Modify the javadoc of the following methods of javax.crypto.Cipher class
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
+     *         specified {@code transformation} is not available from
+     *         the {@code provider} due to causes not covered by the
+     *         {@code NoSuchPaddingException}
      *
-     * @throws NoSuchPaddingException if {@code transformation}
-     *         contains a padding scheme that is not available
+     * @throws NoSuchPaddingException if a {@code CipherSpi} object
+     *         from the {@code provider} is found using the algorithm
+     *         and mode but not the padding scheme
      *
-     * @throws NoSuchProviderException if the specified provider is not
+     * @throws NoSuchProviderException if the specified {@code provider} is not
      *         registered in the security provider list

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
+     *         specified {@code transformation} is not available from
+     *         the specified {@code provider} due to causes not covered
+     *         by the {@code NoSuchPaddingException}
      *
-     * @throws NoSuchPaddingException if {@code transformation}
-     *         contains a padding scheme that is not available
+     * @throws NoSuchPaddingException if the {@code CipherSpi} object
+     *         from the {@code provider} is found using the algorithm
+     *         and mode but not the padding scheme