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