harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r769463 [3/9] - in /harmony/enhanced/classlib/trunk/modules/security/src/main/java/common: java/security/ java/security/acl/ java/security/cert/ java/security/interfaces/ java/security/spec/ javax/security/cert/
Date Tue, 28 Apr 2009 17:01:47 GMT
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyRep.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyRep.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyRep.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyRep.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vladimir N. Molotkov
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.io.IOException;
@@ -36,13 +31,11 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * {@code KeyRep} is a standardized representation for serialized {@link Key}
+ * objects.
  */
 public class KeyRep implements Serializable {
-    /**
-     * @com.intel.drl.spec_ref
-     */
+
     private static final long serialVersionUID = -4757683898830641853L;
     // Key type
     private final Type type;
@@ -54,7 +47,22 @@
     private byte[] encoded;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code KeyRep} with the specified arguments.
+     * The arguments should be obtained from the {@code Key} object that has to
+     * be serialized.
+     *
+     * @param type
+     *            the type of the key.
+     * @param algorithm
+     *            the algorithm (obtained by {@link Key#getAlgorithm()}).
+     * @param format
+     *            the format of the key (obtained by {@link Key#getFormat()}).
+     * @param encoded
+     *            the encoded {@code byte[]} (obtained by
+     *            {@link Key#getEncoded()}).
+     * @throws NullPointerException
+     *             if {@code type, algorithm, format or encoded} is {@code null}
+     *             .
      */
     public KeyRep(Type type,
             String algorithm, String format, byte[] encoded) {
@@ -77,7 +85,25 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Resolves and returns the {@code Key} object. Three {@link Type}|format
+     * combinations are supported:
+     * <ul>
+     * <li> {@code Type.PRIVATE} | "PKCS#8" : returns a {@link PrivateKey}
+     * instance, generated from a key factory (suitable for the algorithm) that
+     * is initialized with a {@link PKCS8EncodedKeySpec} using the encoded key
+     * bytes.
+     * <li> {@code Type.SECRET} | "RAW" : returns a {@link SecretKeySpec}
+     * instance, created with the encoded key bytes and the algorithm.
+     * <li> {@code Type.PUBLIC} | "X.509": returns a {@link PublicKey} instance,
+     * generated from a key factory (suitable for the algorithm) that is
+     * initialized with a {@link X509EncodedKeySpec} using the encoded key
+     * bytes.
+     * </ul>
+     *
+     * @return the resolved {@code Key} object.
+     * @throws ObjectStreamException
+     *             if the {@code Type}|format combination is not recognized, or
+     *             the resolution of any key parameter fails.
      */
     protected Object readResolve() throws ObjectStreamException {
         switch (type) {
@@ -138,11 +164,21 @@
     }
 
     /**
-     * Supported key types
+     * {@code Type} enumerates the supported key types.
      */
     public static enum Type {
+
+        /**
+         * Type for secret keys.
+         */
         SECRET,
+        /**
+         * Type for public keys.
+         */
         PUBLIC,
+        /**
+         * Type for private keys.
+         */
         PRIVATE
     }
 }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStore.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStore.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStore.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStore.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.io.File;
@@ -43,6 +38,17 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 
+/**
+ * {@code KeyStore} is responsible for maintaining cryptographic keys and their
+ * owners.
+ * <p>
+ * The type of the system key store can be changed by setting the {@code
+ * 'keystore.type'} property in the file named {@code
+ * JAVA_HOME/lib/security/java.security}.
+ *
+ * @see Certificate
+ * @see PrivateKey
+ */
 public class KeyStore {
 
     // Store KeyStore SERVICE name
@@ -72,6 +78,16 @@
     // Store used type
     private final String type;
 
+    /**
+     * Constructs a new instance of {@code KeyStore} with the given arguments.
+     *
+     * @param keyStoreSpi
+     *            the concrete key store.
+     * @param provider
+     *            the provider.
+     * @param type
+     *            the type of the {@code KeyStore} to be constructed.
+     */
     protected KeyStore(KeyStoreSpi keyStoreSpi, Provider provider, String type) {
         this.type = type;
         this.provider = provider;
@@ -80,7 +96,17 @@
     }
 
     /**
-     * @throws NullPointerException if type is null
+     * Returns a new instance of {@code KeyStore} with the specified type.
+     *
+     * @param type
+     *            the type of the returned {@code KeyStore}.
+     * @return a new instance of {@code KeyStore} with the specified type.
+     * @throws KeyStoreException
+     *             if an error occurred during the creation of the new {@code
+     *             KeyStore}.
+     * @throws NullPointerException
+     *             if {@code type} is {@code null}.
+     * @see #getDefaultType
      */
     public static KeyStore getInstance(String type) throws KeyStoreException {
         if (type == null) {
@@ -97,10 +123,26 @@
     }
 
     /**
-     * 
-     * 
-     * @throws NullPointerException if type is null (instead of
-     * NoSuchAlgorithmException) as in 1.4 release
+     * Returns a new instance of {@code KeyStore} from the specified provider
+     * with the given type.
+     *
+     * @param type
+     *            the type of the returned {@code KeyStore}.
+     * @param provider
+     *            name of the provider of the {@code KeyStore}.
+     * @return a new instance of {@code KeyStore} from the specified provider
+     *         with the given type.
+     * @throws KeyStoreException
+     *             if an error occurred during the creation of the new {@code
+     *             KeyStore}.
+     * @throws NoSuchProviderException
+     *             if the specified provider is not available.
+     * @throws IllegalArgumentException
+     *             if {@code provider} is {@code null} or the empty string.
+     * @throws NullPointerException
+     *             if {@code type} is {@code null} (instead of
+     *             NoSuchAlgorithmException) as in 1.4 release
+     * @see #getDefaultType
      */
     public static KeyStore getInstance(String type, String provider)
             throws KeyStoreException, NoSuchProviderException {
@@ -119,10 +161,24 @@
     }
 
     /**
-     * 
-     * 
-     * throws NullPointerException if type is null (instead of
-     * NoSuchAlgorithmException) as in 1.4 release
+     * Returns a new instance of {@code KeyStore} from the specified provider
+     * with the given type.
+     *
+     * @param type
+     *            the type of the returned {@code KeyStore}.
+     * @param provider
+     *            the provider of the {@code KeyStore}.
+     * @return a new instance of {@code KeyStore} from the specified provider
+     *         with the given type.
+     * @throws KeyStoreException
+     *             if an error occurred during the creation of the new {@code
+     *             KeyStore}.
+     * @throws IllegalArgumentException
+     *             if {@code provider} is {@code null} or the empty string.
+     * @throws NullPointerException
+     *             if {@code type} is {@code null} (instead of
+     *             NoSuchAlgorithmException) as in 1.4 release
+     * @see #getDefaultType
      */
     public static KeyStore getInstance(String type, Provider provider)
             throws KeyStoreException {
@@ -146,8 +202,13 @@
     }
 
     /**
-     * 
-     *  
+     * Returns the default type for {@code KeyStore} instances.
+     * <p>
+     * The default is specified in the {@code 'keystore.type'} property in the
+     * file named {@code JAVA_HOME/lib/security/java.security}. If this property
+     * is not set, {@code "jks"} will be used.
+     *
+     * @return the default type for {@code KeyStore} instances
      */
     public static final String getDefaultType() {
         String dt = AccessController.doPrivileged(
@@ -161,24 +222,39 @@
     }
 
     /**
-     * 
-     *  
+     * Returns the provider associated with this {@code KeyStore}.
+     *
+     * @return the provider associated with this {@code KeyStore}.
      */
     public final Provider getProvider() {
         return provider;
     }
 
     /**
-     * 
-     *  
+     * Returns the type of this {@code KeyStore}.
+     *
+     * @return the type of this {@code KeyStore}.
      */
     public final String getType() {
         return type;
     }
 
     /**
-     * 
-     *  
+     * Returns the key with the given alias, using the password to recover the
+     * key from the store.
+     *
+     * @param alias
+     *            the alias for the entry.
+     * @param password
+     *            the password used to recover the key.
+     * @return the key with the specified alias, or {@code null} if the
+     *         specified alias is not bound to an entry.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized.
+     * @throws NoSuchAlgorithmException
+     *             if the algorithm for recovering the key is not available.
+     * @throws UnrecoverableKeyException
+     *             if the key can not be recovered.
      */
     public final Key getKey(String alias, char[] password)
             throws KeyStoreException, NoSuchAlgorithmException,
@@ -190,8 +266,14 @@
     }
 
     /**
-     * 
-     *  
+     * Returns the certificate chain for the entry with the given alias.
+     *
+     * @param alias
+     *            the alias for the entry.
+     * @return the certificate chain for the entry with the given alias, or
+     *         {@code null} if the specified alias is not bound to an entry.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized.
      */
     public final Certificate[] getCertificateChain(String alias)
             throws KeyStoreException {
@@ -202,8 +284,14 @@
     }
 
     /**
-     * 
-     *  
+     * Returns the trusted certificate for the entry with the given alias.
+     *
+     * @param alias
+     *            the alias for the entry.
+     * @return the trusted certificate for the entry with the given alias, or
+     *         {@code null} if the specified alias is not bound to an entry.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized.
      */
     public final Certificate getCertificate(String alias)
             throws KeyStoreException {
@@ -214,8 +302,14 @@
     }
 
     /**
-     * 
-     *  
+     * Returns the creation date of the entry with the given alias.
+     *
+     * @param alias
+     *            the alias for the entry.
+     * @return the creation date, or {@code null} if the specified alias is not
+     *         bound to an entry.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized.
      */
     public final Date getCreationDate(String alias) throws KeyStoreException {
         if (!isInit) {
@@ -225,12 +319,25 @@
     }
 
     /**
-     * 
-     * 
-     * 1.4.2 and 1.5 releases throw unspecified NullPointerException -
-     * when alias is null IllegalArgumentException - when password is null
-     * IllegalArgumentException - when key is instance of PrivateKey and chain
-     * is null or empty
+     * Associates the given alias with the key, password and certificate chain.
+     * <p>
+     * If the specified alias already exists, it will be reassigned.
+     *
+     * @param alias
+     *            the alias for the key.
+     * @param key
+     *            the key.
+     * @param password
+     *            the password.
+     * @param chain
+     *            the certificate chain.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized.
+     * @throws IllegalArgumentException
+     *             if {@code key} is a {@code PrivateKey} and {@code chain} does
+     *             not contain any certificates.
+     * @throws NullPointerException
+     *             if {@code alias} is {@code null}.
      */
     public final void setKeyEntry(String alias, Key key, char[] password,
             Certificate[] chain) throws KeyStoreException {
@@ -248,8 +355,28 @@
     }
 
     /**
-     * 
-     *  
+     * Associates the given alias with a key and a certificate chain.
+     * <p>
+     * If the specified alias already exists, it will be reassigned.
+     * <p>
+     * If this {@code KeyStore} is of type {@code "jks"}, {@code key} must be
+     * encoded conform to the PKS#8 standard as an
+     * {@link javax.crypto.EncryptedPrivateKeyInfo}.
+     *
+     * @param alias
+     *            the alias for the key.
+     * @param key
+     *            the key in an encoded format.
+     * @param chain
+     *            the certificate chain.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized or if {@code key}
+     *             is null.
+     * @throws IllegalArgumentException
+     *             if {@code key} is a {@code PrivateKey} and {@code chain}
+     *             does.
+     * @throws NullPointerException
+     *             if {@code alias} is {@code null}.
      */
     public final void setKeyEntry(String alias, byte[] key, Certificate[] chain)
             throws KeyStoreException {
@@ -260,10 +387,20 @@
     }
 
     /**
-     * 
-     * 
-     * 1.4.2 and 1.5 releases throw unspecified NullPointerException
-     * when alias is null
+     * Associates the given alias with a certificate.
+     * <p>
+     * If the specified alias already exists, it will be reassigned.
+     *
+     * @param alias
+     *            the alias for the certificate.
+     * @param cert
+     *            the certificate.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized, or an existing
+     *             alias is not associated to an entry containing a trusted
+     *             certificate, or this method fails for any other reason.
+     * @throws NullPointerException
+     *             if {@code alias} is {@code null}.
      */
     public final void setCertificateEntry(String alias, Certificate cert)
             throws KeyStoreException {
@@ -274,9 +411,16 @@
     }
 
     /**
-     * 
-     * 
-     * 1.4.2 and 1.5 releases throw NullPointerException when alias is null
+     * Deletes the entry identified with the given alias from this {@code
+     * KeyStore}.
+     *
+     * @param alias
+     *            the alias for the entry.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized, or if the entry
+     *             can not be deleted.
+     * @throws NullPointerException
+     *             if {@code alias} is {@code null}.
      */
     public final void deleteEntry(String alias) throws KeyStoreException {
         if (!isInit) {
@@ -289,7 +433,13 @@
     }
 
     /**
-     * 
+     * Returns an {@code Enumeration} over all alias names stored in this
+     * {@code KeyStore}.
+     *
+     * @return an {@code Enumeration} over all alias names stored in this
+     *         {@code KeyStore}.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized.
      */
     public final Enumeration<String> aliases() throws KeyStoreException {
         if (!isInit) {
@@ -299,10 +449,15 @@
     }
 
     /**
-     * 
-     * 
-     * 1.4.2 and 1.5 releases throw unspecified NullPointerException when
-     * alias is null
+     * Indicates whether the given alias is present in this {@code KeyStore}.
+     *
+     * @param alias
+     *            the alias of an entry.
+     * @return {@code true} if the alias exists, {@code false} otherwise.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized.
+     * @throws NullPointerException
+     *             if {@code alias} is {@code null}.
      */
     public final boolean containsAlias(String alias) throws KeyStoreException {
         if (!isInit) {
@@ -315,8 +470,11 @@
     }
 
     /**
-     * 
-     *  
+     * Returns the number of entries stored in this {@code KeyStore}.
+     *
+     * @return the number of entries stored in this {@code KeyStore}.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized.
      */
     public final int size() throws KeyStoreException {
         if (!isInit) {
@@ -326,10 +484,16 @@
     }
 
     /**
-     * 
-     * 
-     * jdk1.4.2 and 1.5 releases throw unspecified NullPointerException
-     * when alias is null
+     * Indicates whether the specified alias is associated with either a
+     * {@link PrivateKeyEntry} or a {@link SecretKeyEntry}.
+     *
+     * @param alias
+     *            the alias of an entry.
+     * @return {@code true} if the given alias is associated with a key entry.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized.
+     * @throws NullPointerException
+     *             if {@code alias} is {@code null}.
      */
     public final boolean isKeyEntry(String alias) throws KeyStoreException {
         if (!isInit) {
@@ -342,10 +506,17 @@
     }
 
     /**
-     * 
-     * 
-     * jdk1.4.2 and 1.5 releases throw unspecified NullPointerException
-     * when alias is null
+     * Indicates whether the specified alias is associated with a
+     * {@link TrustedCertificateEntry}.
+     *
+     * @param alias
+     *            the alias of an entry.
+     * @return {@code true} if the given alias is associated with a certificate
+     *         entry.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized.
+     * @throws NullPointerException
+     *             if {@code alias} is {@code null}.
      */
     public final boolean isCertificateEntry(String alias)
             throws KeyStoreException {
@@ -359,8 +530,15 @@
     }
 
     /**
-     * 
-     *  
+     * Returns the alias associated with the first entry whose certificate
+     * matches the specified certificate.
+     *
+     * @param cert
+     *            the certificate to find the associated entry's alias for.
+     * @return the alias or {@code null} if no entry with the specified
+     *         certificate can be found.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized.
      */
     public final String getCertificateAlias(Certificate cert)
             throws KeyStoreException {
@@ -371,9 +549,23 @@
     }
 
     /**
-     * 
-     * 
-     * throws IOException when stream or password is null
+     * Writes this {@code KeyStore} to the specified {@code OutputStream}. The
+     * data written to the {@code OutputStream} is protected by the specified
+     * password.
+     *
+     * @param stream
+     *            the {@code OutputStream} to write the store's data to.
+     * @param password
+     *            the password to protect the data.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized.
+     * @throws IOException
+     *             if a problem occurred while writing to the stream.
+     * @throws NoSuchAlgorithmException
+     *             if the required algorithm is not available.
+     * @throws CertificateException
+     *             if an exception occurred while storing the certificates of
+     *             this {@code KeyStore}.
      */
     public final void store(OutputStream stream, char[] password)
             throws KeyStoreException, IOException, NoSuchAlgorithmException,
@@ -387,8 +579,23 @@
     }
 
     /**
-     * 
-     *  
+     * Stores this {@code KeyStore} using the specified {@code
+     * LoadStoreParameter}.
+     *
+     * @param param
+     *            the {@code LoadStoreParameter} that specifies how to store
+     *            this {@code KeyStore}, maybe {@code null}.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized.
+     * @throws IOException
+     *             if a problem occurred while writing to the stream.
+     * @throws NoSuchAlgorithmException
+     *             if the required algorithm is not available.
+     * @throws CertificateException
+     *             if an exception occurred while storing the certificates of
+     *             this {@code KeyStore}.
+     * @throws IllegalArgumentException
+     *             if the given {@link LoadStoreParameter} is not recognized.
      */
     public final void store(LoadStoreParameter param) throws KeyStoreException,
             IOException, NoSuchAlgorithmException, CertificateException {
@@ -399,8 +606,24 @@
     }
 
     /**
-     * 
-     *  
+     * Initializes this {@code KeyStore} from the provided {@code InputStream}.
+     * Pass {@code null} as the {@code stream} argument to initialize an empty
+     * {@code KeyStore} or to initialize a {@code KeyStore} which does not rely
+     * on an {@code InputStream}. This {@code KeyStore} utilizes the given
+     * password to verify the stored data.
+     *
+     * @param stream
+     *            the {@code InputStream} to load this {@code KeyStore}'s data
+     *            from or {@code null}.
+     * @param password
+     *            the password to verify the stored data, maybe {@code null}.
+     * @throws IOException
+     *             if a problem occurred while reading from the stream.
+     * @throws NoSuchAlgorithmException
+     *             if the required algorithm is not available.
+     * @throws CertificateException
+     *             if an exception occurred while loading the certificates of
+     *             this {@code KeyStore}.
      */
     public final void load(InputStream stream, char[] password)
             throws IOException, NoSuchAlgorithmException, CertificateException {
@@ -409,8 +632,21 @@
     }
 
     /**
-     * 
-     *  
+     * Loads this {@code KeyStore} using the specified {@code
+     * LoadStoreParameter}.
+     *
+     * @param param
+     *            the {@code LoadStoreParameter} that specifies how to load this
+     *            {@code KeyStore}, maybe {@code null}.
+     * @throws IOException
+     *             if a problem occurred while reading from the stream.
+     * @throws NoSuchAlgorithmException
+     *             if the required algorithm is not available.
+     * @throws CertificateException
+     *             if an exception occurred while loading the certificates of
+     *             this {@code KeyStore}.
+     * @throws IllegalArgumentException
+     *             if the given {@link LoadStoreParameter} is not recognized.
      */
     public final void load(LoadStoreParameter param) throws IOException,
             NoSuchAlgorithmException, CertificateException {
@@ -419,8 +655,24 @@
     }
 
     /**
-     * 
-     *  
+     * Returns the {@code Entry} with the given alias, using the specified
+     * {@code ProtectionParameter}.
+     *
+     * @param alias
+     *            the alias of the requested entry.
+     * @param param
+     *            the {@code ProtectionParameter} used to protect the requested
+     *            entry, maybe {@code null}.
+     * @return he {@code Entry} with the given alias, using the specified
+     *         {@code ProtectionParameter}.
+     * @throws NoSuchAlgorithmException
+     *             if the required algorithm is not available.
+     * @throws UnrecoverableEntryException
+     *             if the entry can not be recovered.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized.
+     * @throws NullPointerException
+     *             if {@code alias} is {@code null}.
      */
     public final Entry getEntry(String alias, ProtectionParameter param)
             throws NoSuchAlgorithmException, UnrecoverableEntryException,
@@ -435,10 +687,23 @@
     }
 
     /**
-     * 
-     * 
-     * 1.5 release throws unspecified NullPointerException when alias or
-     * entry is null
+     * Stores the given {@code Entry} in this {@code KeyStore} and associates
+     * the entry with the given {@code alias}. The entry is protected by the
+     * specified {@code ProtectionParameter}.
+     * <p>
+     * If the specified alias already exists, it will be reassigned.
+     *
+     * @param alias
+     *            the alias for the entry.
+     * @param entry
+     *            the entry to store.
+     * @param param
+     *            the {@code ProtectionParameter} to protect the entry.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized.
+     * @throws NullPointerException
+     *             if {@code alias} is {@code null} or {@code entry} is {@code
+     *             null}.
      */
     public final void setEntry(String alias, Entry entry,
             ProtectionParameter param) throws KeyStoreException {
@@ -455,7 +720,17 @@
     }
 
     /**
-     * 
+     * Indicates whether the entry for the given alias is assignable to the
+     * provided {@code Class}.
+     *
+     * @param alias
+     *            the alias for the entry.
+     * @param entryClass
+     *            the type of the entry.
+     * @return {@code true} if the {@code Entry} for the alias is assignable to
+     *         the specified {@code entryClass}.
+     * @throws KeyStoreException
+     *             if this {@code KeyStore} is not initialized.
      */
     public final boolean entryInstanceOf(String alias, 
             Class<? extends KeyStore.Entry> entryClass)
@@ -474,34 +749,61 @@
     }
 
     /**
-     * 
-     * 
-     * 
+     * {@code Builder} is used to construct new instances of {@code KeyStore}.
      */
     public abstract static class Builder {
         /**
-         * 
-         *  
+         * Constructs a new instance of {@code Builder}.
          */
         protected Builder() {
         }
 
         /**
-         * 
-         *  
+         * Returns the {@code KeyStore} created by this {@code Builder}.
+         *
+         * @return the {@code KeyStore} created by this {@code Builder}.
+         * @throws KeyStoreException
+         *             if an error occurred during construction.
          */
         public abstract KeyStore getKeyStore() throws KeyStoreException;
 
         /**
-         * 
-         *  
+         * Returns the {@code ProtectionParameter} to be used when a {@code
+         * Entry} with the specified alias is requested. Before this method is
+         * invoked, {@link #getKeyStore()} must be called.
+         *
+         * @param alias
+         *            the alias for the entry.
+         * @return the {@code ProtectionParameter} to be used when a {@code
+         *         Entry} with the specified alias is requested.
+         * @throws KeyStoreException
+         *             if an error occurred during the lookup for the protection
+         *             parameter.
+         * @throws IllegalStateException
+         *             if {@link #getKeyStore()} is not called prior the
+         *             invocation of this method.
+         * @throws NullPointerException
+         *             if {@code alias} is {@code null}.
          */
-        public abstract ProtectionParameter getProtectionParameter(String alise)
+        public abstract ProtectionParameter getProtectionParameter(String alias)
                 throws KeyStoreException;
 
         /**
-         * 
-         *  
+         * Returns a new {@code Builder} that holds the given {@code KeyStore}
+         * and the given {@code ProtectionParameter}.
+         *
+         * @param keyStore
+         *            the {@code KeyStore} to be held.
+         * @param protectionParameter
+         *            the {@code ProtectionParameter} to be held.
+         * @return a new instance of {@code Builder} that holds the specified
+         *         {@code KeyStore} and the specified {@code
+         *         ProtectionParameter}.
+         * @throws NullPointerException
+         *             if {@code keyStore} or {@code protectionParameter} is
+         *             {@code null}.
+         * @throws IllegalArgumentException
+         *             if the given {@code KeyStore} is not initialized.
          */
         public static Builder newInstance(KeyStore keyStore,
                 ProtectionParameter protectionParameter) {
@@ -520,8 +822,34 @@
         }
 
         /**
-         * 
-         *  
+         * Returns a new {@code Builder} that creates a new {@code KeyStore}
+         * based on the provided arguments.
+         * <p>
+         * If {@code provider} is {@code null}, all installed providers are
+         * searched, otherwise the key store from the specified provider is
+         * used.
+         *
+         * @param type
+         *            the type of the {@code KeyStore} to be constructed.
+         * @param provider
+         *            the provider of the {@code KeyStore} to be constructed,
+         *            maybe {@code null}.
+         * @param file
+         *            the {@code File} that contains the data for the {@code
+         *            KeyStore}.
+         * @param protectionParameter
+         *            the {@code ProtectionParameter} used to protect the stored
+         *            keys.
+         * @return a new {@code Builder} that creates a new {@code KeyStore}
+         *         based on the provided arguments.
+         * @throws NullPointerException
+         *             if {@code type, protectionParameter} or {@code file} is
+         *             {@code null}.
+         * @throws IllegalArgumentException
+         *             {@code protectionParameter} not an instance of either
+         *             {@code PasswordProtection} or {@code
+         *             CallbackHandlerProtection}, {@code file} is not a file or
+         *             does not exist at all.
          */
         public static Builder newInstance(String type, Provider provider,
                 File file, ProtectionParameter protectionParameter) {
@@ -554,8 +882,31 @@
         }
 
         /**
-         * 
-         *  
+         * Returns a new {@code Builder} that creates a new {@code KeyStore}
+         * based on the provided arguments.
+         * <p>
+         * If {@code provider} is {@code null}, all installed providers are
+         * searched, otherwise the key store from the specified provider is
+         * used.
+         *
+         * @param type
+         *            the type of the {@code KeyStore} to be constructed.
+         * @param provider
+         *            the provider of the {@code KeyStore} to be constructed,
+         *            maybe {@code null}.
+         * @param protectionParameter
+         *            the {@code ProtectionParameter} used to protect the stored
+         *            keys.
+         * @return a new {@code Builder} that creates a new {@code KeyStore}
+         *         based on the provided arguments.
+         * @throws NullPointerException
+         *             if {@code type} or {@code protectionParameter} is {@code
+         *             null}.
+         * @throws IllegalArgumentException
+         *             {@code protectionParameter} not an instance of either
+         *             {@code PasswordProtection} or {@code
+         *             CallbackHandlerProtection}, {@code file} is not a file or
+         *             does not exist at all.
          */
         public static Builder newInstance(String type, Provider provider,
                 ProtectionParameter protectionParameter) {
@@ -747,9 +1098,8 @@
     }
 
     /**
-     * 
-     * 
-     * 
+     * {@code CallbackHandlerProtection} is a {@code ProtectionParameter} that
+     * encapsulates a {@link CallbackHandler}.
      */
     public static class CallbackHandlerProtection implements
             ProtectionParameter {
@@ -757,8 +1107,13 @@
         private final CallbackHandler callbackHandler;
 
         /**
-         * 
-         *  
+         * Constructs a new instance of {@code CallbackHandlerProtection} with
+         * the {@code CallbackHandler}.
+         *
+         * @param handler
+         *            the {@code CallbackHandler}.
+         * @throws NullPointerException
+         *             if {@code handler} is {@code null}.
          */
         public CallbackHandlerProtection(CallbackHandler handler) {
             if (handler == null) {
@@ -768,8 +1123,9 @@
         }
 
         /**
-         * 
-         *  
+         * Returns the {@code CallbackHandler}.
+         *
+         * @return the {@code CallbackHandler}.
          */
         public CallbackHandler getCallbackHandler() {
             return callbackHandler;
@@ -777,30 +1133,33 @@
     }
 
     /**
-     * 
-     * 
-     * 
+     * {@code Entry} is the common marker interface for a {@code KeyStore}
+     * entry.
      */
     public static interface Entry {
     }
 
     /**
-     * 
-     * 
-     * 
+     * {@code LoadStoreParameter} represents a parameter that specifies how a
+     * {@code KeyStore} can be loaded and stored.
+     *
+     * @see KeyStore#load(LoadStoreParameter)
+     * @see KeyStore#store(LoadStoreParameter)
      */
     public static interface LoadStoreParameter {
         /**
-         * 
-         *  
+         * Returns the {@code ProtectionParameter} which is used to protect data
+         * in the {@code KeyStore}.
+         *
+         * @return the {@code ProtectionParameter} which is used to protect data
+         *         in the {@code KeyStore}, maybe {@code null}.
          */
         public ProtectionParameter getProtectionParameter();
     }
 
     /**
-     * 
-     * 
-     * 
+     * {@code PasswordProtection} is a {@code ProtectionParameter} that protects
+     * a {@code KeyStore} using a password.
      */
     public static class PasswordProtection implements ProtectionParameter,
             Destroyable {
@@ -811,8 +1170,12 @@
         private boolean isDestroyed = false;
 
         /**
-         * 
-         *  
+         * Constructs a new instance of {@code PasswordProtection} with a
+         * password. A copy of the password is stored in the new {@code
+         * PasswordProtection} object.
+         *
+         * @param password
+         *            the password, maybe {@code null}.
          */
         public PasswordProtection(char[] password) {
         	if (password != null) {
@@ -821,8 +1184,11 @@
         }
 
         /**
-         * 
-         *  
+         * Returns the password.
+         *
+         * @return the password.
+         * @throws IllegalStateException
+         *             if the password has been destroyed.
          */
         public synchronized char[] getPassword() {
             if (isDestroyed) {
@@ -832,8 +1198,10 @@
         }
 
         /**
-         * 
-         *  
+         * Destroys / invalidates the password.
+         *
+         * @throws DestroyFailedException
+         *             if the password could not be invalidated.
          */
         public synchronized void destroy() throws DestroyFailedException {
             isDestroyed = true;
@@ -844,8 +1212,10 @@
         }
 
         /**
-         * 
-         *  
+         * Indicates whether the password is invalidated.
+         *
+         * @return {@code true} if the password is invalidated, {@code false}
+         *         otherwise.
          */
         public synchronized boolean isDestroyed() {
             return isDestroyed;
@@ -853,17 +1223,16 @@
     }
 
     /**
-     * 
-     * 
-     * 
+     * {@code ProtectionParameter} is a marker interface for protection
+     * parameters. A protection parameter is used to protect the content of a
+     * {@code KeyStore}.
      */
     public static interface ProtectionParameter {
     }
 
     /**
-     * 
-     * 
-     * 
+     * {@code PrivateKeyEntry} represents a {@code KeyStore} entry that
+     * holds a private key.
      */
     public static final class PrivateKeyEntry implements Entry {
         // Store Certificate chain
@@ -873,8 +1242,21 @@
         private PrivateKey privateKey;
 
         /**
-         * 
-         *  
+         * Constructs a new instance of {@code PrivateKeyEntry} with the given
+         * {@code PrivateKey} and the provided certificate chain.
+         *
+         * @param privateKey
+         *            the private key.
+         * @param chain
+         *            the ordered certificate chain with the certificate
+         *            corresponding to the private key at index 0.
+         * @throws NullPointerException
+         *             if {@code privateKey} or {@code chain} is {@code null}.
+         * @throws IllegalArgumentException
+         *             if {@code chain.length == 0}, the algorithm of the
+         *             private key does not match the algorithm of the public
+         *             key of the first certificate or the certificates are not
+         *             all of the same type.
          */
         public PrivateKeyEntry(PrivateKey privateKey, Certificate[] chain) {
             if (privateKey == null) {
@@ -922,32 +1304,37 @@
         }
 
         /**
-         * 
-         *  
+         * Returns the private key.
+         *
+         * @return the private key.
          */
         public PrivateKey getPrivateKey() {
             return privateKey;
         }
 
         /**
-         * 
-         *  
+         * Returns the certificate chain.
+         *
+         * @return the certificate chain.
          */
         public Certificate[] getCertificateChain() {
             return chain.clone();
         }
 
         /**
-         * 
-         *  
+         * Returns the certificate corresponding to the private key.
+         *
+         * @return the certificate corresponding to the private key.
          */
         public Certificate getCertificate() {
             return chain[0];
         }
 
         /**
-         * 
-         *  
+         * Returns a string containing a concise, human-readable description of
+         * this {@code PrivateKeyEntry}.
+         *
+         * @return a printable representation for this {@code PrivateKeyEntry}.
          */
         public String toString() {
             StringBuffer sb = new StringBuffer(
@@ -963,9 +1350,8 @@
     }
 
     /**
-     * 
-     * 
-     * 
+     * {@code SecretKeyEntry} represents a {@code KeyStore} entry that
+     * holds a secret key.
      */
     public static final class SecretKeyEntry implements Entry {
 
@@ -973,8 +1359,13 @@
         private final SecretKey secretKey;
 
         /**
-         * 
-         *  
+         * Constructs a new instance of {@code SecretKeyEntry} with the given
+         * {@code SecretKey}.
+         *
+         * @param secretKey
+         *            the secret key.
+         * @throws NullPointerException
+         *             if {@code secretKey} is {@code null}.
          */
         public SecretKeyEntry(SecretKey secretKey) {
             if (secretKey == null) {
@@ -984,16 +1375,20 @@
         }
 
         /**
-         * 
-         *  
+         * Returns the secret key.
+         *
+         * @return the secret key.
          */
         public SecretKey getSecretKey() {
             return secretKey;
         }
 
         /**
-         * 
-         *  
+         * Returns a string containing a concise, human-readable description of
+         * this {@code SecretKeyEntry}.
+         *
+         * @return a printable representation for this {@code
+         *         SecretKeyEntry}.
          */
         public String toString() {
             StringBuffer sb = new StringBuffer("SecretKeyEntry: algorithm - "); //$NON-NLS-1$
@@ -1003,9 +1398,8 @@
     }
 
     /**
-     * 
-     * 
-     * 
+     * {@code TrustedCertificateEntry} represents a {@code KeyStore} entry that
+     * holds a trusted certificate.
      */
     public static final class TrustedCertificateEntry implements Entry {
 
@@ -1013,8 +1407,13 @@
         private final Certificate trustCertificate;
 
         /**
-         * 
-         *  
+         * Constructs a new instance of {@code TrustedCertificateEntry} with the
+         * given {@code Certificate}.
+         *
+         * @param trustCertificate
+         *            the trusted certificate.
+         * @throws NullPointerException
+         *             if {@code trustCertificate} is {@code null}.
          */
         public TrustedCertificateEntry(Certificate trustCertificate) {
             if (trustCertificate == null) {
@@ -1024,16 +1423,20 @@
         }
 
         /**
-         * 
-         *  
+         * Returns the trusted certificate.
+         *
+         * @return the trusted certificate.
          */
         public Certificate getTrustedCertificate() {
             return trustCertificate;
         }
 
         /**
-         * 
-         *  
+         * Returns a string containing a concise, human-readable description of
+         * this {@code TrustedCertificateEntry}.
+         *
+         * @return a printable representation for this {@code
+         *         TrustedCertificateEntry}.
          */
         public String toString() {
             return "Trusted certificate entry:\n" + trustCertificate; //$NON-NLS-1$

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStoreException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStoreException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStoreException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStoreException.java Tue Apr 28 17:01:41 2009
@@ -15,46 +15,53 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * @com.intel.drl.spec_ref
+ * {@code KeyStoreException} is a general {@code KeyStore} exception.
  * 
+ * @see KeyStore
  */
 public class KeyStoreException extends GeneralSecurityException {
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private static final long serialVersionUID = -1119353179322377262L;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code KeyStoreException} with the
+     * given message.
+     *
+     * @param msg
+     *            the detail message for this exception.
      */
     public KeyStoreException(String msg) {
         super(msg);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code KeyStoreException}.
      */
     public KeyStoreException() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code KeyStoreException} with the
+     * given message and the cause.
+     *
+     * @param message
+     *            the detail message for this exception.
+     * @param cause
+     *            the exception which is the cause for this exception.
      */
     public KeyStoreException(String message, Throwable cause) {
         super(message, cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code KeyStoreException} with the
+     * cause.
+     *
+     * @param cause
+     *            the exception which is the cause for this exception.
      */
     public KeyStoreException(Throwable cause) {
         super(cause);

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStoreSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStoreSpi.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStoreSpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStoreSpi.java Tue Apr 28 17:01:41 2009
@@ -30,52 +30,272 @@
 
 import org.apache.harmony.security.internal.nls.Messages;
 
+/**
+ * {@code KeyStoreSpi} is the Service Provider Interface (SPI) definition for
+ * {@link KeyStore}.
+ *
+ * @see KeyStore
+ */
 public abstract class KeyStoreSpi {
 
+    /**
+     * Returns the key with the given alias, using the password to recover the
+     * key from the store.
+     *
+     * @param alias
+     *            the alias for the entry.
+     * @param password
+     *            the password used to recover the key.
+     * @return the key with the specified alias, or {@code null} if the
+     *         specified alias is not bound to an entry.
+     * @throws NoSuchAlgorithmException
+     *             if the algorithm for recovering the key is not available.
+     * @throws UnrecoverableKeyException
+     *             if the key can not be recovered.
+     */
     public abstract Key engineGetKey(String alias, char[] password)
             throws NoSuchAlgorithmException, UnrecoverableKeyException;
 
+    /**
+     * Returns the certificate chain for the entry with the given alias.
+     *
+     * @param alias
+     *            the alias for the entry
+     * @return the certificate chain for the entry with the given alias, or
+     *         {@code null} if the specified alias is not bound to an entry.
+     */
     public abstract Certificate[] engineGetCertificateChain(String alias);
 
+    /**
+     * Returns the trusted certificate for the entry with the given alias.
+     *
+     * @param alias
+     *            the alias for the entry.
+     * @return the trusted certificate for the entry with the given alias, or
+     *         {@code null} if the specified alias is not bound to an entry.
+     */
     public abstract Certificate engineGetCertificate(String alias);
 
+    /**
+     * Returns the creation date of the entry with the given alias.
+     *
+     * @param alias
+     *            the alias for the entry.
+     * @return the creation date, or {@code null} if the specified alias is not
+     *         bound to an entry.
+     */
     public abstract Date engineGetCreationDate(String alias);
 
+    /**
+     * Associates the given alias with the key, password and certificate chain.
+     * <p>
+     * If the specified alias already exists, it will be reassigned.
+     *
+     * @param alias
+     *            the alias for the key.
+     * @param key
+     *            the key.
+     * @param password
+     *            the password.
+     * @param chain
+     *            the certificate chain.
+     * @throws KeyStoreException
+     *             if the specified key can not be protected, or if this
+     *             operation fails for another reason.
+     * @throws IllegalArgumentException
+     *             if {@code key} is a {@code PrivateKey} and {@code chain} does
+     *             not contain any certificates.
+     */
     public abstract void engineSetKeyEntry(String alias, Key key,
             char[] password, Certificate[] chain) throws KeyStoreException;
 
+    /**
+     * Associates the given alias with a key and a certificate chain.
+     * <p>
+     * If the specified alias already exists, it will be reassigned.
+     *
+     * @param alias
+     *            the alias for the key.
+     * @param key
+     *            the key in an encoded format.
+     * @param chain
+     *            the certificate chain.
+     * @throws KeyStoreException
+     *             if this operation fails.
+     * @throws IllegalArgumentException
+     *             if {@code key} is a {@code PrivateKey} and {@code chain}
+     *             does.
+     */
     public abstract void engineSetKeyEntry(String alias, byte[] key,
             Certificate[] chain) throws KeyStoreException;
 
+    /**
+     * Associates the given alias with a certificate.
+     * <p>
+     * If the specified alias already exists, it will be reassigned.
+     *
+     * @param alias
+     *            the alias for the certificate.
+     * @param cert
+     *            the certificate.
+     * @throws KeyStoreException
+     *             if an existing alias is not associated to an entry containing
+     *             a trusted certificate, or this method fails for any other
+     *             reason.
+     */
     public abstract void engineSetCertificateEntry(String alias,
             Certificate cert) throws KeyStoreException;
 
+    /**
+     * Deletes the entry identified with the given alias from this {@code
+     * KeyStoreSpi}.
+     *
+     * @param alias
+     *            the alias for the entry.
+     * @throws KeyStoreException
+     *             if the entry can not be deleted.
+     */
     public abstract void engineDeleteEntry(String alias)
             throws KeyStoreException;
 
+    /**
+     * Returns an {@code Enumeration} over all alias names stored in this
+     * {@code KeyStoreSpi}.
+     *
+     * @return an {@code Enumeration} over all alias names stored in this
+     *         {@code KeyStoreSpi}.
+     */
     public abstract Enumeration<String> engineAliases();
 
+    /**
+     * Indicates whether the given alias is present in this {@code KeyStoreSpi}.
+     *
+     * @param alias
+     *            the alias of an entry.
+     * @return {@code true} if the alias exists, {@code false} otherwise.
+     */
     public abstract boolean engineContainsAlias(String alias);
 
+    /**
+     * Returns the number of entries stored in this {@code KeyStoreSpi}.
+     *
+     * @return the number of entries stored in this {@code KeyStoreSpi}.
+     */
     public abstract int engineSize();
 
+    /**
+     * Indicates whether the specified alias is associated with either a
+     * {@link KeyStore.PrivateKeyEntry} or a {@link KeyStore.SecretKeyEntry}.
+     *
+     * @param alias
+     *            the alias of an entry.
+     * @return {@code true} if the given alias is associated with a key entry.
+     */
     public abstract boolean engineIsKeyEntry(String alias);
 
+    /**
+     * Indicates whether the specified alias is associated with a
+     * {@link KeyStore.TrustedCertificateEntry}.
+     *
+     * @param alias
+     *            the alias of an entry.
+     * @return {@code true} if the given alias is associated with a certificate
+     *         entry.
+     */
     public abstract boolean engineIsCertificateEntry(String alias);
 
+    /**
+     * Returns the alias associated with the first entry whose certificate
+     * matches the specified certificate.
+     *
+     * @param cert
+     *            the certificate to find the associated entry's alias for.
+     * @return the alias or {@code null} if no entry with the specified
+     *         certificate can be found.
+     */
     public abstract String engineGetCertificateAlias(Certificate cert);
 
+    /**
+     * Writes this {@code KeyStoreSpi} to the specified {@code OutputStream}.
+     * The data written to the {@code OutputStream} is protected by the
+     * specified password.
+     *
+     * @param stream
+     *            the {@code OutputStream} to write the store's data to.
+     * @param password
+     *            the password to protect the data.
+     * @throws IOException
+     *             if a problem occurred while writing to the stream.
+     * @throws NoSuchAlgorithmException
+     *             if the required algorithm is not available.
+     * @throws CertificateException
+     *             if the an exception occurred while storing the certificates
+     *             of this code {@code KeyStoreSpi}.
+     */
     public abstract void engineStore(OutputStream stream, char[] password)
             throws IOException, NoSuchAlgorithmException, CertificateException;
 
+    /**
+     * Stores this {@code KeyStoreSpi} using the specified {@code
+     * LoadStoreParameter}.
+     *
+     * @param param
+     *            the {@code LoadStoreParameter} that specifies how to store
+     *            this {@code KeyStoreSpi}, maybe {@code null}.
+     * @throws IOException
+     *             if a problem occurred while writing to the stream.
+     * @throws NoSuchAlgorithmException
+     *             if the required algorithm is not available.
+     * @throws CertificateException
+     *             if the an exception occurred while storing the certificates
+     *             of this code {@code KeyStoreSpi}.
+     * @throws IllegalArgumentException
+     *             if the given {@link KeyStore.LoadStoreParameter} is not
+     *             recognized.
+     */
     public void engineStore(KeyStore.LoadStoreParameter param)
             throws IOException, NoSuchAlgorithmException, CertificateException {
         throw new UnsupportedOperationException(Messages.getString("security.33")); //$NON-NLS-1$
     }
 
+    /**
+     * Loads this {@code KeyStoreSpi} from the given {@code InputStream}.
+     * Utilizes the given password to verify the stored data.
+     *
+     * @param stream
+     *            the {@code InputStream} to load this {@code KeyStoreSpi}'s
+     *            data from.
+     * @param password
+     *            the password to verify the stored data, maybe {@code null}.
+     * @throws IOException
+     *             if a problem occurred while reading from the stream.
+     * @throws NoSuchAlgorithmException
+     *             if the required algorithm is not available.
+     * @throws CertificateException
+     *             if the an exception occurred while loading the certificates
+     *             of this code {@code KeyStoreSpi}.
+     */
     public abstract void engineLoad(InputStream stream, char[] password)
             throws IOException, NoSuchAlgorithmException, CertificateException;
 
+    /**
+     * Loads this {@code KeyStoreSpi} using the specified {@code
+     * LoadStoreParameter}.
+     *
+     * @param param
+     *            the {@code LoadStoreParameter} that specifies how to load this
+     *            {@code KeyStoreSpi}, maybe {@code null}.
+     * @throws IOException
+     *             if a problem occurred while reading from the stream.
+     * @throws NoSuchAlgorithmException
+     *             if the required algorithm is not available.
+     * @throws CertificateException
+     *             if the an exception occurred while loading the certificates
+     *             of this code {@code KeyStoreSpi}.
+     * @throws IllegalArgumentException
+     *             if the given {@link KeyStore.LoadStoreParameter} is not
+     *             recognized.
+     */
     public void engineLoad(KeyStore.LoadStoreParameter param)
             throws IOException, NoSuchAlgorithmException, CertificateException {
         if (param == null) {
@@ -106,6 +326,24 @@
                 Messages.getString("security.35")); //$NON-NLS-1$
     }
 
+    /**
+     * Returns the {@code Entry} with the given alias, using the specified
+     * {@code ProtectionParameter}.
+     *
+     * @param alias
+     *            the alias of the requested entry.
+     * @param protParam
+     *            the {@code ProtectionParameter}, used to protect the requested
+     *            entry, maybe {@code null}.
+     * @return he {@code Entry} with the given alias, using the specified
+     *         {@code ProtectionParameter}.
+     * @throws NoSuchAlgorithmException
+     *             if the required algorithm is not available.
+     * @throws UnrecoverableEntryException
+     *             if the entry can not be recovered.
+     * @throws KeyStoreException
+     *             if this operation fails
+     */
     public KeyStore.Entry engineGetEntry(String alias,
             KeyStore.ProtectionParameter protParam) throws KeyStoreException,
             NoSuchAlgorithmException, UnrecoverableEntryException {
@@ -150,6 +388,22 @@
         throw new NoSuchAlgorithmException(Messages.getString("security.38")); //$NON-NLS-1$
     }
 
+    /**
+     * Stores the given {@code Entry} in this {@code KeyStoreSpi} and associates
+     * the entry with the given {@code alias}. The entry is protected by the
+     * specified {@code ProtectionParameter}.
+     * <p>
+     * If the specified alias already exists, it will be reassigned.
+     *
+     * @param alias
+     *            the alias for the entry.
+     * @param entry
+     *            the entry to store.
+     * @param protParam
+     *            the {@code ProtectionParameter} to protect the entry.
+     * @throws KeyStoreException
+     *             if this operation fails.
+     */
     public void engineSetEntry(String alias, KeyStore.Entry entry,
             KeyStore.ProtectionParameter protParam) throws KeyStoreException {
         if (entry == null) {
@@ -204,6 +458,17 @@
                 Messages.getString("security.3B", entry.toString())); //$NON-NLS-1$
     }
 
+    /**
+     * Indicates whether the entry for the given alias is assignable to the
+     * provided {@code Class}.
+     *
+     * @param alias
+     *            the alias for the entry.
+     * @param entryClass
+     *            the type of the entry.
+     * @return {@code true} if the {@code Entry} for the alias is assignable to
+     *         the specified {@code entryClass}.
+     */
     public boolean engineEntryInstanceOf(String alias,
             Class<? extends KeyStore.Entry> entryClass) {
         if (!engineContainsAlias(alias)) {

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/MessageDigest.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/MessageDigest.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/MessageDigest.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/MessageDigest.java Tue Apr 28 17:01:41 2009
@@ -22,6 +22,13 @@
 import org.apache.harmony.security.fortress.Engine;
 import org.apache.harmony.security.internal.nls.Messages;
 
+/**
+ * {@code MessageDigest} is an engine class which is capable of generating one
+ * way hash values for arbitrary input, utilizing the algorithm it was
+ * initialized with.
+ *
+ * @see MessageDigestSpi
+ */
 public abstract class MessageDigest extends MessageDigestSpi {
 
     // The service name
@@ -37,16 +44,28 @@
     private String algorithm;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code MessageDigest} with the name of
+     * the algorithm to use.
      * 
+     * @param algorithm
+     *            the name of algorithm to use
      */
     protected MessageDigest(String algorithm) {
         this.algorithm = algorithm;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a new instance of {@code MessageDigest} that utilizes the
+     * specified algorithm.
      * 
+     * @param algorithm
+     *            the name of the algorithm to use
+     * @return a new instance of {@code MessageDigest} that utilizes the
+     *         specified algorithm
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm is not available
+     * @throws NullPointerException
+     *             if {@code algorithm} is {@code null}
      */
     public static MessageDigest getInstance(String algorithm)
             throws NoSuchAlgorithmException {
@@ -70,8 +89,21 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a new instance of {@code MessageDigest} that utilizes the
+     * specified algorithm from the specified provider.
      * 
+     * @param algorithm
+     *            the name of the algorithm to use
+     * @param provider
+     *            the name of the provider
+     * @return a new instance of {@code MessageDigest} that utilizes the
+     *         specified algorithm from the specified provider
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm is not available
+     * @throws NoSuchProviderException
+     *             if the specified provider is not available
+     * @throws NullPointerException
+     *             if {@code algorithm} is {@code null}
      */
     public static MessageDigest getInstance(String algorithm, String provider)
             throws NoSuchAlgorithmException, NoSuchProviderException {
@@ -88,20 +120,19 @@
     }
 
     /**
-     * Answers a new MessageDigest which is capable of running the algorithm
-     * described by the argument. The result will be an instance of a subclass
-     * of MessageDigest which implements that algorithm.
-     * 
+     * Returns a new instance of {@code MessageDigest} that utilizes the
+     * specified algorithm from the specified provider.
      * 
      * @param algorithm
-     *            java.lang.String Name of the algorithm desired
+     *            the name of the algorithm to use
      * @param provider
-     *            Provider Provider which has to implement the algorithm
-     * @return MessageDigest a concrete implementation for the algorithm
-     *         desired.
-     * 
-     * @exception NoSuchAlgorithmException
-     *                If the algorithm cannot be found
+     *            the provider
+     * @return a new instance of {@code MessageDigest} that utilizes the
+     *         specified algorithm from the specified provider
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm is not available
+     * @throws NullPointerException
+     *             if {@code algorithm} is {@code null}
      */
     public static MessageDigest getInstance(String algorithm, Provider provider)
             throws NoSuchAlgorithmException {
@@ -129,19 +160,18 @@
     }
 
     /**
-     * Puts the receiver back in an initial state, such that it is ready to
-     * compute a new hash.
+     * Puts this {@code MessageDigest} back in an initial state, such that it is
+     * ready to compute a one way hash value.
      */
     public void reset() {
         engineReset();
     }
 
     /**
-     * Includes the argument in the hash value computed by the receiver.
+     * Updates this {@code MessageDigest} using the given {@code byte}.
      * 
      * @param arg0
-     *            byte the byte to feed to the hash algorithm
-     * 
+     *            the {@code byte} to update this {@code MessageDigest} with
      * @see #reset()
      */
     public void update(byte arg0) {
@@ -149,8 +179,17 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Updates this {@code MessageDigest} using the given {@code byte[]}.
      * 
+     * @param input
+     *            the {@code byte} array
+     * @param offset
+     *            the index of the first byte in {@code input} to update from
+     * @param len
+     *            the number of bytes in {@code input} to update from
+     * @throws IllegalArgumentException
+     *             if {@code offset} or {@code len} are not valid in respect to
+     *             {@code input}
      */
     public void update(byte[] input, int offset, int len) {
         if (input == null ||
@@ -165,8 +204,12 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Updates this {@code MessageDigest} using the given {@code byte[]}.
      * 
+     * @param input
+     *            the {@code byte} array
+     * @throws NullPointerException
+     *             if {@code input} is {@code null}
      */
     public void update(byte[] input) {
         if (input == null) {
@@ -176,11 +219,10 @@
     }
 
     /**
-     * Computes and answers the final hash value that the receiver represents.
+     * Computes and returns the final hash value for this {@link MessageDigest}.
      * After the digest is computed the receiver is reset.
      * 
-     * @return the hash the receiver computed
-     * 
+     * @return the computed one way hash value
      * @see #reset
      */
     public byte[] digest() {
@@ -188,8 +230,22 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Computes and stores the final hash value for this {@link MessageDigest}.
+     * After the digest is computed the receiver is reset.
      * 
+     * @param buf
+     *            the buffer to store the result
+     * @param offset
+     *            the index of the first byte in {@code buf} to store
+     * @param len
+     *            the number of bytes allocated for the digest
+     * @return the number of bytes written to {@code buf}
+     * @throws DigestException
+     *             if an error occures
+     * @throws IllegalArgumentException
+     *             if {@code offset} or {@code len} are not valid in respect to
+     *             {@code buf}
+     * @see #reset()
      */
     public int digest(byte[] buf, int offset, int len) throws DigestException {
         if (buf == null ||
@@ -204,8 +260,14 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     * 
+     * Performs the final update and then computes and returns the final hash
+     * value for this {@link MessageDigest}. After the digest is computed the
+     * receiver is reset.
+     * 
+     * @param input
+     *            the {@code byte} array
+     * @return the computed one way hash value
+     * @see #reset()
      */
     public byte[] digest(byte[] input) {
         update(input);
@@ -213,25 +275,24 @@
     }
 
     /**
-     * Answers a string containing a concise, human-readable description of the
-     * receiver.
+     * Returns a string containing a concise, human-readable description of this
+     * {@code MessageDigest} including the name of its algorithm.
      * 
-     * @return a printable representation for the receiver.
+     * @return a printable representation for this {@code MessageDigest}
      */
     public String toString() {
         return "MESSAGE DIGEST " + algorithm; //$NON-NLS-1$
     }
 
     /**
-     * Does a simply byte-per-byte compare of the two digests.
+     * Indicates whether to digest are equal by performing a simply
+     * byte-per-byte compare of the two digests.
      * 
      * @param digesta
-     *            One of the digests to compare
+     *            the first digest to be compared
      * @param digestb
-     *            The digest to compare to
-     * 
-     * @return <code>true</code> if the two hashes are equal
-     *         <code>false</code> if the two hashes are not equal
+     *            the second digest to be compared
+     * @return {@code true} if the two hashes are equal, {@code false} otherwise
      */
     public static boolean isEqual(byte[] digesta, byte[] digestb) {
         if (digesta.length != digestb.length) {
@@ -246,29 +307,29 @@
     }
 
     /**
-     * Answers the standard Java Security name for the algorithm being used by
-     * the receiver.
+     * Returns the name of the algorithm of this {@code MessageDigest}.
      * 
-     * @return String the name of the algorithm
+     * @return the name of the algorithm of this {@code MessageDigest}
      */
     public final String getAlgorithm() {
         return algorithm;
     }
 
     /**
-     * Returns the Provider of the digest represented by the receiver.
+     * Returns the provider associated with this {@code MessageDigest}.
      * 
-     * @return Provider an instance of a subclass of java.security.Provider
+     * @return the provider associated with this {@code MessageDigest}
      */
     public final Provider getProvider() {
         return provider;
     }
 
     /**
-     * Return the engine digest length in bytes. Default is 0.
-     * 
-     * @return int the engine digest length in bytes
+     * Returns the engine digest length in bytes. If the implementation does not
+     * implement this function or is not an instance of {@code Cloneable},
+     * {@code 0} is returned.
      * 
+     * @return the digest length in bytes, or {@code 0}
      */
     public final int getDigestLength() {
         int l = engineGetDigestLength();
@@ -286,10 +347,6 @@
         }
     }
 
-    /**
-     * @com.intel.drl.spec_ref
-     * 
-     */
     public Object clone() throws CloneNotSupportedException {
         if (this instanceof Cloneable) {
             return super.clone();
@@ -299,8 +356,10 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Updates this {@code MessageDigest} using the given {@code input}.
      * 
+     * @param input
+     *            the {@code ByteBuffer}
      */
     public final void update(ByteBuffer input) {
         engineUpdate(input);

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/MessageDigestSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/MessageDigestSpi.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/MessageDigestSpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/MessageDigestSpi.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
  *  limitations under the License.
  */
 
-/**
-* @author Boris V. Kuznetsov
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.nio.ByteBuffer;
@@ -28,39 +23,54 @@
 
 
 /**
- * This class is a Service Provider Interface (therefore the Spi suffix) for
- * digest algorithms to be supplied by providers. Examples of digest algorithms
- * are MD5 and SHA.
- * 
- * A digest is a secure hash function for a stream of bytes, like a fingerprint
- * for the stream of bytes.
+ * {@code MessageDigestSpi} is the Service Provider Interface (SPI) definition
+ * for {@link MessageDigest}. Examples of digest algorithms are MD5 and SHA. A
+ * digest is a secure one way hash function for a stream of bytes. It acts like
+ * a fingerprint for a stream of bytes.
  * 
+ * @see MessageDigest
  */
 public abstract class MessageDigestSpi {
     
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the engine digest length in bytes. If the implementation does not
+     * implement this function {@code 0} is returned.
      * 
+     * @return the digest length in bytes, or {@code 0}.
      */
     protected int engineGetDigestLength() {
         return 0;
     }
     
     /**
-     * @com.intel.drl.spec_ref
+     * Updates this {@code MessageDigestSpi} using the given {@code byte}.
      * 
+     * @param input
+     *            the {@code byte} to update this {@code MessageDigestSpi} with.
+     * @see #engineReset()
      */
     protected abstract void engineUpdate(byte input);
     
     /**
-     * @com.intel.drl.spec_ref
+     * Updates this {@code MessageDigestSpi} using the given {@code byte[]}.
      * 
+     * @param input
+     *            the {@code byte} array.
+     * @param offset
+     *            the index of the first byte in {@code input} to update from.
+     * @param len
+     *            the number of bytes in {@code input} to update from.
+     * @throws IllegalArgumentException
+     *             if {@code offset} or {@code len} are not valid in respect to
+     *             {@code input}.
      */
     protected abstract void engineUpdate(byte[] input, int offset, int len);
     
     /**
-     * @com.intel.drl.spec_ref
+     * Updates this {@code MessageDigestSpi} using the given {@code input}.
      * 
+     * @param input
+     *            the {@code ByteBuffer}.
      */
     protected void engineUpdate(ByteBuffer input) {
         if (!input.hasRemaining()) {
@@ -82,14 +92,33 @@
     }
     
     /**
-     * @com.intel.drl.spec_ref
+     * Computes and returns the final hash value for this
+     * {@link MessageDigestSpi}. After the digest is computed the receiver is
+     * reset.
      * 
+     * @return the computed one way hash value.
+     * @see #engineReset()
      */
     protected abstract byte[] engineDigest();
     
     /**
-     * @com.intel.drl.spec_ref
-     * 
+     * Computes and stores the final hash value for this
+     * {@link MessageDigestSpi}. After the digest is computed the receiver is
+     * reset.
+     * 
+     * @param buf
+     *            the buffer to store the result in.
+     * @param offset
+     *            the index of the first byte in {@code buf} to store in.
+     * @param len
+     *            the number of bytes allocated for the digest.
+     * @return the number of bytes written to {@code buf}.
+     * @throws DigestException
+     *             if an error occures.
+     * @throws IllegalArgumentException
+     *             if {@code offset} or {@code len} are not valid in respect to
+     *             {@code buf}.
+     * @see #engineReset()
      */
     protected int engineDigest(byte[] buf, int offset, int len)
                     throws DigestException {
@@ -114,15 +143,11 @@
     }
     
     /**
-     * @com.intel.drl.spec_ref
-     * 
+     * Puts this {@code MessageDigestSpi} back in an initial state, such that it
+     * is ready to compute a one way hash value.
      */
     protected abstract void engineReset();
     
-    /**
-     * @com.intel.drl.spec_ref
-     * 
-     */
     public Object clone() throws CloneNotSupportedException {
         return super.clone();
     }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/NoSuchAlgorithmException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/NoSuchAlgorithmException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/NoSuchAlgorithmException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/NoSuchAlgorithmException.java Tue Apr 28 17:01:41 2009
@@ -15,54 +15,52 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * Instances of this class are thrown when an attempt is made to access an
- * algorithm which is not provided by the library.
- * 
- * @see Throwable
+ * {@code NoSuchAlgorithmException} indicates that a requested algorithm could
+ * not be found.
  */
 public class NoSuchAlgorithmException extends GeneralSecurityException {
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private static final long serialVersionUID = -7443947487218346562L;
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * 
-	 * @param msg
-	 *            String The detail message for the exception.
-	 */
+    /**
+     * Constructs a new instance of {@code NoSuchAlgorithmException} with the
+     * given message.
+     *
+     * @param msg
+     *            the detail message for this exception.
+     */
     public NoSuchAlgorithmException(String msg) {
         super(msg);
     }
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 * 
-	 */
+    /**
+     * Constructs a new instance of {@code NoSuchAlgorithmException}.
+     */
     public NoSuchAlgorithmException() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code NoSuchAlgorithmException} with the
+     * given message and the cause.
+     *
+     * @param message
+     *            the detail message for this exception.
+     * @param cause
+     *            the exception which is the cause for this exception.
      */
     public NoSuchAlgorithmException(String message, Throwable cause) {
         super(message, cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code NoSuchAlgorithmException} with the
+     * cause.
+     *
+     * @param cause
+     *            the exception which is the cause for this exception.
      */
     public NoSuchAlgorithmException(Throwable cause) {
         super(cause);

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/NoSuchProviderException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/NoSuchProviderException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/NoSuchProviderException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/NoSuchProviderException.java Tue Apr 28 17:01:41 2009
@@ -15,41 +15,30 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * Instances of this class are thrown when an attempt is made to access a
- * provider by name which is not currently available.
- * 
- * 
- * @see Throwable
+ * {@code NoSuchProviderException} indicates that a requested security provider
+ * could not be found.
  */
 public class NoSuchProviderException extends GeneralSecurityException {
-    /**
-     * @com.intel.drl.spec_ref
-     */
+
     private static final long serialVersionUID = 8488111756688534474L;
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param msg
-	 *            String The detail message for the exception.
-	 */
+    /**
+     * Constructs a new instance of {@code NoSuchProviderException} with the
+     * given message.
+     *
+     * @param msg
+     *            the detail message for this exception.
+     */
     public NoSuchProviderException(String msg) {
         super(msg);
     }
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 * 
-	 */
+    /**
+     * Constructs a new instance of {@code NoSuchProviderException}.
+     */
     public NoSuchProviderException() {
     }
 }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Permission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Permission.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Permission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Permission.java Tue Apr 28 17:01:41 2009
@@ -15,91 +15,111 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexey V. Varlamov
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.io.Serializable;
 
 /**
- * Abstract superclass of all classes which represent permission to access
- * system resources.
- * 
+ * {@code Permission} is the common base class of all permissions that
+ * participate in the access control security framework around
+ * {@link AccessController} and {@link AccessControlContext}. A permission
+ * constitutes of a name and associated actions.
  */
 public abstract class Permission implements Guard, Serializable {
 
-    /** 
-     * @com.intel.drl.spec_ref 
-     */
     private static final long serialVersionUID = -5636570222231596674L;
 
     private final String name;
 
-    /** 
-     * @com.intel.drl.spec_ref 
+    /**
+     * Compares the specified object with this {@code Permission} for equality
+     * and returns {@code true} if the specified object is equal, {@code false}
+     * otherwise.
+     * <p>
+     * The {@link #implies(Permission)} method should be used for making access
+     * control checks.
+     *
+     * @param obj
+     *            object to be compared for equality with this {@code
+     *            Permission}.
+     * @return {@code true} if the specified object is equal to this {@code
+     *         Permission}, otherwise {@code false}.
      */
     public abstract boolean equals(Object obj);
 
-	/**
-	 * Answers an integer hash code for the receiver. Any two objects which
-	 * answer <code>true</code> when passed to <code>.equals</code> must
-	 * answer the same value for this method.
-	 * 
-	 * 
-	 * @return int the receiver's hash.
-	 * 
-	 * @see #equals
-	 */
+    /**
+     * Returns the hash code value for this {@code Permission}. Returns the same
+     * hash code for {@code Permission}s that are equal to each other as
+     * required by the general contract of {@link Object#hashCode}.
+     *
+     * @return the hash code value for this {@code Permission}.
+     * @see Object#equals(Object)
+     * @see Permission#equals(Object)
+     */
     public abstract int hashCode();
 
-	/**
-	 * Answers the actions associated with the receiver. Subclasses should
-	 * return their actions in canonical form. If no actions are associated with
-	 * the receiver, the empty string should be returned.
-	 * 
-	 * 
-	 * @return String the receiver's actions.
-	 */
+    /**
+     * Returns a comma separated string identifying the actions associated with
+     * this permission. The returned actions are in canonical form. For example:
+     *
+     * <pre>
+     * sp0 = new SocketPermission(&quot;www.example.com&quot;, &quot;connect,resolve&quot;)
+     * sp1 = new SocketPermission(&quot;www.example.com&quot;, &quot;resolve,connect&quot;)
+     * sp0.getActions().equals(sp1.getActions()) //yields true
+     * </pre>
+     *
+     * Both permissions return "connect,resolve" (in that order) if {@code
+     * #getActions()} is invoked. Returns an empty String, if no actions are
+     * associated with this permission.
+     *
+     * @return the actions associated with this permission or an empty string if
+     *         no actions are associated with this permission.
+     */
     public abstract String getActions();
 
-	/**
-	 * Indicates whether the argument permission is implied by the receiver.
-	 * 
-	 * 
-	 * @return boolean <code>true</code> if the argument permission is implied
-	 *         by the receiver, and <code>false</code> if it is not.
-	 * @param permission
-	 *            Permission the permission to check.
-	 */
+    /**
+     * Indicates whether the specified permission is implied by this permission.
+     * The {@link AccessController} uses this method to check whether permission
+     * protected access is allowed with the present policy.
+     *
+     * @param permission
+     *            the permission to check against this permission.
+     * @return {@code true} if the specified permission is implied by this
+     *         permission, {@code false} otherwise.
+     */
     public abstract boolean implies(Permission permission);
 
-	/**
-	 * Constructs a new instance of this class with its name set to the
-	 * argument.
-	 * 
-	 * 
-	 * @param name
-	 *            String the name of the permission.
-	 */
+    /**
+     * Constructs a new instance of {@code Permission} with its name.
+     *
+     * @param name
+     *            the name of the permission.
+     */
     public Permission(String name) {
         this.name = name;
     }
 
-	/**
-	 * Answers the name of the receiver.
-	 * 
-	 * 
-	 * @return String the receiver's name.
-	 */
+    /**
+     * Returns the name of this permission.
+     *
+     * @return the name of this permission.
+     */
     public final String getName() {
         return name;
     }
 
-    /** 
-     * @com.intel.drl.spec_ref 
+    /**
+     * Invokes {@link SecurityManager#checkPermission(Permission)} with this
+     * permission as its argument. This method implements the {@link Guard}
+     * interface.
+     *
+     * @param obj
+     *            as specified in {@link Guard#checkGuard(Object)} but ignored
+     *            in this implementation.
+     * @throws SecurityException
+     *             if this permission is not granted.
+     * @see Guard
+     * @see SecurityManager#checkPermission(Permission)
      */
     public void checkGuard(Object obj) throws SecurityException {
         SecurityManager sm = System.getSecurityManager();
@@ -108,25 +128,27 @@
         }
     }
 
-	/**
-	 * Answers a new PermissionCollection for holding permissions of this class.
-	 * Answer null if any permission collection can be used.
-	 * 
-	 * 
-	 * @return PermissionCollection or null a suitable permission collection for
-	 *         instances of the class of the receiver.
-	 */
+    /**
+     * Returns a specific {@link PermissionCollection} container for permissions
+     * of this type. Returns {@code null} if any permission collection can be
+     * used.
+     * <p>
+     * Subclasses may override this method to return an appropriate collection
+     * for the specific permissions they implement.
+     *
+     * @return an empty {@link PermissionCollection} or {@code null} if any
+     *         permission collection can be used.
+     */
     public PermissionCollection newPermissionCollection() {
         return null;
     }
 
-	/**
-	 * Answers a string containing a concise, human-readable description of the
-	 * receiver.
-	 * 
-	 * 
-	 * @return String a printable representation for the receiver.
-	 */
+    /**
+     * Returns a string containing a concise, human-readable description of the
+     * this {@code Permission} including its name and its actions.
+     *
+     * @return a printable representation for this {@code Permission}.
+     */
     public String toString() {
         String actions = getActions();
         actions = (actions == null || actions.length() == 0) ? "" : " " //$NON-NLS-1$ //$NON-NLS-2$



Mime
View raw message