Summary

Update the javadoc for java.security.Signature.getParameters() and java.security.SignatureSpi.engineGetParameters() methods with the changes below:

1. document existing exception UnsupportedOperationException
2. the returned parameters may be a combination of user-supplied parameter values and provider-specific default or random parameter values. Adopted the recent javadoc update for Cipher.getParameters() (under JDK-8209038) for consistency sake.

Problem

java.security.Signature.getParameters() method throws UnsupportedOperationException if the provider's signature impl does not override the SignatureSpi.engineGetParameters() method. Thus, Signature.getParameters() should document the UnsupportedOperationException. In addition, the javadoc also states that the returned parameter is either the user-specified parameters or provider-specific default/random parameters. However, it's possible that callers may not supply all parameter values and the returned parameters may contain additional provider-specific defaults or random values. Existing javadoc should be clarified.

Solution

Update the javadoc of java.security.Signature.getParameters() method to cover the UnsupportedOperationException and the combined parameters scenario. Similar javadoc wording changes are made to java.security.SignatureSpi.engineGetParameters() method.

Specification

1) Update of the java.security.Signature.getParameters() method javadoc:

@@ -1003,21 +1003,24 @@
     }

     /**
      * Returns the parameters used with this signature object.
      *
-     * <p> If this signature has been initialized with parameters
-     * (by calling {@link #setParameter(AlgorithmParameterSpec)} or
-     * {@link #setParameter(String, Object)}) and the underlying signature
-     * implementation supports returning the parameters as
-     * {@code AlgorithmParameters}, this method returns the same parameters.
-     * If the parameters were not set, this method may return a combination
-     * of default and randomly generated parameter values if the
-     * underlying signature implementation supports it and can successfully
-     * generate them. Otherwise, {@code null} is returned.
-     *
-     * @return the parameters used with this signature, or {@code null}
+     * <p>The returned parameters may be the same that were used to initialize
+     * this signature object, or may contain additional default or random
+     * parameter values used by the underlying signature scheme. If the required
+     * parameters were not supplied and can be generated by the signature
+     * object, the generated parameters are returned; otherwise {@code null} is
+     * returned.
+     *
+     * <p>However, if the signature scheme does not support returning
+     * the parameters as {@code AlgorithmParameters}, {@code null} is always
+     * returned.
+     *
+     * @return the parameters used with this signature object, or {@code null}
+     * @throws UnsupportedOperationException if the provider does not support
+     * this method
      *
      * @see #setParameter(AlgorithmParameterSpec)
      * @since 1.4
      */
     public final AlgorithmParameters getParameters() {

2) Update of the java.security.SignatureSpi.engineGetParameters() method javadoc:

@@ -387,27 +386,27 @@
             throws InvalidAlgorithmParameterException {
         throw new UnsupportedOperationException();
     }

     /**
-     * <p>This method is overridden by providers to return the parameters
-     * used with this signature engine.
-     *
-     * <p> If this signature engine has been initialized with parameters
-     * (by calling {@link #engineSetParameter(AlgorithmParameterSpec)} or
-     * {@link #engineSetParameter(String, Object)}) and the underlying signature
-     * implementation supports returning the parameters as
-     * {@code AlgorithmParameters}, this method returns the same parameters.
-     * If the parameters were not set, this method may return a combination
-     * of default and randomly generated parameter values if the
-     * underlying signature implementation supports it and can successfully
-     * generate them. Otherwise, {@code null} is returned.
-     *
-     * @return the parameters used with this signature engine, or {@code null}
-     *
-     * @throws    UnsupportedOperationException if this method is
-     * not overridden by a provider
+     * Returns the parameters used with this signature object.
+     *
+     * <p>The returned parameters may be the same that were used to initialize
+     * this signature object, or may contain additional default or random
+     * parameter values used by the underlying signature scheme. If the required
+     * parameters were not supplied and can be generated by the signature
+     * object, the generated parameters are returned; otherwise {@code null} is
+     * returned.
+     *
+     * <p>However, if the signature scheme does not support returning
+     * the parameters as {@code AlgorithmParameters}, {@code null} is always
+     * returned.
+     *
+     * @return the parameters used with this signature object, or {@code null}
+     *
+     * @throws UnsupportedOperationException if this method is not overridden
+     * by a provider
      * @since 1.4
      */
     protected AlgorithmParameters engineGetParameters() {
         throw new UnsupportedOperationException();
     }