/**
 * PEMDecoder is an immutable Privacy-Enhanced Mail (PEM) decoding class.
 * PEM is a textual encoding used for storing and transferring security
 * objects, such as asymmetric keys, certificates, and certificate revocation
 * lists (CRL). Defined in RFC 1421 and RFC 7468, PEM consists of a
 * Base64-formatted binary encoding surrounded by a type identifying header
 * and footer.
 * <p>
 * Decoding methods return a class that matches the data type and implements
 * {@link DEREncodable}.
 * If a return class is specified, an IllegalAlgorithmException is thrown if
 * data is not valid for the class.
 * <p>
 * When passing input data into {@code decode}, the application is responsible
 * for processing input data non-PEM text. All data before the PEM
 * header will be ignored.
 * <p>
 * A new immutable PEMDecoder instance is returned by
 * {@linkplain #withFactory} and/or {@linkplain #withDecryption}.  Configuring
 * an instance for decryption does not prevent decoding with unencrypted PEM.
 * Any encrypted PEM that does not use the configured password will cause an
 * exception. A decoder instance not configured with decryption will return an
 * {@link EncryptedPrivateKeyInfo} with encrypted PEM.  EncryptedPrivateKeyInfo
 * methods must be used to retrieve the {@link PrivateKey}.
 * <p>
 * PEMDecoder supports the follow types:
 * <pre>
 *     PRIVATE KEY, RSA PRIVATE KEY, PUBLIC KEY, CERTIFICATE, CRL, and
 *     ENCRYPTED PRIVATE KEY.
 * </pre>
 * @apiNote
 * Here is an example of encoding a PrivateKey object:
 * <pre>
 *     PEMDecoder pd = PEMDecoder.of();
 *     PrivateKey priKey = pd.decode(PriKeyPEM);
 * </pre>
 *
 * @since 24
 */

@PreviewFeature(feature = PreviewFeature.Feature.PEM_API)
public final class PEMDecoder {


    /**
     * Returns an instance of PEMDecoder.  This instance may be repeatedly used
     * to decode different PEM text.
     *
     * @return returns a PEMDecoder
     */
    public static PEMDecoder of() {


    /**
     * Decodes and returns {@link DEREncodable} from the given string.
     *
     * @param str PEM data in a String.
     * @return an DEREncodable generated from the PEM data.
     * @throws IllegalArgumentException on error in decoding or if the PEM is
     * unsupported.
     */
    public DEREncodable decode(String str) {


    /**
     * Decodes and returns a {@link DEREncodable} from the given
     * {@code InputStream}.
     * The method will read the {@code InputStream} until PEM data is
     * found or until the end of the stream.  Non-PEM data in the
     * {@code InputStream} before the PEM header will be ignored by the decoder.
     *
     * @param is InputStream containing PEM data.
     * @return an DEREncodable generated from the PEM data.
     * @throws IOException on IO error with the InputStream.
     * @throws IllegalArgumentException on error in decoding or if the PEM is
     * unsupported.
     */
    public DEREncodable decode(InputStream is) throws IOException {


    /**
     * Decodes and returns the specified class for the given PEM string.  The
     * class must extend {@link DEREncodable} and be the appropriate class for
     * the PEM type.
     *
     * <p>With the {@code tClass} argument, the returned object may be cast to a
     * subclass or converted to a different return class, if
     * appropriate for that PEM data.  Using EC public key PEM as an example,
     * {@code tClass} may be set to {@code PublicKey.class},
     * {@code ECPublicKey}, or a {@code X509EncodedKeySpec}.  {@code PublicKey}
     * is useful for algorithm-agnostic methods, {@code ECPublicKey} for
     * algorithm-specific operations, or {@code X509EncodedKeySpec} if the
     * X.509 binary encoding is desired instead of a Key object.  An IOException
     * will be thrown if the class is incorrect for the given PEM data.
     *
     * @param <S> Class type parameter that extends {@link DEREncodable}
     * @param string the String containing PEM data.
     * @param tClass  the returned object class that implementing
     * {@link DEREncodable}.
     * @return The DEREncodable typecast to tClass.
     * @throws IllegalArgumentException on error in decoding or if the PEM is
     * unsupported.
     */
    public <S extends DEREncodable> S decode(String string, Class<S> tClass) {


    /**
     * Decodes and returns the specified class for the given PEM stream.  The
     * class must extend {@link DEREncodable} and be an appropriate class for
     * the PEM type.
     *
     * <p>See {@link PEMDecoder#decode(String, Class)} for details about
     * {@code tClass}.
     * <br>See {@link PEMDecoder#decode(InputStream)} for details on using an
     * {@code InputStream}.
     *
     * @param <S> Class type parameter that extends {@code DEREncodable}
     * @param is an InputStream containing PEM data.
     * @param tClass the returned object class that implementing
     *   {@code DEREncodable}.
     * @return  tClass.
     * @throws IOException on IO error with the InputStream.
     * @throws IllegalArgumentException on error in decoding or if the PEM is
     * unsupported.
     */
    public <S extends DEREncodable> S decode(InputStream is, Class<S> tClass)
        throws IOException {

    }

    /**
     * Configures and return a new PEMDecoder instance from the current instance
     * that will use Factory classes from the specified Provider.
     *
     * @param provider the Factory provider.
     * @return a new PEM decoder instance.
     */
    public PEMDecoder withFactory(Provider provider) {


    /**
     * Returns a new PEMDecoder instance from the current instance configured
     * to decrypt encrypted PEM data with given password.
     * Non-encrypted PEM may still be decoded from this instance.
     *
     * @param password the password to decrypt encrypted PEM data.
     * @return the decoder
     * @throws NullPointerException if password is null.
     */
    public PEMDecoder withDecryption(char[] password) {

}