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
26package java.security.cert;
27
28import java.security.InvalidAlgorithmParameterException;
29import 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 */
58public 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}
126