Summary

Improve the PKIXParameters and PKIXRevocationChecker specifications to be consistent with the existing behavior when a PKIXRevocationChecker is supplied as one of the CertPathChecker parameters.

Problem

The behavior as currently specified by PKIXParameters.setRevocationEnabled when a PKIXRevocationChecker is passed in as a CertPathChecker is not very clear, and could be improved.

Solution

Clarify the PKIXParameters and PKIXRevocationChecker specifications to be consistent with the existing behavior and make it more clear that a PKIXRevocationChecker overrides the default revocation checking mechanism of a PKIX service provider, and will be used to check revocation irrespective of the setting of the RevocationEnabled parameter.

Specification

1. Clarify the specification of the setRevocationEnabled and getRevocationEnabled methods of PKIXParameters as follows:

     /**
      * Sets the RevocationEnabled flag. If this flag is true, the default
      * revocation checking mechanism of the underlying PKIX service provider
-     * will be used. If this flag is false, the default revocation checking
-     * mechanism will be disabled (not used).
+     * will be used, unless a {@link PKIXRevocationChecker} is passed in
+     * as a {@code CertPathChecker} (see below for further explanation). If
+     * this flag is false, the default revocation checking mechanism will be
+     * disabled (not used).
      * <p>
      * When a {@code PKIXParameters} object is created, this flag is set
      * to true. This setting reflects the most common strategy for checking
      * revocation, since each service provider must support revocation
      * checking to be PKIX compliant. Sophisticated applications should set
@@ -331,10 +333,15 @@
      * this flag to false when it is not practical to use a PKIX service
      * provider's default revocation checking mechanism or when an alternative
      * revocation checking mechanism is to be substituted (by also calling the
      * {@link #addCertPathChecker addCertPathChecker} or {@link
      * #setCertPathCheckers setCertPathCheckers} methods).
+     * <p>
+     * Note that when a {@code PKIXRevocationChecker} is passed in as a
+     * parameter via the {@code addCertPathChecker} or
+     * {@code setCertPathCheckers} methods, it will be used to check
+     * revocation irrespective of the setting of the RevocationEnabled flag.
      *
      * @param val the new value of the RevocationEnabled flag
      */
     public void setRevocationEnabled(boolean val) {
         revocationEnabled = val;

     /**
      * Checks the RevocationEnabled flag. If this flag is true, the default
      * revocation checking mechanism of the underlying PKIX service provider
-     * will be used. If this flag is false, the default revocation checking
-     * mechanism will be disabled (not used). See the {@link
+     * will be used, unless a {@link PKIXRevocationChecker} is passed in as
+     * a {@code CertPathChecker}. If this flag is false, the default revocation
+     * checking mechanism will be disabled (not used). See the {@link
      * #setRevocationEnabled setRevocationEnabled} method for more details on
      * setting the value of this flag.
      *
      * @return the current value of the RevocationEnabled flag
      */

2. Change the class summary of PKIXRevocationChecker to be more clear that it will override the default revocation checking mechanism:

  * or {@link PKIXParameters#setCertPathCheckers setCertPathCheckers} method,
  * and then the {@code PKIXParameters} is passed along with the {@code CertPath}
  * to be validated to the {@link CertPathValidator#validate validate} method
  * of a PKIX {@code CertPathValidator}. When supplying a revocation checker in
  * this manner, it will be used to check revocation irrespective of the setting
- * of the {@link PKIXParameters#isRevocationEnabled RevocationEnabled} flag.
- * Similarly, a {@code PKIXRevocationChecker} may be added to a
- * {@code PKIXBuilderParameters} object for use with a PKIX
+ * of the {@link PKIXParameters#isRevocationEnabled RevocationEnabled} flag,
+ * and will override the default revocation checking mechanism of the PKIX
+ * service provider. Similarly, a {@code PKIXRevocationChecker} may be added
+ * to a {@code PKIXBuilderParameters} object for use with a PKIX
  * {@code CertPathBuilder}.
  *
  * <p>Note that when a {@code PKIXRevocationChecker} is added to
  * {@code PKIXParameters}, it clones the {@code PKIXRevocationChecker};
  * thus any subsequent modifications to the {@code PKIXRevocationChecker}