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;
29
30/**
31 *
32 * The <i>Service Provider Interface</i> (<b>SPI</b>)
33 * for the {@link CertPathValidator CertPathValidator} class. All
34 * {@code CertPathValidator} implementations must include a class (the
35 * SPI class) that extends this class ({@code CertPathValidatorSpi})
36 * and implements all of its methods. In general, instances of this class
37 * should only be accessed through the {@code CertPathValidator} class.
38 * For details, see the Java Cryptography Architecture.
39 * <p>
40 * <b>Concurrent Access</b>
41 * <p>
42 * Instances of this class need not be protected against concurrent
43 * access from multiple threads. Threads that need to access a single
44 * {@code CertPathValidatorSpi} instance concurrently should synchronize
45 * amongst themselves and provide the necessary locking before calling the
46 * wrapping {@code CertPathValidator} object.
47 * <p>
48 * However, implementations of {@code CertPathValidatorSpi} may still
49 * encounter concurrency issues, since multiple threads each
50 * manipulating a different {@code CertPathValidatorSpi} instance need not
51 * synchronize.
52 *
53 * @since       1.4
54 * @author      Yassir Elley
55 */
56public abstract class CertPathValidatorSpi {
57
58    /**
59     * The default constructor.
60     */
61    public CertPathValidatorSpi() {}
62
63    /**
64     * Validates the specified certification path using the specified
65     * algorithm parameter set.
66     * <p>
67     * The {@code CertPath} specified must be of a type that is
68     * supported by the validation algorithm, otherwise an
69     * {@code InvalidAlgorithmParameterException} will be thrown. For
70     * example, a {@code CertPathValidator} that implements the PKIX
71     * algorithm validates {@code CertPath} objects of type X.509.
72     *
73     * @param certPath the {@code CertPath} to be validated
74     * @param params the algorithm parameters
75     * @return the result of the validation algorithm
76     * @exception CertPathValidatorException if the {@code CertPath}
77     * does not validate
78     * @exception InvalidAlgorithmParameterException if the specified
79     * parameters or the type of the specified {@code CertPath} are
80     * inappropriate for this {@code CertPathValidator}
81     */
82    public abstract CertPathValidatorResult
83        engineValidate(CertPath certPath, CertPathParameters params)
84        throws CertPathValidatorException, InvalidAlgorithmParameterException;
85
86    /**
87     * Returns a {@code CertPathChecker} that this implementation uses to
88     * check the revocation status of certificates. A PKIX implementation
89     * returns objects of type {@code PKIXRevocationChecker}.
90     *
91     * <p>The primary purpose of this method is to allow callers to specify
92     * additional input parameters and options specific to revocation checking.
93     * See the class description of {@code CertPathValidator} for an example.
94     *
95     * <p>This method was added to version 1.8 of the Java Platform Standard
96     * Edition. In order to maintain backwards compatibility with existing
97     * service providers, this method cannot be abstract and by default throws
98     * an {@code UnsupportedOperationException}.
99     *
100     * @return a {@code CertPathChecker} that this implementation uses to
101     * check the revocation status of certificates
102     * @throws UnsupportedOperationException if this method is not supported
103     * @since 1.8
104     */
105    public CertPathChecker engineGetRevocationChecker() {
106        throw new UnsupportedOperationException();
107    }
108}
109