content: /*
   * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
   * particular file as subject to the "Classpath" exception as provided
   * by Oracle in the LICENSE file that accompanied this code.
   *
   * This code is distributed in the hope that it will be useful, but WITHOUT
   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   * version 2 for more details (a copy is included in the LICENSE file that
   * accompanied this code).
   *
   * You should have received a copy of the GNU General Public License version
   * 2 along with this work; if not, write to the Free Software Foundation,
   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   *
   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   * or visit www.oracle.com if you need additional information or have any
   * questions.
   */
  
  package java.security.cert;
  
  import java.util.Collection;
  import java.util.Set;
  
  /**
   * An abstract class that performs one or more checks on an
   * {@code X509Certificate}.
   *
   * <p>A concrete implementation of the {@code PKIXCertPathChecker} class
   * can be created to extend the PKIX certification path validation algorithm.
   * For example, an implementation may check for and process a critical private
   * extension of each certificate in a certification path.
   *
   * <p>Instances of {@code PKIXCertPathChecker} are passed as parameters
   * using the {@link PKIXParameters#setCertPathCheckers setCertPathCheckers}
   * or {@link PKIXParameters#addCertPathChecker addCertPathChecker} methods
   * of the {@code PKIXParameters} and {@code PKIXBuilderParameters}
   * class. Each of the {@code PKIXCertPathChecker}s {@link #check check}
   * methods will be called, in turn, for each certificate processed by a PKIX
   * {@code CertPathValidator} or {@code CertPathBuilder}
   * implementation.
   *
   * <p>A {@code PKIXCertPathChecker} may be called multiple times on
   * successive certificates in a certification path. Concrete subclasses
   * are expected to maintain any internal state that may be necessary to
   * check successive certificates. The {@link #init init} method is used
   * to initialize the internal state of the checker so that the certificates
   * of a new certification path may be checked. A stateful implementation
   * <b>must</b> override the {@link #clone clone} method if necessary in
   * order to allow a PKIX {@code CertPathBuilder} to efficiently
   * backtrack and try other paths. In these situations, the
   * {@code CertPathBuilder} is able to restore prior path validation
   * states by restoring the cloned {@code PKIXCertPathChecker}s.
   *
   * <p>The order in which the certificates are presented to the
   * {@code PKIXCertPathChecker} may be either in the forward direction
   * (from target to most-trusted CA) or in the reverse direction (from
   * most-trusted CA to target). A {@code PKIXCertPathChecker} implementation
   * <b>must</b> support reverse checking (the ability to perform its checks when
   * it is presented with certificates in the reverse direction) and <b>may</b>
   * support forward checking (the ability to perform its checks when it is
   * presented with certificates in the forward direction). The
   * {@link #isForwardCheckingSupported isForwardCheckingSupported} method
   * indicates whether forward checking is supported.
   * <p>
   * Additional input parameters required for executing the check may be
   * specified through constructors of concrete implementations of this class.
   * <p>
   * <b>Concurrent Access</b>
   * <p>
   * Unless otherwise specified, the methods defined in this class are not
   * thread-safe. Multiple threads that need to access a single
   * object concurrently should synchronize amongst themselves and
   * provide the necessary locking. Multiple threads each manipulating
   * separate objects need not synchronize.
   *
   * @see PKIXParameters
   * @see PKIXBuilderParameters
   *
   * @since       1.4
   * @author      Yassir Elley
   * @author      Sean Mullan
   */
  public abstract class PKIXCertPathChecker
      implements CertPathChecker, Cloneable {
  
      /**
       * Default constructor.
       */
      protected PKIXCertPathChecker() {}
  
      /**
       * Initializes the internal state of this {@code PKIXCertPathChecker}.
       * <p>
       * The {@code forward} flag specifies the order that
       * certificates will be passed to the {@link #check check} method
       * (forward or reverse). A {@code PKIXCertPathChecker} <b>must</b>
       * support reverse checking and <b>may</b> support forward checking.
       *
       * @param forward the order that certificates are presented to
       * the {@code check} method. If {@code true}, certificates
       * are presented from target to most-trusted CA (forward); if
       * {@code false}, from most-trusted CA to target (reverse).
       * @throws CertPathValidatorException if this
       * {@code PKIXCertPathChecker} is unable to check certificates in
       * the specified order; it should never be thrown if the forward flag
       * is false since reverse checking must be supported
       */
      @Override
      public abstract void init(boolean forward)
          throws CertPathValidatorException;
  
      /**
       * Indicates if forward checking is supported. Forward checking refers
       * to the ability of the {@code PKIXCertPathChecker} to perform
       * its checks when certificates are presented to the {@code check}
       * method in the forward direction (from target to most-trusted CA).
       *
       * @return {@code true} if forward checking is supported,
       * {@code false} otherwise
       */
      @Override
      public abstract boolean isForwardCheckingSupported();
  
      /**
       * Returns an immutable {@code Set} of X.509 certificate extensions
       * that this {@code PKIXCertPathChecker} supports (i.e. recognizes, is
       * able to process), or {@code null} if no extensions are supported.
       * <p>
       * Each element of the set is a {@code String} representing the
       * Object Identifier (OID) of the X.509 extension that is supported.
       * The OID is represented by a set of nonnegative integers separated by
       * periods.
       * <p>
       * All X.509 certificate extensions that a {@code PKIXCertPathChecker}
       * might possibly be able to process should be included in the set.
       *
       * @return an immutable {@code Set} of X.509 extension OIDs (in
       * {@code String} format) supported by this
       * {@code PKIXCertPathChecker}, or {@code null} if no
       * extensions are supported
       */
      public abstract Set<String> getSupportedExtensions();
  
      /**
       * Performs the check(s) on the specified certificate using its internal
       * state and removes any critical extensions that it processes from the
       * specified collection of OID strings that represent the unresolved
       * critical extensions. The certificates are presented in the order
       * specified by the {@code init} method.
       *
       * @param cert the {@code Certificate} to be checked
       * @param unresolvedCritExts a {@code Collection} of OID strings
       * representing the current set of unresolved critical extensions
       * @exception CertPathValidatorException if the specified certificate does
       * not pass the check
       */
      public abstract void check(Certificate cert,
              Collection<String> unresolvedCritExts)
              throws CertPathValidatorException;
  
      /**
       * {@inheritDoc}
       *
       * <p>This implementation calls
       * {@code check(cert, java.util.Collections.<String>emptySet())}.
       */
      @Override
      public void check(Certificate cert) throws CertPathValidatorException {
          check(cert, java.util.Collections.<String>emptySet());
      }
  
      /**
       * Returns a clone of this object. Calls the {@code Object.clone()}
       * method.
       * All subclasses which maintain state must support and
       * override this method, if necessary.
       *
       * @return a copy of this {@code PKIXCertPathChecker}
       */
      @Override
      public Object clone() {
          try {
              return super.clone();
          } catch (CloneNotSupportedException e) {
              /* Cannot happen */
              throw new InternalError(e.toString(), e);
          }
      }
  }
  