CertStoreSpi


1   /*
2    * @(#)CertStoreSpi.java    1.7 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.security.cert;
9   
10  import java.security.InvalidAlgorithmParameterException  ;
11  import java.util.Collection  ;
12  
13  /**
14   * The <i>Service Provider Interface</i> (<b>SPI</b>)
15   * for the {@link CertStore CertStore} class. All <code>CertStore</code>
16   * implementations must include a class (the SPI class) that extends
17   * this class (<code>CertStoreSpi</code>), provides a constructor with
18   * a single argument of type <code>CertStoreParameters</code>, and implements 
19   * all of its methods. In general, instances of this class should only be
20   * accessed through the <code>CertStore</code> class. 
21   * For details, see the Java Cryptography Architecture.
22   * <p>
23   * <b>Concurrent Access</b>
24   * <p>
25   * The public methods of all <code>CertStoreSpi</code> objects must be 
26   * thread-safe. That is, multiple threads may concurrently invoke these 
27   * methods on a single <code>CertStoreSpi</code> object (or more than one) 
28   * with no ill effects. This allows a <code>CertPathBuilder</code> to search 
29   * for a CRL while simultaneously searching for further certificates, for 
30   * instance.
31   * <p>
32   * Simple <code>CertStoreSpi</code> implementations will probably ensure
33   * thread safety by adding a <code>synchronized</code> keyword to their
34   * <code>engineGetCertificates</code> and <code>engineGetCRLs</code> methods.
35   * More sophisticated ones may allow truly concurrent access.
36   *
37   * @version     1.7 12/19/03
38   * @since   1.4
39   * @author  Steve Hanna
40   */
41  public abstract class CertStoreSpi {
42  
43      /**
44       * The sole constructor.
45       *
46       * @param params the initialization parameters (may be <code>null</code>)
47       * @throws InvalidAlgorithmParameterException if the initialization
48       * parameters are inappropriate for this <code>CertStoreSpi</code>
49       */
50      public CertStoreSpi(CertStoreParameters   params) 
51      throws InvalidAlgorithmParameterException   { }
52  
53      /**
54       * Returns a <code>Collection</code> of <code>Certificate</code>s that
55       * match the specified selector. If no <code>Certificate</code>s
56       * match the selector, an empty <code>Collection</code> will be returned.
57       * <p>
58       * For some <code>CertStore</code> types, the resulting
59       * <code>Collection</code> may not contain <b>all</b> of the
60       * <code>Certificate</code>s that match the selector. For instance,
61       * an LDAP <code>CertStore</code> may not search all entries in the
62       * directory. Instead, it may just search entries that are likely to
63       * contain the <code>Certificate</code>s it is looking for. 
64       * <p>
65       * Some <code>CertStore</code> implementations (especially LDAP
66       * <code>CertStore</code>s) may throw a <code>CertStoreException</code>
67       * unless a non-null <code>CertSelector</code> is provided that includes
68       * specific criteria that can be used to find the certificates. Issuer
69       * and/or subject names are especially useful criteria.
70       *
71       * @param selector A <code>CertSelector</code> used to select which
72       *  <code>Certificate</code>s should be returned. Specify <code>null</code>
73       *  to return all <code>Certificate</code>s (if supported).
74       * @return A <code>Collection</code> of <code>Certificate</code>s that
75       *         match the specified selector (never <code>null</code>)
76       * @throws CertStoreException if an exception occurs 
77       */
78      public abstract Collection  <? extends Certificate  > engineGetCertificates
79          (CertSelector   selector) throws CertStoreException  ;
80       
81      /**
82       * Returns a <code>Collection</code> of <code>CRL</code>s that
83       * match the specified selector. If no <code>CRL</code>s
84       * match the selector, an empty <code>Collection</code> will be returned.
85       * <p>
86       * For some <code>CertStore</code> types, the resulting
87       * <code>Collection</code> may not contain <b>all</b> of the
88       * <code>CRL</code>s that match the selector. For instance,
89       * an LDAP <code>CertStore</code> may not search all entries in the
90       * directory. Instead, it may just search entries that are likely to
91       * contain the <code>CRL</code>s it is looking for. 
92       * <p>
93       * Some <code>CertStore</code> implementations (especially LDAP 
94       * <code>CertStore</code>s) may throw a <code>CertStoreException</code> 
95       * unless a non-null <code>CRLSelector</code> is provided that includes 
96       * specific criteria that can be used to find the CRLs. Issuer names 
97       * and/or the certificate to be checked are especially useful.
98       *
99       * @param selector A <code>CRLSelector</code> used to select which
100      *  <code>CRL</code>s should be returned. Specify <code>null</code>
101      *  to return all <code>CRL</code>s (if supported).
102      * @return A <code>Collection</code> of <code>CRL</code>s that
103      *         match the specified selector (never <code>null</code>)
104      * @throws CertStoreException if an exception occurs 
105      */
106     public abstract Collection  <? extends CRL  > engineGetCRLs
107         (CRLSelector   selector) throws CertStoreException  ;
108 }
109
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags