Summary
-------
The protected constructor of javax.crypto.Cipher class throws an undocumented NullPointerException.

Problem
-------
javax.crypto.Cipher class has a protected constructor for JCE providers to wrap their implementation class into a Cipher object. This constructor throws NullPointerException when provider argument is null. It also throws NullPointerException when provider argument is not null but cannot be verified or used for this Cipher object construction. This may be unexpected as NullPointerException is often thrown as a result of illegal uses of null values.

Solution
--------
Change the constructor to throw IllegalArgumentException instead of NullPointerException when provider argument is not null but invalid. Document the javadoc of the protected constructor with both IllegalArgumentExceptionexception and NullPointerException (i.e. when provider argument is null).

Specification
-------------
Updating the javadoc for Cipher(CipherSpi, Provider, String) constructor with following changes:

        @@ -266,19 +266,22 @@
          * Creates a Cipher object.
          *
          * @param cipherSpi the delegate
          * @param provider the provider
          * @param transformation the transformation
    +     * @throws NullPointerException if {@code provider} is null
    +     * @throws IllegalArgumentException if the supplied arguments
    +     *         are deemed invalid for constructing the Cipher object
          */
         protected Cipher(CipherSpi cipherSpi,
                          Provider provider,
                          String transformation) {
             // See bug 4341369 & 4334690 for more info.
             // If the caller is trusted, then okay.
    -        // Otherwise throw a NullPointerException.
    +        // Otherwise throw an IllegalArgumentException.
             if (!JceSecurityManager.INSTANCE.isCallerTrusted(provider)) {
    -            throw new NullPointerException();
    +            throw new IllegalArgumentException("Cannot construct cipher");
             }
             this.spi = cipherSpi;
             this.provider = provider;
             this.transformation = transformation;
             this.cryptoPerm = CryptoAllPermission.INSTANCE;