harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r769463 [6/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/acl/AclEntry.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/AclEntry.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/AclEntry.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/AclEntry.java Tue Apr 28 17:01:41 2009
@@ -15,70 +15,103 @@
  *  limitations under the License.
  */
 
-/**
-* @author Aleksei Y. Semenov
-* @version $Revision$
-*/
-
 package java.security.acl;
 
 import java.security.Principal;
 import java.util.Enumeration;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The <i>Access Control List Entry</i> interface definition.
+ * <p>
+ * An {@code AclEntry} is a list of the {@link Permission}s that are 
+ *  granted (<i>positive</i>) or denied (<i>negative</i>) to a {@link Principal}.
  */
-
 public interface AclEntry extends Cloneable {
 
     /**
-     * @com.intel.drl.spec_ref
+     * Set the principal for this ACL entry.
+     * <p>
+     * The principal for an ACL entry can only be set once.
+     *
+     * @param user
+     *            the principal for this ACL entry.
+     * @return {@code true} on success, {@code false} if there is a principal already set for
+     *         this entry.
      */
     boolean setPrincipal(Principal user);
     
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the principal of this ACL entry.
+     * 
+     * @return the principal of this ACL entry, or null if none is set.
      */
     Principal getPrincipal();
     
     /**
-     * @com.intel.drl.spec_ref
+     * Sets this ACL entry to be <i>negative</i>.
+     * <p>
+     * The permissions in this ACL entry will be denied to the principal
+     * associated with this entry.
+     * <p>
+     * Note: An ACL entry is <i>positive</i> by default and can only become
+     * <i>negative</i> by calling this method.
      */
     void setNegativePermissions();
     
     /**
-     * @com.intel.drl.spec_ref
+     * Returns whether this ACL entry is <i>negative</i>.
+     * 
+     * @return {@code true} if this ACL entry is negative, {@code false} if it's positive.
      */
     boolean isNegative();
     
     /**
-     * @com.intel.drl.spec_ref
+     * Adds the specified permission to this ACL entry.
+     * 
+     * @param permission
+     *            the permission to be added.
+     * @return {@code true} if the specified permission is added, {@code false} if the
+     *         permission was already in this entry.
      */
     boolean addPermission(Permission permission);
     
     /**
-     * @com.intel.drl.spec_ref
+     * Removes the specified permission from this ACL entry.
+     * 
+     * @param permission
+     *            the permission to be removed.
+     * @return {@code true} if the permission is removed, {@code false} if the permission was
+     *         not in this entry.
      */
     boolean removePermission(Permission permission);
     
     /**
-     * @com.intel.drl.spec_ref
+     * Checks whether the specified permission is in this ACL entry.
+     * 
+     * @param permission
+     *            the permission to check.
+     * @return {@code true} if the permission is in this entry, otherwise {@code false}.
      */
     boolean checkPermission(Permission permission);
     
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the list of permissions of this ACL entry.
+     * 
+     * @return the list of permissions of this ACL entry,
      */
     Enumeration<Permission> permissions();
     
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the string representation of this ACL entry.
+     * 
+     * @return the string representation of this ACL entry.
      */
     String toString();
     
     /**
-     * @com.intel.drl.spec_ref
+     * Clones this ACL entry instance.
+     * 
+     * @return a copy of this entry.
      */
     Object clone();
     

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/AclNotFoundException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/AclNotFoundException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/AclNotFoundException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/AclNotFoundException.java Tue Apr 28 17:01:41 2009
@@ -15,26 +15,18 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexander V. Astapchuk
-* @version $Revision$
-*/
-
 package java.security.acl;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The exception, that is thrown when a reference to a non-existent <i>Access
+ * Control List</i> (ACL) is made.
  */
-
 public class AclNotFoundException extends Exception {
-    /**
-     * @com.intel.drl.spec_ref 
-     */
+
     private static final long serialVersionUID = 5684295034092681791L;
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Creates a new {@code AclNotFoundException}.
      */
     public AclNotFoundException() {
 

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Group.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Group.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Group.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Group.java Tue Apr 28 17:01:41 2009
@@ -15,40 +15,49 @@
  *  limitations under the License.
  */
 
-/**
-* @author Aleksei Y. Semenov
-* @version $Revision$
-*/
-
 package java.security.acl;
 
 import java.security.Principal;
 import java.util.Enumeration;
 
 /**
- * @com.intel.drl.spec_ref
+ * A {@code Principal} that represents a group of principals.
  * 
+ * @see Principal
  */
-
 public interface Group extends Principal {
     
     /**
-     * @com.intel.drl.spec_ref
+     * Adds a member to this group.
+     * 
+     * @param user
+     *            the member to add.
+     * @return {@code true} if the member was added, {@code false} if it was already a member.
      */
     boolean addMember(Principal user);
     
     /**
-     * @com.intel.drl.spec_ref
+     * Removes a member from this group.
+     * 
+     * @param user
+     *            the member to remove.
+     * @return {@code true} if the member was removed, {@code false} if it was not a member.
      */
     boolean removeMember(Principal user);
     
     /**
-     * @com.intel.drl.spec_ref
+     * Returns whether the specified principal is a member of this group.
+     * 
+     * @param member
+     *            the principal to check.
+     * @return {@code true} if the principal is a member, otherwise {@code false}.
      */
     boolean isMember(Principal member);
     
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the members of this group.
+     * 
+     * @return the members of this group.
      */
     Enumeration<? extends Principal> members();
     

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/LastOwnerException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/LastOwnerException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/LastOwnerException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/LastOwnerException.java Tue Apr 28 17:01:41 2009
@@ -15,26 +15,20 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexander V. Astapchuk
-* @version $Revision$
-*/
-
 package java.security.acl;
 
 /**
- * @com.intel.drl.spec_ref
- *  
+ * The exception that is thrown when an attempt is made to remove the
+ * the last {@code Owner} from an {@code Owner}.
+ *
+ * @see Owner
  */
-
 public class LastOwnerException extends Exception {
-    /**
-     * @com.intel.drl.spec_ref 
-     */
+
     private static final long serialVersionUID = -5141997548211140359L;
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Creates a new {@code LastOwnerException}.
      */
     public LastOwnerException() {
     }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/NotOwnerException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/NotOwnerException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/NotOwnerException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/NotOwnerException.java Tue Apr 28 17:01:41 2009
@@ -15,26 +15,22 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexander V. Astapchuk
-* @version $Revision$
-*/
-
 package java.security.acl;
 
 /**
- * @com.intel.drl.spec_ref
+ * The exception that is thrown when an action that requires ownership is
+ * attempted by a principal that is not an owner of the object for which
+ * ownership is required.
  * 
+ * @see Acl
+ * @see Owner
  */
-
 public class NotOwnerException extends Exception {
-    /**
-     * @com.intel.drl.spec_ref 
-     */
+
     private static final long serialVersionUID = -5555597911163362399L;
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Creates a new {@code NotOwnerException}.
      */
     public NotOwnerException() {
     }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Owner.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Owner.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Owner.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Owner.java Tue Apr 28 17:01:41 2009
@@ -15,36 +15,55 @@
  *  limitations under the License.
  */
 
-/**
-* @author Aleksei Y. Semenov
-* @version $Revision$
-*/
-
 package java.security.acl;
 
 import java.security.Principal;
 
 /**
- * @com.intel.drl.spec_ref
+ * The interface to manage owners of objects that require ownership.
  * 
+ * @see Acl
+ * @see Principal
  */
-
 public interface Owner {
     
     /**
-     * @com.intel.drl.spec_ref
+     * Adds a principal to the list of owners.
+     * 
+     * @param caller
+     *            the invoking principal.
+     * @param owner
+     *            the owner to added.
+     * @return {@code true} if the owner was added, {@code false} if it was already an owner.
+     * @throws NotOwnerException
+     *             if the invoking principal is not an owner.
      */
     boolean addOwner(Principal caller, Principal owner) 
                  throws NotOwnerException;
     
     /**
-     * @com.intel.drl.spec_ref
+     * Removes a principal from the list of owners.
+     * 
+     * @param caller
+     *            the invoking principal.
+     * @param owner
+     *            the owner to be removed.
+     * @return {@code true} if the owner was removed, {@code false} if it was not an owner.
+     * @throws NotOwnerException
+     *             if the invoking principal is not an owner.
+     * @throws LastOwnerException
+     *             if the owner to be removed is the last owner and hence removing it
+     *             would make this object owner-less.
      */
     boolean deleteOwner(Principal caller, Principal owner) 
                 throws NotOwnerException, LastOwnerException;
     
     /**
-     * @com.intel.drl.spec_ref
+     * Checks whether the specified principal is an owner of this object.
+     * 
+     * @param owner
+     *            the principal to check.
+     * @return {@code true} if the specified principal is an owner, otherwise {@code false}.
      */
     boolean isOwner(Principal owner);
 }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Permission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Permission.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Permission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Permission.java Tue Apr 28 17:01:41 2009
@@ -15,28 +15,31 @@
  *  limitations under the License.
  */
 
-/**
-* @author Aleksei Y. Semenov
-* @version $Revision$
-*/
-
 package java.security.acl;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The interface that represents a permission.
+ * <p>
+ * It can be granted or denied to a {@link java.security.Principal Principal} 
+ * using an {@link Acl}. 
  */
-
 public interface Permission {
 
     
     /**
-     * @com.intel.drl.spec_ref
+     * Checks whether the specified object equals this permission.
+     * 
+     * @param another
+     *            the permission object to compare to this permission.
+     * @return true if the specified permission object is equal to this, false
+     *         if not.
      */
     boolean equals(Object another);
     
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the string representation of this permission.
+     * 
+     * @return the string representation of this permission.
      */
     String toString();
 }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CRL.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CRL.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CRL.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CRL.java Tue Apr 28 17:01:41 2009
@@ -15,16 +15,12 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vladimir N. Molotkov
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 /**
- * This class represents Certificate Revocation Lists (CRLs). They are used to
- * indicate that a given Certificate has expired already.
+ * This class represents Certificate Revocation Lists (CRLs) maintained by a
+ * certificate authority. They are used to indicate that a given Certificate has
+ * expired and consequently has become invalid.
  * 
  * @see CertificateFactory
  */
@@ -33,37 +29,38 @@
     private final String type;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new certificate revocation list of the specified type.
+     *
+     * @param type
+     *            the type for the CRL.
      */
     protected CRL(String type) {
         this.type = type;
     }
 
-	/**
-	 * Answers the type of this CRL.
-	 * 
-	 * @return String the type of this CRL.
-	 */
+    /**
+     * Returns the type of this CRL.
+     *
+     * @return the type of this CRL.
+     */
     public final String getType() {
         return type;
     }
 
-	/**
-	 * Answers if a given Certificate has been revoked or not.
-	 * 
-	 * @param cert
-	 *            Certificate The Certificate to test
-	 * 
-	 * @return true if the certificate has been revoked false if the certificate
-	 *         has not been revoked yet
-	 */
+    /**
+     * Returns whether the specified certificate is revoked by this CRL.
+     *
+     * @param cert
+     *            the certificate to check.
+     * @return {@code true} if the certificate is revoked by this CRL, otherwise
+     *         {@code false}.
+     */
     public abstract boolean isRevoked(Certificate cert);
 
-	/**
-	 * Answers a string containing a concise, human-readable description of the
-	 * receiver.
-	 * 
-	 * @return a printable representation for the receiver.
-	 */
+    /**
+     * Returns the string representation of this instance.
+     *
+     * @return the string representation of this instance.
+     */
     public abstract String toString();
 }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CRLException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CRLException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CRLException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CRLException.java Tue Apr 28 17:01:41 2009
@@ -15,52 +15,50 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 import java.security.GeneralSecurityException;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The exception that is thrown if errors occur during handling of {@code CRL}s.
  */
 public class CRLException extends GeneralSecurityException {
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private static final long serialVersionUID = -6694728944094197147L;
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param msg
-	 *            String The detail message for the exception.
-	 */
+    /**
+     * Creates a new {@code CRLException} with the specified message.
+     * 
+     * @param msg
+     *            the detail message for this exception.
+     */
     public CRLException(String msg) {
         super(msg);
     }
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
+    /**
+     * Creates a new {@code CRLException}.
+     */
     public CRLException() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CRLException} with the specified message and cause.
+     * 
+     * @param message
+     *            the detail message for this exception.
+     * @param cause
+     *            the cause for this exception.
      */
     public CRLException(String message, Throwable cause) {
         super(message, cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CRLException} with the specified cause.
+     * 
+     * @param cause
+     *            the cause for this exception.
      */
     public CRLException(Throwable cause) {
         super(cause);

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CRLSelector.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CRLSelector.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CRLSelector.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CRLSelector.java Tue Apr 28 17:01:41 2009
@@ -15,26 +15,35 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 /**
- * @com.intel.drl.spec_ref
+ * The interface specification for determining whether a CRL meets some criteria
+ * to select CRL objects among a set of {@code CRL}s.
+ * <p>
+ * The implementations of this interface are typically used to define the
+ * criteria for selecting {@code CRL}s from a {@code CertStore}.
  * 
+ * @see CertStore
+ * @see CRL
  */
 public interface CRLSelector extends Cloneable {
 
     /**
-     * @com.intel.drl.spec_ref
+     * Clones this {@code CRLSelector} instance.
+     * 
+     * @return the cloned instance.
      */
     public Object clone();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Checks whether the defined criteria of this instance match the specified
+     * CRL.
+     * 
+     * @param crl
+     *            the CRL to be evaluated.
+     * @return {@code true} if the CRL matches the criteria, {@code false}
+     *         otherwise.
      */
     public boolean match(CRL crl);
 }
\ No newline at end of file

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPath.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPath.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPath.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPath.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.cert;
 
 import java.io.ByteArrayInputStream;
@@ -35,49 +30,51 @@
 /**
  * An immutable certificate path that can be validated. All certificates in the
  * path are of the same type (i.e., X509).
- * 
- * A <code>CertPath</code> can be represented as a byte array in at least one
- * supported encoding when serialized.
- * 
- * When a <code>List</code> of the certificates is obtained it must be
- * immutable.
- * 
- * A <code>CertPath</code> must be thread-safe without requiring coordinated
- * access.
+ * <p>
+ * A {@code CertPath} can be represented as a byte array in at least one
+ * supported encoding scheme (i.e. PkiPath or PKCS7) when serialized.
+ * <p>
+ * When a {@code List} of the certificates is obtained it must be immutable.
+ * <p>
+ * A {@code CertPath} must be thread-safe without requiring coordinated access.
+ *
+ * @see Certificate
  */
 public abstract class CertPath implements Serializable {
-    /**
-     * @com.intel.drl.spec_ref
-     */
+
     private static final long serialVersionUID = 6068470306649138683L;
     // Standard name of the type of certificates in this path
     private final String type;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertPath} instance for the specified certificate
+     * type.
+     *
+     * @param type
+     *            the certificate type.
      */
     protected CertPath(String type) {
         this.type = type;
     }
 
-	/**
-	 * Returns the type of <code>Certificate</code> in the
-	 * <code>CertPath</code>
-	 * 
-	 * @return <code>Certificate</code> type
-	 */
+    /**
+     * Returns the type of {@code Certificate} in this instance.
+     *
+     * @return the certificate type.
+     */
     public String getType() {
         return type;
     }
 
-	/**
-	 * Returns true if <code>Certificate</code>s in the list are the same
-	 * type and the lists are equal (and by implication the certificates
-	 * contained within are the same).
-	 * 
-	 * @param other
-	 *            <code>CertPath</code> to be compared for equality
-	 */
+    /**
+     * Returns {@code true} if {@code Certificate}s in the list are the same
+     * type and the lists are equal (and by implication the certificates
+     * contained within are the same).
+     *
+     * @param other
+     *            {@code CertPath} to be compared for equality.
+     * @return {@code true} if the object are equal, {@code false} otherwise.
+     */
     public boolean equals(Object other) {
         if (this == other) {
             return true;
@@ -93,27 +90,28 @@
         return false;
     }
 
-	/**
-	 * Overrides Object.hashCode() Defined as: hashCode = 31 *
-	 * path.getType().hashCode() + path.getCertificates().hashCode();
-	 * 
-	 * @return hash code for CertPath object
-	 */
+    /**
+     * Overrides {@code Object.hashCode()}. The function is defined as follows:
+     * <pre>
+     * {@code hashCode = 31 * path.getType().hashCode() +
+     * path.getCertificates().hashCode();}
+     * </pre>
+     *
+     * @return the hash code for this instance.
+     */
     public int hashCode() {
         int hash = getType().hashCode();
         hash = hash*31 + getCertificates().hashCode();
         return hash;
     }
 
-	/**
-	 * Returns a <code>String</code> representation of the
-	 * <code>CertPath</code>
-	 * <code>Certificate</code>s. It is the result of
-	 * calling <code>toString</code> on all <code>Certificate</code>s in
-	 * the <code>List</code>. <code>Certificate</code>s
-	 * 
-	 * @return string representation of <code>CertPath</code>
-	 */
+    /**
+     * Returns a {@code String} representation of this {@code CertPath}
+     * instance. It is the result of calling {@code toString} on all {@code
+     * Certificate}s in the {@code List}.
+     *
+     * @return a string representation of this instance.
+     */
     public String toString() {
         StringBuffer sb = new StringBuffer(getType());
         sb.append(" Cert Path, len="); //$NON-NLS-1$
@@ -132,46 +130,49 @@
     }
 
     /**
-     * Returns an immutable List of the <code>Certificate</code>s contained
-     * in the <code>CertPath</code>.
+     * Returns an immutable List of the {@code Certificate}s contained
+     * in the {@code CertPath}.
      * 
-     * @return list of <code>Certificate</code>s in the <code>CertPath</code>
+     * @return a list of {@code Certificate}s in the {@code CertPath}.
      */
     public abstract List<? extends Certificate> getCertificates();
 
     /**
-     * Returns an encoding of the <code>CertPath</code> using the default
-     * encoding
+     * Returns an encoding of the {@code CertPath} using the default encoding.
      * 
-     * @return default encoding of the <code>CertPath</code>
+     * @return default encoding of the {@code CertPath}.
      * @throws CertificateEncodingException
+     *             if the encoding fails.
      */
     public abstract byte[] getEncoded()
         throws CertificateEncodingException;
 
     /**
-     * Returns an encoding of the <code>CertPath</code> using the specified
-     * encoding
+     * Returns an encoding of the {@code CertPath} using the specified encoding.
      * 
      * @param encoding
-     *            encoding that should be generated
-     * @return default encoding of the <code>CertPath</code>
+     *            encoding that should be generated.
+     * @return default encoding of the {@code CertPath}.
      * @throws CertificateEncodingException
+     *             if the encoding fails.
      */
     public abstract byte[] getEncoded(String encoding)
         throws CertificateEncodingException;
 
     /**
-     * Return an <code>Iterator</code> over the supported encodings for a
+     * Returns an {@code Iterator} over the supported encodings for a
      * representation of the certificate path.
      * 
-     * @return <code>Iterator</code> over supported encodings (as
-     *         <code>String</code>s)
+     * @return {@code Iterator} over supported encodings (as {@code String}s).
      */
     public abstract Iterator<String> getEncodings();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns an alternate object to be serialized.
+     *
+     * @return an alternate object to be serialized.
+     * @throws ObjectStreamException
+     *             if the creation of the alternate object fails.
      */
     protected Object writeReplace() throws ObjectStreamException {
         try {
@@ -183,12 +184,11 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * The alternate {@code Serializable} class to be used for serialization and
+     * deserialization on {@code CertPath} objects.
      */
     protected static class CertPathRep implements Serializable {
-        /**
-         * @com.intel.drl.spec_ref
-         */
+
         private static final long serialVersionUID = 3015633072427920915L;
         // Standard name of the type of certificates in this path
         private final String type;
@@ -203,7 +203,13 @@
         };
 
         /**
-         * @com.intel.drl.spec_ref
+         * Creates a new {@code CertPathRep} instance with the specified type
+         * and encoded data.
+         *
+         * @param type
+         *            the certificate type.
+         * @param data
+         *            the encoded data.
          */
         protected CertPathRep(String type, byte[] data) {
             this.type = type;
@@ -211,7 +217,12 @@
         }
 
         /**
-         * @com.intel.drl.spec_ref
+         * Deserializes a {@code CertPath} from a serialized {@code CertPathRep}
+         * object.
+         *
+         * @return the deserialized {@code CertPath}.
+         * @throws ObjectStreamException
+         *             if deserialization fails.
          */
         protected Object readResolve() throws ObjectStreamException {
             try {

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathBuilder.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathBuilder.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathBuilder.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathBuilder.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.cert;
 
 import java.security.AccessController;
@@ -34,10 +29,9 @@
 
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * This class implements the functionality of a builder for an unverified
+ * <i>Certification Path</i>s from a specified certificate to a trust anchor.
  */
-
 public class CertPathBuilder {
 
     // Store CertPathBuilder service name
@@ -63,7 +57,14 @@
     private final String algorithm;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertPathBuilder}.
+     *
+     * @param builderSpi
+     *            the implementation delegate.
+     * @param provider
+     *            the provider.
+     * @param algorithm
+     *            the desired algorithm available at the provider.
      */
     protected CertPathBuilder(CertPathBuilderSpi builderSpi, Provider provider,
             String algorithm) {
@@ -73,24 +74,34 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the algorithm name of this instance.
+     *
+     * @return the algorithm name of this instance.
      */
     public final String getAlgorithm() {
         return algorithm;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the provider of this instance.
+     *
+     * @return the provider of this instance.
      */
     public final Provider getProvider() {
         return provider;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertPathBuilder} instance with the specified
+     * algorithm.
      * 
-     * throws NullPointerException if algorithm is null (instead of
-     * NoSuchAlgorithmException as in 1.4 release)
+     * @param algorithm
+     *            the name of the algorithm.
+     * @return a builder for the requested algorithm.
+     * @throws NullPointerException
+     *             if the algorithm is {@code null}.
+     * @throws NoSuchAlgorithmException
+     *             if no installed provider can provide the algorithm.
      */
     public static CertPathBuilder getInstance(String algorithm)
             throws NoSuchAlgorithmException {
@@ -105,13 +116,22 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     * 
-     * throws NullPointerException if algorithm is null (instead of
-     * NoSuchAlgorithmException as in 1.4 release)
+     * Creates a new {@code CertPathBuilder} instance from the specified
+     * provider providing the specified algorithm.
      * 
-     * FIXME: jrockit-j2re1.4.2_04 throws IllegalArgumentException when provider
-     * is empty
+     * @param algorithm
+     *            the name of the algorithm.
+     * @param provider
+     *            the name of the provider.
+     * @return a builder for the requested algorithm.
+     * @throws NoSuchAlgorithmException
+     *             if the specified provider cannot provide the algorithm.
+     * @throws NoSuchProviderException
+     *             if no provider with the specified name can be found.
+     * @throws NullPointerException
+     *             if algorithm is {@code null}.
+     * @throws IllegalArgumentException
+     *             if provider is {@code null} or empty.
      */
     public static CertPathBuilder getInstance(String algorithm, String provider)
             throws NoSuchAlgorithmException, NoSuchProviderException {
@@ -127,10 +147,20 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertPathBuilder} instance from the specified
+     * provider providing the specified algorithm.
      * 
-     * throws NullPointerException if algorithm is null (instead of
-     * NoSuchAlgorithmException as in 1.4 release)
+     * @param algorithm
+     *            the name of the algorithm.
+     * @param provider
+     *            the provider.
+     * @return a builder for the requested algorithm
+     * @throws NoSuchAlgorithmException
+     *             if the specified provider cannot provide the algorithm.
+     * @throws IllegalArgumentException
+     *             if provider is {@code null}.
+     * @throws NullPointerException
+     *             if algorithm is {@code null}.
      */
     public static CertPathBuilder getInstance(String algorithm,
             Provider provider) throws NoSuchAlgorithmException {
@@ -148,7 +178,17 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Builds a certification path with the specified algorithm parameters.
+     *
+     * @param params
+     *            the algorithm parameters.
+     * @return the built certification path.
+     * @throws CertPathBuilderException
+     *             if the build fails.
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified parameters cannot be used to build with this
+     *             builder.
+     * @see CertPathBuilderResult
      */
     public final CertPathBuilderResult build(CertPathParameters params)
             throws CertPathBuilderException, InvalidAlgorithmParameterException {
@@ -156,7 +196,12 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the default {@code CertPathBuilder} type from the <i>Security
+     * Properties</i>.
+     *
+     * @return the default {@code CertPathBuilder} type from the <i>Security
+     *         Properties</i>, or the string "{@code PKIX}" if it cannot be
+     *         determined.
      */
     public static final String getDefaultType() {
         String defaultType = AccessController

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathBuilderException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathBuilderException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathBuilderException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathBuilderException.java Tue Apr 28 17:01:41 2009
@@ -15,49 +15,53 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 import java.security.GeneralSecurityException;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The exception that is thrown when a {@code CertPathBuilder} method fails.
  */
 public class CertPathBuilderException extends GeneralSecurityException {
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private static final long serialVersionUID = 5316471420178794402L;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertPathBuilderException} with the specified message
+     * and cause.
+     * 
+     * @param msg
+     *            the detail message for the exception
+     * @param cause
+     *            why the building of the certification path failed.
      */
     public CertPathBuilderException(String msg, Throwable cause) {
         super(msg, cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertPathBuilderException} with the specified cause.
+     * 
+     * @param cause
+     *            why the building of the certification path failed.
      */
     public CertPathBuilderException(Throwable cause) {
         super(cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertPathBuilderException} with the specified
+     * message.
+     * 
+     * @param msg
+     *            the detail message for the exception.
      */
     public CertPathBuilderException(String msg) {
         super(msg);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertPathBuilderException}.
      */
     public CertPathBuilderException() {
     }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathBuilderResult.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathBuilderResult.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathBuilderResult.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathBuilderResult.java Tue Apr 28 17:01:41 2009
@@ -15,26 +15,25 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The interface for results generated by
+ * {@link CertPathBuilder#build(CertPathParameters)}.
  */
 public interface CertPathBuilderResult extends Cloneable {
 
     /**
-     * @com.intel.drl.spec_ref
+     * Clones this {@code CertPathBuilderResult} instance.
+     * 
+     * @return the copy of this instance.
      */
     public Object clone();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the built {@code CertPath} instance. Never returns {@code null}.
+     * 
+     * @return the built certificate path instance.
      */
     public CertPath getCertPath();
 }
\ No newline at end of file

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathBuilderSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathBuilderSpi.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathBuilderSpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathBuilderSpi.java Tue Apr 28 17:01:41 2009
@@ -15,30 +15,34 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 import java.security.InvalidAlgorithmParameterException;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The <i>Service Provider Interface</i> (<b>SPI</b>) for the {@code
+ * CertPathBuilder} class to be implemented by security providers.
  */
-
 public abstract class CertPathBuilderSpi {
+
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertPathBuilderSpi} instance.
      */
     public CertPathBuilderSpi() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Builds a certification path with the specified algorithm parameters.
+     * 
+     * @param params
+     *            the algorithm parameters.
+     * @return a result of the build.
+     * @throws CertPathBuilderException
+     *             if the build fails.
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified parameters cannot be used to build the path
+     *             with this builder.
      */
     public abstract CertPathBuilderResult engineBuild(CertPathParameters params)
             throws CertPathBuilderException, InvalidAlgorithmParameterException;
-}
\ No newline at end of file
+}

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathParameters.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathParameters.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathParameters.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathParameters.java Tue Apr 28 17:01:41 2009
@@ -15,21 +15,20 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The interface specification for certification path algorithm parameters.
+ * <p>
+ * This interface is for grouping purposes of {@code CertPath} parameter
+ * implementations.
  */
 public interface CertPathParameters extends Cloneable {
 
     /**
-     * @com.intel.drl.spec_ref
+     * Clones this {@code CertPathParameters} instance.
+     * 
+     * @return the cloned instance.
      */
     public Object clone();
 }
\ No newline at end of file

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathValidator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathValidator.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathValidator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathValidator.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.cert;
 
 import java.security.AccessController;
@@ -34,10 +29,10 @@
 
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * This class provides the functionality for validating certification paths
+ * (certificate chains) establishing a trust chain from a certificate to a trust
+ * anchor.
  */
-
 public class CertPathValidator {
     // Store CertPathValidator implementation service name
     private static final String SERVICE = "CertPathValidator"; //$NON-NLS-1$
@@ -62,8 +57,14 @@
     private final String algorithm;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code CertPathValidator} instance.
+     *
+     * @param validatorSpi
+     *            the implementation delegate.
+     * @param provider
+     *            the security provider.
+     * @param algorithm
+     *            the name of the algorithm.
      */
     protected CertPathValidator(CertPathValidatorSpi validatorSpi,
             Provider provider, String algorithm) {
@@ -73,25 +74,33 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the certification path algorithm name.
+     *
+     * @return the certification path algorithm name.
      */
     public final String getAlgorithm() {
         return algorithm;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the security provider.
+     *
+     * @return the provider.
      */
     public final Provider getProvider() {
         return provider;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a new certification path validator for the specified algorithm.
      * 
-     * throws NullPointerException if algorithm is null
+     * @param algorithm
+     *            the algorithm name.
+     * @return a certification path validator for the requested algorithm.
+     * @throws NoSuchAlgorithmException
+     *             if no installed provider provides the specified algorithm.
+     * @throws NullPointerException
+     *             if algorithm is {@code null}.
      */
     public static CertPathValidator getInstance(String algorithm)
             throws NoSuchAlgorithmException {
@@ -106,9 +115,23 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a new certification path validator for the specified algorithm
+     * from the specified provider.
      * 
-     * throws NullPointerException if algorithm is null
+     * @param algorithm
+     *            the algorithm name.
+     * @param provider
+     *            the security provider name.
+     * @return a certification path validator for the requested algorithm.
+     * @throws NoSuchAlgorithmException
+     *             if the specified security provider cannot provide the
+     *             requested algorithm.
+     * @throws NoSuchProviderException
+     *             if no provider with the specified name can be found.
+     * @throws NullPointerException
+     *             if algorithm is {@code null}.
+     * @throws IllegalArgumentException
+     *             if provider is {@code null} or empty.
      */
     public static CertPathValidator getInstance(String algorithm,
             String provider) throws NoSuchAlgorithmException,
@@ -124,9 +147,21 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref*
+     * Returns a new certification path validator for the specified algorithm
+     * from the specified provider.
      * 
-     * throws NullPointerException if algorithm is null
+     * @param algorithm
+     *            the algorithm name.
+     * @param provider
+     *            the security provider name.
+     * @return a certification path validator for the requested algorithm.
+     * @throws NoSuchAlgorithmException
+     *             if the specified provider cannot provide the requested
+     *             algorithm.
+     * @throws IllegalArgumentException
+     *             if provider is {@code null}.
+     * @throws NullPointerException
+     *             if algorithm is {@code null}.
      */
     public static CertPathValidator getInstance(String algorithm,
             Provider provider) throws NoSuchAlgorithmException {
@@ -144,8 +179,22 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Validates the {@code CertPath} with the algorithm of this {@code
+     * CertPathValidator} using the specified algorithm parameters.
      * 
+     * @param certPath
+     *            the certification path to be validated.
+     * @param params
+     *            the certification path validator algorithm parameters.
+     * @return the validation result.
+     * @throws CertPathValidatorException
+     *             if the validation fails, or the algorithm of the specified
+     *             certification path cannot be validated using the algorithm of
+     *             this instance.
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified algorithm parameters cannot be used with
+     *             this algorithm.
+     * @see CertPathValidatorResult
      */
     public final CertPathValidatorResult validate(CertPath certPath,
             CertPathParameters params) throws CertPathValidatorException,
@@ -154,8 +203,12 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the default {@code CertPathValidator} type from the <i>Security
+     * Properties</i>.
+     *
+     * @return the default {@code CertPathValidator} type from the <i>Security
+     *         Properties</i>, or the string {@code "PKIX"} if it cannot be
+     *         determined.
      */
     public static final String getDefaultType() {
         String defaultType = AccessController

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathValidatorException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathValidatorException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathValidatorException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathValidatorException.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.cert;
 
 import java.security.GeneralSecurityException;
@@ -27,33 +22,46 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The exception that is thrown when a certification path (or certificate chain)
+ * cannot be validated.
+ * <p>
+ * A {@code CertPathValidatorException} may optionally include the certification
+ * path instance that failed the validation and the index of the failed
+ * certificate.
  */
 public class CertPathValidatorException extends GeneralSecurityException {
-    /**
-     * @com.intel.drl.spec_ref
-     */
+
     private static final long serialVersionUID = -3083180014971893139L;
 
     /**
-     * @com.intel.drl.spec_ref
-     * 
-     * Serialized field for storing certPath which is defined in constructor
-     * CertPathValidatorException(msg, cause, certPath, index)
+     * the certification path.
      */
     private CertPath certPath;
 
     /**
-     * @com.intel.drl.spec_ref
-     * 
-     * Serialized field for storing index which is defined in constructor
-     * CertPathValidatorException(msg, cause, certPath, index)
+     * the index of the certificate.
      */
     private int index = -1;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertPathValidatorException} with the specified
+     * message , cause, certification path and certificate index in the
+     * certification path.
+     * 
+     * @param msg
+     *            the detail message for this exception.
+     * @param cause
+     *            the cause.
+     * @param certPath
+     *            the certification path that failed the validation.
+     * @param index
+     *            the index of the failed certificate.
+     * @throws IllegalArgumentException
+     *             if {@code certPath} is {@code null} and index is not {@code
+     *             -1}.
+     * @throws IndexOutOfBoundsException
+     *             if {@code certPath} is not {@code null} and index is not
+     *             referencing an certificate in the certification path.
      */
     public CertPathValidatorException(String msg, Throwable cause,
             CertPath certPath, int index) {
@@ -72,41 +80,61 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertPathValidatorException} with the specified
+     * message and cause.
+     * 
+     * @param msg
+     *            the detail message for this exception.
+     * @param cause
+     *            the cause why the path could not be validated.
      */
     public CertPathValidatorException(String msg, Throwable cause) {
         super(msg, cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertPathValidatorException} with the specified
+     * cause.
+     * 
+     * @param cause
+     *            the cause why the path could not be validated.
      */
     public CertPathValidatorException(Throwable cause) {
         super(cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertPathValidatorException} with the specified
+     * message.
+     * 
+     * @param msg
+     *            the detail message for this exception.
      */
     public CertPathValidatorException(String msg) {
         super(msg);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertPathValidatorException}.
      */
     public CertPathValidatorException() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the certification path that failed validation.
+     * 
+     * @return the certification path that failed validation, or {@code null} if
+     *         none was specified.
      */
     public CertPath getCertPath() {
         return certPath;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the index of the failed certificate in the certification path.
+     * 
+     * @return the index of the failed certificate in the certification path, or
+     *         {@code -1} if none was specified.
      */
     public int getIndex() {
         return index;

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathValidatorResult.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathValidatorResult.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathValidatorResult.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathValidatorResult.java Tue Apr 28 17:01:41 2009
@@ -15,21 +15,19 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The interface specification for certification path validation results.
+ * <p>
+ * This interface is for grouping purposes of validation result implementations.
  */
 public interface CertPathValidatorResult extends Cloneable {
 
     /**
-     * @com.intel.drl.spec_ref
+     * Clones this {@code CertPathValidatorResult} instance.
+     * 
+     * @return the cloned instance.
      */
     public Object clone();
 }
\ No newline at end of file

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathValidatorSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathValidatorSpi.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathValidatorSpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertPathValidatorSpi.java Tue Apr 28 17:01:41 2009
@@ -15,30 +15,38 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 import java.security.InvalidAlgorithmParameterException;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The <i>Service Provider Interface</i> (<b>SPI</b>) for the {@code
+ * CertPathValidator} class to be implemented by security providers.
  */
-
 public abstract class CertPathValidatorSpi {
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertPathValidatorSpi} instance.
      */
     public CertPathValidatorSpi() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Validates the {@code CertPath} with the algorithm of this {@code
+     * CertPathValidator} using the specified algorithm parameters.
+     *
+     * @param certPath
+     *            the certification path to be validated.
+     * @param params
+     *            the certification path validator algorithm parameters.
+     * @return the validation result.
+     * @throws CertPathValidatorException
+     *             if the validation fails, or the algorithm of the specified
+     *             certification path cannot be validated using the algorithm of
+     *             this instance.
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified algorithm parameters cannot be used with
+     *             this algorithm.
      */
     public abstract CertPathValidatorResult engineValidate(CertPath certPath,
             CertPathParameters params) throws CertPathValidatorException,

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertSelector.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertSelector.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertSelector.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertSelector.java Tue Apr 28 17:01:41 2009
@@ -15,26 +15,35 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 /**
- * @com.intel.drl.spec_ref
+ * The interface specification to determine whether a {@code
+ * Certificate} meets some criteria.
+ * <p>
+ * The implementations of this interface are typically used to define the
+ * criteria for selecting {@code Certificate}s from a {@code CertStore}.
  * 
+ * @see CertStore
+ * @see Certificate
  */
 public interface CertSelector extends Cloneable {
 
     /**
-     * @com.intel.drl.spec_ref
+     * Clones this {@code CertSelector} instance.
+     * 
+     * @return the cloned instance.
      */
     public Object clone();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Checks whether the defined criteria of this instance match the specified
+     * certificate.
+     * 
+     * @param cert
+     *            the certificate to be evaluated.
+     * @return {@code true} if the certificate matches the criteria, {@code
+     *         false} otherwise.
      */
     public boolean match(Certificate cert);
 }
\ No newline at end of file

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertStore.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertStore.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertStore.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertStore.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.cert;
 
 import java.security.AccessController;
@@ -35,10 +30,10 @@
 
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * This class provides the functionality to retrieve {@code Certificate}s and
+ * {@code CRL}s from a read-only repository. This repository may be very large
+ * and may store trusted as well as untrusted certificates.
  */
-
 public class CertStore {
 
     // Store spi implementation service name
@@ -67,7 +62,16 @@
     private final CertStoreParameters certStoreParams;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertStore} instance.
+     *
+     * @param storeSpi
+     *            the implementation delegate.
+     * @param provider
+     *            the security provider.
+     * @param type
+     *            the certificate store type.
+     * @param params
+     *            the certificate store parameters (may be {@code null}.
      */
     protected CertStore(CertStoreSpi storeSpi, Provider provider, String type,
             CertStoreParameters params) {
@@ -78,10 +82,22 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertStore} instance with the specified type and
+     * initialized with the specified parameters.
      * 
-     * throws NullPointerException if type is null (instead of
-     * NoSuchAlgorithmException as in 1.4 release)
+     * @param type
+     *            the certificate store type.
+     * @param params
+     *            the certificate store parameters (may be {@code null}).
+     * @return the new certificate store instance.
+     * @throws NoSuchAlgorithmException
+     *             if no provider can provide the specified certificate store
+     *             type.
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified parameters cannot be used to initialize this
+     *             certificate store instance.
+     * @throws NullPointerException
+     *             if the {@code type} is {@code null}.
      */
     public static CertStore getInstance(String type, CertStoreParameters params)
             throws InvalidAlgorithmParameterException, NoSuchAlgorithmException {
@@ -105,12 +121,28 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertStore} instance from the specified provider with
+     * the specified type and initialized with the specified parameters.
      * 
-     * throws NullPointerException if type is null (instead of
-     * NoSuchAlgorithmException as in 1.4 release)
-     * 
-     * FIXME: IllegalArgumentException when provider is empty
+     * @param type
+     *            the certificate store type.
+     * @param params
+     *            the certificate store parameters (may be {@code null}).
+     * @param provider
+     *            the name of the provider.
+     * @return the new certificate store instance.
+     * @throws NoSuchAlgorithmException
+     *             if the specified provider cannot provide the requested
+     *             certificate store type.
+     * @throws NoSuchProviderException
+     *             if no provider with the specified name can be found.
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified parameters cannot be used to initialize this
+     *             certificate store instance.
+     * @throws IllegalArgumentException
+     *             if provider is null of empty.
+     * @throws NullPointerException
+     *             if {@code type} is {@code null}.
      */
     public static CertStore getInstance(String type,
             CertStoreParameters params, String provider)
@@ -127,10 +159,25 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     * 
-     * throws NullPointerException if type is null (instead of
-     * NoSuchAlgorithmException as in 1.4 release)
+     * Creates a new {@code CertStore} instance from the specified provider with
+     * the specified type and initialized with the specified parameters.
+     * @param type
+     *            the certificate store type.
+     * @param params
+     *            the certificate store parameters (may be {@code null}).
+     * @param provider
+     *            the name of the provider.
+     * @return the new certificate store instance.
+     * @throws NoSuchAlgorithmException
+     *             if the specified provider cannot provide the requested
+     *             certificate store type.
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified parameters cannot be used to initialize this
+     *             certificate store instance.
+     * @throws IllegalArgumentException
+     *             if provider is {@code null}.
+     * @throws NullPointerException
+     *             if {@code type} is {@code null}.
      */
     public static CertStore getInstance(String type,
             CertStoreParameters params, Provider provider)
@@ -158,21 +205,29 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the certificate store type.
+     *
+     * @return the certificate store type.
      */
     public final String getType() {
         return type;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the security provider.
+     *
+     * @return the security provider.
      */
     public final Provider getProvider() {
         return provider;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a copy of the certificate store parameters that were used to
+     * initialize this instance.
+     *
+     * @return a copy of the certificate store parameters or {@code null} if
+     *         none were specified.
      */
     public final CertStoreParameters getCertStoreParameters() {
         if (certStoreParams == null) {
@@ -183,7 +238,16 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the list of {@code Certificate}s for the specified {@code
+     * CertSelector} from this certificate store.
+     *
+     * @param selector
+     *            the selector containing the criteria to search for
+     *            certificates in this certificate store.
+     * @return the list of {@code Certificate}s that match the criteria of the
+     *         specified selector.
+     * @throws CertStoreException
+     *             if error(s) occur.
      */
     public final Collection<? extends Certificate> getCertificates(CertSelector selector)
             throws CertStoreException {
@@ -191,7 +255,16 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the list of {@code CRL}s for the specified {@code CRLSelector}
+     * from this certificate store.
+     *
+     * @param selector
+     *            the selector containing the criteria to search for certificate
+     *            revocation lists in this store.
+     * @return the list of {@code CRL}s that match the criteria of the specified
+     *         selector
+     * @throws CertStoreException
+     *             if error(s) occur.
      */
     public final Collection<? extends CRL> getCRLs(CRLSelector selector)
             throws CertStoreException {
@@ -199,7 +272,12 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the default {@code CertStore} type from the <i>Security
+     * Properties</i>.
+     *
+     * @return the default {@code CertStore} type from the <i>Security
+     *         Properties</i>, or the string {@code "LDAP"} if it cannot be
+     *         determined.
      */
     public static final String getDefaultType() {
         String defaultType = AccessController

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertStoreException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertStoreException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertStoreException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertStoreException.java Tue Apr 28 17:01:41 2009
@@ -15,48 +15,52 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 import java.security.GeneralSecurityException;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The exception that is thrown when an access to a {@code CertStore} fails.
  */
 public class CertStoreException extends GeneralSecurityException {
-    /**
-     * @com.intel.drl.spec_ref
-     */
+
     private static final long serialVersionUID = 2395296107471573245L;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertStoreException} with the specified message and
+     * cause.
+     * 
+     * @param msg
+     *            the detail message for this exception.
+     * @param cause
+     *            the cause why the access to the certificate store failed.
      */
     public CertStoreException(String msg, Throwable cause) {
         super(msg, cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertStoreException} with the specified cause.
+     * 
+     * @param cause
+     *            the cause why the access to the certificate store failed.
      */
     public CertStoreException(Throwable cause) {
         super(cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertStoreException} with the specified message.
+     * 
+     * @param msg
+     *            the detail message for this exception.
      */
     public CertStoreException(String msg) {
         super(msg);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertStoreException}.
      */
     public CertStoreException() {
     }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertStoreParameters.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertStoreParameters.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertStoreParameters.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertStoreParameters.java Tue Apr 28 17:01:41 2009
@@ -15,21 +15,18 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The marker interface specifying the parameters used to initialize a {@code
+ * CertStore} instance.
  */
 public interface CertStoreParameters extends Cloneable {
 
     /**
-     * @com.intel.drl.spec_ref
+     * Clones this {@code CertStoreParameters} instance.
+     * 
+     * @return the cloned instance.
      */
     public Object clone();
 }
\ No newline at end of file

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertStoreSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertStoreSpi.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertStoreSpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertStoreSpi.java Tue Apr 28 17:01:41 2009
@@ -15,43 +15,56 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 import java.security.InvalidAlgorithmParameterException;
 import java.util.Collection;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The <i>Service Provider Interface</i> (<b>SPI</b>) definition for the {@code
+ * CertStore} class to be implemented by security providers.
  */
-
 public abstract class CertStoreSpi {
+
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertStoreSpi}.
      * 
-     * Parameter 'params' is unusable but required by the spec
+     * @param params
+     *            the initialization parameters.
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified initialization parameters cannot be used to
+     *             initialize this instance.
      */
     public CertStoreSpi(CertStoreParameters params)
             throws InvalidAlgorithmParameterException {
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the list of {@code Certificate}s for the specified {@code
+     * CertSelector} from this instance.
      * 
-     * FIXME: 1.5 updated are needed Collection <? extends Certificate>
+     * @param selector
+     *            the selector containing the criteria to search for
+     *            certificates in this instance.
+     * @return the list of {@code Certificate}s that match the criteria of the
+     *         specified selector.
+     * @throws CertStoreException
+     *             if error(s) occur.
      */
     public abstract Collection<? extends Certificate> engineGetCertificates(CertSelector selector)
             throws CertStoreException;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the list of {@code CRL}s for the specified {@code CRLSelector}
+     * from this instance.
      * 
-     * FIXME: 1.5 updated are needed Collection <? extends CRL>
+     * @param selector
+     *            the selector containing the criteria to search for certificate
+     *            revocation lists in instance.
+     * @return the list of {@code CRL}s that match the criteria of the specified
+     *         selector
+     * @throws CertStoreException
+     *             if error(s) occur.
      */
     public abstract Collection<? extends CRL> engineGetCRLs(CRLSelector selector)
             throws CertStoreException;

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/Certificate.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/Certificate.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/Certificate.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/Certificate.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.cert;
 
 import java.io.ByteArrayInputStream;
@@ -42,42 +37,43 @@
  * PGP, and SDSI.
  */
 public abstract class Certificate implements Serializable {
-    /**
-     * @com.intel.drl.spec_ref
-     */
+
     private static final long serialVersionUID = -3585440601605666277L;
 
     // The standard name of the certificate type
     private final String type;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code Certificate} with the specified type.
+     *
+     * @param type
+     *        the certificate type.
      */
     protected Certificate(String type) {
         this.type = type;
     }
 
-	/**
-	 * Answers the certificate type represented by the receiver.
-	 * 
-	 * @return the certificate type represented by the receiver.
-	 */
+    /**
+     * Returns the certificate type.
+     *
+     * @return the certificate type.
+     */
     public final String getType() {
         return type;
     }
 
-	/**
-	 * Compares the argument to the receiver, and answers true if they represent
-	 * the <em>same</em> object using a class specific comparison. The
-	 * implementation in Object answers true only if the argument is the exact
-	 * same object as the receiver (==).
-	 * 
-	 * @param other
-	 *            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 argument to the certificate, and returns {@code true} if they
+     * represent the <em>same</em> object using a class specific comparison. The
+     * implementation in Object returns {@code true} only if the argument is the
+     * exact same object as the callee (==).
+     *
+     * @param other
+     *            the object to compare with this object.
+     * @return {@code true} if the object is the same as this object, {@code
+     *         false} if it is different from this object.
+     * @see #hashCode
+     */
     public boolean equals(Object other) {
         // obj equal to itself
         if (this == other) {
@@ -95,15 +91,14 @@
         return false;
     }
 
-	/**
-	 * 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 the receiver's hash
-	 * 
-	 * @see #equals
-	 */
+    /**
+     * Returns an integer hash code for the certificate. Any two objects which
+     * return {@code true} when passed to {@code equals} must return the same
+     * value for this method.
+     *
+     * @return the certificate's hash
+     * @see #equals
+     */
     public int hashCode() {
         try {
             byte[] encoded = getEncoded();
@@ -117,31 +112,32 @@
         }
     }
 
-	/**
-	 * Answers the encoded representation for this certificate.
-	 * 
-	 * @return the encoded representation for this certificate.
-	 */
+    /**
+     * Returns the encoded representation for this certificate.
+     *
+     * @return the encoded representation for this certificate.
+     * @throws CertificateEncodingException
+     *             if the encoding fails.
+     */
     public abstract byte[] getEncoded() throws CertificateEncodingException;
 
-	/**
-	 * Verifies that this certificate was signed with the given public key.
-	 * 
-	 * @param key
-	 *            PublicKey public key for which verification should be
-	 *            performed.
-	 * 
-	 * @exception CertificateException
-	 *                if encoding errors are detected
-	 * @exception NoSuchAlgorithmException
-	 *                if an unsupported algorithm is detected
-	 * @exception InvalidKeyException
-	 *                if an invalid key is detected
-	 * @exception NoSuchProviderException
-	 *                if there is no default provider
-	 * @exception SignatureException
-	 *                if signature errors are detected
-	 */
+    /**
+     * Verifies that this certificate was signed with the given public key.
+     *
+     * @param key
+     *            PublicKey public key for which verification should be
+     *            performed.
+     * @throws CertificateException
+     *             if encoding errors are detected.
+     * @throws NoSuchAlgorithmException
+     *             if an unsupported algorithm is detected.
+     * @throws InvalidKeyException
+     *             if an invalid key is detected.
+     * @throws NoSuchProviderException
+     *             if there is no default provider.
+     * @throws SignatureException
+     *             if signature errors are detected.
+     */
     public abstract void verify(PublicKey key)
         throws CertificateException,
                NoSuchAlgorithmException,
@@ -149,27 +145,26 @@
                NoSuchProviderException,
                SignatureException;
 
-	/**
-	 * Verifies that this certificate was signed with the given public key. Uses
-	 * the signature algorithm given by the provider.
-	 * 
-	 * @param key
-	 *            PublicKey public key for which verification should be
-	 *            performed.
-	 * @param sigProvider
-	 *            String the name of the signature provider.
-	 * 
-	 * @exception CertificateException
-	 *                if encoding errors are detected
-	 * @exception NoSuchAlgorithmException
-	 *                if an unsupported algorithm is detected
-	 * @exception InvalidKeyException
-	 *                if an invalid key is detected
-	 * @exception NoSuchProviderException
-	 *                if there is no default provider
-	 * @exception SignatureException
-	 *                if signature errors are detected
-	 */
+    /**
+     * Verifies that this certificate was signed with the given public key. It
+     * Uses the signature algorithm given by the provider.
+     *
+     * @param key
+     *            PublicKey public key for which verification should be
+     *            performed.
+     * @param sigProvider
+     *            String the name of the signature provider.
+     * @exception CertificateException
+     *                if encoding errors are detected.
+     * @exception NoSuchAlgorithmException
+     *                if an unsupported algorithm is detected.
+     * @exception InvalidKeyException
+     *                if an invalid key is detected.
+     * @exception NoSuchProviderException
+     *                if the specified provider does not exists.
+     * @exception SignatureException
+     *                if signature errors are detected.
+     */
     public abstract void verify(PublicKey key, String sigProvider)
         throws CertificateException,
                NoSuchAlgorithmException,
@@ -177,23 +172,27 @@
                NoSuchProviderException,
                SignatureException;
 
-	/**
-	 * 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
+     * certificate.
+     *
+     * @return a printable representation for the certificate.
+     */
     public abstract String toString();
 
-	/**
-	 * Answers the public key corresponding to this certificate.
-	 * 
-	 * @return the public key corresponding to this certificate.
-	 */
+    /**
+     * Returns the public key corresponding to this certificate.
+     *
+     * @return the public key corresponding to this certificate.
+     */
     public abstract PublicKey getPublicKey();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns an alternate object to be serialized.
+     *
+     * @return the object to serialize.
+     * @throws ObjectStreamException
+     *             if the creation of the alternate object fails.
      */
     protected Object writeReplace() throws ObjectStreamException {
         try {
@@ -205,13 +204,11 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     * 
+     * The alternate {@code Serializable} class to be used for serialization and
+     * deserialization of {@code Certificate} objects.
      */
     protected static class CertificateRep implements Serializable {
-        /**
-         * @com.intel.drl.spec_ref
-         */
+
         private static final long serialVersionUID = -8563758940495660020L;
         // The standard name of the certificate type
         private final String type;
@@ -226,7 +223,13 @@
         };
 
         /**
-         * @com.intel.drl.spec_ref
+         * Creates a new {@code CertificateRep} instance with the specified
+         * certificate type and encoded data.
+         *
+         * @param type
+         *            the certificate type.
+         * @param data
+         *            the encoded data.
          */
         protected CertificateRep(String type, byte[] data) {
             this.type = type;
@@ -234,7 +237,12 @@
         }
 
         /**
-         * @com.intel.drl.spec_ref
+         * Deserializes a {@code Certificate} from a serialized {@code
+         * CertificateRep} object.
+         *
+         * @return the deserialized {@code Certificate}.
+         * @throws ObjectStreamException
+         *             if deserialization fails.
          */
         protected Object readResolve() throws ObjectStreamException {
             try {

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateEncodingException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateEncodingException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateEncodingException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateEncodingException.java Tue Apr 28 17:01:41 2009
@@ -15,50 +15,52 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 /**
- * This class represents an encoding exception for a certificate.
+ * The exception that is thrown when an error occurs while a {@code Certificate}
+ * is being encoded.
  */
 public class CertificateEncodingException extends CertificateException {
-    /**
-     * @com.intel.drl.spec_ref
-     */
+
     private static final long serialVersionUID = 6219492851589449162L;
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param msg
-	 *            String The detail message for the exception.
-	 */
+    /**
+     * Creates a new {@code CertificateEncodingException} with the specified
+     * message.
+     * 
+     * @param msg
+     *            The detail message for the exception.
+     */
     public CertificateEncodingException(String msg) {
         super(msg);
     }
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
+    /**
+     * Creates a new {@code CertificateEncodingException}.
+     */
     public CertificateEncodingException() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code CertificateEncodingException} with the specified
+     * message and cause.
+     * 
+     * @param message
+     *            the detail message for the exception.
+     * @param cause
+     *            the cause.
      */
     public CertificateEncodingException(String message, Throwable cause) {
         super(message, cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code CertificateEncodingException} with the specified
+     * cause.
+     * 
+     * @param cause
+     *            the cause.
      */
     public CertificateEncodingException(Throwable cause) {
         super(cause);



Mime
View raw message