jdk-sandbox: comparison src/java.base/share/classes/java/security/KeyStore.java

equal deleted inserted replaced

-:33de7752835c
+:94bb65cb37d3
 /*
-* Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
+* Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * "{@docRoot}/../specs/security/standard-names.html#cipher-algorithm-names">
 * Java Security Standard Algorithm Names Specification</a>
 *     for information about standard encryption algorithm names.
 * @param protectionParameters the encryption algorithm parameter
 *     specification, which may be {@code null}
-* @exception NullPointerException if {@code protectionAlgorithm} is
+* @throws    NullPointerException if {@code protectionAlgorithm} is
 *     {@code null}
 *
 * @since 1.8
 */
 public PasswordProtection(char[] password, String protectionAlgorithm,
 * responsibility to zero out the password information
 * after it is no longer needed.
 *
 * @see #destroy()
 * @return the password, which may be {@code null}
-* @exception IllegalStateException if the password has
+* @throws    IllegalStateException if the password has
 *              been cleared (destroyed)
 */
 public synchronized char[] getPassword() {
 if (destroyed) {
 throw new IllegalStateException("password has been cleared");
 }
 /**
 * Clears the password.
 *
-* @exception DestroyFailedException if this method was unable
+* @throws    DestroyFailedException if this method was unable
 *      to clear the password
 */
 public synchronized void destroy() throws DestroyFailedException {
 destroyed = true;
 if (password != null) {
 /**
 * Constructs a new CallbackHandlerProtection from a
 * CallbackHandler.
 *
 * @param handler the CallbackHandler
-* @exception NullPointerException if handler is null
+* @throws    NullPointerException if handler is null
 */
 public CallbackHandlerProtection(CallbackHandler handler) {
 if (handler == null) {
 throw new NullPointerException("handler must not be null");
 }
 *      representing the certificate chain.
 *      The chain must be ordered and contain a
 *      {@code Certificate} at index 0
 *      corresponding to the private key.
 *
-* @exception NullPointerException if
+* @throws    NullPointerException if
 *      {@code privateKey} or {@code chain}
 *      is {@code null}
-* @exception IllegalArgumentException if the specified chain has a
+* @throws    IllegalArgumentException if the specified chain has a
 *      length of 0, if the specified chain does not contain
 *      {@code Certificate}s of the same type,
 *      or if the {@code PrivateKey} algorithm
 *      does not match the algorithm of the {@code PublicKey}
 *      in the end entity {@code Certificate} (at index 0)
 *      The chain must be ordered and contain a
 *      {@code Certificate} at index 0
 *      corresponding to the private key.
 * @param attributes the attributes
 *
-* @exception NullPointerException if {@code privateKey}, {@code chain}
+* @throws    NullPointerException if {@code privateKey}, {@code chain}
 *      or {@code attributes} is {@code null}
-* @exception IllegalArgumentException if the specified chain has a
+* @throws    IllegalArgumentException if the specified chain has a
 *      length of 0, if the specified chain does not contain
 *      {@code Certificate}s of the same type,
 *      or if the {@code PrivateKey} algorithm
 *      does not match the algorithm of the {@code PublicKey}
 *      in the end entity {@code Certificate} (at index 0)
 * Constructs a {@code SecretKeyEntry} with a
 * {@code SecretKey}.
 *
 * @param secretKey the {@code SecretKey}
 *
-* @exception NullPointerException if {@code secretKey}
+* @throws    NullPointerException if {@code secretKey}
 *      is {@code null}
 */
 public SecretKeyEntry(SecretKey secretKey) {
 if (secretKey == null) {
 throw new NullPointerException("invalid null input");
 * in the new {@code SecretKeyEntry} object.
 *
 * @param secretKey the {@code SecretKey}
 * @param attributes the attributes
 *
-* @exception NullPointerException if {@code secretKey} or
+* @throws    NullPointerException if {@code secretKey} or
 *     {@code attributes} is {@code null}
 *
 * @since 1.8
 */
 public SecretKeyEntry(SecretKey secretKey, Set<Attribute> attributes) {
 * Constructs a {@code TrustedCertificateEntry} with a
 * trusted {@code Certificate}.
 *
 * @param trustedCert the trusted {@code Certificate}
 *
-* @exception NullPointerException if
+* @throws    NullPointerException if
 *      {@code trustedCert} is {@code null}
 */
 public TrustedCertificateEntry(Certificate trustedCert) {
 if (trustedCert == null) {
 throw new NullPointerException("invalid null input");
 * in the new {@code TrustedCertificateEntry} object.
 *
 * @param trustedCert the trusted {@code Certificate}
 * @param attributes the attributes
 *
-* @exception NullPointerException if {@code trustedCert} or
+* @throws    NullPointerException if {@code trustedCert} or
 *     {@code attributes} is {@code null}
 *
 * @since 1.8
 */
 public TrustedCertificateEntry(Certificate trustedCert,
 * @param password the password for recovering the key
 *
 * @return the requested key, or null if the given alias does not exist
 * or does not identify a key-related entry.
 *
-* @exception KeyStoreException if the keystore has not been initialized
+* @throws    KeyStoreException if the keystore has not been initialized
 * (loaded).
-* @exception NoSuchAlgorithmException if the algorithm for recovering the
+* @throws    NoSuchAlgorithmException if the algorithm for recovering the
 * key cannot be found
-* @exception UnrecoverableKeyException if the key cannot be recovered
+* @throws    UnrecoverableKeyException if the key cannot be recovered
 * (e.g., the given password is wrong).
 */
 public final Key getKey(String alias, char[] password)
 throws KeyStoreException, NoSuchAlgorithmException,
 UnrecoverableKeyException
 *
 * @return the certificate chain (ordered with the user's certificate first
 * followed by zero or more certificate authorities), or null if the given alias
 * does not exist or does not contain a certificate chain
 *
-* @exception KeyStoreException if the keystore has not been initialized
+* @throws    KeyStoreException if the keystore has not been initialized
 * (loaded).
 */
 public final Certificate[] getCertificateChain(String alias)
 throws KeyStoreException
 {
 * @param alias the alias name
 *
 * @return the certificate, or null if the given alias does not exist or
 * does not contain a certificate.
 *
-* @exception KeyStoreException if the keystore has not been initialized
+* @throws    KeyStoreException if the keystore has not been initialized
 * (loaded).
 */
 public final Certificate getCertificate(String alias)
 throws KeyStoreException
 {
 * @param alias the alias name
 *
 * @return the creation date of this entry, or null if the given alias does
 * not exist
 *
-* @exception KeyStoreException if the keystore has not been initialized
+* @throws    KeyStoreException if the keystore has not been initialized
 * (loaded).
 */
 public final Date getCreationDate(String alias)
 throws KeyStoreException
 {
 * @param password the password to protect the key
 * @param chain the certificate chain for the corresponding public
 * key (only required if the given key is of type
 * {@code java.security.PrivateKey}).
 *
-* @exception KeyStoreException if the keystore has not been initialized
+* @throws    KeyStoreException if the keystore has not been initialized
 * (loaded), the given key cannot be protected, or this operation fails
 * for some other reason
 */
 public final void setKeyEntry(String alias, Key key, char[] password,
 Certificate[] chain)
 * @param key the key (in protected format) to be associated with the alias
 * @param chain the certificate chain for the corresponding public
 *          key (only useful if the protected key is of type
 *          {@code java.security.PrivateKey}).
 *
-* @exception KeyStoreException if the keystore has not been initialized
+* @throws    KeyStoreException if the keystore has not been initialized
 * (loaded), or if this operation fails for some other reason.
 */
 public final void setKeyEntry(String alias, byte[] key,
 Certificate[] chain)
 throws KeyStoreException
 * is overridden by the given certificate.
 *
 * @param alias the alias name
 * @param cert the certificate
 *
-* @exception KeyStoreException if the keystore has not been initialized,
+* @throws    KeyStoreException if the keystore has not been initialized,
 * or the given alias already exists and does not identify an
 * entry containing a trusted certificate,
 * or this operation fails for some other reason.
 */
 public final void setCertificateEntry(String alias, Certificate cert)
 /**
 * Deletes the entry identified by the given alias from this keystore.
 *
 * @param alias the alias name
 *
-* @exception KeyStoreException if the keystore has not been initialized,
+* @throws    KeyStoreException if the keystore has not been initialized,
 * or if the entry cannot be removed.
 */
 public final void deleteEntry(String alias)
 throws KeyStoreException
 {
 /**
 * Lists all the alias names of this keystore.
 *
 * @return enumeration of the alias names
 *
-* @exception KeyStoreException if the keystore has not been initialized
+* @throws    KeyStoreException if the keystore has not been initialized
 * (loaded).
 */
 public final Enumeration<String> aliases()
 throws KeyStoreException
 {
 *
 * @param alias the alias name
 *
 * @return true if the alias exists, false otherwise
 *
-* @exception KeyStoreException if the keystore has not been initialized
+* @throws    KeyStoreException if the keystore has not been initialized
 * (loaded).
 */
 public final boolean containsAlias(String alias)
 throws KeyStoreException
 {
 /**
 * Retrieves the number of entries in this keystore.
 *
 * @return the number of entries in this keystore
 *
-* @exception KeyStoreException if the keystore has not been initialized
+* @throws    KeyStoreException if the keystore has not been initialized
 * (loaded).
 */
 public final int size()
 throws KeyStoreException
 {
 * @param alias the alias for the keystore entry to be checked
 *
 * @return true if the entry identified by the given alias is a
 * key-related entry, false otherwise.
 *
-* @exception KeyStoreException if the keystore has not been initialized
+* @throws    KeyStoreException if the keystore has not been initialized
 * (loaded).
 */
 public final boolean isKeyEntry(String alias)
 throws KeyStoreException
 {
 * @param alias the alias for the keystore entry to be checked
 *
 * @return true if the entry identified by the given alias contains a
 * trusted certificate, false otherwise.
 *
-* @exception KeyStoreException if the keystore has not been initialized
+* @throws    KeyStoreException if the keystore has not been initialized
 * (loaded).
 */
 public final boolean isCertificateEntry(String alias)
 throws KeyStoreException
 {
 * @param cert the certificate to match with.
 *
 * @return the alias name of the first entry with a matching certificate,
 * or null if no such entry exists in this keystore.
 *
-* @exception KeyStoreException if the keystore has not been initialized
+* @throws    KeyStoreException if the keystore has not been initialized
 * (loaded).
 */
 public final String getCertificateAlias(Certificate cert)
 throws KeyStoreException
 {
 * integrity with the given password.
 *
 * @param stream the output stream to which this keystore is written.
 * @param password the password to generate the keystore integrity check
 *
-* @exception KeyStoreException if the keystore has not been initialized
+* @throws    KeyStoreException if the keystore has not been initialized
 * (loaded).
-* @exception IOException if there was an I/O problem with data
+* @throws    IOException if there was an I/O problem with data
-* @exception NoSuchAlgorithmException if the appropriate data integrity
+* @throws    NoSuchAlgorithmException if the appropriate data integrity
 * algorithm could not be found
-* @exception CertificateException if any of the certificates included in
+* @throws    CertificateException if any of the certificates included in
 * the keystore data could not be stored
 */
 public final void store(OutputStream stream, char[] password)
 throws KeyStoreException, IOException, NoSuchAlgorithmException,
 CertificateException
 *
 * @param param the {@code LoadStoreParameter}
 *          that specifies how to store the keystore,
 *          which may be {@code null}
 *
-* @exception IllegalArgumentException if the given
+* @throws    IllegalArgumentException if the given
 *          {@code LoadStoreParameter}
 *          input is not recognized
-* @exception KeyStoreException if the keystore has not been initialized
+* @throws    KeyStoreException if the keystore has not been initialized
 *          (loaded)
-* @exception IOException if there was an I/O problem with data
+* @throws    IOException if there was an I/O problem with data
-* @exception NoSuchAlgorithmException if the appropriate data integrity
+* @throws    NoSuchAlgorithmException if the appropriate data integrity
 *          algorithm could not be found
-* @exception CertificateException if any of the certificates included in
+* @throws    CertificateException if any of the certificates included in
 *          the keystore data could not be stored
 *
 * @since 1.5
 */
 public final void store(LoadStoreParameter param)
 * or {@code null}
 * @param password the password used to check the integrity of
 * the keystore, the password used to unlock the keystore,
 * or {@code null}
 *
-* @exception IOException if there is an I/O or format problem with the
+* @throws    IOException if there is an I/O or format problem with the
 * keystore data, if a password is required but not given,
 * or if the given password was incorrect. If the error is due to a
 * wrong password, the {@link Throwable#getCause cause} of the
 * {@code IOException} should be an
 * {@code UnrecoverableKeyException}
-* @exception NoSuchAlgorithmException if the algorithm used to check
+* @throws    NoSuchAlgorithmException if the algorithm used to check
 * the integrity of the keystore cannot be found
-* @exception CertificateException if any of the certificates in the
+* @throws    CertificateException if any of the certificates in the
 * keystore could not be loaded
 */
 public final void load(InputStream stream, char[] password)
 throws IOException, NoSuchAlgorithmException, CertificateException
 {
 *
 * @param param the {@code LoadStoreParameter}
 *          that specifies how to load the keystore,
 *          which may be {@code null}
 *
-* @exception IllegalArgumentException if the given
+* @throws    IllegalArgumentException if the given
 *          {@code LoadStoreParameter}
 *          input is not recognized
-* @exception IOException if there is an I/O or format problem with the
+* @throws    IOException if there is an I/O or format problem with the
 *          keystore data. If the error is due to an incorrect
 *         {@code ProtectionParameter} (e.g. wrong password)
 *         the {@link Throwable#getCause cause} of the
 *         {@code IOException} should be an
 *         {@code UnrecoverableKeyException}
-* @exception NoSuchAlgorithmException if the algorithm used to check
+* @throws    NoSuchAlgorithmException if the algorithm used to check
 *          the integrity of the keystore cannot be found
-* @exception CertificateException if any of the certificates in the
+* @throws    CertificateException if any of the certificates in the
 *          keystore could not be loaded
 *
 * @since 1.5
 */
 public final void load(LoadStoreParameter param)
 *          which may be {@code null}
 *
 * @return the keystore {@code Entry} for the specified alias,
 *          or {@code null} if there is no such entry
 *
-* @exception NullPointerException if
+* @throws    NullPointerException if
 *          {@code alias} is {@code null}
-* @exception NoSuchAlgorithmException if the algorithm for recovering the
+* @throws    NoSuchAlgorithmException if the algorithm for recovering the
 *          entry cannot be found
-* @exception UnrecoverableEntryException if the specified
+* @throws    UnrecoverableEntryException if the specified
 *          {@code protParam} were insufficient or invalid
-* @exception UnrecoverableKeyException if the entry is a
+* @throws    UnrecoverableKeyException if the entry is a
 *          {@code PrivateKeyEntry} or {@code SecretKeyEntry}
 *          and the specified {@code protParam} does not contain
 *          the information needed to recover the key (e.g. wrong password)
-* @exception KeyStoreException if the keystore has not been initialized
+* @throws    KeyStoreException if the keystore has not been initialized
 *          (loaded).
 * @see #setEntry(String, KeyStore.Entry, KeyStore.ProtectionParameter)
 *
 * @since 1.5
 */
 * @param entry the {@code Entry} to save
 * @param protParam the {@code ProtectionParameter}
 *          used to protect the {@code Entry},
 *          which may be {@code null}
 *
-* @exception NullPointerException if
+* @throws    NullPointerException if
 *          {@code alias} or {@code entry}
 *          is {@code null}
-* @exception KeyStoreException if the keystore has not been initialized
+* @throws    KeyStoreException if the keystore has not been initialized
 *          (loaded), or if this operation fails for some other reason
 *
 * @see #getEntry(String, KeyStore.ProtectionParameter)
 *
 * @since 1.5
 *
 * @return true if the keystore {@code Entry} for the specified
 *          {@code alias} is an instance or subclass of the
 *          specified {@code entryClass}, false otherwise
 *
-* @exception NullPointerException if
+* @throws    NullPointerException if
 *          {@code alias} or {@code entryClass}
 *          is {@code null}
-* @exception KeyStoreException if the keystore has not been
+* @throws    KeyStoreException if the keystore has not been
 *          initialized (loaded)
 *
 * @since 1.5
 */
 public final boolean
 /**
 * Returns the KeyStore described by this object.
 *
 * @return the {@code KeyStore} described by this object
-* @exception KeyStoreException if an error occurred during the
+* @throws    KeyStoreException if an error occurred during the
 *   operation, for example if the KeyStore could not be
 *   instantiated or loaded
 */
 public abstract KeyStore getKeyStore() throws KeyStoreException;

changeset 58242	94bb65cb37d3
parent 53018	8bf9268df0e2