harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r769463 [7/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/cert/CertificateException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateException.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.cert;
 
 import java.security.GeneralSecurityException;
 
 /**
- * This class represents a general certificate exception.
+ * The base class for all {@code Certificate} related exceptions.
  */
 public class CertificateException extends GeneralSecurityException {
 
-    /**
-     * @com.intel.drl.spec_ref
-     *  
-     */
     private static final long serialVersionUID = 3192535253797119798L;
 
-	/**
-	 * 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 CertificateException} with the specified message.
+     * 
+     * @param msg
+     *            the detail message for the exception.
+     */
     public CertificateException(String msg) {
         super(msg);
     }
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
+    /**
+     * Creates a new {@code CertificateException}.
+     */
     public CertificateException() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code CertificateException} with the specified message and
+     * cause.
+     * 
+     * @param message
+     *            the detail message for the exception.
+     * @param cause
+     *            the cause.
      */
     public CertificateException(String message, Throwable cause) {
         super(message, cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code CertificateException} with the specified cause.
+     * 
+     * @param cause
+     *            the cause
      */
     public CertificateException(Throwable cause) {
         super(cause);

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateExpiredException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateExpiredException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateExpiredException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateExpiredException.java Tue Apr 28 17:01:41 2009
@@ -15,38 +15,29 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 /**
- * This class indicates that a given certificate has expired.
+ * The exception that is thrown when a {@code Certificate} has expired.
  */
 public class CertificateExpiredException extends CertificateException {
 
-    /**
-     * @com.intel.drl.spec_ref
-     *  
-     */
     private static final long serialVersionUID = 9071001339691533771L;
 
-	/**
-	 * 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 CertificateExpiredException} with the specified
+     * message.
+     * 
+     * @param msg
+     *            the detail message for this exception
+     */
     public CertificateExpiredException(String msg) {
         super(msg);
     }
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
+    /**
+     * Creates a new {@code CertificateExpiredException}.
+     */
     public CertificateExpiredException() {
     }
 }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateFactory.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateFactory.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateFactory.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.io.InputStream;
@@ -36,9 +31,12 @@
 
 
 /**
- * This class provides the functionality of a certificate factory algorithm.
+ * This class implements the functionality of a certificate factory algorithm,
+ * relying on parsing a stream of bytes.
+ * <p>
+ * It defines methods for parsing certificate chains (certificate paths) and
+ * <i>Certificate Revocation Lists</i> (CRLs).
  */
-
 public class CertificateFactory {
 
     // Store CertificateFactory service name
@@ -57,8 +55,14 @@
     private final String type;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code CertificateFactory} instance.
+     *
+     * @param certFacSpi
+     *            the implementation delegate.
+     * @param provider
+     *            the associated provider.
+     * @param type
+     *            the certificate type.
      */
     protected CertificateFactory(CertificateFactorySpi certFacSpi,
             Provider provider, String type) {
@@ -68,18 +72,17 @@
     }
 
     /**
-     * Answers a new CertificateFactory of the given type.
+     * Creates a new {@code CertificateFactory} instance that provides the
+     * requested certificate type.
      * 
      * @param type
-     *            java.lang.String Type of certificate desired
-     * @return CertificateFactory a concrete implementation for the certificate
-     *         type desired.
-     * 
-     * @exception CertificateException
-     *                If the type cannot be found
-     *
-     * @exception NullPointerException
-     *                If the type is null
+     *            the certificate type.
+     * @return the new {@code CertificateFactory} instance.
+     * @throws CertificateException
+     *             if the specified certificate type is not available at any
+     *             installed provider.
+     * @throws NullPointerException
+     *             if {@code type} is {@code null}.
      */
     public static final CertificateFactory getInstance(String type)
             throws CertificateException {
@@ -98,10 +101,24 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertificateFactory} instance from the specified
+     * provider that provides the requested certificate type.
      * 
-     * throws NullPointerException if algorithm is null (instead of
-     * CertificateException as in 1.4 release)
+     * @param type
+     *            the certificate type.
+     * @param provider
+     *            the name of the provider providing certificates of the
+     *            specified type.
+     * @return the new {@code CertificateFactory} instance.
+     * @throws CertificateException
+     *             if the specified certificate type is not available by the
+     *             specified provider.
+     * @throws NoSuchProviderException
+     *             if no provider with the specified name can be found.
+     * @throws IllegalArgumentException
+     *             if the specified provider name is {@code null} or empty.
+     * @throws NullPointerException
+     *             it {@code type} is {@code null}.
      */
     public static final CertificateFactory getInstance(String type,
             String provider) throws CertificateException,
@@ -117,21 +134,22 @@
     }
 
     /**
-     * Answers a new CertificateFactory of the given type.
+     * Creates a new {@code CertificateFactory} instance from the specified
+     * provider that provides the requested certificate type.
      * 
      * @param type
-     *            java.lang.String Type of certificate desired
+     *            the certificate type.
      * @param provider
-     *            java.security.Provider Provider which has to implement the
-     *            algorithm
-     * @return CertificateFactory a concrete implementation for the certificate
-     *         type desired.
-     * 
-     * @exception CertificateException
-     *                If the type cannot be found
-     *
-     * @exception NullPointerException
-     *                If algorithm is null
+     *            the name of the provider providing certificates of the
+     *            specified type.
+     * @return the new {@code CertificateFactory} instance.
+     * @throws CertificateException
+     *             if the specified certificate type is not available at the
+     *             specified provider.
+     * @throws IllegalArgumentException
+     *             if the specified provider is {@code null}.
+     * @throws NullPointerException
+     *             is {@code type} is {@code null}.
      */
     public static final CertificateFactory getInstance(String type,
             Provider provider) throws CertificateException {
@@ -153,35 +171,34 @@
     }
 
     /**
-     * Returns the Provider of the certificate factory represented by the
-     * receiver.
+     * Returns the {@code Provider} of the certificate factory represented by
+     * the certificate.
      * 
-     * @return Provider an instance of a subclass of java.security.Provider
+     * @return the provider of this certificate factory.
      */
     public final Provider getProvider() {
         return provider;
     }
 
     /**
-     * Returns the Certificate type
+     * Returns the Certificate type.
      * 
-     * @return String type of certificate being used
+     * @return type of certificate being used.
      */
     public final String getType() {
         return type;
     }
 
     /**
-     * Generates and initializes a Certificate from data from the
-     * provided input stream.
+     * Generates and initializes a {@code Certificate} from the provided input
+     * stream.
      * 
      * @param inStream
-     *            InputStream Stream from where data is read to create the
-     *            Certificate
-     * 
-     * @return Certificate an initialized Certificate
-     * @exception CertificateException
-     *                if parsing problems are detected
+     *            the stream from where data is read to create the {@code
+     *            Certificate}.
+     * @return an initialized Certificate.
+     * @throws CertificateException
+     *             if parsing problems are detected.
      */
     public final Certificate generateCertificate(InputStream inStream)
             throws CertificateException {
@@ -189,26 +206,25 @@
     }
 
     /**
-     * Returns an Iterator over the supported CertPath encodings (as Strings).
-     * The first element is the default encoding.
+     * Returns an {@code Iterator} over the supported {@code CertPath} encodings
+     * (as Strings). The first element is the default encoding scheme to apply.
      * 
-     * @return Iterator Iterator over supported CertPath encodings (as Strings)
+     * @return an iterator over supported {@link CertPath} encodings (as
+     *         Strings).
      */
     public final Iterator<String> getCertPathEncodings() {
         return spiImpl.engineGetCertPathEncodings();
     }
 
     /**
-     * Generates a <code>CertPath</code> from data from the provided
-     * <code>InputStream</code>. The default encoding is assumed.
+     * Generates a {@code CertPath} (a certificate chain) from the provided
+     * {@code InputStream}. The default encoding scheme is applied.
      * 
      * @param inStream
-     *            InputStream with PKCS7 or PkiPath encoded data
-     * 
-     * @return CertPath a CertPath initialized from the provided data
-     * 
+     *            {@code InputStream} with encoded data.
+     * @return a {@code CertPath} initialized from the provided data.
      * @throws CertificateException
-     *             if parsing problems are detected
+     *             if parsing problems are detected.
      */
     public final CertPath generateCertPath(InputStream inStream)
             throws CertificateException {
@@ -220,22 +236,19 @@
     }
 
     /**
-     * Generates a <code>CertPath</code> from data from the provided
-     * <code>InputStream</code>. The encoding is that specified by the
-     * encoding parameter.
+     * Generates a {@code CertPath} (a certificate chain) from the provided
+     * {@code InputStream} and the specified encoding scheme.
      * 
      * @param inStream
-     *            InputStream containing certificate path data in specified
-     *            encoding
+     *            {@code InputStream} containing certificate path data in
+     *            specified encoding.
      * @param encoding
-     *            encoding of the data in the input stream
-     * 
-     * @return CertPath a CertPath initialized from the provided data
-     * 
+     *            encoding of the data in the input stream.
+     * @return a {@code CertPath} initialized from the provided data.
      * @throws CertificateException
-     *             if parsing problems are detected
+     *             if parsing problems are detected.
      * @throws UnsupportedOperationException
-     *             if the provider does not implement this method
+     *             if the provider does not implement this method.
      */
     public final CertPath generateCertPath(InputStream inStream, String encoding)
             throws CertificateException {
@@ -243,19 +256,17 @@
     }
 
     /**
-     * Generates a <code>CertPath</code> from the provided List of
-     * Certificates. The encoding is the default encoding.
+     * Generates a {@code CertPath} from the provided list of certificates. The
+     * encoding is the default encoding.
      * 
      * @param certificates
-     *            List containing certificates in a format supported by the
-     *            CertificateFactory
-     * 
-     * @return CertPath a CertPath initialized from the provided data
-     * 
+     *            the list containing certificates in a format supported by the
+     *            {@code CertificateFactory}.
+     * @return a {@code CertPath} initialized from the provided data.
      * @throws CertificateException
-     *             if parsing problems are detected
+     *             if parsing problems are detected.
      * @throws UnsupportedOperationException
-     *             if the provider does not implement this method
+     *             if the provider does not implement this method.
      */
     public final CertPath generateCertPath(List<? extends Certificate> certificates)
             throws CertificateException {
@@ -263,16 +274,15 @@
     }
 
     /**
-     * Generates and initializes a collection of Certificates from
-     * data from the provided input stream.
+     * Generates and initializes a collection of (unrelated) certificates from
+     * the provided input stream.
      * 
      * @param inStream
-     *            InputStream Stream from where data is read to create the
-     *            Certificates
-     * 
-     * @return Collection an initialized collection of Certificates
-     * @exception CertificateException
-     *                if parsing problems are detected
+     *            the stream from which the data is read to create the
+     *            collection.
+     * @return an initialized collection of certificates.
+     * @throws CertificateException
+     *             if parsing problems are detected.
      */
     public final Collection<? extends Certificate> generateCertificates(InputStream inStream)
             throws CertificateException {
@@ -280,32 +290,28 @@
     }
 
     /**
-     * Generates and initializes a Certificate Revocation List from data from
+     * Generates and initializes a <i>Certificate Revocation List</i> (CRL) from
      * the provided input stream.
      * 
      * @param inStream
-     *            InputStream Stream from where data is read to create the CRL
-     * 
-     * @return CRL an initialized Certificate Revocation List
+     *            the stream from where data is read to create the CRL.
+     * @return an initialized CRL.
      * @exception CRLException
-     *                if parsing problems are detected
+     *                if parsing problems are detected.
      */
     public final CRL generateCRL(InputStream inStream) throws CRLException {
         return spiImpl.engineGenerateCRL(inStream);
     }
 
     /**
-     * Generates and initializes a collection of Certificate Revocation List
-     * from data from the provided input stream.
+     * Generates and initializes a collection of <i>Certificate Revocation
+     * List</i> (CRL) from the provided input stream.
      * 
      * @param inStream
-     *            InputStream Stream from where data is read to create the CRLs
-     * 
-     * @return Collection an initialized collection of Certificate Revocation
-     *         List
+     *            the stream from which the data is read to create the CRLs.
+     * @return an initialized collection of CRLs.
      * @exception CRLException
-     *                if parsing problems are detected
-     * 
+     *                if parsing problems are detected.
      */
     public final Collection<? extends CRL> generateCRLs(InputStream inStream)
             throws CRLException {

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateFactorySpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateFactorySpi.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateFactorySpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateFactorySpi.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.io.InputStream;
@@ -30,8 +25,9 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * This class is a Service Provider Interface (therefore the Spi suffix) for
- * certificate factories to be supplied by providers.
+ * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>) for the
+ * {@code CertificateFactory} class. This SPI must be implemented for each
+ * certificate type a security provider wishes to support.
  */
 
 public abstract class CertificateFactorySpi {
@@ -43,75 +39,67 @@
     }
 
     /**
-     * Generates and initializes a Certificate from data from the
-     * provided input stream.
+     * Generates and initializes a {@code Certificate} from the provided input
+     * stream.
      * 
      * @param inStream
-     *            InputStream Stream from where data is read to create the
-     *            Certificate
-     * 
-     * @return Certificate an initialized Certificate
+     *            the stream from which the data is read to create the
+     *            certificate.
+     * @return an initialized certificate.
      * @exception CertificateException
-     *                if parsing problems are detected
+     *                if parsing problems are detected.
      */
     public abstract Certificate engineGenerateCertificate(InputStream inStream)
             throws CertificateException;
 
     /**
-     * Generates and initializes a collection of Certificates from
-     * data from the provided input stream.
+     * Generates and initializes a collection of certificates from the provided
+     * input stream.
      * 
      * @param inStream
-     *            InputStream Stream from where data is read to create the
-     *            Certificates
-     * 
-     * @return Collection an initialized collection of Certificates
+     *            the stream from where data is read to create the certificates.
+     * @return a collection of certificates.
      * @exception CertificateException
-     *                if parsing problems are detected
+     *                if parsing problems are detected.
      */
     public abstract Collection<? extends Certificate> 
         engineGenerateCertificates(InputStream inStream) throws CertificateException;
 
     /**
-     * Generates and initializes a Certificate Revocation List from data from
+     * Generates and initializes a <i>Certificate Revocation List</i> (CRL) from
      * the provided input stream.
      * 
      * @param inStream
-     *            InputStream Stream from where data is read to create the CRL
-     * 
-     * @return CRL an initialized Certificate Revocation List
+     *            the stream from where data is read to create the CRL.
+     * @return an CRL instance.
      * @exception CRLException
-     *                if parsing problems are detected
+     *                if parsing problems are detected.
      */
     public abstract CRL engineGenerateCRL(InputStream inStream)
             throws CRLException;
 
     /**
-     * Generates and initializes a collection of Certificate Revocation List
-     * from data from the provided input stream.
+     * Generates and initializes a collection of <i>Certificate Revocation
+     * List</i> (CRL) from the provided input stream.
      * 
      * @param inStream
-     *            InputStream Stream from where data is read to create the CRLs
-     * 
-     * @return Collection an initialized collection of Certificate Revocation
-     *         List
+     *            the stream from which the data is read to create the CRLs.
+     * @return a collection of CRLs.
      * @exception CRLException
-     *                if parsing problems are detected
+     *                if parsing problems are detected.
      */
     public abstract Collection<? extends CRL> 
         engineGenerateCRLs(InputStream inStream) throws CRLException;
 
     /**
-     * Generates a <code>CertPath</code> from data from the provided
-     * <code>InputStream</code>. The default encoding is assumed.
+     * Generates a {@code CertPath} from the provided {@code InputStream}. The
+     * default encoding scheme is applied.
      * 
      * @param inStream
-     *            InputStream with PKCS7 or PkiPath encoded data
-     * 
-     * @return CertPath a CertPath initialized from the provided data
-     * 
+     *            an input stream with encoded data.
+     * @return a {@code CertPath} initialized from the provided data.
      * @throws CertificateException
-     *             if parsing problems are detected
+     *             if parsing problems are detected.
      */
     public CertPath engineGenerateCertPath(InputStream inStream)
             throws CertificateException {
@@ -120,22 +108,19 @@
     }
 
     /**
-     * Generates a <code>CertPath</code> from data from the provided
-     * <code>InputStream</code>. The encoding is that specified by the
-     * encoding parameter.
+     * Generates a {@code CertPath} from the provided {@code
+     * InputStream} in the specified encoding.
      * 
      * @param inStream
-     *            InputStream containing certificate path data in specified
-     *            encoding
+     *            an input stream containing certificate path data in specified
+     *            encoding.
      * @param encoding
-     *            encoding of the data in the input stream
-     * 
-     * @return CertPath a CertPath initialized from the provided data
-     * 
+     *            the encoding of the data in the input stream.
+     * @return a {@code CertPath} initialized from the provided data
      * @throws CertificateException
-     *             if parsing problems are detected
+     *             if parsing problems are detected.
      * @throws UnsupportedOperationException
-     *             if the provider does not implement this method
+     *             if the provider does not implement this method.
      */
     public CertPath engineGenerateCertPath(InputStream inStream, String encoding)
             throws CertificateException {
@@ -144,19 +129,17 @@
     }
 
     /**
-     * Generates a <code>CertPath</code> from the provided List of
-     * Certificates. The encoding is the default encoding.
+     * Generates a {@code CertPath} from the provided list of certificates. The
+     * encoding is the default encoding.
      * 
      * @param certificates
-     *            List containing certificates in a format supported by the
-     *            CertificateFactory
-     * 
-     * @return CertPath a CertPath initialized from the provided data
-     * 
+     *            the list containing certificates in a format supported by the
+     *            {@code CertificateFactory}.
+     * @return a {@code CertPath} initialized from the provided data.
      * @throws CertificateException
-     *             if parsing problems are detected
+     *             if parsing problems are detected.
      * @throws UnsupportedOperationException
-     *             if the provider does not implement this method
+     *             if the provider does not implement this method.
      */
     public CertPath engineGenerateCertPath(List<? extends Certificate>  certificates) 
             throws CertificateException {
@@ -165,10 +148,11 @@
     }
 
     /**
-     * Returns an Iterator over the supported CertPath encodings (as Strings).
-     * The first element is the default encoding.
+     * Returns an {@code Iterator} over the supported {@code CertPath} encodings
+     * (as Strings). The first element is the default encoding.
      * 
-     * @return Iterator Iterator over supported CertPath encodings (as Strings)
+     * @return an iterator over supported {@code CertPath} encodings (as
+     *         Strings).
      */
     public Iterator<String> engineGetCertPathEncodings() {
         throw new UnsupportedOperationException(

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateNotYetValidException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateNotYetValidException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateNotYetValidException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateNotYetValidException.java Tue Apr 28 17:01:41 2009
@@ -15,36 +15,30 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 /**
- * This class indicates that a given certificate is not valid yet.
+ * The exception that is thrown when a {@code Certificate} is not yet valid or
+ * will not yet be valid on a specified date.
  */
 public class CertificateNotYetValidException extends CertificateException {
-    /**
-     * @com.intel.drl.spec_ref
-     */
+
     private static final long serialVersionUID = 4355919900041064702L;
 
-	/**
-	 * 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 CertificateNotYetValidException} with the specified
+     * message.
+     * 
+     * @param msg
+     *            the detail message for the exception.
+     */
     public CertificateNotYetValidException(String msg) {
         super(msg);
     }
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
+    /**
+     * Creates a new {@code CertificateNotYetValidException}.
+     */
     public CertificateNotYetValidException() {
     }
 }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateParsingException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateParsingException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateParsingException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CertificateParsingException.java Tue Apr 28 17:01:41 2009
@@ -15,49 +15,51 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 /**
- * This class indicates that a given certificate could not be parsed.
+ * The exception that is thrown when a {@code Certificate} can not be parsed.
  */
 public class CertificateParsingException extends CertificateException {
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private static final long serialVersionUID = -7989222416793322029L;
 
-	/**
-	 * 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 CertificateParsingException} with the specified
+     * message.
+     *
+     * @param msg
+     *            the detail message for the exception.
+     */
     public CertificateParsingException(String msg) {
         super(msg);
     }
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
+    /**
+     * Creates a new {@code CertificateParsingException}.
+     */
     public CertificateParsingException() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertificateParsingException} with the specified
+     * message and cause.
+     *
+     * @param message
+     *            the detail message for the exception.
+     * @param cause
+     *            the exception's source.
      */
     public CertificateParsingException(String message, Throwable cause) {
         super(message, cause);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CertificateParsingException} with the specified
+     * cause.
+     *
+     * @param cause
+     *            the exception's source.
      */
     public CertificateParsingException(Throwable cause) {
         super(cause);

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CollectionCertStoreParameters.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CollectionCertStoreParameters.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CollectionCertStoreParameters.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/CollectionCertStoreParameters.java Tue Apr 28 17:01:41 2009
@@ -15,19 +15,16 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vladimir N. Molotkov
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 import java.util.Collection;
 import java.util.Collections;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The parameters to initialize a <i>Collection</i> type {@code CertStore} instance.
+ * <p>
+ * It is used to specify the {@code Collection} where the {@code CertStore} will
+ * retrieve the certificates and CRLs from.
  */
 public class CollectionCertStoreParameters implements CertStoreParameters {
     // Default empty and immutable collection.
@@ -39,14 +36,26 @@
     private final Collection collection;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CollectionCertStoreParameters} without a collection.
+     * <p>
+     * The default collection is an empty and unmodifiable {@code Collection}.
      */
     public CollectionCertStoreParameters() {
         this.collection = defaultCollection;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CollectionCertStoreParameters} with the specified
+     * collection.
+     * <p>
+     * The specified collection is not copied and therefore may be modified at
+     * any time.
+     *
+     * @param collection
+     *            the collection where the {@code Certificate}s and {@code CRL}s
+     *            will be retrieved from.
+     * @throws NullPointerException
+     *             if {@code collection is null}.
      */
     public CollectionCertStoreParameters(Collection<?> collection) {
         this.collection = collection;
@@ -56,7 +65,10 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Clones this {@code CollectionCertStoreParameters} instance, but not the
+     * underlying collection.
+     *
+     * @return the cloned instance.
      */
     public Object clone() {
         try {
@@ -67,14 +79,20 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the collection where the {@code Certificate}s and {@code CRL}s
+     * are retrieved from.
+     *
+     * @return the collection where the {@code Certificate}s and {@code CRL}s
+     *         will be retrieved from.
      */
     public Collection<?> getCollection() {
         return collection;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the string representation of this instance.
+     *
+     * @return the string representation of this instance.
      */
     public String toString() {
         StringBuffer sb =

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/LDAPCertStoreParameters.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/LDAPCertStoreParameters.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/LDAPCertStoreParameters.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/LDAPCertStoreParameters.java Tue Apr 28 17:01:41 2009
@@ -15,16 +15,10 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vladimir N. Molotkov
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The parameters to initialize a LDAP {@code CertStore} instance.
  */
 public class LDAPCertStoreParameters implements CertStoreParameters {
     // Default LDAP server name
@@ -38,7 +32,15 @@
     private final int port;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code LDAPCertStoreParameters} instance with the specified
+     * server name and port.
+     *
+     * @param serverName
+     *            the LDAP server name.
+     * @param port
+     *            the port.
+     * @throws NullPointerException
+     *             is {@code serverName} is {@code null}.
      */
     public LDAPCertStoreParameters(String serverName, int port) {
         this.port = port;
@@ -49,7 +51,10 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code LDAPCertStoreParameters} instance with default
+     * parameters.
+     * <p>
+     * The default parameters are server name "localhost" and port 389.
      */
     public LDAPCertStoreParameters() {
         this.serverName = DEFAULT_LDAP_SERVER_NAME;
@@ -57,7 +62,13 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code LDAPCertStoreParameters} instance with the specified
+     * server name and default port 389.
+     *
+     * @param serverName
+     *            the LDAP server name.
+     * @throws NullPointerException
+     *             if {@code serverName} is {@code null}.
      */
     public LDAPCertStoreParameters(String serverName) {
         this.port = DEFAULT_LDAP_PORT;
@@ -68,7 +79,9 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Clones this {@code LDAPCertStoreParameters} instance.
+     *
+     * @return the cloned instance.
      */
     public Object clone() {
     	try {
@@ -79,21 +92,29 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the LDAP server port.
+     *
+     * @return the LDAP server port.
      */
     public int getPort() {
         return port;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the LDAP server name.
+     *
+     * @return the LDAP server name.
      */
     public String getServerName() {
         return serverName;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the string representation of this {@code LDAPCertStoreParameters}
+     * instance.
+     *
+     * @return the string representation of this {@code LDAPCertStoreParameters}
+     *         instance.
      */
     public String toString() {
         StringBuffer sb =

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXBuilderParameters.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXBuilderParameters.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXBuilderParameters.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXBuilderParameters.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.security.InvalidAlgorithmParameterException;
@@ -31,15 +26,33 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The parameter specification for a PKIX {@code CertPathBuilder}
+ * algorithm used to {@link CertPathBuilder#build(CertPathParameters) build} 
+ * certificate chains validated with the PKIX certification path validation. 
+ * <p>
+ * The parameters must be created with <i>trusted</i> certificate authorities
+ * and constraints for the target certificates.
+ *
+ * @see CertPathBuilder
+ * @see CertPathParameters
  */
 public class PKIXBuilderParameters extends PKIXParameters {
     // Maximum certificate path length (5 by default)
     private int maxPathLength = 5;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code PKIXBuilderParameters} instance with the specified
+     * set of {@code TrustAnchor} and certificate constraints.
+     * 
+     * @param trustAnchors
+     *            the set of {@code TrustAnchors}.
+     * @param targetConstraints
+     *            the certificate constraints.
+     * @throws InvalidAlgorithmParameterException
+     *             if {@code trustAnchors} is empty.
+     * @throws ClassCastException
+     *             if one of the items in {@code trustAnchors} is not an
+     *             instance of {@code java.security.cert.TrustAnchor}.
      */
     public PKIXBuilderParameters(Set<TrustAnchor> trustAnchors,
             CertSelector targetConstraints)
@@ -49,7 +62,18 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code PKIXBuilderParameters} instance with the trusted
+     * {@code X509Certificate} entries from the specified {@code KeyStore}.
+     * 
+     * @param keyStore
+     *            the key store containing trusted certificates.
+     * @param targetConstraints
+     *            the certificate constraints.
+     * @throws KeyStoreException
+     *             if the {@code keyStore} is not initialized.
+     * @throws InvalidAlgorithmParameterException
+     *             if {@code keyStore} does not contained any trusted
+     *             certificate entry.
      */
     public PKIXBuilderParameters(KeyStore keyStore,
             CertSelector targetConstraints)
@@ -60,14 +84,28 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the maximum length of a certification path.
+     * <p>
+     * This is the maximum number of non-self-signed certificates in a
+     * certification path.
+     *
+     * @return the maximum length of a certification path, or {@code -1} if it
+     *         is unlimited.
      */
     public int getMaxPathLength() {
         return maxPathLength;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Set the maximum length of a certification path.
+     * <p>
+     * This is the maximum number of non-self-signed certificates in a
+     * certification path.
+     * 
+     * @param maxPathLength
+     *            the maximum length of a certification path.
+     * @throws InvalidParameterException
+     *             if {@code maxPathLength} is less than {@code -1}.
      */
     public void setMaxPathLength(int maxPathLength) {
         if (maxPathLength < -1) {
@@ -78,7 +116,11 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a string representation of this {@code PKIXBuilderParameters}
+     * instance.
+     * 
+     * @return a string representation of this {@code PKIXBuilderParameters}
+     *         instance.
      */
     public String toString() {
         StringBuffer sb = new StringBuffer("[\n"); //$NON-NLS-1$

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXCertPathBuilderResult.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXCertPathBuilderResult.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXCertPathBuilderResult.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXCertPathBuilderResult.java Tue Apr 28 17:01:41 2009
@@ -15,10 +15,6 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vladimir N. Molotkov
-* @version $Revision$
-*/
 
 package java.security.cert;
 
@@ -27,8 +23,8 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The result of the PKIX certification path builder, returned by
+ * {@link CertPathBuilder#build(CertPathParameters)}.
  */
 public class PKIXCertPathBuilderResult extends PKIXCertPathValidatorResult
         implements CertPathBuilderResult {
@@ -36,7 +32,21 @@
     private final CertPath certPath;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code PKIXCertPathBuilderResult} instance with the
+     * specified validated certification path, the trust anchor of the
+     * certification path, the policy tree and the public key of the subject.
+     * 
+     * @param certPath
+     *            the validated certification path.
+     * @param trustAnchor
+     *            the trust anchor.
+     * @param policyTree
+     *            the policy tree (or {@code null} if not used).
+     * @param subjectPublicKey
+     *            the public key.
+     * @throws NullPointerException
+     *             if the {@code cerPath}, {@code trustAnchor} or {@code
+     *             subjectPolicyKey} is {@code null}.
      */
     public PKIXCertPathBuilderResult(CertPath certPath, TrustAnchor trustAnchor,
             PolicyNode policyTree, PublicKey subjectPublicKey) {
@@ -48,14 +58,20 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the validated certification path.
+     * 
+     * @return the validated certification path.
      */
     public CertPath getCertPath() {
         return certPath;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a string representation of this {@code PKIXCertPathBuilderResult}
+     * instance.
+     * 
+     * @return a string representation of this {@code PKIXCertPathBuilderResult}
+     *         instance.
      */
     public String toString() {
         StringBuffer sb = new StringBuffer(super.toString());

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXCertPathChecker.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXCertPathChecker.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXCertPathChecker.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXCertPathChecker.java Tue Apr 28 17:01:41 2009
@@ -15,29 +15,41 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vladimir N. Molotkov
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 import java.util.Collection;
 import java.util.Set;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The class specifying the interface to extend the certification path
+ * validation algorithm by checks to perform on an {@code X509Certificate}.
+ * <p>
+ * The checks are added to a certification path validation using the
+ * {@link PKIXParameters#setCertPathCheckers(java.util.List)
+ * setCertPathCheckers} or
+ * {@link PKIXBuilderParameters#addCertPathChecker(PKIXCertPathChecker)
+ * addCertPathChecker} of the {@code PKIXParameters} and {@code
+ * PKIXBuilderParameters} class respectively. The
+ * {@link #check(Certificate, Collection) check} method will be called for each
+ * certificate processed by a {@code CertPathBuilder} of {@code
+ * CertPathValidator}.
+ * <p>
+ * A {@code PKIXCertPathChecker} implementation <u>must</u> support reverse
+ * checking (from trusted CA to target) and <u>may</u> support forward checking
+ * (from target to trusted CA). The return value of {@code
+ * isForwardCheckingSupported} indicates whether forward checking is supported.
  */
 public abstract class PKIXCertPathChecker implements Cloneable {
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code PKIXCertPathChecker} instance.
      */
     protected PKIXCertPathChecker() {}
 
     /**
-     * @com.intel.drl.spec_ref
+     * Clones this {@code PKIXCertPathChecker} instance.
+     * 
+     * @return the cloned instance.
      */
     public Object clone() {
         try {
@@ -48,23 +60,51 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Initializes this {@code PKIXCertPathChecker} instance for specified
+     * <i>checking direction</i>.
+     * 
+     * @param forward
+     *            the direction of the certification path processing, {@code
+     *            true} if the certificates are processed in forward direction
+     *            (from target to trusted CA), {@code false} if processed in
+     *            reverse direction (from trusted CA to target).
+     * @throws CertPathValidatorException
+     *             if initialization of this {@code PKIXCertPathChecker}
+     *             instance fails, or if it cannot process certificates in the
+     *             specified order.
      */
     public abstract void init(boolean forward)
         throws CertPathValidatorException;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns whether this {@code PKIXCertPathChecker} instance supports
+     * <i>forward checking</i>.
+     * 
+     * @return {@code true} if this {@code PKIXCertPathChecker} instance
+     *         supports forward checking, otherwise {@code false}.
      */
     public abstract boolean isForwardCheckingSupported();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the list of extensions of X.509 certificates that this {@code
+     * PKIXCertPathChecker} is able to process.
+     * 
+     * @return the list of extensions of X.509 certificates that this {@code
+     *         PKIXCertPathChecker} is able to process, or {@code null} if there
+     *         are none.
      */
     public abstract Set<String> getSupportedExtensions();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Checks the specified certificate and removes the processed critical
+     * extensions from the specified list of X.509 extension <i>OID</i>s.
+     * 
+     * @param cert
+     *            the certificate.
+     * @param unresolvedCritExts
+     *            the list of critical X.509 extension OID strings.
+     * @throws CertPathValidatorException
+     *             if check(s) fail on the specified certificate.
      */
     public abstract void check(Certificate cert, Collection<String> unresolvedCritExts)
         throws CertPathValidatorException;

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXCertPathValidatorResult.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXCertPathValidatorResult.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXCertPathValidatorResult.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXCertPathValidatorResult.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.security.PublicKey;
@@ -27,8 +22,10 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * @com.intel.drl.spec_ref
+ * The implementation of the result of the PKIX certification path validation.
  * 
+ * @see CertPathValidator
+ * @see CertPathValidator#validate(CertPath, CertPathParameters)
  */
 public class PKIXCertPathValidatorResult implements CertPathValidatorResult {
     // A trust anchor used during validation of certification path
@@ -40,7 +37,16 @@
     private final PublicKey subjectPublicKey;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code PKIXCertPathValidatorResult} with the specified
+     * trust anchor, the valid policy tree and the subject public key.
+     * 
+     * @param trustAnchor
+     *            the trust anchor describing the certification authority (CA)
+     *            that served as trust anchor for the certification path.
+     * @param policyTree
+     *            the valid policy tree from the validation.
+     * @param subjectPublicKey
+     *            the subject public key from the validation.
      */
     public PKIXCertPathValidatorResult(TrustAnchor trustAnchor,
             PolicyNode policyTree, PublicKey subjectPublicKey) {
@@ -57,28 +63,37 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the valid policy tree from the validation.
+     * 
+     * @return the valid policy tree from the validation.
      */
     public PolicyNode getPolicyTree() {
         return policyTree;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the subject public key from the validation.
+     * 
+     * @return the subject public key from the validation.
      */
     public PublicKey getPublicKey() {
         return subjectPublicKey;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the trust anchor describing the certification authority (CA) that
+     * served as trust anchor for this certification path.
+     * 
+     * @return the trust anchor.
      */
     public TrustAnchor getTrustAnchor() {
         return trustAnchor;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Clones this {@code PKIXCertPathValidatorResult} instance.
+     * 
+     * @return the cloned instance.
      */
     public Object clone() {
         try {
@@ -90,7 +105,11 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a string representation for this {@code
+     * PKIXCertPathValidatorResult} instance.
+     * 
+     * @return a string representation for this {@code
+     *         PKIXCertPathValidatorResult} instance.
      */
     public String toString() {
         StringBuffer sb = new StringBuffer(super.toString());

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXParameters.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXParameters.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXParameters.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PKIXParameters.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.security.InvalidAlgorithmParameterException;
@@ -37,8 +32,13 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * This class implements the parameters for the {@code PKIX CertPathValidator}.
+ * <p>
+ * The parameters must be created with <i>trusted</i> certificate authorities
+ * (trust anchors).
+ *
+ * @see CertPathValidator
+ * @see CertPathParameters
  */
 public class PKIXParameters implements CertPathParameters {
     // Set of trust anchors - most trusted CAs
@@ -70,7 +70,13 @@
     private boolean policyQualifiersRejected = true;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code PKIXParameters} instance with the specified set of
+     * <i>trusted</i> certificate authorities.
+     * 
+     * @param trustAnchors
+     *            the trusted CAs.
+     * @throws InvalidAlgorithmParameterException
+     *             if {@code trustAnchors} is empty.
      */
     public PKIXParameters(Set<TrustAnchor> trustAnchors)
         throws InvalidAlgorithmParameterException {
@@ -82,7 +88,16 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code PKIXParameters} instance with the trusted {@code
+     * X509Certificate} entries from the specified {@code KeyStore}.
+     * 
+     * @param keyStore
+     *            the key store containing trusted certificates.
+     * @throws KeyStoreException
+     *             if the {@code keyStore} is not initialized.
+     * @throws InvalidAlgorithmParameterException
+     *             if {@code keyStore} does not contained any trusted
+     *             certificate entry.
      */
     public PKIXParameters(KeyStore keyStore)
         throws KeyStoreException,
@@ -115,14 +130,21 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a unmodifiable set of the <i>trusted</i> certificate authorities.
+     * 
+     * @return a unmodifiable set of the <i>trusted</i> certificate authorities.
      */
     public Set<TrustAnchor> getTrustAnchors() {
         return Collections.unmodifiableSet(trustAnchors);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Sets the set of <i>trusted</i> certificate authorities.
+     * 
+     * @param trustAnchors
+     *            the set of <i>trusted</i> certificate authorities.
+     * @throws InvalidAlgorithmParameterException
+     *             if {@code trustAnchors} is empty.
      */
     public void setTrustAnchors(Set<TrustAnchor> trustAnchors)
         throws InvalidAlgorithmParameterException {
@@ -136,21 +158,34 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns whether the <i>any policy OID</i> will be inhibited if it's
+     * included in a certificate.
+     * 
+     * @return {@code true} if the <i>any policy OID</i> will be inhibited,
+     *         otherwise {@code false}.
      */
     public boolean isAnyPolicyInhibited() {
         return anyPolicyInhibited;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Sets whether the <i>any policy OID</i> should be inhibited if it's
+     * included in a certificate.
+     * 
+     * @param anyPolicyInhibited
+     *            {@code true} if the <i>any policy OID</i> should be inhibited,
+     *            otherwise {@code false}.
      */
     public void setAnyPolicyInhibited(boolean anyPolicyInhibited) {
         this.anyPolicyInhibited = anyPolicyInhibited;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the list of checkers for the certification path.
+     * <p>
+     * The list is unmodifiable and the entries in the list are cloned.
+     *
+     * @return the list of checkers for the certification path.
      */
     public List<PKIXCertPathChecker> getCertPathCheckers() {
         if (certPathCheckers == null) {
@@ -174,7 +209,13 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Sets the list of checkers for the certification path.
+     * <p>
+     * The list is copied and the entries are cloned.
+     * 
+     * @param certPathCheckers
+     *            the list of checkers for the certification path, or {@code
+     *            null} to clear the checkers.
      */
     public void setCertPathCheckers(List<PKIXCertPathChecker> certPathCheckers) {
         if (certPathCheckers == null || certPathCheckers.isEmpty()) {
@@ -195,7 +236,12 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Adds the specified {@code PKIXCertPathChecker} to the list of
+     * certification path checkers.
+     * 
+     * @param checker
+     *            the {@code PKIXCertPathChecker} to add, if {@code null}, it
+     *            will be ignored.
      */
     public void addCertPathChecker(PKIXCertPathChecker checker) {
         if (checker == null) {
@@ -211,7 +257,10 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the list of certificate stores that are used to find certificates
+     * and CRLs.
+     * 
+     * @return an immutable list of certificate stores.
      */
     public List<CertStore> getCertStores() {
         if (certStores == null) {
@@ -231,7 +280,10 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Set the list of certificate stores that are used to find certificates and
+     * CRLs.
+     * 
+     * @param certStores the list of certificate stores.
      */
     public void setCertStores(List<CertStore> certStores) {
         if (certStores == null || certStores.isEmpty()) {
@@ -253,7 +305,11 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Adds a certificate store to the list of certificate stores that are used
+     * to find certificates and CRLs.
+     * 
+     * @param store
+     *            the store to add, if {@code null}, it will be ignored.
      */
     public void addCertStore(CertStore store) {
         if (store == null) {
@@ -269,35 +325,57 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the time for which the validation of the certification path
+     * should be evaluated.
+     * 
+     * @return the time for the validation, or {@code null} for the current
+     *         time.
      */
     public Date getDate() {
         return date == null ? null : (Date)date.clone();
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Sets the time for which the validation of the certification path sould be
+     * evaluated.
+     * 
+     * @param date
+     *            the time for the validation, or {@code null} for the current
+     *            time.
      */
     public void setDate(Date date) {
         this.date = (date == null ? null : new Date(date.getTime()));
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns whether an acceptable policy needs to be explicit identified in
+     * every certificate.
+     * 
+     * @return {@code true} if an explicit policy is required, otherwise {@code
+     *         false}.
      */
     public boolean isExplicitPolicyRequired() {
         return explicitPolicyRequired;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Sets whether an an acceptable policy needs to be explicit identified in
+     * every certificate.
+     * 
+     * @param explicitPolicyRequired
+     *            {@code true} if an explicit policy is required, otherwise
+     *            {@code false}.
      */
     public void setExplicitPolicyRequired(boolean explicitPolicyRequired) {
         this.explicitPolicyRequired = explicitPolicyRequired;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the list of policies (as OID strings) that would be acceptable
+     * for the purpose of certification path processing.
+     * 
+     * @return the unmodifiable list of policies, or an empty set if any policy
+     *         is acceptable.
      */
     public Set<String> getInitialPolicies() {
         if (initialPolicies == null) {
@@ -316,7 +394,12 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Sets the list of policies (as OID strings) that would be acceptable for
+     * the purpose of certification path processing.
+     * 
+     * @param initialPolicies
+     *            the list of policies, or an empty set or {@code null} if any
+     *            policy is acceptable.
      */
     public void setInitialPolicies(Set<String> initialPolicies) {
         if (initialPolicies == null || initialPolicies.isEmpty()) {
@@ -339,63 +422,102 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns whether policy mapping is inhibited.
+     * 
+     * @return {@code true} if policy mapping is inhibited, otherwise {@code
+     *         false}.
      */
     public boolean isPolicyMappingInhibited() {
         return policyMappingInhibited;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Sets whether policy mapping is to be inhibited.
+     * 
+     * @param policyMappingInhibited
+     *            {@code true} if policy mapping is to be inhibited, otherwise
+     *            {@code false}.
      */
     public void setPolicyMappingInhibited(boolean policyMappingInhibited) {
         this.policyMappingInhibited = policyMappingInhibited;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns whether certificates are rejected that include policy
+     * qualifiers in a certificate policy extension that is marked as critical.
+     * 
+     * @return {@code true} if the certificates should be rejected, otherwise
+     *         {@code false}.
      */
     public boolean getPolicyQualifiersRejected() {
         return policyQualifiersRejected;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Sets whether certificates should be rejected that include policy
+     * qualifiers in a certificate policy extension that is marked as critical.
+     * 
+     * @param policyQualifiersRejected
+     *            {@code true} if the certificates should be rejected, otherwise
+     *            {@code false}.
      */
     public void setPolicyQualifiersRejected(boolean policyQualifiersRejected) {
         this.policyQualifiersRejected = policyQualifiersRejected;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns whether the default revocation checking mechanism of the
+     * underlying service provider is used.
+     * 
+     * @return {@code true} if the default revocation checking mechanism is
+     *         used, otherwise {@code false}.
      */
     public boolean isRevocationEnabled() {
         return revocationEnabled;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Sets whether the default revocation checking mechanism of the underlying
+     * service provider should be used.
+     * 
+     * @param revocationEnabled
+     *            {@code true} id the default revocation checking mechanism
+     *            should be used, otherwise {@code false}.
      */
     public void setRevocationEnabled(boolean revocationEnabled) {
         this.revocationEnabled = revocationEnabled;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the name of the signature provider.
+     * 
+     * @return the name of the signature provider, or {@code null} if none is
+     *         set.
      */
     public String getSigProvider() {
         return sigProvider;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Sets the name of the preferred signature provider.
+     * <p>
+     * If set, the specified provider will be preferred for creating signatures.
+     * If not set, the first provider found supporting creation of signatures
+     * will be used.
+     * 
+     * @param sigProvider
+     *            the name of the preferred signature provider, or {@code null}
+     *            if none is preferred.
      */
     public void setSigProvider(String sigProvider) {
         this.sigProvider = sigProvider;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the constraints that are required for the target certificate.
+     * 
+     * @return the constraints for the target certificate, or {@code null} if
+     *         none are set.
      */
     public CertSelector getTargetCertConstraints() {
         return (targetCertConstraints == null ? null
@@ -403,7 +525,11 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Sets the constraints that are required for the target certificate.
+     * 
+     * @param targetCertConstraints
+     *            the constraints for the target certificate, or {@code null} if
+     *            none should be used.
      */
     public void setTargetCertConstraints(CertSelector targetCertConstraints) {
         this.targetCertConstraints = (targetCertConstraints == null ? null
@@ -411,7 +537,9 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Clones this {@code PKIXParameters} instance.
+     * 
+     * @return the cloned instance.
      */
     public Object clone() {
         try {
@@ -431,7 +559,9 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a string representation of this {@code PKIXParameters} instance.
+     * 
+     * @return a string representation of this {@code PKIXParameters} instance.
      */
     public String toString() {
         StringBuffer sb =

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PolicyNode.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PolicyNode.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PolicyNode.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PolicyNode.java Tue Apr 28 17:01:41 2009
@@ -15,54 +15,70 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 import java.util.Iterator;
 import java.util.Set;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The interface to a valid policy tree node for the PKIX certification path
+ * validation algorithm.
+ * <p>
+ * Instances of this class are one of the outputs of the PKIX certification path
+ * validation algorithm.
  */
 public interface PolicyNode {
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the list of children of this node as an {@code Iterator}.
+     * 
+     * @return the list of children of this node as an {@code Iterator}.
      */
     public Iterator<? extends PolicyNode> getChildren();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the depth of this node in the policy tree.
+     * <p>
+     * the depth is zero based.
+     * 
+     * @return the depth of this node in the policy tree.
      */
     public int getDepth();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the expected policies for the next certificate to be valid.
+     * 
+     * @return the expected policies.
      */
     public Set<String> getExpectedPolicies();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the parent policy node.
+     * 
+     * @return the parent policy node.
      */
     public PolicyNode getParent();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the policy qualifiers associated with the policy of this node.
+     * 
+     * @return the policy qualifiers associated with the policy of this node.
      */
     public Set<? extends PolicyQualifierInfo> getPolicyQualifiers();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the valid policy of this node.
+     * 
+     * @return the valid policy of this node.
      */
     public String getValidPolicy();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns whether the certificate policy extension of the most recently
+     * processed certificate is marked as critical.
+     * 
+     * @return {@code true} if the extension is marked as critical, otherwise
+     *         {@code false}.
      */
     public boolean isCritical();
 }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PolicyQualifierInfo.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PolicyQualifierInfo.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PolicyQualifierInfo.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/PolicyQualifierInfo.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.IOException;
@@ -30,8 +25,8 @@
 
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * This class implements a policy qualifier as defined by the ASN.1
+ * {@code PolicyQualifierInfo} structure.
  */
 public class PolicyQualifierInfo {
     // This PolicyQualifierInfo DER encoding
@@ -44,7 +39,13 @@
     private final byte[] policyQualifier;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code PolicyQualifierInfo} from the specified encoded
+     * form.
+     * 
+     * @param encoded
+     *            the DER encoded policy qualifier.
+     * @throws IOException
+     *             the policy qualifier cannot be decoded.
      */
     public PolicyQualifierInfo(byte[] encoded) throws IOException {
         if (encoded == null) {
@@ -64,7 +65,9 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a ASN.1 DER encoded copy of policy qualifier info.
+     * 
+     * @return a ASN.1 DER encoded copy of policy qualifier info.
      */
     public final byte[] getEncoded() {
         byte[] ret = new byte[encoded.length];
@@ -73,14 +76,20 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the identifier (an OID) of this policy qualifier info.
+     * 
+     * @return the identifier of this policy qualifier info.
      */
     public final String getPolicyQualifierId() {
         return policyQualifierId;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a ASN.1 DER encoded copy of the qualifier of this policy
+     * qualifier info.
+     * 
+     * @return a ASN.1 DER encoded copy of the qualifier of this policy
+     *         qualifier info.
      */
     public final byte[] getPolicyQualifier() {
         if (policyQualifier == null) {
@@ -92,7 +101,11 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a string representation of this {@code PolicyQualifierInfo}
+     * instance.
+     * 
+     * @return a string representation of this {@code PolicyQualifierInfo}
+     *         instance.
      */
     public String toString() {
         StringBuffer sb =

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/TrustAnchor.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/TrustAnchor.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/TrustAnchor.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/TrustAnchor.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.IOException;
@@ -34,8 +29,13 @@
 
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * This class represents a trust anchor for validation of X.509 certification
+ * path.
+ * <p>
+ * It is a <i>trusted</i> certificate authority (CA) and includes the public key
+ * of the CA, the CA's name and the constraints for the validation of
+ * certification paths. The constructor also allows to specify a binary
+ * representation of a so called "Name Constraints" extension as a byte array.
  */
 public class TrustAnchor {
     // Most trusted CA as a X500Principal
@@ -50,7 +50,19 @@
     private final byte[] nameConstraints;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code TrustAnchor} with the specified certificate and name
+     * constraints.
+     * <p>
+     * The name constraints will be used as additional constraints during the
+     * validation of certification paths.
+     *
+     * @param trustedCert
+     *            the trusted certificate
+     * @param nameConstraints
+     *            the ASN.1 DER encoded form of the name constraints or {@code
+     *            null} if none.
+     * @throws IllegalArgumentException
+     *             if the decoding of the name constraints fail.
      */
     public TrustAnchor(X509Certificate trustedCert, byte[] nameConstraints) {
         if (trustedCert == null) {
@@ -72,7 +84,23 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code TrustAnchor} with the specified certificate
+     * authority name, its public key and the specified name constraints.
+     * <p>
+     * The name constraints will be used as additional constraints during the
+     * validation of certification paths.
+     *
+     * @param caName
+     *            the X.500 name of the certificate authority in RFC 2253
+     *            {@code String} format.
+     * @param caPublicKey
+     *            the public key of the certificate authority
+     * @param nameConstraints
+     *            the ASN.1 DER encoded form of the name constraints or {@code
+     *            null} if none.
+     * @throws IllegalArgumentException
+     *             if the {@code caName} is empty or if decoding of the name
+     *             constraints fail.
      */
     public TrustAnchor(String caName, PublicKey caPublicKey,
             byte[] nameConstraints) {
@@ -105,7 +133,22 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code TrustAnchor} with the specified certificate
+     * authority name as principal, its public key and the specified name
+     * constraints.
+     * <p>
+     * The name constraints will be used as additional constraints during the
+     * validation of certification paths.
+     * 
+     * @param caPrincipal
+     *            the name of the certificate authority as X500 principal.
+     * @param caPublicKey
+     *            the public key of the certificate authority.
+     * @param nameConstraints
+     *            the ASN.1 DER encoded form of the name constraints or {@code
+     *            null} if none.
+     * @throws IllegalArgumentException
+     *             if decoding of the name constraints fail.
      */
     public TrustAnchor(X500Principal caPrincipal,
             PublicKey caPublicKey, byte[] nameConstraints) {
@@ -132,7 +175,9 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a copy of the name constraints in ASN.1 DER encoded form.
+     * 
+     * @return a copy of the name constraints in ASN.1 DER encoded form.
      */
     public final byte[] getNameConstraints() {
         if (nameConstraints == null) {
@@ -145,35 +190,53 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the certificate of this <i>trusted</i> certificate authority.
+     * 
+     * @return the certificate of this CA or {@code null}, if the trust anchor
+     *         of this instance was not created with a certificate.
      */
     public final X509Certificate getTrustedCert() {
         return trustedCert;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the name of the certificate authority as {@code X500Principal}.
+     * 
+     * @return the name of the certificate authority or {@code null} if the
+     *         trust anchor of this instance was not created with a {@code
+     *         X500Principal}.
      */
     public final X500Principal getCA() {
         return caPrincipal;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the name of the certificate authority as {@code String} in RFC
+     * 2253 format.
+     * 
+     * @return the name of the certificate authority as {@code String} in RFC
+     *         2253 format or {@code null} if the trust anchor of this instance
+     *         was not created with a CA name.
      */
     public final String getCAName() {
         return caName;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the public key of the certificate authority.
+     * 
+     * @return the public key of the certificate authority or {@code null} if
+     *         the trust anchor if this instance was not created with a public
+     *         key.
      */
     public final PublicKey getCAPublicKey() {
         return caPublicKey;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a string representation of this {@code TrustAnchor} instance.
+     * 
+     * @return a string representation of this {@code TrustAnchor} instance.
      */
     public String toString() {
         StringBuffer sb = new StringBuffer("TrustAnchor: [\n"); //$NON-NLS-1$

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/X509CRL.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/X509CRL.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/X509CRL.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/cert/X509CRL.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexander Y. Kleymenov
-* @version $Revision$
-*/
-
 package java.security.cert;
 
 import java.io.ByteArrayInputStream;
@@ -42,19 +37,30 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * @com.intel.drl.spec_ref
+ * Abstract base class for X.509 certificate revocation lists (CRL).
+ * <p>
+ * More information regarding CRL can be found in RFC 2459,
+ * "Internet X.509 Public Key Infrastructure Certificate and CRL Profile" at <a
+ * href
+ * ="http://www.ietf.org/rfc/rfc2459.txt">http://www.ietf.org/rfc/rfc2459.txt
+ * </a>.
  */
 public abstract class X509CRL extends CRL implements X509Extension {
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code X509CRL} instance.
      */
     protected X509CRL() {
         super("X.509"); //$NON-NLS-1$
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns whether the specified object equals to this instance.
+     * 
+     * @param other
+     *            the object to compare.
+     * @return {@code true} if the specified object is equal to this, otherwise
+     *         {@code false}.
      */
     public boolean equals(Object other) {
         if (other == this) {
@@ -72,7 +78,9 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the hashcode of this CRL instance.
+     * 
+     * @return the hashcode.
      */
     public int hashCode() {
         try {
@@ -88,13 +96,31 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns this CRL in ASN.1 DER encoded form.
+     * 
+     * @return this CRL in ASN.1 DER encoded form.
+     * @throws CRLException
+     *             if encoding fails.
      */
     public abstract byte[] getEncoded() throws CRLException;
 
 
     /**
-     * @com.intel.drl.spec_ref
+     * Verifies this CRL by verifying that this CRL was signed with the
+     * corresponding private key to the specified public key.
+     * 
+     * @param key
+     *            the public key to verify this CRL with.
+     * @throws CRLException
+     *             if encoding or decoding fails.
+     * @throws NoSuchAlgorithmException
+     *             if a needed algorithm is not present.
+     * @throws InvalidKeyException
+     *             if the specified key is invalid.
+     * @throws NoSuchProviderException
+     *             if no provider can be found.
+     * @throws SignatureException
+     *             if errors occur on signatures.
      */
     public abstract void verify(PublicKey key)
                      throws CRLException, NoSuchAlgorithmException,
@@ -102,7 +128,24 @@
                             SignatureException;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Verifies this CRL by verifying that this CRL was signed with the
+     * corresponding private key to the specified public key. The signature
+     * verification engine of the specified provider will be used.
+     * 
+     * @param key
+     *            the public key to verify this CRL with.
+     * @param sigProvider
+     *            the name of the provider for the signature algorithm.
+     * @throws CRLException
+     *             if encoding decoding fails.
+     * @throws NoSuchAlgorithmException
+     *             if a needed algorithm is not present.
+     * @throws InvalidKeyException
+     *             if the specified key is invalid.
+     * @throws NoSuchProviderException
+     *             if the specified provider cannot be found.
+     * @throws SignatureException
+     *             if errors occur on signatures.
      */
     public abstract void verify(PublicKey key, String sigProvider)
                      throws CRLException, NoSuchAlgorithmException,
@@ -110,17 +153,24 @@
                             SignatureException;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the version number of this CRL.
+     * 
+     * @return the version number of this CRL.
      */
     public abstract int getVersion();
 
     /**
-     * @com.intel.drl.spec_ref
+     * <b>Do not use</b>, use {@link #getIssuerX500Principal()} instead. Returns
+     * the issuer as an implementation specific Principal object.
+     * 
+     * @return the issuer distinguished name.
      */
     public abstract Principal getIssuerDN();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the issuer distinguished name of this CRL.
+     * 
+     * @return the issuer distinguished name of this CRL.
      */
     public X500Principal getIssuerX500Principal() {
         try {
@@ -140,22 +190,37 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the {@code thisUpdate} value of this CRL.
+     * 
+     * @return the {@code thisUpdate} value of this CRL.
      */
     public abstract Date getThisUpdate();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the {@code nextUpdate} value of this CRL.
+     * 
+     * @return the {@code nextUpdate} value of this CRL, or {@code null} if none
+     *         is present.
      */
     public abstract Date getNextUpdate();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the CRL entry with the specified certificate serial number.
+     * 
+     * @param serialNumber
+     *            the certificate serial number to search for a CRL entry.
+     * @return the entry for the specified certificate serial number, or {@code
+     *         null} if not found.
      */
     public abstract X509CRLEntry getRevokedCertificate(BigInteger serialNumber);
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the CRL entry for the specified certificate.
+     * 
+     * @param certificate
+     *            the certificate to search a CRL entry for.
+     * @return the entry for the specified certificate, or {@code null} if not
+     *         found.
      */
     public X509CRLEntry getRevokedCertificate(X509Certificate certificate) {
         if (certificate == null) {
@@ -165,32 +230,49 @@
     }
         
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the set of revoked certificates.
+     * 
+     * @return the set of revoked certificates, or {@code null} if no revoked
+     *         certificates are in this CRL.
      */
     public abstract Set<? extends X509CRLEntry> getRevokedCertificates();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the {@code tbsCertList} information of this CRL in DER encoded
+     * form.
+     * 
+     * @return the CRL information in DER encoded form.
+     * @throws CRLException
+     *             if encoding fails.
      */
     public abstract byte[] getTBSCertList() throws CRLException;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the signature bytes of this CRL.
+     * 
+     * @return the signature bytes of this CRL.
      */
     public abstract byte[] getSignature();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the name of the signature algorithm.
+     * 
+     * @return the name of the signature algorithm.
      */
     public abstract String getSigAlgName();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the OID of the signature algorithm.
+     * 
+     * @return the OID of the signature algorithm.
      */
     public abstract String getSigAlgOID();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the parameters of the signature algorithm in DER encoded form.
+     * 
+     * @return the parameters of the signature algorithm in DER encoded form, or
+     *         {@code null} if not present.
      */
     public abstract byte[] getSigAlgParams();
 }



Mime
View raw message