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.security.InvalidAlgorithmParameterException;
  import java.util.Collection;
  
  /**
   * The <i>Service Provider Interface</i> (<b>SPI</b>)
   * for the {@link CertStore CertStore} class. All {@code CertStore}
   * implementations must include a class (the SPI class) that extends
   * this class ({@code CertStoreSpi}), provides a constructor with
   * a single argument of type {@code CertStoreParameters}, and implements
   * all of its methods. In general, instances of this class should only be
   * accessed through the {@code CertStore} class.
   * For details, see the Java Cryptography Architecture.
   * <p>
   * <b>Concurrent Access</b>
   * <p>
   * The public methods of all {@code CertStoreSpi} objects must be
   * thread-safe. That is, multiple threads may concurrently invoke these
   * methods on a single {@code CertStoreSpi} object (or more than one)
   * with no ill effects. This allows a {@code CertPathBuilder} to search
   * for a CRL while simultaneously searching for further certificates, for
   * instance.
   * <p>
   * Simple {@code CertStoreSpi} implementations will probably ensure
   * thread safety by adding a {@code synchronized} keyword to their
   * {@code engineGetCertificates} and {@code engineGetCRLs} methods.
   * More sophisticated ones may allow truly concurrent access.
   *
   * @since       1.4
   * @author      Steve Hanna
   */
  public abstract class CertStoreSpi {
  
      /**
       * The sole constructor.
       *
       * @param params the initialization parameters (may be {@code null})
       * @throws InvalidAlgorithmParameterException if the initialization
       * parameters are inappropriate for this {@code CertStoreSpi}
       */
      public CertStoreSpi(CertStoreParameters params)
      throws InvalidAlgorithmParameterException { }
  
      /**
       * Returns a {@code Collection} of {@code Certificate}s that
       * match the specified selector. If no {@code Certificate}s
       * match the selector, an empty {@code Collection} will be returned.
       * <p>
       * For some {@code CertStore} types, the resulting
       * {@code Collection} may not contain <b>all</b> of the
       * {@code Certificate}s that match the selector. For instance,
       * an LDAP {@code CertStore} may not search all entries in the
       * directory. Instead, it may just search entries that are likely to
       * contain the {@code Certificate}s it is looking for.
       * <p>
       * Some {@code CertStore} implementations (especially LDAP
       * {@code CertStore}s) may throw a {@code CertStoreException}
       * unless a non-null {@code CertSelector} is provided that includes
       * specific criteria that can be used to find the certificates. Issuer
       * and/or subject names are especially useful criteria.
       *
       * @param selector A {@code CertSelector} used to select which
       *  {@code Certificate}s should be returned. Specify {@code null}
       *  to return all {@code Certificate}s (if supported).
       * @return A {@code Collection} of {@code Certificate}s that
       *         match the specified selector (never {@code null})
       * @throws CertStoreException if an exception occurs
       */
      public abstract Collection<? extends Certificate> engineGetCertificates
              (CertSelector selector) throws CertStoreException;
  
      /**
       * Returns a {@code Collection} of {@code CRL}s that
       * match the specified selector. If no {@code CRL}s
       * match the selector, an empty {@code Collection} will be returned.
       * <p>
       * For some {@code CertStore} types, the resulting
       * {@code Collection} may not contain <b>all</b> of the
       * {@code CRL}s that match the selector. For instance,
       * an LDAP {@code CertStore} may not search all entries in the
       * directory. Instead, it may just search entries that are likely to
       * contain the {@code CRL}s it is looking for.
       * <p>
       * Some {@code CertStore} implementations (especially LDAP
       * {@code CertStore}s) may throw a {@code CertStoreException}
       * unless a non-null {@code CRLSelector} is provided that includes
       * specific criteria that can be used to find the CRLs. Issuer names
       * and/or the certificate to be checked are especially useful.
       *
       * @param selector A {@code CRLSelector} used to select which
       *  {@code CRL}s should be returned. Specify {@code null}
       *  to return all {@code CRL}s (if supported).
       * @return A {@code Collection} of {@code CRL}s that
       *         match the specified selector (never {@code null})
       * @throws CertStoreException if an exception occurs
       */
      public abstract Collection<? extends CRL> engineGetCRLs
              (CRLSelector selector) throws CertStoreException;
  }
  