harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r769463 [2/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/CodeSource.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/CodeSource.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/CodeSource.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/CodeSource.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexander V. Astapchuk
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.io.ByteArrayInputStream;
@@ -44,6 +39,14 @@
 import org.apache.harmony.security.fortress.PolicyUtils;
 import org.apache.harmony.security.internal.nls.Messages;
 
+/**
+ * {@code CodeSource} encapsulates the location from where code is loaded and
+ * the certificates that were used to verify that code. This information is used
+ * by {@code SecureClassLoader} to define protection domains for loaded classes.
+ *
+ * @see SecureClassLoader
+ * @see ProtectionDomain
+ */
 public class CodeSource implements Serializable {
 
     private static final long serialVersionUID = 4977541819976013951L;
@@ -64,15 +67,17 @@
     // Cached factory used to build CertPath-s in <code>getCodeSigners()</code>.  
     private transient CertificateFactory factory;
 
-	/**
-	 * Constructs a new instance of this class with its url and certificates
-	 * fields filled in from the arguments.
-	 * 
-	 * @param location
-	 *            URL the URL.
-	 * @param certs
-	 *            Certificate[] the Certificates.
-	 */
+    /**
+     * Constructs a new instance of {@code CodeSource} with the specified
+     * {@code URL} and the {@code Certificate}s.
+     *
+     * @param location
+     *            the {@code URL} representing the location from where code is
+     *            loaded, maybe {@code null}.
+     * @param certs
+     *            the {@code Certificate} used to verify the code, loaded from
+     *            the specified {@code location}, maybe {@code null}.
+     */
     public CodeSource(URL location, Certificate[] certs) {
         this.location = location;
         if (certs != null) {
@@ -81,6 +86,17 @@
         }
     }
 
+    /**
+     * Constructs a new instance of {@code CodeSource} with the specified
+     * {@code URL} and the {@code CodeSigner}s.
+     *
+     * @param location
+     *            the {@code URL} representing the location from where code is
+     *            loaded, maybe {@code null}.
+     * @param signers
+     *            the {@code CodeSigner}s of the code, loaded from the specified
+     *            {@code location}. Maybe {@code null}.
+     */
     public CodeSource(URL location, CodeSigner[] signers) {
         this.location = location;
         if (signers != null) {
@@ -89,19 +105,19 @@
         }
     }
 
-	/**
-	 * Compares the argument to the receiver, and answers true if they represent
-	 * the <em>same</em> object using a class specific comparison. In this
-	 * case, the receiver and the object must have the same URL and the same
-	 * collection of certificates.
-	 * 
-	 * 
-	 * @param obj
-	 *            the object to compare with this object
-	 * @return <code>true</code> if the object is the same as this object
-	 *         <code>false</code> if it is different from this object
-	 * @see #hashCode
-	 */
+    /**
+     * Compares the specified object with this {@code CodeSource} for equality.
+     * Returns {@code true} if the specified object is also an instance of
+     * {@code CodeSource}, points to the same {@code URL} location and the two
+     * code sources encapsulate the same {@code Certificate}s. The order of the
+     * {@code Certificate}s is ignored by this method.
+     *
+     * @param obj
+     *            object to be compared for equality with this {@code
+     *            CodeSource}.
+     * @return {@code true} if the specified object is equal to this {@code
+     *         CodeSource}, otherwise {@code false}.
+     */
     public boolean equals(Object obj) {
         if (obj == this) {
             return true;
@@ -137,12 +153,17 @@
         return true;
     }
 
-	/**
-	 * Answers the certificates held onto by the receiver.
-	 * 
-	 * 
-	 * @return Certificate[] the receiver's certificates
-	 */
+    /**
+     * Returns the certificates of this {@code CodeSource}. If the
+     * {@link #CodeSource(URL, CodeSigner[])} constructor was used to create
+     * this instance, the certificates are obtained from the supplied signers.
+     * <p>
+     * External modifications of the returned {@code Certificate[]} has no
+     * impact on this {@code CodeSource}.
+     *
+     * @return the certificates of this {@code CodeSource} or {@code null} if
+     *         there is none.
+     */
     public final Certificate[] getCertificates() {
         getCertificatesNoClone();
         if (certs == null) {
@@ -176,6 +197,15 @@
         return certs;
     }
 
+    /**
+     * Returns the {@code CodeSigner}s of this {@code CodeSource}. If the
+     * {@link #CodeSource(URL, Certificate[])} constructor was used to create
+     * this instance, the signers are obtained from the supplied certificates.
+     * Only X.509 certificates are analyzed.
+     *
+     * @return the signers of this {@code CodeSource}, or {@code null} if there
+     *         is none.
+     */
     public final CodeSigner[] getCodeSigners() {
         if (signers != null) {
             CodeSigner[] tmp = new CodeSigner[signers.length];
@@ -264,26 +294,25 @@
         return null;
     }
 
-	/**
-	 * Answers the receiver's location.
-	 * 
-	 * 
-	 * @return URL the receiver's URL
-	 */
+    /**
+     * Returns the location of this {@code CodeSource}.
+     *
+     * @return the location of this {@code CodeSource}, maybe {@code null}.
+     */
     public final URL getLocation() {
         return location;
     }
 
-	/**
-	 * 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 CodeSource}.
+     * Returns the same hash code for {@code CodeSource}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 CodeSource}.
+     * @see Object#equals(Object)
+     * @see CodeSource#equals(Object)
+     */
     public int hashCode() {
         //
         // hashCode() is undocumented there. Should we also use certs[i] to
@@ -292,15 +321,71 @@
         return location == null ? 0 : location.hashCode();
     }
 
-	/**
-	 * Indicates whether the argument code source is implied by the receiver.
-	 * 
-	 * 
-	 * @return boolean <code>true</code> if the argument code source is
-	 *         implied by the receiver, and <code>false</code> if it is not.
-	 * @param cs
-	 *            CodeSource the code source to check
-	 */
+    /**
+     * Indicates whether the specified code source is implied by this {@code
+     * CodeSource}. Returns {@code true} if all of the following conditions are
+     * {@code true}, otherwise {@code false}:
+     * <p>
+     * <ul>
+     * <li>{@code cs} is not {@code null}
+     * <li>if this {@code CodeSource} has associated certificates, all
+     * certificates are present in {@code cs}. The certificates are extracted
+     * from the signers if signers are present.
+     * <li>if this {@code CodeSource}'s location is not {@code null}, the
+     * following conditions are checked
+     * <ul>
+     * <li>this {@code CodeSource}'s location is not {@code null}
+     * <li>this {@code CodeSource}'s location protocol is equal to {@code cs}'s
+     * location protocol
+     * <li>if this {@code CodeSource}'s location host is not {@code null}, the
+     * following conditions are checked
+     * <ul>
+     * <li>{@code cs}'s host is not {@code null}
+     * <li>the {@link SocketPermission} of this {@code CodeSource}'s location
+     * host implies the {@code SocketPermission} of {@code cs}'s location host
+     * </ul>
+     * <li>if this {@code CodeSource}'s location port != -1 the port of {@code
+     * cs}'s location is equal to this {@code CodeSource}'s location port
+     * <li>this {@code CodeSource}'s location file matches {@code cs}'s file
+     * whereas special wildcard matching applies as described below
+     * <li>this {@code CodeSource}'s location reference is equal to to {@code
+     * cs}'s location reference
+     * </ul>
+     * </ul>
+     * <p>
+     * Note: If this {@code CodeSource} has a {@code null} location and not any
+     * certificates, this method returns {@code true}.
+     * <p>
+     * Matching rules for the {@code CodeSource}'s location file:
+     * <ul>
+     * <li>if this {@code CodeSource}'s location file ends with {@code "/-"},
+     * then {@code cs}'s file must start with {@code CodeSource}'s location file
+     * (exclusive the trailing '-')
+     * <li>if this {@code CodeSource}'s location file ends with {@code "/*"},
+     * then {@code cs}'s file must start with {@code CodeSource}'s location file
+     * (exclusive the trailing '*') and must not have any further '/'
+     * <li>if this {@code CodeSource}'s location file ends with {@code "/"},
+     * then {@code cs}'s file must start with {@code CodeSource}'s location file
+     * <li>if this {@code CodeSource}'s location file does not end with {@code
+     * "/"}, then {@code cs}'s file must start with {@code CodeSource}'s
+     * location file with the '/' appended to it.
+     * </ul>
+     * Examples for locations that imply the location
+     * "http://harmony.apache.org/milestones/M9/apache-harmony.jar":
+     *
+     * <pre>
+     * http:
+     * http://&#42;/milestones/M9/*
+     * http://*.apache.org/milestones/M9/*
+     * http://harmony.apache.org/milestones/-
+     * http://harmony.apache.org/milestones/M9/apache-harmony.jar
+     * </pre>
+     *
+     * @param cs
+     *            the code source to check.
+     * @return {@code true} if the argument code source is implied by this
+     *         {@code CodeSource}, otherwise {@code false}.
+     */
     public boolean implies(CodeSource cs) {
         //
         // Here, javadoc:N refers to the appropriate item in the API spec for 
@@ -447,13 +532,13 @@
         return true;
     }
 
-	/**
-	 * Answers a string containing a concise, human-readable description of the
-	 * receiver.
-	 * 
-	 * 
-	 * @return a printable representation for the receiver.
-	 */
+    /**
+     * Returns a string containing a concise, human-readable description of the
+     * this {@code CodeSource} including its location, its certificates and its
+     * signers.
+     *
+     * @return a printable representation for this {@code CodeSource}.
+     */
     public String toString() {
         StringBuilder buf = new StringBuilder();
         buf.append("CodeSource, url="); //$NON-NLS-1$

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/DigestException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/DigestException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/DigestException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/DigestException.java Tue Apr 28 17:01:41 2009
@@ -15,52 +15,51 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * This class represents exceptions for message digest computation.
- * 
+ *{@code DigestException} is a general message digest exception.
  */
 public class DigestException extends GeneralSecurityException {
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private static final long serialVersionUID = 5821450303093652515L;
 
-	/**
-	 * 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 DigestException} with the
+     * given message.
+     *
+     * @param msg
+     *            the detail message for this exception.
+     */
     public DigestException(String msg) {
         super(msg);
     }
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 * 
-	 */
+    /**
+     * Constructs a new instance of {@code DigestException}.
+     */
     public DigestException() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code DigestException} 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 DigestException(String message, Throwable cause) {
         super(message, cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code DigestException} with the
+     * cause.
+     *
+     * @param cause
+     *            the exception which is the cause for this exception.
      */
     public DigestException(Throwable cause) {
         super(cause);

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/DigestInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/DigestInputStream.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/DigestInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/DigestInputStream.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.FilterInputStream;
@@ -27,13 +22,13 @@
 import java.io.InputStream;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * {@code DigestInputStream} is a {@code FilterInputStream} which maintains an
+ * associated message digest.
  */
 public class DigestInputStream extends FilterInputStream {
 
     /**
-     * @com.intel.drl.spec_ref
+     * The message digest for this stream.
      */
     protected MessageDigest digest;
 
@@ -41,51 +36,48 @@
     private boolean isOn = true;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of this {@code DigestInputStream}, using the
+     * given {@code stream} and the {@code digest}.
+     *
+     * @param stream
+     *            the input stream.
+     * @param digest
+     *            the message digest.
      */
     public DigestInputStream(InputStream stream, MessageDigest digest) {
         super(stream);
         this.digest = digest;
     }
 
-	/**
-	 * Answers the MessageDigest which the receiver uses when computing the
-	 * hash.
-	 * 
-	 * 
-	 * @return MessageDigest the digest the receiver uses when computing the
-	 *         hash.
-	 * 
-	 */
+    /**
+     * Returns the message digest for this stream.
+     *
+     * @return the message digest for this stream.
+     */
     public MessageDigest getMessageDigest() {
         return digest;
     }
 
-	/**
-	 * Sets the MessageDigest which the receiver will use when computing the
-	 * hash.
-	 * 
-	 * 
-	 * @param digest
-	 *            MessageDigest the digest to use when computing the hash.
-	 * 
-	 * @see MessageDigest
-	 * @see #on
-	 */
+    /**
+     * Sets the message digest which this stream will use.
+     *
+     * @param digest
+     *            the message digest which this stream will use.
+     */
     public void setMessageDigest(MessageDigest digest) {
         this.digest = digest;
     }
 
-	/**
-	 * Reads the next byte and answers it as an int. Updates the digest for the
-	 * byte if this function is enabled.
-	 * 
-	 * 
-	 * @return int the byte which was read or -1 at end of stream.
-	 * 
-	 * @exception java.io.IOException
-	 *                If reading the source stream causes an IOException.
-	 */
+    /**
+     * Reads the next byte and returns it as an {@code int}. Updates the digest
+     * for the byte if this function is {@link #on(boolean)}.
+     * <p>
+     * This operation is blocking.
+     *
+     * @return the byte which was read or -1 at end of stream.
+     * @throws IOException
+     *             if reading the source stream causes an {@code IOException}.
+     */
     public int read() throws IOException {
         // read the next byte
         int byteRead = in.read();
@@ -100,7 +92,23 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Reads {@code len} bytes into the specified {@code byte[]}, starting from
+     * the specified offset. Updates the digest if this function is
+     * {@link #on(boolean)}.
+     * <p>
+     * This operation is blocking.
+     *
+     * @param b
+     *            the byte array in which to store the bytes
+     * @param off
+     *            the initial position in {@code b} to store the bytes read from
+     *            this stream
+     * @param len
+     *            the maximum number of bytes to store in {@code b}
+     * @return the number of bytes actually read or -1 if the end of the
+     *         filtered stream has been reached while reading
+     * @throws IOException
+     *             if reading the source stream causes an {@code IOException}
      */
     public int read(byte[] b, int off, int len) throws IOException {
         // read next up to len bytes
@@ -115,27 +123,24 @@
         return bytesRead;
     }
 
-	/**
-	 * Enables or disables the digest function (default is on).
-	 * 
-	 * 
-	 * @param on
-	 *            boolean true if the digest should be computed, and false
-	 *            otherwise.
-	 * 
+    /**
+     * Enables or disables the digest function (default is on).
+     *
+     * @param on
+     *            {@code true} if the digest should be computed, {@code false}
+     *            otherwise.
 	 * @see MessageDigest
-	 */
+     */
     public void on(boolean on) {
         isOn = on;
     }
 
-	/**
-	 * 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 this
+     * {@code DigestInputStream} including the digest.
+     *
+     * @return a printable representation for this {@code DigestInputStream}.
+     */
     public String toString() {
         return super.toString() + ", " + digest.toString() + //$NON-NLS-1$
             (isOn ? ", is on" : ", is off"); //$NON-NLS-1$ //$NON-NLS-2$

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/DigestOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/DigestOutputStream.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/DigestOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/DigestOutputStream.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.FilterOutputStream;
@@ -27,13 +22,13 @@
 import java.io.OutputStream;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * {@code DigestOutputStream} is a {@code FilterOutputStream} which maintains an
+ * associated message digest.
  */
 public class DigestOutputStream extends FilterOutputStream {
 
     /**
-     * @com.intel.drl.spec_ref
+     * The message digest for this stream.
      */
     protected MessageDigest digest;
 
@@ -41,43 +36,46 @@
     private boolean isOn = true;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of this {@code DigestOutputStream}, using the
+     * given {@code stream} and the {@code digest}.
+     *
+     * @param stream
+     *            the output stream.
+     * @param digest
+     *            the message digest.
      */
     public DigestOutputStream(OutputStream stream, MessageDigest digest) {
         super(stream);
         this.digest = digest;
     }
 
-	/**
-	 * Answers the MessageDigest which the receiver uses when computing the
-	 * hash.
-	 * 
-	 * 
-	 * @return MessageDigest the digest the receiver uses when computing the
-	 *         hash.
-	 */
-
+    /**
+     * Returns the message digest for this stream.
+     *
+     * @return the message digest for this stream.
+     */
     public MessageDigest getMessageDigest() {
         return digest;
     }
 
-	/**
-	 * Sets the MessageDigest which the receiver will use when computing the
-	 * hash.
-	 * 
-	 * 
-	 * @param digest
-	 *            MessageDigest the digest to use when computing the hash.
-	 * 
-	 * @see MessageDigest
-	 * @see #on
-	 */
+    /**
+     * Sets the message digest which this stream will use.
+     *
+     * @param digest
+     *            the message digest which this stream will use.
+     */
     public void setMessageDigest(MessageDigest digest) {
         this.digest = digest;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Writes the specified {@code int} to the stream. Updates the digest if
+     * this function is {@link #on(boolean)}.
+     *
+     * @param b
+     *            the byte to be written.
+     * @throws IOException
+     *             if writing to the stream causes a {@code IOException}
      */
     public void write(int b) throws IOException {
         // update digest only if digest functionality is on
@@ -89,7 +87,17 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Writes {@code len} bytes into the stream, starting from the specified
+     * offset. Updates the digest if this function is {@link #on(boolean)}.
+     *
+     * @param b
+     *            the buffer to write to.
+     * @param off
+     *            the index of the first byte in {@code b} to write.
+     * @param len
+     *            the number of bytes in {@code b} to write.
+     * @throws IOException
+     *             if writing to the stream causes an {@code IOException}.
      */
     public void write(byte[] b, int off, int len) throws IOException {
         // update digest only if digest functionality is on
@@ -100,27 +108,24 @@
         out.write(b, off, len);
     }
 
-	/**
-	 * Enables or disables the digest function (default is on).
-	 * 
-	 * 
-	 * @param on
-	 *            boolean true if the digest should be computed, and false
-	 *            otherwise.
-	 * 
+    /**
+     * Enables or disables the digest function (default is on).
+     *
+     * @param on
+     *            {@code true} if the digest should be computed, {@code false}
+     *            otherwise.
 	 * @see MessageDigest
-	 */
+     */
     public void on(boolean on) {
         isOn = on;
     }
 
-	/**
-	 * 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 this
+     * {@code DigestOutputStream} including the digest.
+     *
+     * @return a printable representation for this {@code DigestOutputStream}.
+     */
     public String toString() {
         return super.toString() + ", " + digest.toString() + //$NON-NLS-1$
             (isOn ? ", is on" : ", is off"); //$NON-NLS-1$ //$NON-NLS-2$

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/DomainCombiner.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/DomainCombiner.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/DomainCombiner.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/DomainCombiner.java Tue Apr 28 17:01:41 2009
@@ -15,21 +15,32 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexander V. Astapchuk
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * A DomainCombiner is a way to update the protection domains from an
- * AccessControlContext
+ * {@code DomainCombiner} is used to update and optimize {@code
+ * ProtectionDomain}s from an {@code AccessControlContext}.
  * 
+ * @see AccessControlContext
+ * @see AccessControlContext#AccessControlContext(AccessControlContext,
+ *      DomainCombiner)
  */
 public interface DomainCombiner {
+
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a combination of the two provided {@code ProtectionDomain}
+     * arrays. Implementers can simply merge the two arrays into one, remove
+     * duplicates and perform other optimizations.
+     *
+     * @param current
+     *            the protection domains of the current execution thread (since
+     *            the most recent call to {@link AccessController#doPrivileged}
+     *            ).
+     * @param assigned
+     *            the protection domains of the parent thread, maybe {@code
+     *            null}.
+     * @return a single {@code ProtectionDomain} array computed from the two
+     *         provided arrays.
      */
     ProtectionDomain[] combine(ProtectionDomain[] current,
             ProtectionDomain[] assigned);

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/GeneralSecurityException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/GeneralSecurityException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/GeneralSecurityException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/GeneralSecurityException.java Tue Apr 28 17:01:41 2009
@@ -15,52 +15,52 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * This class represents the general security exception. Subclasses will
- * represents specific security problems.
- * 
+ * {@code GeneralSecurityException} is a general security exception and the
+ * superclass for all security specific exceptions.
  */
 public class GeneralSecurityException extends Exception {
-    /**
-     * @com.intel.drl.spec_ref
-     */
+
     private static final long serialVersionUID = 894798122053539237L;
 
-	/**
-	 * 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 GeneralSecurityException} with the
+     * given message.
+     *
+     * @param msg
+     *            the detail message for this exception.
+     */
     public GeneralSecurityException(String msg) {
         super(msg);
     }
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 * 
-	 */
+    /**
+     * Constructs a new instance of {@code GeneralSecurityException}.
+     */
     public GeneralSecurityException() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code GeneralSecurityException} 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 GeneralSecurityException(String message, Throwable cause) {
         super(message, cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code GeneralSecurityException} with the
+     * cause.
+     *
+     * @param cause
+     *            the exception which is the cause for this exception.
      */
     public GeneralSecurityException(Throwable cause) {
         super(cause);

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Guard.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Guard.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Guard.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Guard.java Tue Apr 28 17:01:41 2009
@@ -15,22 +15,22 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexey V. Varlamov
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * This interface is implemented by objects which wish to control access to
- * other objects.
- * 
+ * {@code Guard} implementors protect access to other objects.
  */
 public interface Guard {
 
-    /** 
-     * @com.intel.drl.spec_ref 
+    /**
+     * Checks whether access to the specified {@code Object} should be granted.
+     * This method returns silently if access is granted, otherwise a {@code
+     * SecurityException} is thrown.
+     *
+     * @param object
+     *            the object to be protected by this {@code Guard}.
+     * @throws SecurityException
+     *             if access is not granted.
      */
     public void checkGuard(Object object) throws SecurityException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/GuardedObject.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/GuardedObject.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/GuardedObject.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/GuardedObject.java Tue Apr 28 17:01:41 2009
@@ -15,63 +15,47 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexey V. Varlamov
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.io.IOException;
 import java.io.Serializable;
 
 /**
- * GuardedObject controls access to an object, by checking all requests for the
- * object with a Guard.
- * 
+ * {@code GuardedObject} controls access to an object, by checking all requests
+ * for the object with a {@code Guard}.
  */
 public class GuardedObject implements Serializable {
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private static final long serialVersionUID = -5240450096227834308L;
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private final Object object;
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private final Guard guard;
 
-	/**
-	 * Constructs a GuardedObject to protect access to the specified Object
-	 * using the specified Guard.
-	 * 
-	 * @param object
-	 *            the Object to guard
-	 * @param guard
-	 *            the Guard
-	 */
+    /**
+     * Constructs a new instance of {@code GuardedObject} which protects access
+     * to the specified {@code Object} using the specified {@code Guard}.
+     *
+     * @param object
+     *            the {@code Object} to protect.
+     * @param guard
+     *            the {@code Guard} which protects the specified {@code Object},
+     *            maybe {@code null}.
+     */
     public GuardedObject(Object object, Guard guard) {
         this.object = object;
         this.guard = guard;
     }
 
-	/**
-	 * Checks whether access should be granted to the object. If access is
-	 * granted, this method returns the object. If it is not granted, then a
-	 * <code>SecurityException</code> is thrown.
-	 * 
-	 * 
-	 * @return the guarded object
-	 * 
-	 * @exception java.lang.SecurityException
-	 *                If access is not granted to the object
-	 */
+    /**
+     * Returns the guarded {@code Object} if the associated {@code Guard}
+     * permits access. If access is not granted, then a {@code
+     * SecurityException} is thrown.
+     *
+     * @return the guarded object.
+     * @exception SecurityException
+     *                if access is not granted to the guarded object.
+     */
     public Object getObject() throws SecurityException {
         if (guard != null) {
             guard.checkGuard(object);
@@ -79,8 +63,9 @@
         return object;
     }
 
-    /** 
-     * Checks guard (if there is one) before performing a default serialization. 
+    /**
+     * Checks the guard (if there is one) before performing a default
+     * serialization.
      */
     private void writeObject(java.io.ObjectOutputStream out) throws IOException {
         if (guard != null) {

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Identity.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Identity.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Identity.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Identity.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexander V. Astapchuk
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.io.Serializable;
@@ -29,8 +24,11 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * 
- * @deprecated
+ * {@code Identity} represents an identity like a person or a company.
+ *
+ * @deprecated The functionality of this class has been replace by
+ *             {@link Principal}, {@link KeyStore} and the {@code
+ *             java.security.cert} package.
  */
 @Deprecated
 public abstract class Identity implements Principal, Serializable {
@@ -46,13 +44,34 @@
 
     private Vector<Certificate> certificates;
 
+    /**
+     * Constructs a new instance of {@code Identity}.
+     */
     protected Identity() {
     }
 
+    /**
+     * Creates a new instance of {@code Identity} with the specified name.
+     *
+     * @param name
+     *            the name of this {@code Identity}.
+     */
     public Identity(String name) {
         this.name = name;
     }
 
+    /**
+     * Creates a new instance of {@code Identity} with the specified name and
+     * the scope of this {@code Identity}.
+     *
+     * @param name
+     *            the name of this {@code Identity}.
+     * @param scope
+     *            the {@code IdentityScope} of this {@code Identity}.
+     * @throws KeyManagementException
+     *             if an {@code Identity} with the same name is already present
+     *             in the specified scope.
+     */
     public Identity(String name, IdentityScope scope)
             throws KeyManagementException {
         this(name);
@@ -62,6 +81,21 @@
         }
     }
 
+    /**
+     * Adds a {@code Certificate} to this {@code Identity}.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code addIdentityCertificate} to be
+     * granted, otherwise a {@code SecurityException} will be thrown.
+     *
+     * @param certificate
+     *            the {@code Certificate} to be added to this {@code Identity}.
+     * @throws KeyManagementException
+     *             if the certificate is not valid.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
+     */
     public void addCertificate(Certificate certificate)
             throws KeyManagementException {
         SecurityManager sm = System.getSecurityManager();
@@ -106,6 +140,22 @@
 
       
 
+    /**
+     * Removes the specified {@code Certificate} from this {@code Identity}.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code "removeIdentityCertificate"} to be
+     * granted, otherwise a {@code SecurityException} will be thrown.
+     * <p>
+     *
+     * @param certificate
+     *            the {@code Certificate} to be removed.
+     * @throws KeyManagementException
+     *             if the certificate is not found.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
+     */
     public void removeCertificate(Certificate certificate)
             throws KeyManagementException {
         SecurityManager sm = System.getSecurityManager();
@@ -120,6 +170,13 @@
 
       
 
+    /**
+     * Returns the certificates for this {@code Identity}. External
+     * modifications of the returned array has no impact on this {@code
+     * Identity}.
+     *
+     * @return the {@code Certificates} for this {@code Identity}
+     */
     public Certificate[] certificates() {
         if (certificates == null) {
             return new Certificate[0];
@@ -132,6 +189,19 @@
 
       
 
+    /**
+     * Compares the specified {@code Identity} with this {@code Identity} for
+     * equality and returns {@code true} if the specified object is equal,
+     * {@code false} otherwise.
+     * <p>
+     * To be equal, two {@code Identity} objects need to have the same name and
+     * the same public keys.
+     *
+     * @param identity
+     *            the identity to check for equality.
+     * @return {@code true} if the {@code Identity} objects are equal, {@code
+     *         false} otherwise.
+     */
     protected boolean identityEquals(Identity identity) {
         if (!name.equals(identity.name)) {
             return false;
@@ -147,6 +217,14 @@
 
       
 
+    /**
+     * Returns a string containing a concise, human-readable description of the
+     * this {@code Identity}.
+     *
+     * @param detailed
+     *            whether or not this method should return detailed information.
+     * @return a printable representation for this {@code Permission}.
+     */
     public String toString(boolean detailed) {
         String s = toString();
         if (detailed) {
@@ -158,6 +236,11 @@
 
       
 
+    /**
+     * Returns the {@code IdentityScope} of this {@code Identity}.
+     *
+     * @return the {@code IdentityScope} of this {@code Identity}.
+     */
     public final IdentityScope getScope() {
         return scope;
     }
@@ -165,6 +248,22 @@
 
       
 
+    /**
+     * Sets the specified {@code PublicKey} to this {@code Identity}.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code setIdentityPublicKey} to be
+     * granted, otherwise a {@code SecurityException} will be thrown.
+     *
+     * @param key
+     *            the {@code PublicKey} to be set.
+     * @throws KeyManagementException
+     *             if another {@code Identity} in the same scope as this {@code
+     *             Identity} already has the same {@code PublicKey}.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
+     */
     public void setPublicKey(PublicKey key) throws KeyManagementException {
         SecurityManager sm = System.getSecurityManager();
         if (sm != null) {
@@ -185,6 +284,11 @@
 
       
 
+    /**
+     * Returns the {@code PublicKey} associated with this {@code Identity}.
+     *
+     * @return the {@code PublicKey} associated with this {@code Identity}.
+     */
     public PublicKey getPublicKey() {
         return publicKey;
     }
@@ -192,6 +296,19 @@
 
       
 
+    /**
+     * Sets an information string for this {@code Identity}.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code setIdentityInfo} to be granted,
+     * otherwise a {@code SecurityException} will be thrown.
+     *
+     * @param info
+     *            the information to be set.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
+     */
     public void setInfo(String info) {
         SecurityManager sm = System.getSecurityManager();
         if (sm != null) {
@@ -203,6 +320,11 @@
 
       
 
+    /**
+     * Returns the information string of this {@code Identity}.
+     *
+     * @return the information string of this {@code Identity}.
+     */
     public String getInfo() {
         return info;
     }
@@ -210,6 +332,18 @@
 
       
 
+    /**
+     * Compares the specified object with this {@code Identity} for equality and
+     * returns {@code true} if the specified object is equal, {@code false}
+     * otherwise. {@code Identity} objects are considered equal, if they have
+     * the same name and are in the same scope.
+     *
+     * @param obj
+     *            object to be compared for equality with this {@code
+     *            Identity}.
+     * @return {@code true} if the specified object is equal to this {@code
+     *         Identity}, otherwise {@code false}.
+     */
     public final boolean equals(Object obj) {
         if (this == obj) {
             return true;
@@ -228,6 +362,11 @@
 
       
 
+    /**
+     * Returns the name of this {@code Identity}.
+     *
+     * @return the name of this {@code Identity}.
+     */
     public final String getName() {
         return name;
     }
@@ -235,6 +374,15 @@
 
       
 
+    /**
+     * Returns the hash code value for this {@code Identity}. Returns the same
+     * hash code for {@code Identity}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 Identity}.
+     * @see Object#equals(Object)
+     * @see Identity#equals(Object)
+     */
     public int hashCode() {
         int hash = 0;
         if (name != null) {
@@ -249,6 +397,19 @@
 
       
 
+    /**
+     * Returns a string containing a concise, human-readable description of the
+     * this {@code Identity} including its name and its scope.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method
+     * needs the {@code SecurityPermission} {@code printIdentity} to be granted,
+     * otherwise a {@code SecurityException} will be thrown.
+     *
+     * @return a printable representation for this {@code Identity}.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
+     */
     public String toString() {
         SecurityManager sm = System.getSecurityManager();
         if (sm != null) {

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/IdentityScope.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/IdentityScope.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/IdentityScope.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/IdentityScope.java Tue Apr 28 17:01:41 2009
@@ -15,47 +15,54 @@
  *  limitations under the License.
  */
 
-/**
-* @author Aleksei Y. Semenov
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.util.Enumeration;
 
 
 /**
- * @com.intel.drl.spec_ref 
- * @deprecated
+ * {@code IdentityScope} represents a scope for {@link Identity} objects.
+ *
+ * @deprecated The functionality of this class has been replace by
+ *             {@link Principal}, {@link KeyStore} and the {@code
+ *             java.security.cert} package.
  */
 @Deprecated
 public abstract class IdentityScope extends Identity {
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private static final long serialVersionUID = -2337346281189773310L;
 
     // systemScope holds reference to the current system scope
     private static IdentityScope systemScope;
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Constructs a new instance of {@code IdentityScope}.
      */
     protected IdentityScope() {
         super();
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Constructs a new instance of {@code IdentityScope} with the specified
+     * name.
+     *
+     * @param name
+     *            the name of this {@code IdentityScope}.
      */
     public IdentityScope(String name) {
         super(name);
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Constructs a new instance of {@code IdentityScope} with the specified
+     * name and the specified scope.
+     *
+     * @param name
+     *            the name of this {@code IdentityScope}.
+     * @param scope
+     *            the scope of this {@code IdentityScope}.
+     * @throws KeyManagementException
+     *             if an identity with the same key already exists.
      */
     public IdentityScope(String name, IdentityScope scope)
             throws KeyManagementException {
@@ -63,7 +70,9 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Returns the system's scope.
+     *
+     * @return the system's scope.
      */
     public static IdentityScope getSystemScope() {
         /* 
@@ -89,7 +98,10 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Sets the system's scope.
+     *
+     * @param scope
+     *            the scope to set.
      */
     protected static void setSystemScope(IdentityScope scope) {
         SecurityManager sm = System.getSecurityManager();
@@ -100,46 +112,87 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Returns the number of {@code Identity} objects in this scope.
+     *
+     * @return the number of {@code Identity} objects in this scope.
      */
     public abstract int size();
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Returns the {@code Identity} with the specified name or {@code null} if
+     * no {@code Identity} with the specified name is present in this scope.
+     *
+     * @param name
+     *            the name of the {@code Identity} to be returned.
+     * @return the {@code Identity} with the specified name or {@code null} if
+     *         not present.
      */
     public abstract Identity getIdentity(String name);
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Returns the {@code Identity} with the name of the specified principal or
+     * {@code null} if no {@code Identity} with the name of the specified
+     * principal is present in this scope.
+     *
+     * @param principal
+     *            the {@code Principal} whose name is used to lookup the {@code
+     *            Identity} to be returned.
+     * @return the {@code Identity} with the specified name or {@code null} if
+     *         not present.
      */
     public Identity getIdentity(Principal principal) {
         return getIdentity(principal.getName());
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Returns the {@code Identity} which is associated with the specified key
+     * or {@code null} if no {@code Identity} associated with the specified key
+     * is present in this scope.
+     *
+     * @param key
+     *            the {@code PublicKey} of the {@code Identity} to be returned.
+     * @return the {@code Identity} associated with the specified key or {@code
+     *         null} if not present.
      */
     public abstract Identity getIdentity(PublicKey key);
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Adds an {@code Identity} to this {@code IdentityScope}.
+     *
+     * @param identity
+     *            the {@code Identity} to be added.
+     * @throws KeyManagementException
+     *             if the specified {@code Identity} is invalid or an identity
+     *             with the same key already exists.
      */
     public abstract void addIdentity(Identity identity)
             throws KeyManagementException;
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Removes an {@code Identity} from this {@code IdentityScope}.
+     *
+     * @param identity
+     *            the {@code Identity} to be removed.
+     * @throws KeyManagementException
+     *             if the {@code Identity} is not present in this scope.
      */
     public abstract void removeIdentity(Identity identity)
             throws KeyManagementException;
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Returns an {@code Enumeration} over the {@code Identity} objects in this
+     * {@code IdentityScope}.
+     *
+     * @return an {@code Enumeration} over the {@code Identity} objects in this
+     *         {@code IdentityScope}.
      */
     public abstract Enumeration<Identity> identities();
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Returns a string containing a concise, human-readable description of this
+     * {@code IdentityScope}.
+     *
+     * @return a printable representation for this {@code IdentityScope}.
      */
     public String toString() {
         return new StringBuffer(super.toString())

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/InvalidAlgorithmParameterException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/InvalidAlgorithmParameterException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/InvalidAlgorithmParameterException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/InvalidAlgorithmParameterException.java Tue Apr 28 17:01:41 2009
@@ -15,52 +15,53 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * This class represents invalid algorithm parameters to cryptographic services.
- * 
+ * {@code InvalidAlgorithmParameterException} indicates the occurrence of
+ * invalid algorithm parameters.
  */
 public class InvalidAlgorithmParameterException extends
         GeneralSecurityException {
-    /**
-     * @com.intel.drl.spec_ref
-     */
+
     private static final long serialVersionUID = 2864672297499471472L;
 
-	/**
-	 * 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 InvalidAlgorithmParameterException}
+     * with the given message.
+     *
+     * @param msg
+     *            the detail message for this exception.
+     */
     public InvalidAlgorithmParameterException(String msg) {
         super(msg);
     }
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 * 
-	 */
+    /**
+     * Constructs a new instance of {@code InvalidAlgorithmParameterException}.
+     */
     public InvalidAlgorithmParameterException() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code InvalidAlgorithmParameterException} 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 InvalidAlgorithmParameterException(String message, Throwable cause) {
         super(message, cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code InvalidAlgorithmParameterException}
+     * with the cause.
+     *
+     * @param cause
+     *            the exception which is the cause for this exception.
      */
     public InvalidAlgorithmParameterException(Throwable cause) {
         super(cause);

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/InvalidKeyException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/InvalidKeyException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/InvalidKeyException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/InvalidKeyException.java Tue Apr 28 17:01:41 2009
@@ -15,54 +15,51 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * Used when invalid cryptography keys are used.
- * 
- * @see Throwable
- * @see Error
+ * {@code InvalidKeyException} indicates exceptional conditions, caused by an
+ * invalid key.
  */
 public class InvalidKeyException extends KeyException {
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private static final long serialVersionUID = 5698479920593359816L;
 
-	/**
-	 * 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 InvalidKeyException} with the given
+     * message.
+     *
+     * @param msg
+     *            the detail message for this exception.
+     */
     public InvalidKeyException(String msg) {
         super(msg);
     }
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 * 
-	 */
+    /**
+     * Constructs a new instance of {@code InvalidKeyException}.
+     */
     public InvalidKeyException() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code InvalidKeyException} 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 InvalidKeyException(String message, Throwable cause) {
         super(message, cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code InvalidKeyException} with the cause.
+     *
+     * @param cause
+     *            the exception which is the cause for this exception.
      */
     public InvalidKeyException(Throwable cause) {
         super(cause);

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/InvalidParameterException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/InvalidParameterException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/InvalidParameterException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/InvalidParameterException.java Tue Apr 28 17:01:41 2009
@@ -15,40 +15,30 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * This exception is thrown when an invalid parameter is passed to a method.
- * 
+ * {@code InvalidParameterException} indicates exceptional conditions, caused by
+ * invalid parameters.
  */
 public class InvalidParameterException extends IllegalArgumentException {
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private static final long serialVersionUID = -857968536935667808L;
 
-	/**
-	 * 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 InvalidParameterException} with the
+     * given message.
+     *
+     * @param msg
+     *            the detail message for this exception.
+     */
     public InvalidParameterException(String msg) {
         super(msg);
     }
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 * 
-	 */
+    /**
+     * Constructs a new instance of {@code InvalidParameterException}.
+     */
     public InvalidParameterException() {
     }
 }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Key.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Key.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Key.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Key.java Tue Apr 28 17:01:41 2009
@@ -15,46 +15,46 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.io.Serializable;
 
 /**
- * Defines the basic properties of all key objects.
+ * {@code Key} is the common interface for all keys.
  * 
  * @see PublicKey
+ * @see PrivateKey
  */
 public interface Key extends Serializable {
     /**
-     * @com.intel.drl.spec_ref
+     * The {@code serialVersionUID} to be compatible with JDK1.1.
      */
     public static final long serialVersionUID = 6603384152749567654L;
 
     /**
-     * Answers the name of the algorithm that this key will work
-     * with. If the algorithm is unknown, it answers null.
+     * Returns the name of the algorithm of this key. If the algorithm is
+     * unknown, {@code null} is returned.
      * 
-     * @return String the receiver's algorithm
+     * @return the name of the algorithm of this key or {@code null} if the
+     *         algorithm is unknown.
      */
     public String getAlgorithm();
 
     /**
-     * Answers the name of the format used to encode the key, or null
+     * Returns the name of the format used to encode this key, or {@code null}
      * if it can not be encoded.
      * 
-     * @return String the receiver's encoding format
+     * @return the name of the format used to encode this key, or {@code null}
+     *         if it can not be encoded.
      */
     public String getFormat();
 
     /**
-     * Answers the encoded form of the receiver.
+     * Returns the encoded form of this key, or {@code null} if encoding is not
+     * supported by this key.
      * 
-     * @return byte[] the encoded form of the receiver
+     * @return the encoded form of this key, or {@code null} if encoding is not
+     *         supported by this key.
      */
     public byte[] getEncoded();
 }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyException.java Tue Apr 28 17:01:41 2009
@@ -15,56 +15,49 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * This class is the superclass of all classes which represent problems with
- * keys.
- * 
- * 
- * @see Throwable
- * @see Error
+ * {@code KeyException} is the common superclass of all key related exceptions.
  */
 public class KeyException extends GeneralSecurityException {
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private static final long serialVersionUID = -7483676942812432108L;
 
-	/**
-	 * 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 KeyException} with the given message.
+     *
+     * @param msg
+     *            the detail message for this exception.
+     */
     public KeyException(String msg) {
         super(msg);
     }
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 * 
-	 */
+    /**
+     * Constructs a new instance of {@code KeyException}.
+     */
     public KeyException() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code KeyException} 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 KeyException(String message, Throwable cause) {
         super(message, cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code KeyException} with the cause.
+     *
+     * @param cause
+     *            the exception which is the cause for this exception.
      */
     public KeyException(Throwable cause) {
         super(cause);

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyFactory.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyFactory.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyFactory.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.security.spec.InvalidKeySpecException;
@@ -28,12 +23,12 @@
 import org.apache.harmony.security.fortress.Engine;
 import org.apache.harmony.security.internal.nls.Messages;
 
-
 /**
- * @com.intel.drl.spec_ref
- * 
+ * {@code KeyFactory} is an engine class that can be used to translate between
+ * public and private key objects and convert keys between their external
+ * representation, that can be easily transported and their internal
+ * representation.
  */
-
 public class KeyFactory {
     // The service name.
     private static final String SERVICE = "KeyFactory"; //$NON-NLS-1$
@@ -52,8 +47,15 @@
     private String algorithm;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code KeyFactory} with the specified
+     * arguments.
      * 
+     * @param keyFacSpi
+     *            the concrete key factory service.
+     * @param provider
+     *            the provider.
+     * @param algorithm
+     *            the algorithm to use.
      */
     protected KeyFactory(KeyFactorySpi keyFacSpi, 
                          Provider provider,
@@ -64,8 +66,15 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a new instance of {@code KeyFactory} that utilizes the specified
+     * algorithm.
      * 
+     * @param algorithm
+     *            the name of the algorithm.
+     * @return a new instance of {@code KeyFactory} that utilizes the specified
+     *         algorithm.
+     * @throws NoSuchAlgorithmException
+     *             if no provider provides the requested algorithm.
      */
     public static KeyFactory getInstance(String algorithm)
                                 throws NoSuchAlgorithmException {
@@ -79,8 +88,21 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a new instance of {@code KeyFactory} that utilizes the specified
+     * algorithm from the specified provider.
      * 
+     * @param algorithm
+     *            the name of the algorithm.
+     * @param provider
+     *            the name of the provider.
+     * @return a new instance of {@code KeyFactory} that utilizes the specified
+     *         algorithm from the specified provider.
+     * @throws NoSuchAlgorithmException
+     *             if the provider does not provide the requested algorithm.
+     * @throws NoSuchProviderException
+     *             if the requested provider is not available.
+     * @throws IllegalArgumentException
+     *             if {@code provider} is {@code null} or empty.
      */
     public static KeyFactory getInstance(String algorithm, String provider)
                                 throws NoSuchAlgorithmException, NoSuchProviderException {
@@ -95,8 +117,17 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a new instance of {@code KeyFactory} that utilizes the specified
+     * algorithm from the specified provider.
      * 
+     * @param algorithm
+     *            the name of the algorithm.
+     * @param provider
+     *            the security provider.
+     * @return a new instance of {@code KeyFactory} that utilizes the specified
+     *         algorithm from the specified provider.
+     * @throws NoSuchAlgorithmException
+     *             if the provider does not provide the requested algorithm.
      */
     public static KeyFactory getInstance(String algorithm, Provider provider)
                                  throws NoSuchAlgorithmException {
@@ -113,24 +144,34 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the provider associated with this {@code KeyFactory}.
      * 
+     * @return the provider associated with this {@code KeyFactory}.
      */
     public final Provider getProvider() {
         return provider;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the name of the algorithm associated with this {@code
+     * KeyFactory}.
      * 
+     * @return the name of the algorithm associated with this {@code
+     *         KeyFactory}.
      */
     public final String getAlgorithm() {
         return algorithm;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Generates a instance of {@code PublicKey} from the given key
+     * specification.
      * 
+     * @param keySpec
+     *            the specification of the public key
+     * @return the public key
+     * @throws InvalidKeySpecException
+     *             if the specified {@code keySpec} is invalid
      */
     public final PublicKey generatePublic(KeySpec keySpec)
                                 throws InvalidKeySpecException {
@@ -138,8 +179,14 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Generates a instance of {@code PrivateKey} from the given key
+     * specification.
      * 
+     * @param keySpec
+     *            the specification of the private key.
+     * @return the private key.
+     * @throws InvalidKeySpecException
+     *             if the specified {@code keySpec} is invalid.
      */
     public final PrivateKey generatePrivate(KeySpec keySpec)
                                 throws InvalidKeySpecException {
@@ -147,8 +194,16 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the key specification for the specified key.
      * 
+     * @param key
+     *            the key from which the specification is requested.
+     * @param keySpec
+     *            the type of the requested {@code KeySpec}.
+     * @return the key specification for the specified key.
+     * @throws InvalidKeySpecException
+     *             if the key can not be processed, or the requested requested
+     *             {@code KeySpec} is inappropriate for the given key.
      */
     public final <T extends KeySpec> T getKeySpec(Key key,
                                     Class<T> keySpec)
@@ -157,8 +212,14 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Translates the given key into a key from this key factory.
      * 
+     * @param key
+     *            the key to translate.
+     * @return the translated key.
+     * @throws InvalidKeyException
+     *             if the specified key can not be translated by this key
+     *             factory.
      */
     public final Key translateKey(Key key)
                         throws InvalidKeyException {

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyFactorySpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyFactorySpi.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyFactorySpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyFactorySpi.java Tue Apr 28 17:01:41 2009
@@ -15,49 +15,70 @@
  *  limitations under the License.
  */
 
-/**
-* @author Boris V. Kuznetsov
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.security.spec.InvalidKeySpecException;
 import java.security.spec.KeySpec;
 
-
 /**
- * @com.intel.drl.spec_ref
+ * {@code KeyFactorySpi} is the Service Provider Interface (SPI) definition for
+ * {@link KeyFactory}.
  * 
+ * @see KeyFactory
  */
-
 public abstract class KeyFactorySpi {
     
     /**
-     * @com.intel.drl.spec_ref
+     * Generates a instance of {@code PublicKey} from the given key
+     * specification.
      * 
+     * @param keySpec
+     *            the specification of the public key.
+     * @return the public key.
+     * @throws InvalidKeySpecException
+     *             if the specified {@code keySpec} is invalid.
      */
     protected abstract PublicKey engineGeneratePublic(KeySpec keySpec) 
                                     throws InvalidKeySpecException;
     
     /**
-     * @com.intel.drl.spec_ref
+     * Generates a instance of {@code PrivateKey} from the given key
+     * specification.
      * 
+     * @param keySpec
+     *            the specification of the private key.
+     * @return the private key.
+     * @throws InvalidKeySpecException
+     *             if the specified {@code keySpec} is invalid.
      */
     protected abstract PrivateKey engineGeneratePrivate(KeySpec keySpec)
                                     throws InvalidKeySpecException;
     
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the key specification for the specified key.
      * 
+     * @param key
+     *            the key from which the specification is requested.
+     * @param keySpec
+     *            the type of the requested {@code KeySpec}.
+     * @return the key specification for the specified key.
+     * @throws InvalidKeySpecException
+     *             if the key can not be processed, or the requested requested
+     *             {@code KeySpec} is inappropriate for the given key.
      */
     protected abstract <T extends KeySpec> T engineGetKeySpec(Key key, Class<T> keySpec)
                                     throws InvalidKeySpecException;
     //FIXME 1.5 signature: protected abstract <T extends KeySpec> T engineGetKeySpec(Key key, Class<T> keySpec) throws InvalidKeySpecException
     
     /**
-     * @com.intel.drl.spec_ref
+     * Translates the given key into a key from this key factory.
      * 
+     * @param key
+     *            the key to translate.
+     * @return the translated key.
+     * @throws InvalidKeyException
+     *             if the specified key can not be translated by this key
+     *             factory.
      */
     protected abstract Key engineTranslateKey(Key key) throws InvalidKeyException;
 

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyManagementException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyManagementException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyManagementException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyManagementException.java Tue Apr 28 17:01:41 2009
@@ -15,46 +15,52 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * {@code KeyManagementException} is a general exception, thrown to indicate an
+ * exception during processing an operation concerning key management.
  */
 public class KeyManagementException extends KeyException {
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private static final long serialVersionUID = 947674216157062695L;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code KeyManagementException} with the
+     * given message.
+     *
+     * @param msg
+     *            the detail message for this exception.
      */
     public KeyManagementException(String msg) {
         super(msg);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code KeyManagementException}.
      */
     public KeyManagementException() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code KeyManagementException} 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 KeyManagementException(String message, Throwable cause) {
         super(message, cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code KeyManagementException} with the
+     * cause.
+     *
+     * @param cause
+     *            the exception which is the cause for this exception.
      */
     public KeyManagementException(Throwable cause) {
         super(cause);

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyPair.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyPair.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyPair.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyPair.java Tue Apr 28 17:01:41 2009
@@ -15,29 +15,31 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vladimir N. Molotkov
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.io.Serializable;
 
 /**
- * @com.intel.drl.spec_ref
+ * {@code KeyPair} is a container for a public key and a private key. Since the
+ * private key can be accessed, instances must be treated like a private key.
  * 
+ * @see PrivateKey
+ * @see PublicKey
  */
 public final class KeyPair implements Serializable {
-    /**
-     * @com.intel.drl.spec_ref
-     */
+
     private static final long serialVersionUID = -7565189502268009837L;
     private final PrivateKey privateKey;
     private final PublicKey publicKey;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code KeyPair} with a public key and the
+     * corresponding private key.
+     *
+     * @param publicKey
+     *            the public key.
+     * @param privateKey
+     *            the private key.
      */
     public KeyPair(PublicKey publicKey, PrivateKey privateKey) {
         this.privateKey = privateKey;
@@ -45,14 +47,18 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the private key.
+     *
+     * @return the private key.
      */
     public PrivateKey getPrivate() {
         return privateKey;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the public key.
+     *
+     * @return the public key.
      */
     public PublicKey getPublic() {
         return publicKey;

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyPairGenerator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyPairGenerator.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyPairGenerator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyPairGenerator.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.security.spec.AlgorithmParameterSpec;
@@ -29,9 +24,11 @@
 
 
 /**
- * 
- * @com.intel.drl.spec_ref
- * 
+ * {@code KeyPairGenerator} is an engine class which is capable of generating a
+ * private key and its related public key utilizing the algorithm it was
+ * initialized with.
+ *
+ * @see KeyPairGeneratorSpi
  */
 public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {
 
@@ -51,25 +48,36 @@
     private String algorithm;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Constructs a new instance of {@code KeyPairGenerator} with the name of
+     * the algorithm to use.
+     *
+     * @param algorithm
+     *            the name of algorithm to use
      */
     protected KeyPairGenerator(String algorithm) {
         this.algorithm = algorithm;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the name of the algorithm of this {@code KeyPairGenerator}.
+     *
+     * @return the name of the algorithm of this {@code KeyPairGenerator}
      */
     public String getAlgorithm() {
         return algorithm;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a new instance of {@code KeyPairGenerator} that utilizes the
+     * specified algorithm.
      * 
-     * throws NullPointerException when algorithm is null
+     * @param algorithm
+     *            the name of the algorithm to use
+     * @return a new instance of {@code KeyPairGenerator} that utilizes the
+     *         specified algorithm
+     * @throws NoSuchAlgorithmException if the specified algorithm is not available
+     * @throws NullPointerException
+     *             if {@code algorithm} is {@code null}
      */
     public static KeyPairGenerator getInstance(String algorithm)
             throws NoSuchAlgorithmException {
@@ -93,10 +101,19 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a new instance of {@code KeyPairGenerator} that utilizes the
+     * specified algorithm from the specified provider.
      * 
-     * throws NullPointerException if algorithm is null (instead of
-     * NoSuchAlgorithmException) as in 1.4 release
+     * @param algorithm
+     *            the name of the algorithm to use
+     * @param provider
+     *            the name of the provider
+     * @return a new instance of {@code KeyPairGenerator} 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 KeyPairGenerator getInstance(String algorithm, String provider)
             throws NoSuchAlgorithmException, NoSuchProviderException {
@@ -112,10 +129,18 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a new instance of {@code KeyPairGenerator} that utilizes the
+     * specified algorithm from the specified provider.
      * 
-     * throws NullPointerException if algorithm is null (instead of
-     * NoSuchAlgorithmException) as in 1.4 release
+     * @param algorithm
+     *            the name of the algorithm to use
+     * @param provider
+     *            the provider
+     * @return a new instance of {@code KeyPairGenerator} 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 KeyPairGenerator getInstance(String algorithm,
             Provider provider) throws NoSuchAlgorithmException {
@@ -142,24 +167,35 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the provider associated with this {@code KeyPairGenerator}.
+     *
+     * @return the provider associated with this {@code KeyPairGenerator}
      */
     public final Provider getProvider() {
         return provider;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyPairGenerator} with the given key size. The
+     * default parameter set and a default {@code SecureRandom} instance will be
+     * used.
+     *
+     * @param keysize
+     *            the size of the key (number of bits)
      */
     public void initialize(int keysize) {
         initialize(keysize, random);
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyPairGenerator} with the given {@code
+     * AlgorithmParameterSpec}. A default {@code SecureRandom} instance will be
+     * used.
+     *
+     * @param param
+     *            the parameters to use
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified parameters are not supported
      */
     public void initialize(AlgorithmParameterSpec param)
             throws InvalidAlgorithmParameterException {
@@ -167,27 +203,51 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Computes and returns a new unique {@code KeyPair} each time this method
+     * is called.
+     * <p>
+     * This does exactly the same as {@link #generateKeyPair()}.
+     *
+     * @return a new unique {@code KeyPair} each time this method is called
      */
     public final KeyPair genKeyPair() {
         return generateKeyPair();
     }
 
+    /**
+     * Computes and returns a new unique {@code KeyPair} each time this method
+     * is called.
+     * <p>
+     * This does exactly the same as {@link #genKeyPair()}.
+     *
+     * @return a new unique {@code KeyPair} each time this method is called
+     */
     public KeyPair generateKeyPair() {
         return null;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyPairGenerator} with the given key size and the
+     * given {@code SecureRandom}. The default parameter set will be used.
+     *
+     * @param keysize
+     *            the key size
+     * @param random
+     *            the source of randomness
      */
     public void initialize(int keysize, SecureRandom random) {
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyPairGenerator} with the given {@code
+     * AlgorithmParameterSpec} and the given {@code SecureRandom}.
+     *
+     * @param param
+     *            the parameters to use
+     * @param random
+     *            the source of randomness
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified parameters are not supported
      */
     public void initialize(AlgorithmParameterSpec param, SecureRandom random)
             throws InvalidAlgorithmParameterException {

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyPairGeneratorSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyPairGeneratorSpi.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyPairGeneratorSpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyPairGeneratorSpi.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.security.spec.AlgorithmParameterSpec;
@@ -27,33 +22,47 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * @com.intel.drl.spec_ref
+ * {@code KeyPairGeneratorSpi} is the Service Provider Interface (SPI)
+ * definition for {@link KeyPairGenerator}.
  * 
+ * @see KeyPairGenerator
  */
-
 public abstract class KeyPairGeneratorSpi {
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Constructs a new instance of {@code KeyPairGeneratorSpi}.
      */
     public KeyPairGeneratorSpi() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Computes and returns a new unique {@code KeyPair} each time this method
+     * is called.
+     *
+     * @return a new unique {@code KeyPair} each time this method is called.
      */
     public abstract KeyPair generateKeyPair();
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyPairGeneratorSpi} with the given key size and
+     * the given {@code SecureRandom}. The default parameter set will be used.
+     *
+     * @param keysize
+     *            the key size (number of bits).
+     * @param random
+     *            the source of randomness.
      */
     public abstract void initialize(int keysize, SecureRandom random);
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyPairGeneratorSpi} with the given {@code
+     * AlgorithmParameterSpec} and the given {@code SecureRandom}.
+     *
+     * @param params
+     *            the parameters to use.
+     * @param random
+     *            the source of randomness.
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified parameters are not supported.
      */
     public void initialize(AlgorithmParameterSpec params, SecureRandom random)
             throws InvalidAlgorithmParameterException {



Mime
View raw message