Add implementation notes to public APIs

Update public APIs documentation with implementation notes to reflect
the effect of the jdk.security.providers.filter Security and System
properties.

Co-authored-by: Martin Balao Alonso <[email protected]>
Co-authored-by: Francisco Ferrari Bihurriet <[email protected]>

Author: martinuy

src/java.base/share/classes/java/security/AlgorithmParameterGenerator.java

@@ -148,12 +148,20 @@ public final String getAlgorithm() {
      * the {@link Security#getProviders() Security.getProviders()} method.
      *
      * @implNote
-     * The JDK Reference Implementation additionally uses the
-     * {@code jdk.security.provider.preferred}
-     * {@link Security#getProperty(String) Security} property to determine
-     * the preferred provider order for the specified algorithm. This
-     * may be different from the order of providers returned by
-     * {@link Security#getProviders() Security.getProviders()}.
+     * The JDK Reference Implementation additionally uses the following
+     * properties to customize the behavior of this method:
+     * <ul>
+     * <li> The {@code jdk.security.provider.preferred}
+     * {@link Security#getProperty(String) Security} property determines
+     * the preferred provider order for the specified algorithm.
+     * This may be different from the order of providers returned by
+     * {@link Security#getProviders() Security.getProviders()}.</li>
+     * <li> The {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties determine
+     * which services are enabled. A service that is not enabled by the
+     * filter will not make its algorithm implementation available.</li>
+     * </ul>
      *
      * @param algorithm the name of the algorithm this
      * parameter generator is associated with.
@@ -201,6 +209,14 @@ public static AlgorithmParameterGenerator getInstance(String algorithm)
      * <p> Note that the list of registered providers may be retrieved via
      * the {@link Security#getProviders() Security.getProviders()} method.
      *
+     * @implNote
+     * The JDK Reference Implementation additionally uses the
+     * {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties to determine
+     * which services are enabled. A service that is not enabled by the filter
+     * will not make its algorithm implementation available.
+     *
      * @param algorithm the name of the algorithm this
      * parameter generator is associated with.
      * See the AlgorithmParameterGenerator section in the <a href=
@@ -252,6 +268,14 @@ public static AlgorithmParameterGenerator getInstance(String algorithm,
      * provider is returned.  Note that the specified provider does not
      * have to be registered in the provider list.
      *
+     * @implNote
+     * The JDK Reference Implementation additionally uses the
+     * {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties to determine
+     * which services are enabled. A service that is not enabled by the filter
+     * will not make its algorithm implementation available.
+     *
      * @param algorithm the string name of the algorithm this
      * parameter generator is associated with.
      * See the AlgorithmParameterGenerator section in the <a href=

src/java.base/share/classes/java/security/AlgorithmParameters.java

@@ -135,12 +135,20 @@ public final String getAlgorithm() {
      * parameter encoding.
      *
      * @implNote
-     * The JDK Reference Implementation additionally uses the
-     * {@code jdk.security.provider.preferred}
-     * {@link Security#getProperty(String) Security} property to determine
-     * the preferred provider order for the specified algorithm. This
-     * may be different from the order of providers returned by
-     * {@link Security#getProviders() Security.getProviders()}.
+     * The JDK Reference Implementation additionally uses the following
+     * properties to customize the behavior of this method:
+     * <ul>
+     * <li> The {@code jdk.security.provider.preferred}
+     * {@link Security#getProperty(String) Security} property determines
+     * the preferred provider order for the specified algorithm.
+     * This may be different from the order of providers returned by
+     * {@link Security#getProviders() Security.getProviders()}.</li>
+     * <li> The {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties determine
+     * which services are enabled. A service that is not enabled by the
+     * filter will not make its algorithm implementation available.</li>
+     * </ul>
      *
      * @param algorithm the name of the algorithm requested.
      * See the AlgorithmParameters section in the <a href=
@@ -188,6 +196,14 @@ public static AlgorithmParameters getInstance(String algorithm)
      * {@code init}, using an appropriate parameter specification or
      * parameter encoding.
      *
+     * @implNote
+     * The JDK Reference Implementation additionally uses the
+     * {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties to determine
+     * which services are enabled. A service that is not enabled by the filter
+     * will not make its algorithm implementation available.
+     *
      * @param algorithm the name of the algorithm requested.
      * See the AlgorithmParameters section in the <a href=
      * "{@docRoot}/../specs/security/standard-names.html#algorithmparameters-algorithms">
@@ -239,6 +255,14 @@ public static AlgorithmParameters getInstance(String algorithm,
      * {@code init}, using an appropriate parameter specification or
      * parameter encoding.
      *
+     * @implNote
+     * The JDK Reference Implementation additionally uses the
+     * {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties to determine
+     * which services are enabled. A service that is not enabled by the filter
+     * will not make its algorithm implementation available.
+     *
      * @param algorithm the name of the algorithm requested.
      * See the AlgorithmParameters section in the <a href=
      * "{@docRoot}/../specs/security/standard-names.html#algorithmparameters-algorithms">

src/java.base/share/classes/java/security/KeyFactory.java

@@ -157,12 +157,20 @@ private KeyFactory(String algorithm) throws NoSuchAlgorithmException {
      * the {@link Security#getProviders() Security.getProviders()} method.
      *
      * @implNote
-     * The JDK Reference Implementation additionally uses the
-     * {@code jdk.security.provider.preferred}
-     * {@link Security#getProperty(String) Security} property to determine
-     * the preferred provider order for the specified algorithm. This
-     * may be different from the order of providers returned by
-     * {@link Security#getProviders() Security.getProviders()}.
+     * The JDK Reference Implementation additionally uses the following
+     * properties to customize the behavior of this method:
+     * <ul>
+     * <li> The {@code jdk.security.provider.preferred}
+     * {@link Security#getProperty(String) Security} property determines
+     * the preferred provider order for the specified algorithm.
+     * This may be different from the order of providers returned by
+     * {@link Security#getProviders() Security.getProviders()}.</li>
+     * <li> The {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties determine
+     * which services are enabled. A service that is not enabled by the
+     * filter will not make its algorithm implementation available.</li>
+     * </ul>
      *
      * @param algorithm the name of the requested key algorithm.
      * See the KeyFactory section in the <a href=
@@ -199,6 +207,14 @@ public static KeyFactory getInstance(String algorithm)
      * <p> Note that the list of registered providers may be retrieved via
      * the {@link Security#getProviders() Security.getProviders()} method.
      *
+     * @implNote
+     * The JDK Reference Implementation additionally uses the
+     * {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties to determine
+     * which services are enabled. A service that is not enabled by the filter
+     * will not make its algorithm implementation available.
+     *
      * @param algorithm the name of the requested key algorithm.
      * See the KeyFactory section in the <a href=
      * "{@docRoot}/../specs/security/standard-names.html#keyfactory-algorithms">
@@ -242,6 +258,14 @@ public static KeyFactory getInstance(String algorithm, String provider)
      * is returned.  Note that the specified provider does not
      * have to be registered in the provider list.
      *
+     * @implNote
+     * The JDK Reference Implementation additionally uses the
+     * {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties to determine
+     * which services are enabled. A service that is not enabled by the filter
+     * will not make its algorithm implementation available.
+     *
      * @param algorithm the name of the requested key algorithm.
      * See the KeyFactory section in the <a href=
      * "{@docRoot}/../specs/security/standard-names.html#keyfactory-algorithms">

src/java.base/share/classes/java/security/KeyPairGenerator.java

@@ -204,12 +204,20 @@ private static KeyPairGenerator getInstance(Instance instance,
      * the {@link Security#getProviders() Security.getProviders()} method.
      *
      * @implNote
-     * The JDK Reference Implementation additionally uses the
-     * {@code jdk.security.provider.preferred}
-     * {@link Security#getProperty(String) Security} property to determine
-     * the preferred provider order for the specified algorithm. This
-     * may be different from the order of providers returned by
-     * {@link Security#getProviders() Security.getProviders()}.
+     * The JDK Reference Implementation additionally uses the following
+     * properties to customize the behavior of this method:
+     * <ul>
+     * <li> The {@code jdk.security.provider.preferred}
+     * {@link Security#getProperty(String) Security} property determines
+     * the preferred provider order for the specified algorithm.
+     * This may be different from the order of providers returned by
+     * {@link Security#getProviders() Security.getProviders()}.</li>
+     * <li> The {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties determine
+     * which services are enabled. A service that is not enabled by the
+     * filter will not make its algorithm implementation available.</li>
+     * </ul>
      *
      * @param algorithm the standard string name of the algorithm.
      * See the KeyPairGenerator section in the <a href=
@@ -269,6 +277,14 @@ public static KeyPairGenerator getInstance(String algorithm)
      * <p> Note that the list of registered providers may be retrieved via
      * the {@link Security#getProviders() Security.getProviders()} method.
      *
+     * @implNote
+     * The JDK Reference Implementation additionally uses the
+     * {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties to determine
+     * which services are enabled. A service that is not enabled by the filter
+     * will not make its algorithm implementation available.
+     *
      * @param algorithm the standard string name of the algorithm.
      * See the KeyPairGenerator section in the <a href=
      * "{@docRoot}/../specs/security/standard-names.html#keypairgenerator-algorithms">
@@ -312,6 +328,14 @@ public static KeyPairGenerator getInstance(String algorithm,
      * is returned.  Note that the specified provider does not
      * have to be registered in the provider list.
      *
+     * @implNote
+     * The JDK Reference Implementation additionally uses the
+     * {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties to determine
+     * which services are enabled. A service that is not enabled by the filter
+     * will not make its algorithm implementation available.
+     *
      * @param algorithm the standard string name of the algorithm.
      * See the KeyPairGenerator section in the <a href=
      * "{@docRoot}/../specs/security/standard-names.html#keypairgenerator-algorithms">

src/java.base/share/classes/java/security/KeyStore.java

@@ -842,12 +842,20 @@ private String getProviderName() {
      * the {@link Security#getProviders() Security.getProviders()} method.
      *
      * @implNote
-     * The JDK Reference Implementation additionally uses the
-     * {@code jdk.security.provider.preferred}
-     * {@link Security#getProperty(String) Security} property to determine
-     * the preferred provider order for the specified algorithm. This
-     * may be different from the order of providers returned by
-     * {@link Security#getProviders() Security.getProviders()}.
+     * The JDK Reference Implementation additionally uses the following
+     * properties to customize the behavior of this method:
+     * <ul>
+     * <li> The {@code jdk.security.provider.preferred}
+     * {@link Security#getProperty(String) Security} property determines
+     * the preferred provider order for the specified type.
+     * This may be different from the order of providers returned by
+     * {@link Security#getProviders() Security.getProviders()}.</li>
+     * <li> The {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties determine
+     * which services are enabled. A service that is not enabled by the
+     * filter will not make its type implementation available.</li>
+     * </ul>.
      *
      * @param type the type of keystore.
      * See the KeyStore section in the <a href=
@@ -889,6 +897,14 @@ public static KeyStore getInstance(String type)
      * <p> Note that the list of registered providers may be retrieved via
      * the {@link Security#getProviders() Security.getProviders()} method.
      *
+     * @implNote
+     * The JDK Reference Implementation additionally uses the
+     * {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties to determine
+     * which services are enabled. A service that is not enabled by the filter
+     * will not make its type implementation available.
+     *
      * @param type the type of keystore.
      * See the KeyStore section in the <a href=
      * "{@docRoot}/../specs/security/standard-names.html#keystore-types">
@@ -936,6 +952,14 @@ public static KeyStore getInstance(String type, String provider)
      * object is returned.  Note that the specified provider object
      * does not have to be registered in the provider list.
      *
+     * @implNote
+     * The JDK Reference Implementation additionally uses the
+     * {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties to determine
+     * which services are enabled. A service that is not enabled by the filter
+     * will not make its type implementation available.
+     *
      * @param type the type of keystore.
      * See the KeyStore section in the <a href=
      * "{@docRoot}/../specs/security/standard-names.html#keystore-types">
@@ -1678,6 +1702,14 @@ public final void setEntry(String alias, Entry entry,
      * <p> Note that the list of registered providers may be retrieved via
      * the {@link Security#getProviders() Security.getProviders()} method.
      *
+     * @implNote
+     * The JDK Reference Implementation additionally uses the
+     * {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties to determine
+     * which services are enabled. A service that is not enabled by the filter
+     * will not make its type implementation available.
+     *
      * @param  file the keystore file
      * @param  password the keystore password, which may be {@code null}
      *
@@ -1731,6 +1763,14 @@ public static final KeyStore getInstance(File file, char[] password)
      * <p> Note that the list of registered providers may be retrieved via
      * the {@link Security#getProviders() Security.getProviders()} method.
      *
+     * @implNote
+     * The JDK Reference Implementation additionally uses the
+     * {@code jdk.security.providers.filter}
+     * {@link System#getProperty(String) System} and
+     * {@link Security#getProperty(String) Security} properties to determine
+     * which services are enabled. A service that is not enabled by the filter
+     * will not make its type implementation available.
+     *
      * @param  file the keystore file
      * @param  param the {@code LoadStoreParameter} that specifies how to load
      *             the keystore, which may be {@code null}