View Javadoc
1   /*
2    * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package java.security.cert;
27  
28  import java.security.InvalidAlgorithmParameterException;
29  import java.util.Collection;
30  
31  /**
32   * The <i>Service Provider Interface</i> (<b>SPI</b>)
33   * for the {@link CertStore CertStore} class. All {@code CertStore}
34   * implementations must include a class (the SPI class) that extends
35   * this class ({@code CertStoreSpi}), provides a constructor with
36   * a single argument of type {@code CertStoreParameters}, and implements
37   * all of its methods. In general, instances of this class should only be
38   * accessed through the {@code CertStore} class.
39   * For details, see the Java Cryptography Architecture.
40   * <p>
41   * <b>Concurrent Access</b>
42   * <p>
43   * The public methods of all {@code CertStoreSpi} objects must be
44   * thread-safe. That is, multiple threads may concurrently invoke these
45   * methods on a single {@code CertStoreSpi} object (or more than one)
46   * with no ill effects. This allows a {@code CertPathBuilder} to search
47   * for a CRL while simultaneously searching for further certificates, for
48   * instance.
49   * <p>
50   * Simple {@code CertStoreSpi} implementations will probably ensure
51   * thread safety by adding a {@code synchronized} keyword to their
52   * {@code engineGetCertificates} and {@code engineGetCRLs} methods.
53   * More sophisticated ones may allow truly concurrent access.
54   *
55   * @since       1.4
56   * @author      Steve Hanna
57   */
58  public abstract class CertStoreSpi {
59  
60      /**
61       * The sole constructor.
62       *
63       * @param params the initialization parameters (may be {@code null})
64       * @throws InvalidAlgorithmParameterException if the initialization
65       * parameters are inappropriate for this {@code CertStoreSpi}
66       */
67      public CertStoreSpi(CertStoreParameters params)
68      throws InvalidAlgorithmParameterException { }
69  
70      /**
71       * Returns a {@code Collection} of {@code Certificate}s that
72       * match the specified selector. If no {@code Certificate}s
73       * match the selector, an empty {@code Collection} will be returned.
74       * <p>
75       * For some {@code CertStore} types, the resulting
76       * {@code Collection} may not contain <b>all</b> of the
77       * {@code Certificate}s that match the selector. For instance,
78       * an LDAP {@code CertStore} may not search all entries in the
79       * directory. Instead, it may just search entries that are likely to
80       * contain the {@code Certificate}s it is looking for.
81       * <p>
82       * Some {@code CertStore} implementations (especially LDAP
83       * {@code CertStore}s) may throw a {@code CertStoreException}
84       * unless a non-null {@code CertSelector} is provided that includes
85       * specific criteria that can be used to find the certificates. Issuer
86       * and/or subject names are especially useful criteria.
87       *
88       * @param selector A {@code CertSelector} used to select which
89       *  {@code Certificate}s should be returned. Specify {@code null}
90       *  to return all {@code Certificate}s (if supported).
91       * @return A {@code Collection} of {@code Certificate}s that
92       *         match the specified selector (never {@code null})
93       * @throws CertStoreException if an exception occurs
94       */
95      public abstract Collection<? extends Certificate> engineGetCertificates
96              (CertSelector selector) throws CertStoreException;
97  
98      /**
99       * Returns a {@code Collection} of {@code CRL}s that
100      * match the specified selector. If no {@code CRL}s
101      * match the selector, an empty {@code Collection} will be returned.
102      * <p>
103      * For some {@code CertStore} types, the resulting
104      * {@code Collection} may not contain <b>all</b> of the
105      * {@code CRL}s that match the selector. For instance,
106      * an LDAP {@code CertStore} may not search all entries in the
107      * directory. Instead, it may just search entries that are likely to
108      * contain the {@code CRL}s it is looking for.
109      * <p>
110      * Some {@code CertStore} implementations (especially LDAP
111      * {@code CertStore}s) may throw a {@code CertStoreException}
112      * unless a non-null {@code CRLSelector} is provided that includes
113      * specific criteria that can be used to find the CRLs. Issuer names
114      * and/or the certificate to be checked are especially useful.
115      *
116      * @param selector A {@code CRLSelector} used to select which
117      *  {@code CRL}s should be returned. Specify {@code null}
118      *  to return all {@code CRL}s (if supported).
119      * @return A {@code Collection} of {@code CRL}s that
120      *         match the specified selector (never {@code null})
121      * @throws CertStoreException if an exception occurs
122      */
123     public abstract Collection<? extends CRL> engineGetCRLs
124             (CRLSelector selector) throws CertStoreException;
125 }