harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r769463 [5/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/Security.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Security.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Security.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Security.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
  *  limitations under the License.
  */
 
-/**
-* @author Boris V. Kuznetsov
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.io.BufferedInputStream;
@@ -44,7 +39,9 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * For access to security providers and properties.
+ * {@code Security} is the central class in the Java Security API. It manages
+ * the list of security {@code Provider} that have been installed into this
+ * runtime environment.
  */
 public final class Security {
 
@@ -131,14 +128,17 @@
         secprops.put("security.provider.4", "org.bouncycastle.jce.provider.BouncyCastleProvider");  //$NON-NLS-1$ //$NON-NLS-2$
     }
 
-	/**
-	 * Deprecated method which returns null.
-	 * @param algName 
-	 * @param propName 
-	 * @return <code>null</code>
-	 *
-	 * @deprecated	Use AlgorithmParameters and KeyFactory instead
-	 */
+    /**
+     * Returns value for the specified algorithm with the specified name.
+     *
+     * @param algName
+     *            the name of the algorithm.
+     * @param propName
+     *            the name of the property.
+     * @return value of the property.
+     * @deprecated Use {@link AlgorithmParameters} and {@link KeyFactory}
+     *             instead.
+     */
     @Deprecated
     public static String getAlgorithmProperty(String algName, String propName) {
         if (algName == null || propName == null) {
@@ -159,8 +159,25 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Insert the given {@code Provider} at the specified {@code position}. The
+     * positions define the preference order in which providers are searched for
+     * requested algorithms.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code insertProvider.NAME} (where NAME is
+     * the provider name) to be granted, otherwise a {@code SecurityException}
+     * will be thrown.
+     *
+     * @param provider
+     *            the provider to insert.
+     * @param position
+     *            the position (starting from 1).
+     * @return the actual position or {@code -1} if the given {@code provider}
+     *         was already in the list. The actual position may be different
+     *         from the desired position.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
      */
     public static synchronized int insertProviderAt(Provider provider,
             int position) {
@@ -180,22 +197,46 @@
         return result;
     }
 
-	/**
-	 * Adds the extra provider to the collection of providers.
-	 * @param provider 
-	 * 
-	 * @return int The priority/position of the provider added.
-	 * @exception SecurityException
-	 *                If there is a SecurityManager installed and it denies
-	 *                adding a new provider.
-	 */
+    /**
+     * Adds the given {@code provider} to the collection of providers at the
+     * next available position.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code insertProvider.NAME} (where NAME is
+     * the provider name) to be granted, otherwise a {@code SecurityException}
+     * will be thrown.
+     *
+     * @param provider
+     *            the provider to be added.
+     * @return the actual position or {@code -1} if the given {@code provider}
+     *         was already in the list.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
+     */
     public static int addProvider(Provider provider) {
         return insertProviderAt(provider, 0);
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Removes the {@code Provider} with the specified name form the collection
+     * of providers. If the the {@code Provider} with the specified name is
+     * removed, all provider at a greater position are shifted down one
+     * position.
+     * <p>
+     * Returns silently if {@code name} is {@code null} or no provider with the
+     * specified name is installed.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code removeProvider.NAME} (where NAME is
+     * the provider name) to be granted, otherwise a {@code SecurityException}
+     * will be thrown.
+     *
+     * @param name
+     *            the name of the provider to remove.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
      */
     public static synchronized void removeProvider(String name) {
         // It is not clear from spec.:
@@ -222,34 +263,51 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns an array containing all installed providers. The providers are
+     * ordered according their preference order.
+     *
+     * @return an array containing all installed providers.
      */
     public static synchronized Provider[] getProviders() {
         return Services.getProviders();
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the {@code Provider} with the specified name. Returns {@code
+     * null} if name is {@code null} or no provider with the specified name is
+     * installed.
+     *
+     * @param name
+     *            the name of the requested provider.
+     * @return the provider with the specified name, maybe {@code null}.
      */
     public static synchronized Provider getProvider(String name) {
         return Services.getProvider(name);
     }
 
-	/**
-	 * Returns the collection of providers which meet the user supplied string
-	 * filter.
-	 * 
-	 * @param filter
-	 *            case-insensitive filter
-	 * @return the providers which meet the user supplied string filter
-	 *         <code>filter</code>. A <code>null</code> value signifies
-	 *         that none of the installed providers meets the filter
-	 *         specification
-	 * @exception InvalidParameterException
-	 *                if an unusable filter is supplied
-	 */
+    /**
+     * Returns the array of providers which meet the user supplied string
+     * filter. The specified filter must be supplied in one of two formats:
+     * <nl>
+     * <li> CRYPTO_SERVICE_NAME.ALGORITHM_OR_TYPE
+     * <p>
+     * (for example: "MessageDigest.SHA")
+     * <li> CRYPTO_SERVICE_NAME.ALGORITHM_OR_TYPE
+     * ATTR_NAME:ATTR_VALUE
+     * <p>
+     * (for example: "Signature.MD2withRSA KeySize:512")
+     * </nl>
+     *
+     * @param filter
+     *            case-insensitive filter.
+     * @return the providers which meet the user supplied string filter {@code
+     *         filter}. A {@code null} value signifies that none of the
+     *         installed providers meets the filter specification.
+     * @throws InvalidParameterException
+     *             if an unusable filter is supplied.
+     * @throws NullPointerException
+     *             if {@code filter} is {@code null}.
+     */
     public static Provider[] getProviders(String filter) {
         if (filter == null) {
             throw new NullPointerException(Messages.getString("security.2A")); //$NON-NLS-1$
@@ -273,8 +331,28 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the array of providers which meet the user supplied set of
+     * filters. The filter must be supplied in one of two formats:
+     * <nl>
+     * <li> CRYPTO_SERVICE_NAME.ALGORITHM_OR_TYPE
+     * <p>
+     * for example: "MessageDigest.SHA" The value associated with the key must
+     * be an empty string. <li> CRYPTO_SERVICE_NAME.ALGORITHM_OR_TYPE
+     * ATTR_NAME:ATTR_VALUE
+     * <p>
+     * for example: "Signature.MD2withRSA KeySize:512" where "KeySize:512" is
+     * the value of the filter map entry.
+     * </nl>
+     *
+     * @param filter
+     *            case-insensitive filter.
+     * @return the providers which meet the user supplied string filter {@code
+     *         filter}. A {@code null} value signifies that none of the
+     *         installed providers meets the filter specification.
+     * @throws InvalidParameterException
+     *             if an unusable filter is supplied.
+     * @throws NullPointerException
+     *             if {@code filter} is {@code null}.
      */
     public static synchronized Provider[] getProviders(Map<String,String> filter) {
         if (filter == null) {
@@ -340,19 +418,21 @@
         }
     }
 
-	/**
-	 * Answers the value of the security property named by the argument.
-	 * 
-	 * 
-	 * @param key
-	 *            String The property name
-	 * @return String The property value
-	 * 
-	 * @exception SecurityException
-	 *                If there is a SecurityManager installed and it will not
-	 *                allow the property to be fetched from the current access
-	 *                control context.
-	 */
+    /**
+     * Returns the value of the security property named by the argument.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code getProperty.KEY} (where KEY is the
+     * specified {@code key}) to be granted, otherwise a {@code
+     * SecurityException} will be thrown.
+     *
+     * @param key
+     *            the name of the requested security property.
+     * @return the value of the security property.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
+     */
     public static String getProperty(String key) {
         if (key == null) {
             throw new NullPointerException(Messages.getString("security.2C")); //$NON-NLS-1$
@@ -368,19 +448,22 @@
         return property;
     }
 
-	/**
-	 * Sets a given security property.
-	 * 
-	 * 
-	 * @param key
-	 *            String The property name.
-	 * @param datnum
-	 *            String The property value.
-	 * @exception SecurityException
-	 *                If there is a SecurityManager installed and it will not
-	 *                allow the property to be set from the current access
-	 *                control context.
-	 */
+    /**
+     * Sets the value of the specified security property.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code setProperty.KEY} (where KEY is the
+     * specified {@code key}) to be granted, otherwise a {@code
+     * SecurityException} will be thrown.
+     *
+     * @param key
+     *            the name of the security property.
+     * @param datnum
+     *            the value of the security property.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
+     */
     public static void setProperty(String key, String datnum) {
         SecurityManager sm = System.getSecurityManager();
         if (sm != null) {
@@ -390,8 +473,16 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns a {@code Set} of all registered algorithms for the specified
+     * cryptographic service. {@code "Signature"}, {@code "Cipher"} and {@code
+     * "KeyStore"} are examples for such kind of services.
+     *
+     * @param serviceName
+     *            the case-insensitive name of the service.
+     * @return a {@code Set} of all registered algorithms for the specified
+     *         cryptographic service, or an empty {@code Set} if {@code
+     *         serviceName} is {@code null} or if no registered provider
+     *         provides the requested service.
      */
     public static Set<String> getAlgorithms(String serviceName) {
         Set<String> result = new HashSet<String>();
@@ -409,7 +500,7 @@
 
     /**
      * 
-     * Update sequence numbers of all providers
+     * Update sequence numbers of all providers.
      *  
      */
     private static void renumProviders() {

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecurityPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecurityPermission.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecurityPermission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecurityPermission.java Tue Apr 28 17:01:41 2009
@@ -15,44 +15,37 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexey V. Varlamov
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * SecurityPermission objects guard access to the mechanisms which implement
- * security. Security permissions have names, but not actions.
- * 
+ * {@code SecurityPermission} objects guard access to the mechanisms which
+ * implement security. Security permissions have names, but not actions.
  */
 public final class SecurityPermission extends BasicPermission {
 
-    /** 
-     * @com.intel.drl.spec_ref 
-     */
     private static final long serialVersionUID = 5236109936224050470L;
 
-	/**
-	 * Creates an instance of this class with the given name.
-	 * 
-	 * @param name
-	 *            String the name of the new permission.
-	 */
+    /**
+     * Constructs a new instance of {@code SecurityPermission} with the given
+     * name.
+     *
+     * @param name
+     *            the name of the permission.
+     */
     public SecurityPermission(String name) {
         super(name);
     }
 
-	/**
-	 * Creates an instance of this class with the given name and action list.
-	 * The action list is ignored.
-	 * 
-	 * @param name
-	 *            String the name of the new permission.
-	 * @param action
-	 *            String ignored.
-	 */
+    /**
+     * Constructs a new instance of {@code SecurityPermission} with the given
+     * {@code name} and {@code action} list. The action list is ignored - it is
+     * existing for compatibility reasons only.
+     *
+     * @param name
+     *            the name of the permission.
+     * @param action
+     *            ignored.
+     */
     public SecurityPermission(String name, String action) {
         super(name, action);
     }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Signature.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Signature.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Signature.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Signature.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
  *  limitations under the License.
  */
 
-/**
-* @author Boris V. Kuznetsov
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.nio.ByteBuffer;
@@ -34,10 +29,12 @@
 
 
 /**
- * @com.intel.drl.spec_ref
+ * {@code Signature} is an engine class which is capable of creating and
+ * verifying digital signatures, using different algorithms that have been
+ * registered with the {@link Security} class.
  * 
+ * @see SignatureSpi
  */
-
 public abstract class Signature extends SignatureSpi {
     
     // The service name.
@@ -53,40 +50,53 @@
     private String algorithm;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Constant that indicates that this {@code Signature} instance has not yet
+     * been initialized.
      */
     protected static final int UNINITIALIZED = 0;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Constant that indicates that this {@code Signature} instance has been
+     * initialized for signing.
      */
     protected static final int SIGN = 2;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Constant that indicates that this {@code Signature} instance has been
+     * initialized for verification.
      */
     protected static final int VERIFY = 3;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Represents the current state of this {@code Signature}. The three
+     * possible states are {@link #UNINITIALIZED}, {@link #SIGN} or
+     * {@link #VERIFY}.
      */
     protected int state = UNINITIALIZED;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Constructs a new instance of {@code Signature} with the name of
+     * the algorithm to use.
+     *
+     * @param algorithm
+     *            the name of algorithm to use.
      */
     protected Signature(String algorithm) {
         this.algorithm = algorithm;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns a new instance of {@code Signature} that utilizes the specified
+     * algorithm.
+     *
+     * @param algorithm
+     *            the name of the algorithm to use.
+     * @return a new instance of {@code Signature} that utilizes the specified
+     *         algorithm.
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm is not available.
+     * @throws NullPointerException
+     *             if {@code algorithm} is {@code null}.
      */
     public static Signature getInstance(String algorithm)
             throws NoSuchAlgorithmException {
@@ -109,8 +119,21 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns a new instance of {@code Signature} that utilizes the specified
+     * algorithm from the specified provider.
+     *
+     * @param algorithm
+     *            the name of the algorithm to use.
+     * @param provider
+     *            the name of the provider.
+     * @return a new instance of {@code Signature} that utilizes the specified
+     *         algorithm from the specified provider.
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm is not available.
+     * @throws NoSuchProviderException
+     *             if the specified provider is not available.
+     * @throws NullPointerException
+     *             if {@code algorithm} is {@code null}.
      */
     public static Signature getInstance(String algorithm, String provider)
             throws NoSuchAlgorithmException, NoSuchProviderException {
@@ -129,8 +152,19 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns a new instance of {@code Signature} that utilizes the specified
+     * algorithm from the specified provider.
+     *
+     * @param algorithm
+     *            the name of the algorithm to use.
+     * @param provider
+     *            the security provider.
+     * @return a new instance of {@code Signature} that utilizes the specified
+     *         algorithm from the specified provider.
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm is not available.
+     * @throws NullPointerException
+     *             if {@code algorithm} is {@code null}.
      */
     public static Signature getInstance(String algorithm, Provider provider)
             throws NoSuchAlgorithmException {
@@ -161,24 +195,32 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the provider associated with this {@code Signature}.
+     *
+     * @return the provider associated with this {@code Signature}.
      */
     public final Provider getProvider() {
         return provider;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the name of the algorithm of this {@code Signature}.
+     *
+     * @return the name of the algorithm of this {@code Signature}.
      */
     public final String getAlgorithm() {
         return algorithm;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code Signature} instance for signature verification,
+     * using the public key of the identity whose signature is going to be
+     * verified.
+     *
+     * @param publicKey
+     *            the public key.
+     * @throws InvalidKeyException
+     *             if {@code publicKey} is not valid.
      */
     public final void initVerify(PublicKey publicKey)
             throws InvalidKeyException {
@@ -187,8 +229,19 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code Signature} instance for signature verification,
+     * using the certificate of the identity whose signature is going to be
+     * verified.
+     * <p>
+     * If the given certificate is an instance of {@link X509Certificate} and
+     * has a key usage parameter that indicates, that this certificate is not to
+     * be used for signing, an {@code InvalidKeyException} is thrown.
+     *
+     * @param certificate
+     *            the certificate used to verify a signature.
+     * @throws InvalidKeyException
+     *             if the publicKey in the certificate is not valid or not to be
+     *             used for signing.
      */
     public final void initVerify(Certificate certificate)
             throws InvalidKeyException {
@@ -224,8 +277,13 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code Signature} instance for signing, using the
+     * private key of the identity whose signature is going to be generated.
+     *
+     * @param privateKey
+     *            the private key.
+     * @throws InvalidKeyException
+     *             if {@code privateKey} is not valid.
      */
     public final void initSign(PrivateKey privateKey)
             throws InvalidKeyException {
@@ -234,8 +292,16 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code Signature} instance for signing, using the
+     * private key of the identity whose signature is going to be generated and
+     * the specified source of randomness.
+     *
+     * @param privateKey
+     *            the private key.
+     * @param random
+     *            the {@code SecureRandom} to use.
+     * @throws InvalidKeyException
+     *             if {@code privateKey} is not valid.
      */
     public final void initSign(PrivateKey privateKey, SecureRandom random)
             throws InvalidKeyException {
@@ -244,8 +310,16 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Generates and returns the signature of all updated data.
+     * <p>
+     * This {@code Signature} instance is reset to the state of its last
+     * initialization for signing and thus can be used for another signature
+     * from the same identity.
+     *
+     * @return the signature of all updated data.
+     * @throws SignatureException
+     *             if this {@code Signature} instance is not initialized
+     *             properly.
      */
     public final byte[] sign() throws SignatureException {
         if (state != SIGN) {
@@ -256,8 +330,26 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Generates and stores the signature of all updated data in the provided
+     * {@code byte[]} at the specified position with the specified length.
+     * <p>
+     * This {@code Signature} instance is reset to the state of its last
+     * initialization for signing and thus can be used for another signature
+     * from the same identity.
+     *
+     * @param outbuf
+     *            the buffer to store the signature.
+     * @param offset
+     *            the index of the first byte in {@code outbuf} to store.
+     * @param len
+     *            the number of bytes allocated for the signature.
+     * @return the number of bytes stored in {@code outbuf}.
+     * @throws SignatureException
+     *             if this {@code Signature} instance is not initialized
+     *             properly.
+     * @throws IllegalArgumentException
+     *             if {@code offset} or {@code len} are not valid in respect to
+     *             {@code outbuf}.
      */
     public final int sign(byte[] outbuf, int offset, int len)
             throws SignatureException {       
@@ -274,8 +366,20 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Indicates whether the given {@code signature} can be verified using the
+     * public key or a certificate of the signer.
+     * <p>
+     * This {@code Signature} instance is reset to the state of its last
+     * initialization for verifying and thus can be used to verify another
+     * signature of the same signer.
+     *
+     * @param signature
+     *            the signature to verify.
+     * @return {@code true} if the signature was verified, {@code false}
+     *         otherwise.
+     * @throws SignatureException
+     *             if this {@code Signature} instance is not initialized
+     *             properly.
      */
     public final boolean verify(byte[] signature) throws SignatureException {
         if (state != VERIFY) {
@@ -286,8 +390,28 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Indicates whether the given {@code signature} starting at index {@code
+     * offset} with {@code length} bytes can be verified using the public key or
+     * a certificate of the signer.
+     * <p>
+     * This {@code Signature} instance is reset to the state of its last
+     * initialization for verifying and thus can be used to verify another
+     * signature of the same signer.
+     *
+     * @param signature
+     *            the {@code byte[]} containing the signature to verify.
+     * @param offset
+     *            the start index in {@code signature} of the signature.
+     * @param length
+     *            the number of bytes allocated for the signature.
+     * @return {@code true} if the signature was verified, {@code false}
+     *         otherwise.
+     * @throws SignatureException
+     *             if this {@code Signature} instance is not initialized
+     *             properly.
+     * @throws IllegalArgumentException
+     *             if {@code offset} or {@code length} are not valid in respect
+     *             to {@code signature}.
      */
     public final boolean verify(byte[] signature, int offset, int length)
             throws SignatureException {
@@ -304,8 +428,14 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Updates the data to be verified or to be signed, using the specified
+     * {@code byte}.
+     *
+     * @param b
+     *            the byte to update with.
+     * @throws SignatureException
+     *             if this {@code Signature} instance is not initialized
+     *             properly.
      */
     public final void update(byte b) throws SignatureException {
         if (state == UNINITIALIZED) {
@@ -316,8 +446,14 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Updates the data to be verified or to be signed, using the specified
+     * {@code byte[]}.
+     *
+     * @param data
+     *            the byte array to update with.
+     * @throws SignatureException
+     *             if this {@code Signature} instance is not initialized
+     *             properly.
      */
     public final void update(byte[] data) throws SignatureException {
         if (state == UNINITIALIZED) {
@@ -328,8 +464,18 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Updates the data to be verified or to be signed, using the given {@code
+     * byte[]}, starting form the specified index for the specified length.
+     *
+     * @param data
+     *            the byte array to update with.
+     * @param off
+     *            the start index in {@code data} of the data.
+     * @param len
+     *            the number of bytes to use.
+     * @throws SignatureException
+     *             if this {@code Signature} instance is not initialized
+     *             properly.
      */
     public final void update(byte[] data, int off, int len)
             throws SignatureException {
@@ -346,8 +492,14 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Updates the data to be verified or to be signed, using the specified
+     * {@code ByteBuffer}.
+     *
+     * @param data
+     *            the {@code ByteBuffer} to update with.
+     * @throws SignatureException
+     *             if this {@code Signature} instance is not initialized
+     *             properly.
      */
     public final void update(ByteBuffer data) throws SignatureException {
         if (state == UNINITIALIZED) {
@@ -358,8 +510,10 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns a string containing a concise, human-readable description of this
+     * {@code Signature} including its algorithm and its state.
+     *
+     * @return a printable representation for this {@code Signature}.
      */
     public String toString() {
         return "SIGNATURE " + algorithm + " state: " + stateToString(state); //$NON-NLS-1$ //$NON-NLS-2$
@@ -380,9 +534,16 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
-     * @deprecated Use {@link Signature#setParameter(AlgorithmParameterSpec) setParameter}
+     * Sets the specified parameter to the given value.
+     *
+     * @param param
+     *            the name of the parameter.
+     * @param value
+     *            the parameter value.
+     * @throws InvalidParameterException
+     *             if the parameter is invalid, already set or is not allowed to
+     *             be changed.
+     * @deprecated Use {@link #setParameter(AlgorithmParameterSpec)}
      */
     @Deprecated
     public final void setParameter(String param, Object value)
@@ -391,8 +552,13 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Sets the specified {@code AlgorithmParameterSpec}.
+     *
+     * @param params
+     *            the parameter to set.
+     * @throws InvalidAlgorithmParameterException
+     *             if the parameter is invalid, already set or is not allowed to
+     *             be changed.
      */
     public final void setParameter(AlgorithmParameterSpec params)
             throws InvalidAlgorithmParameterException {
@@ -400,16 +566,26 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the {@code AlgorithmParameters} of this {@link Signature}
+     * instance.
+     *
+     * @return the {@code AlgorithmParameters} of this {@link Signature}
+     *         instance, maybe {@code null}.
      */
     public final AlgorithmParameters getParameters() {
         return engineGetParameters();
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the value of the parameter with the specified name.
      * 
+     * @param param
+     *            the name of the requested parameter value
+     * @return the value of the parameter with the specified name, maybe {@code
+     *         null}.
+     * @throws InvalidParameterException
+     *             if {@code param} is not a valid parameter for this {@code
+     *             Signature} or an other error occures.
      * @deprecated There is no generally accepted parameter naming convention.
      */
     @Deprecated
@@ -418,10 +594,6 @@
         return engineGetParameter(param);
     }
 
-    /**
-     * @com.intel.drl.spec_ref
-     *  
-     */
     public Object clone() throws CloneNotSupportedException {
         if (this instanceof Cloneable) {
             return super.clone();

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

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignatureSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignatureSpi.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignatureSpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignatureSpi.java Tue Apr 28 17:01:41 2009
@@ -14,10 +14,6 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  */
-/**
-* @author Boris V. Kuznetsov
-* @version $Revision$
-*/
 
 package java.security;
 
@@ -27,35 +23,54 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * @com.intel.drl.spec_ref
+ * {@code SignatureSpi} is the <i>Service Provider Interface</i> (<b>SPI</b>)
+ * definition for {@link Signature}.
  * 
+ * @see Signature
  */
-
 public abstract class SignatureSpi {
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Implementation specific source of randomness.
      */
     protected SecureRandom appRandom;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code SignatureSpi} instance for signature
+     * verification, using the public key of the identity whose signature is
+     * going to be verified.
+     *
+     * @param publicKey
+     *            the public key.
+     * @throws InvalidKeyException
+     *             if {@code publicKey} is not valid.
      */
     protected abstract void engineInitVerify(PublicKey publicKey)
             throws InvalidKeyException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code SignatureSpi} instance for signing, using the
+     * private key of the identity whose signature is going to be generated.
+     *
+     * @param privateKey
+     *            the private key.
+     * @throws InvalidKeyException
+     *             if {@code privateKey} is not valid.
      */
     protected abstract void engineInitSign(PrivateKey privateKey)
             throws InvalidKeyException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code SignatureSpi} instance for signing, using the
+     * private key of the identity whose signature is going to be generated and
+     * the specified source of randomness.
+     *
+     * @param privateKey
+     *            the private key.
+     * @param random
+     *            the {@code SecureRandom} to use.
+     * @throws InvalidKeyException
+     *             if {@code privateKey} is not valid.
      */
     protected void engineInitSign(PrivateKey privateKey, SecureRandom random)
             throws InvalidKeyException {
@@ -64,24 +79,45 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Updates the data to be verified or to be signed, using the specified
+     * {@code byte}.
+     *
+     * @param b
+     *            the byte to update with.
+     * @throws SignatureException
+     *             if this {@code SignatureSpi} instance is not initialized
+     *             properly.
      */
     protected abstract void engineUpdate(byte b) throws SignatureException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Updates the data to be verified or to be signed, using the given {@code
+     * byte[]}, starting form the specified index for the specified length.
+     *
+     * @param b
+     *            the byte array to update with.
+     * @param off
+     *            the start index in {@code b} of the data.
+     * @param len
+     *            the number of bytes to use.
+     * @throws SignatureException
+     *             if this {@code SignatureSpi} instance is not initialized
+     *             properly.
      */
     protected abstract void engineUpdate(byte[] b, int off, int len)
             throws SignatureException;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Updates the data to be verified or to be signed, using the specified
+     * {@code ByteBuffer}.
      * 
-     * The SignatureException is not specified for this method. 
-     * So throw RuntimeException if underlying engineUpdate(byte[] b, int off, int len)
-     * throws SignatureException.
+     * @param input
+     *            the {@code ByteBuffer} to update with.
+     * @throws RuntimeException
+     *             since {@code SignatureException} is not specified for this
+     *             method it throws a {@code RuntimeException} if underlying
+     *             {@link #engineUpdate(byte[], int, int)} throws {@code
+     *             SignatureException}.
      */
     protected void engineUpdate(ByteBuffer input) {
         if (!input.hasRemaining()) {
@@ -111,14 +147,40 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Generates and returns the signature of all updated data.
+     * <p>
+     * This {@code SignatureSpi} instance is reset to the state of its last
+     * initialization for signing and thus can be used for another signature
+     * from the same identity.
+     *
+     * @return the signature of all updated data.
+     * @throws SignatureException
+     *             if this {@code SignatureSpi} instance is not initialized
+     *             properly.
      */
     protected abstract byte[] engineSign() throws SignatureException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Generates and stores the signature of all updated data in the provided
+     * {@code byte[]} at the specified position with the specified length.
+     * <p>
+     * This {@code SignatureSpi} instance is reset to the state of its last
+     * initialization for signing and thus can be used for another signature
+     * from the same identity.
+     *
+     * @param outbuf
+     *            the buffer to store the signature.
+     * @param offset
+     *            the index of the first byte in {@code outbuf} to store.
+     * @param len
+     *            the number of bytes allocated for the signature.
+     * @return the number of bytes stored in {@code outbuf}.
+     * @throws SignatureException
+     *             if this {@code SignatureSpi} instance is not initialized
+     *             properly.
+     * @throws IllegalArgumentException
+     *             if {@code offset} or {@code len} are not valid in respect to
+     *             {@code outbuf}.
      */
     protected int engineSign(byte[] outbuf, int offset, int len)
             throws SignatureException {
@@ -140,15 +202,47 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Indicates whether the given {@code sigBytes} can be verified using the
+     * public key or a certificate of the signer.
+     * <p>
+     * This {@code SignatureSpi} instance is reset to the state of its last
+     * initialization for verifying and thus can be used to verify another
+     * signature of the same signer.
+     *
+     * @param sigBytes
+     *            the signature to verify.
+     * @return {@code true} if the signature was verified, {@code false}
+     *         otherwise.
+     * @throws SignatureException
+     *             if this {@code SignatureSpi} instance is not initialized
+     *             properly.
      */
     protected abstract boolean engineVerify(byte[] sigBytes)
             throws SignatureException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Indicates whether the given {@code sigBytes} starting at index {@code
+     * offset} with {@code length} bytes can be verified using the public key or
+     * a certificate of the signer.
+     * <p>
+     * This {@code SignatureSpi} instance is reset to the state of its last
+     * initialization for verifying and thus can be used to verify another
+     * signature of the same signer.
+     *
+     * @param sigBytes
+     *            the {@code byte[]} containing the signature to verify.
+     * @param offset
+     *            the start index in {@code sigBytes} of the signature
+     * @param length
+     *            the number of bytes allocated for the signature.
+     * @return {@code true} if the signature was verified, {@code false}
+     *         otherwise.
+     * @throws SignatureException
+     *             if this {@code SignatureSpi} instance is not initialized
+     *             properly.
+     * @throws IllegalArgumentException
+     *             if {@code offset} or {@code length} are not valid in respect
+     *             to {@code sigBytes}.
      */
     protected boolean engineVerify(byte[] sigBytes, int offset, int length)
             throws SignatureException {
@@ -158,18 +252,29 @@
     }
 
     /**
-	 * @com.intel.drl.spec_ref
-	 * 
-	 * @deprecated Use
-	 *             {@link SignatureSpi#engineSetParameter(AlgorithmParameterSpec) engineSetParameter}
-	 */
+     * Sets the specified parameter to the given value.
+     *
+     * @param param
+     *            the name of the parameter.
+     * @param value
+     *            the parameter value.
+     * @throws InvalidParameterException
+     *             if the parameter is invalid, already set or is not allowed to
+     *             be changed.
+     * @deprecated Use {@link #engineSetParameter(AlgorithmParameterSpec)}
+     */
     @Deprecated
     protected abstract void engineSetParameter(String param, Object value)
             throws InvalidParameterException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Sets the specified {@code AlgorithmParameterSpec}.
+     *
+     * @param params
+     *            the parameter to set.
+     * @throws InvalidAlgorithmParameterException
+     *             if the parameter is invalid, already set or is not allowed to
+     *             be changed.
      */
     protected void engineSetParameter(AlgorithmParameterSpec params)
             throws InvalidAlgorithmParameterException {
@@ -177,26 +282,32 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the {@code AlgorithmParameters} of this {@link SignatureSpi}
+     * instance.
+     *
+     * @return the {@code AlgorithmParameters} of this {@link SignatureSpi}
+     *         instance, maybe {@code null}.
      */
     protected AlgorithmParameters engineGetParameters() {
         throw new UnsupportedOperationException();
     }
 
     /**
-	 * @com.intel.drl.spec_ref
-	 * 
-	 * @deprecated There is no generally accepted parameter naming convention.
-	 */
+     * Returns the value of the parameter with the specified name.
+     *
+     * @param param
+     *            the name of the requested parameter value.
+     * @return the value of the parameter with the specified name, maybe {@code
+     *         null}.
+     * @throws InvalidParameterException
+     *             if {@code param} is not a valid parameter for this {@code
+     *             SignatureSpi} or an other error occurs.
+     * @deprecated There is no generally accepted parameter naming convention.
+     */
     @Deprecated
     protected abstract Object engineGetParameter(String param)
             throws InvalidParameterException;
 
-    /**
-     * @com.intel.drl.spec_ref
-     *  
-     */
     public Object clone() throws CloneNotSupportedException {
         if (this instanceof Cloneable) {
             return super.clone();

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignedObject.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignedObject.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignedObject.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignedObject.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
  *  limitations under the License.
  */
 
-/**
-* @author Boris V. Kuznetsov
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.io.ByteArrayInputStream;
@@ -30,35 +25,20 @@
 import java.io.Serializable;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * A {@code SignedObject} instance acts as a container for another object. The
+ * {@code SignedObject} contains the target in serialized form along with a
+ * digital signature of the serialized data.
  */
 public final class SignedObject implements Serializable {
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private static final long serialVersionUID = 720502720485447167L;
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private byte[] content;
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private byte[] signature;
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private String thealgorithm;
 
-    /**
-     * @com.intel.drl.spec_ref
-     * 
-     */
     private void readObject(ObjectInputStream s) throws IOException,
             ClassNotFoundException {
 
@@ -72,8 +52,22 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     * 
+     * Constructs a new instance of {@code SignedObject} with the target object,
+     * the private key and the engine to compute the signature. The given
+     * {@code object} is signed with the specified key and engine.
+     * 
+     * @param object
+     *            the object to bes signed.
+     * @param signingKey
+     *            the private key, used to sign the {@code object}.
+     * @param signingEngine
+     *            the engine that performs the signature generation.
+     * @throws IOException
+     *             if a serialization error occurs.
+     * @throws InvalidKeyException
+     *             if the private key is not valid.
+     * @throws SignatureException
+     *             if signature generation failed.
      */
     public SignedObject(Serializable object, PrivateKey signingKey,
             Signature signingEngine) throws IOException, InvalidKeyException,
@@ -96,8 +90,14 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the encapsulated object. Each time this method is invoked, the
+     * encapsulated object is deserialized before it is returned.
      * 
+     * @return the encapsulated object.
+     * @throws IOException
+     *             if deserialization failed.
+     * @throws ClassNotFoundException
+     *             if the class of the encapsulated object can not be found.
      */
     public Object getObject() throws IOException, ClassNotFoundException {
         // deserialize our object
@@ -111,8 +111,9 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the signature data of the encapsulated serialized object.
      * 
+     * @return the signature data of the encapsulated serialized object.
      */
     public byte[] getSignature() {
         byte[] sig = new byte[signature.length];
@@ -121,16 +122,28 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the name of the algorithm of this {@code SignedObject}.
      * 
+     * @return the name of the algorithm of this {@code SignedObject}.
      */
     public String getAlgorithm() {
         return thealgorithm;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Indicates whether the contained signature for the encapsulated object is
+     * valid.
      * 
+     * @param verificationKey
+     *            the public key to verify the signature.
+     * @param verificationEngine
+     *            the signature engine.
+     * @return {@code true} if the contained signature for the encapsulated
+     *         object is valid, {@code false} otherwise.
+     * @throws InvalidKeyException
+     *             if the public key is invalid.
+     * @throws SignatureException
+     *             if signature verification failed.
      */
     public boolean verify(PublicKey verificationKey,
             Signature verificationEngine) throws InvalidKeyException,

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Signer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Signer.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Signer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Signer.java Tue Apr 28 17:01:41 2009
@@ -15,49 +15,51 @@
  *  limitations under the License.
  */
 
-/**
- * @author Aleksei Y. Semenov
- * @version $Revision$
- */
-
 package java.security;
 
 /**
- * @com.intel.drl.spec_ref
+ * {@link Signer} represents an identity (individual or corporation) that owns a
+ * private key and the corresponding public key.
  * 
- * @deprecated Replaced by behavior in
- *             {@link java.security.cert java.security.cert} package and
- *             {@link java.security.Principal Principal}
+ * @deprecated Replaced by behavior in {@link java.security.cert
+ *             java.security.cert} package and {@link java.security.Principal
+ *             Principal}
  */
 @Deprecated
 public abstract class Signer extends Identity {
 
-    /**
-     * @com.intel.drl.spec_ref 
-     */
     private static final long serialVersionUID = -1763464102261361480L;
 
-    /**
-     * @com.intel.drl.spec_ref 
-     */
     private PrivateKey privateKey;
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Constructs a new instance of {@code Signer}.
      */
     protected Signer() {
         super();
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Constructs a new instance of {@code Signer} with the given name.
+     *
+     * @param name
+     *            the name of the signer.
      */
     public Signer(String name) {
         super(name);
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Constructs a new instance of {@code Signer} with the given name in the
+     * given scope.
+     *
+     * @param name
+     *            the name of the signer.
+     * @param scope
+     *            the scope of the signer.
+     * @throws KeyManagementException
+     *             if a signer with the specified name already exists in the
+     *             provided scope.
      */
     public Signer(String name, IdentityScope scope)
             throws KeyManagementException {
@@ -65,7 +67,15 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Returns the private key of this {@code Signer}. If a {@code
+     * SecurityManager} is installed, code calling this method needs the {@code
+     * SecurityPermission} {@code "getSignerPrivateKey"} to be granted, otherwise
+     * a {@code SecurityException} will be thrown.
+     *
+     * @return the private key of this {@code Signer}.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
      */
     public PrivateKey getPrivateKey() {
         SecurityManager sm = System.getSecurityManager();
@@ -77,7 +87,20 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Associates the specified key pair with this {@code Signer}. If a {@code
+     * SecurityManager} is installed, code calling this method needs the {@code
+     * SecurityPermission} {@code getSignerPrivateKey} to be granted, otherwise
+     * a {@code SecurityException} will be thrown.
+     *
+     * @param pair
+     *            the key pair to associate with this {@code Signer}.
+     * @throws InvalidParameterException
+     *             if the key pair is invalid.
+     * @throws KeyException
+     *             if any other key related problem occurs.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
      */
     public final void setKeyPair(KeyPair pair)
             throws InvalidParameterException, KeyException {
@@ -108,7 +131,10 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Returns a string containing a concise, human-readable description of this
+     * {@code Signer} including its name and its scope if present.
+     *
+     * @return a printable representation for this {@code Signer}.
      */
     public String toString() {
         String s = "[Signer]" + getName(); //$NON-NLS-1$

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Timestamp.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Timestamp.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Timestamp.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Timestamp.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexander V. Astapchuk
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.io.Serializable;
@@ -29,14 +24,11 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * @com.intel.drl.spec_ref 
+ * {@code Timestamp} represents a signed time stamp. {@code Timestamp} is
+ * immutable.
  */
-
 public final class Timestamp implements Serializable {
 
-    /**
-     * @com.intel.drl.spec_ref 
-     */
     private static final long serialVersionUID = -5502683707821851294L;
 
     private Date timestamp;
@@ -47,7 +39,16 @@
     private transient int hash;
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Constructs a new instance of {@code Timestamp} with the specified {@code
+     * timestamp} and the given certificate path.
+     *
+     * @param timestamp
+     *            date and time.
+     * @param signerCertPath
+     *            the certificate path.
+     * @throws NullPointerException
+     *             if {@code timestamp} is {@code null} or if {@code
+     *             signerCertPath} is {@code null}.
      */
     public Timestamp(Date timestamp, CertPath signerCertPath) {
         if (timestamp == null) {
@@ -62,7 +63,18 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Compares the specified object with this {@code Timestamp} for equality
+     * and returns {@code true} if the specified object is equal, {@code false}
+     * otherwise. The given object is equal to this {@code Timestamp}, if it is
+     * an instance of {@code Timestamp}, the two timestamps have an equal date
+     * and time and their certificate paths are equal.
+     *
+     * @param obj
+     *            object to be compared for equality with this {@code
+     *            Timestamp}.
+     * @return {@code true} if the specified object is equal to this {@code
+     *         Timestamp}, otherwise {@code false}.
+     * @see #hashCode
      */
     public boolean equals(Object obj) {
         if (obj == this) {
@@ -77,21 +89,31 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Returns the certificate path of this {@code Timestamp}.
+     *
+     * @return the certificate path of this {@code Timestamp}.
      */
     public CertPath getSignerCertPath() {
         return signerCertPath;
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Returns the date and time of this {@code Timestamp}.
+     *
+     * @return the date and time of this {@code Timestamp}.
      */
     public Date getTimestamp() {
         return (Date) timestamp.clone();
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Returns the hash code value for this {@code Timestamp}. Returns the same
+     * hash code for {@code Timestamp}s that are equal to each other as
+     * required by the general contract of {@link Object#hashCode}.
+     *
+     * @return the hash code value for this {@code Timestamp}.
+     * @see Object#equals(Object)
+     * @see Timestamp#equals(Object)
      */
     public int hashCode() {
         if (hash == 0) {
@@ -101,7 +123,10 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Returns a string containing a concise, human-readable description of this
+     * {@code Timestamp}.
+     *
+     * @return a printable representation for this {@code Timestamp}.
      */
     public String toString() {
         StringBuffer buf = new StringBuffer(256);

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

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnrecoverableKeyException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnrecoverableKeyException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnrecoverableKeyException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnrecoverableKeyException.java Tue Apr 28 17:01:41 2009
@@ -15,40 +15,32 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * This class represents exceptions if a key cannot be found in the keystore.
+ * {@code UnrecoverableKeyException} indicates, that a key cannot be recovered
+ * from a {@code KeyStore}.
  * 
+ * @see KeyStore
  */
 public class UnrecoverableKeyException extends GeneralSecurityException {
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private static final long serialVersionUID = 7275063078190151277L;
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * 
-	 * @param msg
-	 *            String The detail message for the exception.
-	 */
+    /**
+     * Constructs a new instance of {@code UnrecoverableKeyException} with the
+     * given message.
+     *
+     * @param msg
+     *            the detail message for this exception
+     */
     public UnrecoverableKeyException(String msg) {
         super(msg);
     }
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 * 
-	 */
+    /**
+     * Constructs a new instance of {@code UnrecoverableKeyException}.
+     */
     public UnrecoverableKeyException() {
     }
 }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnresolvedPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnresolvedPermission.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnresolvedPermission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnresolvedPermission.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexey V. Varlamov
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.io.ByteArrayInputStream;
@@ -37,20 +32,15 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * Holds permissions which are of an unknown type when a policy file is read.
- *
- * Technically, the resolution of UnresolvedPermissions and
- * substitution by actual permissions takes place in the
- * <code>implies()</code> method of a <code>Permissions</code>
- * collection, right before actual checking.
- * 
+ * An {@code UnresolvedPermission} represents a {@code Permission} whose type
+ * should be resolved lazy and not during initialization time of the {@code
+ * Policy}. {@code UnresolvedPermission}s contain all information to be replaced
+ * by a concrete typed {@code Permission} right before the access checks are
+ * performed.
  */
 public final class UnresolvedPermission extends Permission
     implements Serializable {
 
-    /** 
-     * @com.intel.drl.spec_ref 
-     */
     private static final long serialVersionUID = -4821973115467008846L;
 
     private String type;    
@@ -65,17 +55,26 @@
     // Cached hash value
     private transient int hash;
 
-	/**
-	 * Constructs a new instance of this class with its type, name, and
-	 * certificates set to the arguments by definition, actions are ignored
-	 * 
-	 * @param type
-	 *            class of permission object
-	 * @param name
-	 *            identifies the permission that could not be resolved
-	 * @param actions
-	 * @param certs
-	 */
+    /**
+     * Constructs a new instance of {@code UnresolvedPermission}. The supplied
+     * parameters are used when this instance is resolved to the concrete
+     * {@code Permission}.
+     *
+     * @param type
+     *            the fully qualified class name of the permission this class is
+     *            resolved to.
+     * @param name
+     *            the name of the permission this class is resolved to, maybe
+     *            {@code null}.
+     * @param actions
+     *            the actions of the permission this class is resolved to, maybe
+     *            {@code null}.
+     * @param certs
+     *            the certificates of the permission this class is resolved to,
+     *            maybe {@code null}.
+     * @throws NullPointerException
+     *             if type is {@code null}.
+     */
     public UnresolvedPermission(String type, String name, String actions,
                                 Certificate[] certs) {
         super(type);
@@ -105,19 +104,20 @@
         // }
     }
 
-	/**
-	 * Compares the argument to the receiver, and answers true if they represent
-	 * the <em>same</em> object using a class specific comparison. In this
-	 * case, the receiver and the object must have the same class, permission
-	 * name, actions, and certificates
-	 * 
-	 * @param obj
-	 *            the object to compare with this object
-	 * @return <code>true</code> if the object is the same as this object,
-	 *         <code>false</code> otherwise.
-	 * 
-	 * @see #hashCode
-	 */
+    /**
+     * Compares the specified object with this {@code UnresolvedPermission} for
+     * equality and returns {@code true} if the specified object is equal,
+     * {@code false} otherwise. To be equal, the specified object needs to be an
+     * instance of {@code UnresolvedPermission}, the two {@code
+     * UnresolvedPermission}s must refer to the same type and must have the same
+     * name, the same actions and certificates.
+     *
+     * @param obj
+     *            object to be compared for equality with this {@code
+     *            UnresolvedPermission}.
+     * @return {@code true} if the specified object is equal to this {@code
+     *         UnresolvedPermission}, otherwise {@code false}.
+     */
     public boolean equals(Object obj) {
         if (obj == this) {
             return true;
@@ -191,14 +191,15 @@
     }
 
     /**
-	 * 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 the hash code value for this {@code UnresolvedPermission}.
+     * Returns the same hash code for {@code UnresolvedPermission}s that are
+     * equal to each other as required by the general contract of
+     * {@link Object#hashCode}.
+     *
+     * @return the hash code value for this {@code UnresolvedPermission}.
+     * @see Object#equals(Object)
+     * @see UnresolvedPermission#equals(Object)
+     */
     public int hashCode() {
         if (hash == 0) {
             hash = getName().hashCode();
@@ -212,39 +213,56 @@
         return hash;
     }
 
-	/**
-	 * Answers the actions associated with the receiver. Since
-	 * UnresolvedPermission objects have no actions, answer the empty string.
-	 * 
-	 * @return the actions associated with the receiver.
-	 */
+    /**
+     * Returns an empty string since there are no actions allowed for {@code
+     * UnresolvedPermission}. The actions, specified in the constructor, are
+     * used when the concrete permission is resolved and created.
+     *
+     * @return an empty string, indicating that there are no actions.
+     */
     public String getActions() {
         return ""; //$NON-NLS-1$
     }
 
-    /** 
-     * @com.intel.drl.spec_ref 
+    /**
+     * Returns the name of the permission this {@code UnresolvedPermission} is
+     * resolved to.
+     *
+     * @return the name of the permission this {@code UnresolvedPermission} is
+     *         resolved to.
      */
     public String getUnresolvedName() {
         return name;
     }
 
-    /** 
-     * @com.intel.drl.spec_ref 
+    /**
+     * Returns the actions of the permission this {@code UnresolvedPermission}
+     * is resolved to.
+     *
+     * @return the actions of the permission this {@code UnresolvedPermission}
+     *         is resolved to.
      */
     public String getUnresolvedActions() {
         return actions;
     }
 
-    /** 
-     * @com.intel.drl.spec_ref 
+    /**
+     * Returns the fully qualified class name of the permission this {@code
+     * UnresolvedPermission} is resolved to.
+     *
+     * @return the fully qualified class name of the permission this {@code
+     *         UnresolvedPermission} is resolved to.
      */
     public String getUnresolvedType() {
         return super.getName();
     }
 
-    /** 
-     * @com.intel.drl.spec_ref 
+    /**
+     * Returns the certificates of the permission this {@code
+     * UnresolvedPermission} is resolved to.
+     *
+     * @return the certificates of the permission this {@code
+     *         UnresolvedPermission} is resolved to.
      */
     public Certificate[] getUnresolvedCerts() {
         if (targetCerts != null) {
@@ -255,61 +273,62 @@
         return null;
     }
 
-	/**
-	 * Indicates whether the argument permission is implied by the
-	 * receiver.  UnresolvedPermission objects imply nothing
-	 * because nothing is known about them yet.
-	 * 
-         * Before actual implication checking, this method tries to
-         * resolve UnresolvedPermissions (if any) against the passed
-         * instance. Successfully resolved permissions (if any) are
-         * taken into account during further processing.
-         *
-	 * @param permission
-	 *            the permission to check
-	 * @return always replies false
-	 */
+    /**
+     * Indicates whether the specified permission is implied by this {@code
+     * UnresolvedPermission}. {@code UnresolvedPermission} objects imply nothing
+     * since nothing is known about them yet.
+     * <p>
+     * Before actual implication checking, this method tries to resolve
+     * UnresolvedPermissions (if any) against the passed instance. Successfully
+     * resolved permissions (if any) are taken into account during further
+     * processing.
+     *
+     * @param permission
+     *            the permission to check.
+     * @return always {@code false}
+     */
     public boolean implies(Permission permission) {
         return false;
     }
 
-	/**
-	 * 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 this
+     * {@code UnresolvedPermission} including its target name and its target
+     * actions.
+     *
+     * @return a printable representation for this {@code UnresolvedPermission}.
+     */
     public String toString() {
         return "(unresolved " + type + " " + name + " " //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$
             + actions + ")"; //$NON-NLS-1$
     }
 
-	/**
-	 * Answers a new PermissionCollection for holding permissions of this class.
-	 * Answer null if any permission collection can be used.
-	 * 
-	 * @return a new PermissionCollection or null
-	 * 
-	 * @see java.security.BasicPermissionCollection
-	 */
+    /**
+     * Returns a new {@code PermissionCollection} for holding {@code
+     * UnresolvedPermission} objects.
+     *
+     * @return a new PermissionCollection for holding {@code
+     *         UnresolvedPermission} objects.
+     */
     public PermissionCollection newPermissionCollection() {
         return new UnresolvedPermissionCollection();
     }
 
     /**
-     * Tries to resolve this permission into the specified class. It is assumed
-     * that the class has a proper name (as returned by <code>getName()</code>
-     * of this unresolved permission), so no check is performed to verify this.
-     * However, the class must have all required certificates (as per
-     * <code>getUnresolvedCerts()</code>) among the passed collection of
-     * signers. If it does, a zero, one, and/or two-argument constructor is
-     * tried to instantiate a new permission, which is then returned. <br>
-     * If an appropriate constructor is not available or the class is
-     * improperly signed, <code>null</code> is returned.
-     * 
-     * @param targetType - a target class instance, must not be
-     *        <code>null</code>
-     * @param signers - actual signers of the targetType
+     * Tries to resolve this permission into the specified class.
+     * <p>
+     * It is assumed that the class has a proper name (as returned by {@code
+     * getName()} of this unresolved permission), so no check is performed to
+     * verify this. However, the class must have all required certificates (as
+     * per {@code getUnresolvedCerts()}) among the passed collection of signers.
+     * If it does, a zero, one, and/or two-argument constructor is tried to
+     * instantiate a new permission, which is then returned.
+     * <p>
+     * If an appropriate constructor is not available or the class is improperly
+     * signed, {@code null} is returned.
+     *
+     * @param targetType
+     *            - a target class instance, must not be {@code null}
      * @return resolved permission or null
      */
     Permission resolve(Class targetType) {
@@ -329,7 +348,7 @@
     /**
      * @com.intel.drl.spec_ref
      * 
-     * Outputs <code>type</code>,<code>name</code>,<code>actions</code>
+     * Outputs {@code type},{@code name},{@code actions}
      * fields via default mechanism; next manually writes certificates in the
      * following format: <br>
      *

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnresolvedPermissionCollection.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnresolvedPermissionCollection.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnresolvedPermissionCollection.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnresolvedPermissionCollection.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexey V. Varlamov
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.io.IOException;
@@ -41,15 +36,12 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * Specific PermissionCollection for storing UnresolvedPermissions. Contained
- * elements are grouped by their target type.
- * 
+ * {@code UnresolvedPermissionCollection} represents a specific {@code
+ * PermissionCollection} for storing {@link UnresolvedPermission} instances.
+ * Contained elements are grouped by their target type.
  */
 final class UnresolvedPermissionCollection extends PermissionCollection {
 
-    /** 
-     * @com.intel.drl.spec_ref 
-     */
     private static final long serialVersionUID = -7176153071733132400L;
 
     private static final ObjectStreamField[] serialPersistentFields = { 
@@ -59,9 +51,16 @@
     private transient Map klasses = new HashMap();
 
     /**
-     * Adds an unresolved permission to the collection.
+     * Adds an unresolved permission to this {@code
+     * UnresolvedPermissionCollection}.
      * 
-     * @see java.security.PermissionCollection#add(java.security.Permission)
+     * @param permission
+     *            the permission to be added.
+     * @throws SecurityException
+     *             if this collection is read only.
+     * @throws IllegalArgumentException
+     *             if {@code permission} is {@code null} or not an {@code
+     *             UnresolvedPermission}.
      */
     public void add(Permission permission) {
         if (isReadOnly()) {
@@ -83,11 +82,6 @@
         }
     }
 
-    /**
-     * Returns enumeration over collection elements.
-     * 
-     * @see java.security.PermissionCollection#elements()
-     */
     public Enumeration elements() {
         Collection all = new ArrayList();
         for (Iterator iter = klasses.values().iterator(); iter.hasNext();) {
@@ -97,9 +91,10 @@
     }
 
     /**
-     * Always returns false.
+     * Always returns {@code false}.
      * 
-     * @see java.security.UnresolvedPermission#implies(Permission)
+     * @return always {@code false}
+     * @see UnresolvedPermission#implies(Permission).
      */
     public boolean implies(Permission permission) {
         return false;
@@ -116,13 +111,15 @@
     /**
      * Resolves all permissions of the same class as the specified target
      * permission and adds them to the specified collection. If passed
-     * collection is <code>null</code> and some unresolved permissions were
-     * resolved, an appropriate new collection is instantiated and used. All
-     * resolved permissions are removed from this unresolved collection, and
-     * collection with resolved ones is returned.
-     * 
-     * @param target - a kind of permissions to be resolved
-     * @param holder - an existing collection for storing resolved permissions
+     * collection is {@code null} and some unresolved permissions were resolved,
+     * an appropriate new collection is instantiated and used. All resolved
+     * permissions are removed from this unresolved collection, and collection
+     * with resolved ones is returned.
+     * 
+     * @param target
+     *            a kind of permissions to be resolved.
+     * @param holder
+     *            an existing collection for storing resolved permissions.
      * @return a collection containing resolved permissions (if any found)
      */
     PermissionCollection resolveCollection(Permission target,

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Acl.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Acl.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Acl.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Acl.java Tue Apr 28 17:01:41 2009
@@ -15,61 +15,153 @@
  *  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</i> (<b>ACL</b>) interface definition.
+ * <p>
+ * An ACL is a set of {@link AclEntry} objects.
+ * <p>
+ * An {@code AclEntry} is a list of {@link Permission}s that are granted 
+ * (<i>positive</i>) or denied
+ * (<i>negative</i>) to a {@link Principal}.
+ * <p>
+ * An {@code Acl} has a list of owners ({@link Owner}) which are principals as
+ * well {@code Principal}. Only those principals which are the {@code Acl}'s
+ * owners are allowed to modify the {@code
+ * Acl}.
+ * <p>
+ * The <i>ACL</i> has to conform to the following rules:
+ * <ul>
+ * <li>For each {@code Principal} there can be only one <i>positive</i> and one
+ * <i>negative</i> {@code AclEntry}.</li>
+ * <li>If the two {@code AclEntry}'s (<i>positive</i> and <i>negative</i>) for a
+ * specific {@code Principal} grant and deny the same {@code Permission} to that
+ * {@code Principal}, then that {@code Permission} is treated as
+ * neither granted nor denied to that {@code Principal}.</li>
+ * <li>Permissions associated with an individual {@code Principal} always
+ * override permissions of the group(s) to which the individual belongs.</li>
+ * <li>If there is no {@code AclEntry} associated with a specific {@code
+ * Principal}, then it is interpreted as an empty list of permissions.</li>
+ * </ul>
  */
 public interface Acl extends Owner {
 
     /**
-     * @com.intel.drl.spec_ref
+     * Sets the name of this <i>ACL</i> instance.
+     * 
+     * @param caller
+     *            the invoking {@code Principal}.
+     * @param name
+     *            the name to be set.
+     * @throws NotOwnerException
+     *             if the invoking {@code Principal} is not an owner of this
+     *             <i>ACL</i>.
      */
     void setName(Principal caller, String name) throws NotOwnerException;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the name of this <i>ACL</i> instance.
+     * 
+     * @return the name of this <i>ACL</i> instance.
      */
     String getName();
 
     /**
-     * @com.intel.drl.spec_ref
+     * Adds an {@code AclEntry} to this <i>ACL</i> instance.
+     * <p>
+     * If the <i>ACL</i> already has an {@code AclEntry} of the same type (<i>
+     * positive</i> or <i>negative</i>) and principal, then the new entry is not added.
+     *
+     * @param caller
+     *            the invoking {@code Principal}.
+     * @param entry
+     *            the ACL entry to add.
+     * @return {@code true} if the entry is added, {@code false} if there is
+     *             already an entry of the same type for the same principal
+     * @throws NotOwnerException
+     *             if the invoking {@code Principal} is not an owner of this
+     *             <i>ACL</i>.
      */
     boolean addEntry(Principal caller, AclEntry entry) throws NotOwnerException;
     
     /**
-     * @com.intel.drl.spec_ref
+     * Removes an {@code AclEntry} from this <i>ACL</i> instance.
+     * 
+     * @param caller
+     *            the invoking {@code Principal}.
+     * @param entry
+     *            the ACL entry to remove.
+     * @return {@code true} if the entry is removed, {@code false} if the entry
+     *            is not in this <i>ACL</i>.
+     * @throws NotOwnerException
+     *             if the invoking {@code Principal} is not an owner of this
+     *             <i>ACL</i>.
      */
     boolean removeEntry(Principal caller, AclEntry entry) 
                 throws NotOwnerException;
     
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the set of allowed permissions for the specified {@code
+     * Principal}.
+     * <p>
+     * If the specified principal has no entry in this ACL, an empty set is
+     * returned.
+     * <p>
+     * The allowed permissions are collected according to the following rules:
+     * <ul>
+     * <li>The two permission lists (<i>positive</i> and <i>negative</i>) of the
+     * principal's groups ({@link Group}) are collected. The positive (granted)
+     * permissions are the union of all group's positive permissions that the
+     * principal belongs to, the negative (denied) permissions are the union of
+     * all group's negative permissions that the principal belongs to. If a
+     * specific permission is in both the positive and the negative list, it is
+     * removed from both lists.</li>
+     * <li>The individual permissions (<i>positive</i> and <i>negative</i>) of
+     * the principal override the group permissions. The positive individual
+     * permissions override the group's negative permissions and the negative
+     * individual permissions override the grpup's positive permissions.</li>
+     * </ul>
+     *
+     * @param user
+     *            the principal to get the allowed permissions for.
+     * @return the set of allowed permissions for the specified principal.
      */
     Enumeration<Permission> getPermissions(Principal user); 
     
     /**
-     * @com.intel.drl.spec_ref
+     * Returns an {@code Enumeration} of the {@code AclEntry} of this
+     * <i>ACL</i>.
+     * 
+     * @return an {@code Enumeration} of the {@code AclEntry} of this
+     *         <i>ACL</i>.
      */
     Enumeration<AclEntry> entries();
     
     /**
-     * @com.intel.drl.spec_ref
+     * Checks whether the specified principal is granted the specified
+     * permission.
+     * <p>
+     * The list of granted permissions is determined according to the rules
+     * specified by {@code getPermissions}.
+     *
+     * @param principal
+     *            the principal the check the permissions for.
+     * @param permission
+     *            the permission to check for the principal.
+     * @return {@code true} if the principal is granted the permission,
+     *            otherwise {@code false}.
+     * @see #getPermissions(Principal)
      */
     boolean checkPermission(Principal principal, Permission permission);
     
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the string representation of this ACL.
+     * 
+     * @return the string representation of this ACL.
      */
     String toString();
 }



Mime
View raw message