harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r769463 [4/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/PermissionCollection.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PermissionCollection.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PermissionCollection.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PermissionCollection.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.Serializable;
@@ -28,81 +23,77 @@
 import java.util.List;
 
 /**
- * Abstract superclass of classes which are collections of Permission objects.
- * 
+ * {@code PermissionCollection} is the common base class for all collections
+ * that provide a convenient method for determining whether or not a given
+ * permission is implied by any of the permissions present in this collection.
+ * <p>
+ * A {@code PermissionCollection} is typically created by using the
+ * {@link Permission#newPermissionCollection()} factory method. If the mentioned
+ * method returns {@code null}, then a {@code PermissionCollection} of any type
+ * can be used. If a collection is returned, it must be used for holding several
+ * permissions of the particular type.
+ * <p>
+ * Subclasses must be implemented thread save.
  */
 public abstract class PermissionCollection implements Serializable {
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private static final long serialVersionUID = -6727011328946861783L;
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private boolean readOnly; // = false;
 
     /**
-     * Adds the argument to the collection.
-     * 
+     * Adds the specified {@code Permission} to this collection.
      * 
      * @param permission
-     *            java.security.Permission the permission to add to the
-     *            collection.
-     * @exception IllegalStateException
-     *                if the collection is read only.
+     *            the {@code Permission} to add.
+     * @throws IllegalStateException
+     *             if the collection is read only.
      */
     public abstract void add(Permission permission);
 
     /**
-     * Answers an enumeration of the permissions in the receiver.
-     * 
+     * Returns an enumeration over all {@link Permission}s encapsulated by this
+     * {@code PermissionCollection}.
      * 
-     * @return Enumeration the permissions in the receiver.
+     * @return an enumeration over all {@link Permission}s.
      */
     public abstract Enumeration<Permission> elements();
 
     /**
-     * Indicates whether the argument permission is implied by the permissions
-     * contained in the receiver.
-     * 
+     * Indicates whether the specified permission is implied by this {@code
+     * PermissionCollection}.
      * 
-     * @return boolean <code>true</code> if the argument permission is implied
-     *         by the permissions in the receiver, and <code>false</code> if
-     *         it is not.
      * @param permission
-     *            java.security.Permission the permission to check
+     *            the permission to check.
+     * @return {@code true} if the given permission is implied by the
+     *         permissions in this collection, {@code false} otherwise.
      */
     public abstract boolean implies(Permission permission);
 
     /**
-     * Indicates whether new permissions can be added to the receiver.
+     * Indicates whether new permissions can be added to this {@code
+     * PermissionCollection}.
      * 
-     * 
-     * @return boolean <code>true</code> if the receiver is read only
-     *         <code>false</code> if new elements can still be added to the
-     *         receiver.
+     * @return {@code true} if the receiver is read only, {@code false} if new
+     *         elements can still be added to this {@code PermissionCollection}.
      */
     public boolean isReadOnly() {
         return readOnly;
     }
 
     /**
-     * Marks the receiver as read only, so that no new permissions can be added
-     * to it.
-     * 
+     * Marks this {@code PermissionCollection} as read only, so that no new
+     * permissions can be added to it.
      */
     public void setReadOnly() {
         readOnly = true;
     }
 
     /**
-     * Answers a string containing a concise, human-readable description of the
-     * receiver.
-     * 
+     * Returns a string containing a concise, human-readable description of this
+     * {@code PermissionCollection}.
      * 
-     * @return a printable representation for the receiver.
+     * @return a printable representation for this {@code PermissionCollection}.
      */
     public String toString() {
         List elist = new ArrayList(100);

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Permissions.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Permissions.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Permissions.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Permissions.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;
@@ -38,15 +33,16 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * A heterogeneous collection of permissions.
- * 
+ * {@code Permissions} represents a {@code PermissionCollection} where the
+ * contained permissions can be of different types. The permissions are
+ * organized in their appropriate {@code PermissionCollection} obtained by
+ * {@link Permission#newPermissionCollection()}. For permissions which do not
+ * provide a dedicated {@code PermissionCollection}, a default permission
+ * collection, based on a hash table, will be used.
  */
 public final class Permissions extends PermissionCollection implements
     Serializable {
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private static final long serialVersionUID = 4858622370623524688L;
 
     private static final ObjectStreamField[] serialPersistentFields = {
@@ -56,19 +52,21 @@
     // Hash to store PermissionCollection's
     private transient Map klasses = new HashMap();
 
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private boolean allEnabled;  // = false;
 
-	/**
-	 * Adds the argument to the collection.
-	 * 
-	 * 
-	 * @param permission
-	 *            java.security.Permission the permission to add to the
-	 *            collection
-	 */
+    /**
+     * Adds the given {@code Permission} to this heterogeneous {@code
+     * PermissionCollection}. The {@code permission} is stored in its
+     * appropriate {@code PermissionCollection}.
+     *
+     * @param permission
+     *            the {@code Permission} to be added.
+     * @throws SecurityException
+     *             if this collection's {@link #isReadOnly()} method returns
+     *             {@code true}.
+     * @throws NullPointerException
+     *             if {@code permission} is {@code null}.
+     */
     public void add(Permission permission) {
         if (isReadOnly()) {
             throw new SecurityException(Messages.getString("security.15")); //$NON-NLS-1$
@@ -102,12 +100,6 @@
         }
     }
 
-    /**
-     * Answers an enumeration of the permissions in the receiver.
-     * 
-     * 
-     * @return Enumeration the permissions in the receiver.
-     */
     public Enumeration<Permission> elements() {
         return new MetaEnumeration(klasses.values().iterator());
     }
@@ -169,17 +161,6 @@
         }
     }
 
-	/**
-	 * Indicates whether the argument permission is implied by the permissions
-	 * contained in the receiver.
-	 * 
-	 * 
-	 * @return boolean <code>true</code> if the argument permission is implied
-	 *         by the permissions in the receiver, and <code>false</code> if
-	 *         it is not.
-	 * @param permission
-	 *            java.security.Permission the permission to check
-	 */
     public boolean implies(Permission permission) {
         if (permission == null) {
             // RI compatible

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PermissionsHash.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PermissionsHash.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PermissionsHash.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PermissionsHash.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.util.Enumeration;
@@ -28,12 +23,12 @@
 import org.apache.harmony.security.internal.nls.Messages;
 
 /**
- * A default PermissionCollection implementation that uses a hashtable. Each
- * hashtable entry stores a Permission object as both the key and the value.
- * <br>
- * This PermissionCollection is intended for storing &quot;neutral&quot;
+ * A default {@code PermissionCollection} implementation that uses a hashtable.
+ * Each hashtable entry stores a Permission object as both the key and the
+ * value.
+ * <p>
+ * This {@code PermissionCollection} is intended for storing &quot;neutral&quot;
  * permissions which do not require special collection.
- * 
  */
 
 final class PermissionsHash extends PermissionCollection {
@@ -48,39 +43,35 @@
      */
     private final Hashtable perms = new Hashtable();
 
-	/**
-	 * Adds the argument to the collection.
-	 * 
-	 * 
-	 * @param permission
-	 *            java.security.Permission the permission to add to the
-	 *            collection
-	 */
+    /**
+     * Adds the argument to the collection.
+     *
+     * @param permission
+     *            the permission to add to the collection.
+     */
     public void add(Permission permission) {
         perms.put(permission, permission);
     }
 
-	/**
-	 * Answers an enumeration of the permissions in the receiver.
-	 * 
-	 * 
-	 * @return Enumeration the permissions in the receiver.
-	 */
+    /**
+     * Returns an enumeration of the permissions in the receiver.
+     *
+     * @return Enumeration the permissions in the receiver.
+     */
     public Enumeration elements() {
         return perms.elements();
     }
 
-	/**
-	 * Indicates whether the argument permission is implied by the permissions
-	 * contained in the receiver.
-	 * 
-	 * 
-	 * @return boolean <code>true</code> if the argument permission is implied
-	 *         by the permissions in the receiver, and <code>false</code> if
-	 *         it is not.
-	 * @param permission
-	 *            java.security.Permission the permission to check
-	 */
+    /**
+     * Indicates whether the argument permission is implied by the permissions
+     * contained in the receiver.
+     *
+     * @return boolean <code>true</code> if the argument permission is implied
+     *         by the permissions in the receiver, and <code>false</code> if
+     *         it is not.
+     * @param permission
+     *            java.security.Permission the permission to check
+     */
     public boolean implies(Permission permission) {
         for (Enumeration elements = elements(); elements.hasMoreElements();) {
             if (((Permission)elements.nextElement()).implies(permission)) {

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Policy.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Policy.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Policy.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Policy.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.util.Enumeration;
@@ -29,8 +24,15 @@
 
 
 /**
- * Abstract superclass of classes which represent the system security policy.
- * 
+ * {@code Policy} is the common super type of classes which represent a system
+ * security policy. The {@code Policy} specifies which permissions apply to
+ * which code sources.
+ * <p>
+ * The system policy can be changed by setting the {@code 'policy.provider'}
+ * property in the file named {@code JAVA_HOME/lib/security/java.security} to
+ * the fully qualified class name of the desired {@code Policy}.
+ * <p>
+ * Only one instance of a {@code Policy} is active at any time.
  */
 public abstract class Policy {
     
@@ -48,40 +50,43 @@
     // The policy currently in effect. 
     private static Policy activePolicy;
 
-	/**
-	 * Answers a PermissionCollection describing what permissions are available
-	 * to the given CodeSource based on the current security policy.
-	 * <p>
-	 * Note that this method is <em>not</em> called for classes which are in
-	 * the system domain (i.e. system classes). System classes are
-	 * <em>always</em> given full permissions (i.e. AllPermission). This can
-	 * not be changed by installing a new Policy.
-	 * 
-	 * 
-	 * @param cs
-	 *            CodeSource the code source to compute the permissions for.
-	 * @return PermissionCollection the permissions the code source should have.
-	 */
+    /**
+     * Returns a {@code PermissionCollection} describing what permissions are
+     * allowed for the specified {@code CodeSource} based on the current
+     * security policy.
+     * <p>
+     * Note that this method is not called for classes which are in the system
+     * domain (i.e. system classes). System classes are always given
+     * full permissions (i.e. AllPermission). This can not be changed by
+     * installing a new policy.
+     *
+     * @param cs
+     *            the {@code CodeSource} to compute the permissions for.
+     * @return the permissions that are granted to the specified {@code
+     *         CodeSource}.
+     */
     public abstract PermissionCollection getPermissions(CodeSource cs);
 
-	/**
-	 * Reloads the policy configuration, depending on how the type of source
-	 * location for the policy information.
-	 * 
-	 * 
-	 */
+    /**
+     * Reloads the policy configuration for this {@code Policy} instance.
+     */
     public abstract void refresh();
 
-	/**
-	 * Answers a PermissionCollection describing what permissions are available
-	 * to the given ProtectionDomain (more specifically, its CodeSource) based
-	 * on the current security policy.
-	 * 
-	 * @param domain
-	 *            ProtectionDomain the protection domain to compute the
-	 *            permissions for.
-	 * @return PermissionCollection the permissions the code source should have.
-	 */
+    /**
+     * Returns a {@code PermissionCollection} describing what permissions are
+     * allowed for the specified {@code ProtectionDomain} (more specifically,
+     * its {@code CodeSource}) based on the current security policy.
+     * <p>
+     * Note that this method is not< called for classes which are in the
+     * system domain (i.e. system classes). System classes are always
+     * given full permissions (i.e. AllPermission). This can not be changed by
+     * installing a new policy.
+     *
+     * @param domain
+     *            the {@code ProtectionDomain} to compute the permissions for.
+     * @return the permissions that are granted to the specified {@code
+     *         CodeSource}.
+     */
     public PermissionCollection getPermissions(ProtectionDomain domain) {
         if (domain != null) {
             return getPermissions(domain.getCodeSource());
@@ -89,16 +94,19 @@
         return new Permissions();
     }
 
-	/**
-	 * Answers whether the Permission is implied by the PermissionCollection of
-	 * the Protection Domain
-	 * 
-	 * @param domain
-	 *            ProtectionDomain for which Permission to be checked
-	 * @param permission
-	 *            Permission for which authorization is to be verified
-	 * @return boolean Permission implied by ProtectionDomain
-	 */
+    /**
+     * Indicates whether the specified {@code Permission} is implied by the
+     * {@code PermissionCollection} of the specified {@code ProtectionDomain}.
+     *
+     * @param domain
+     *            the {@code ProtectionDomain} for which the permission should
+     *            be granted.
+     * @param permission
+     *            the {@code Permission} for which authorization is to be
+     *            verified.
+     * @return {@code true} if the {@code Permission} is implied by the {@code
+     *         ProtectionDomain}, {@code false} otherwise.
+     */
     public boolean implies(ProtectionDomain domain, Permission permission) {
         if (domain != null) {
             PermissionCollection total = getPermissions(domain);
@@ -117,13 +125,20 @@
         return false;
     }
 
-	/**
-	 * Answers the current system security policy. If no policy has been
-	 * instantiated then this is done using the security property <EM>policy.provider</EM>
-	 * 
-	 * 
-	 * @return Policy the current system security policy.
-	 */
+    /**
+     * Returns the current system security policy. If no policy has been
+     * instantiated then this is done using the security property {@code
+     * "policy.provider"}.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code getPolicy} to be granted, otherwise
+     * a {@code SecurityException} will be thrown.
+     *
+     * @return the current system security policy.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
+     */
     public static Policy getPolicy() {
         SecurityManager sm = System.getSecurityManager();
         if (sm != null) {
@@ -169,7 +184,7 @@
     }
     
     /**
-     * Returns true if system policy provider is instantiated.
+     * Returns {@code true} if system policy provider is instantiated.
      */
     static boolean isSet() {
         return activePolicy != null;
@@ -196,13 +211,19 @@
         return current;
     }
 
-	/**
-	 * Sets the system-wide policy object if it is permitted by the security
-	 * manager.
-	 * 
-	 * @param policy
-	 *            Policy the policy object that needs to be set.
-	 */
+    /**
+     * Sets the system wide policy.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code setPolicy} to be granted, otherwise
+     * a {@code SecurityException} will be thrown.
+     *
+     * @param policy
+     *            the {@code Policy} to set.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
+     */
     public static void setPolicy(Policy policy) {
         SecurityManager sm = System.getSecurityManager();
         if (sm != null) {

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Principal.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Principal.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Principal.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Principal.java Tue Apr 28 17:01:41 2009
@@ -15,34 +15,50 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexander V. Astapchuk
-* @version $Revision$
-*/
-
 package java.security;
 
 
 /**
- * Principals are objects which have identities. These can be individuals,
- * groups, corporations, unique program executions, etc.
- * 
+ * {@code Principal}s are objects which have identities. These can be
+ * individuals, groups, corporations, unique program executions, etc.
  */
 public interface Principal {
-    /** 
-     * @com.intel.drl.spec_ref 
+    /**
+     * Compares the specified object with this {@code Principal} for equality
+     * and returns {@code true} if the specified object is equal, {@code false}
+     * otherwise.
+     *
+     * @param obj
+     *            object to be compared for equality with this {@code
+     *            Principal}.
+     * @return {@code true} if the specified object is equal to this {@code
+     *         Principal}, otherwise {@code false}.
      */
     public boolean equals( Object obj );
-    /** 
-     * @com.intel.drl.spec_ref 
+
+    /**
+     * Returns the name of this {@code Principal}.
+     *
+     * @return the name of this {@code Principal}.
      */
     public String getName();
-    /** 
-     * @com.intel.drl.spec_ref 
+
+    /**
+     * Returns the hash code value for this {@code Principal}. Returns the same
+     * hash code for {@code Principal}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 Principal}.
+     * @see Object#equals(Object)
+     * @see Principal#equals(Object)
      */
     public int hashCode();
-    /** 
-     * @com.intel.drl.spec_ref 
+
+    /**
+     * Returns a string containing a concise, human-readable description of
+     * this {@code Principal}.
+     *
+     * @return a printable representation for this {@code Principal}.
      */
     public String toString();
 }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PrivateKey.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PrivateKey.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PrivateKey.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PrivateKey.java Tue Apr 28 17:01:41 2009
@@ -15,20 +15,17 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * @com.intel.drl.spec_ref
+ * {@code PrivateKey} is the common interface for private keys.
  * 
+ * @see PublicKey
  */
 public interface PrivateKey extends Key {
+
     /**
-     * @com.intel.drl.spec_ref
+     * The {@code serialVersionUID} to be compatible with JDK1.1.
      */
     public static final long serialVersionUID = 6034044314589513430L;
 }
\ No newline at end of file

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PrivilegedAction.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PrivilegedAction.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PrivilegedAction.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PrivilegedAction.java Tue Apr 28 17:01:41 2009
@@ -15,20 +15,23 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexander V. Astapchuk
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * @com.intel.drl.spec_ref 
+ * {@code PrivilegedAction} represents an action that can be executed privileged
+ * regarding access control. Instances of {@code PrivilegedAction} can be
+ * executed on {@code AccessController.doPrivileged()}.
+ *
+ * @see AccessController
+ * @see AccessController#doPrivileged(PrivilegedAction)
+ * @see AccessController#doPrivileged(PrivilegedAction, AccessControlContext)
+ * @see PrivilegedExceptionAction
  */
-
 public interface PrivilegedAction<T> {
     /**
-     * @com.intel.drl.spec_ref 
+     * Returns the result of running the action.
+     *
+     * @return the result of running the action.
      */
     public T run();
 }
\ No newline at end of file

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PrivilegedActionException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PrivilegedActionException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PrivilegedActionException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PrivilegedActionException.java Tue Apr 28 17:01:41 2009
@@ -15,65 +15,73 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexander V. Astapchuk
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * Instances of this class are used to wrap exceptions which occur within
- * privileged operations.
- * 
+ * {@code PrivilegedActionException} wraps exceptions which are thrown from
+ * within privileged operations.
+ * <p>
+ * Privileged actions which can throw exceptions are of type {@code
+ * PrivilegedExceptionAction} and are thrown by
+ * <ul>
+ * {@code AccessController#doPrivileged(PrivilegedExceptionAction)}<br>
+ * {@code AccessController#doPrivileged(PrivilegedExceptionAction,
+ * AccessControlContext)} </br>
+ * </ul>
+ *
+ * @see PrivilegedExceptionAction
+ * @see AccessController#doPrivileged(PrivilegedExceptionAction)
+ * @see AccessController#doPrivileged(PrivilegedExceptionAction,
+ *      AccessControlContext)
  */
 public class PrivilegedActionException extends Exception {
 
-    /**
-     * @com.intel.drl.spec_ref 
-     */
     private static final long serialVersionUID = 4724086851538908602l;
 
-    /**
-     * @com.intel.drl.spec_ref 
-     */
     private Exception exception;
 
-	/**
-	 * Constructs a new instance of this class with its exception filled in.
-	 * @param ex 
-	 */
+    /**
+     * Constructs a new instance of {@code PrivilegedActionException} with the
+     * cause.
+     *
+     * @param ex
+     *            the exception which is the cause for this exception.
+     */
     public PrivilegedActionException(Exception ex) {
         super(ex);
         this.exception = ex;
     }
 
-	/**
-	 * Answers the exception which caused the receiver to be thrown.
-	 * @return exception
-	 */
+    /**
+     * Returns the exception that was thrown by a
+     * {@code PrivilegedExceptionAction}.
+     *
+     * @return the exception that was thrown by a
+     *         {@code PrivilegedExceptionAction}.
+     */
     public Exception getException() {
         return exception; // return ( getCause() instanceof Exception ) ?
         // getCause() : null;
     }
 
-	/**
-	 * Answers the cause of this Throwable, or null if there is no cause.
-	 * 
-	 * 
-	 * @return Throwable The receiver's cause.
-	 */
+    /**
+     * Returns the exception that was thrown by a
+     * {@code PrivilegedExceptionAction}.
+     *
+     * @return the exception that was thrown by a
+     *         {@code PrivilegedExceptionAction}.
+     */
     public Throwable getCause() {
         return exception;
     }
 
-	/**
-	 * Answers a string containing a concise, human-readable description of the
-	 * receiver.
-	 * 
-	 * 
-	 * @return String a printable representation for the receiver.
-	 */
+    /**
+     * Returns a string containing a concise, human-readable description of this
+     * {@code PrivilegedActionException}.
+     *
+     * @return a printable representation for this {@code
+     *         PrivilegedActionException}.
+     */
     public String toString() {
         String s = getClass().getName();
         return exception == null ? s : s + ": " + exception; //$NON-NLS-1$

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PrivilegedExceptionAction.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PrivilegedExceptionAction.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PrivilegedExceptionAction.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PrivilegedExceptionAction.java Tue Apr 28 17:01:41 2009
@@ -15,19 +15,26 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexander V. Astapchuk
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * @com.intel.drl.spec_ref
+ * {@code PrivilegedAction} represents an action, that can be executed
+ * privileged regarding access control. Instances of {@code PrivilegedAction}
+ * can be executed invoking {@code AccessController.doPrivileged()}.
+ *
+ * @see AccessController
+ * @see AccessController#doPrivileged(PrivilegedExceptionAction)
+ * @see AccessController#doPrivileged(PrivilegedExceptionAction,
+ *      AccessControlContext)
+ * @see PrivilegedAction
  */
 public interface PrivilegedExceptionAction<T> {
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the result of running the action.
+     *
+     * @return the result of running the action
+     * @throws Exception
+     *             if an exception occurred.
      */
     T run() throws Exception;
 }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/ProtectionDomain.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/ProtectionDomain.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/ProtectionDomain.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/ProtectionDomain.java Tue Apr 28 17:01:41 2009
@@ -15,19 +15,16 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexander V. Astapchuk
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * This class represents a domain in which classes from the same source (URL)
- * and signed by the same keys are stored. All the classes inside are given the
- * same permissions.
+ * {@code ProtectionDomain} represents all permissions that are granted to a
+ * specific code source. The {@link ClassLoader} associates each class with the
+ * corresponding {@code ProtectionDomain}, depending on the location and the
+ * certificates (encapsulates in {@link CodeSource}) it loads the code from.
  * <p>
- * Note: a class can only belong to one and only one protection domain.
+ * A class belongs to exactly one protection domain and the protection domain
+ * can not be changed during the lifetime of the class.
  */
 public class ProtectionDomain {
 
@@ -47,13 +44,29 @@
     // permissions, true otherwise. 
     private boolean dynamicPerms;
 
-	/**
-	 * Constructs a protection domain from the given code source and the
-	 * permissions that that should be granted to the classes which are
-	 * encapsulated in it.
-	 * @param cs 
-	 * @param permissions 
-	 */
+    /**
+     * Constructs a new instance of {@code ProtectionDomain} with the specified
+     * code source and the specified static permissions.
+     * <p>
+     * If {@code permissions} is not {@code null}, the {@code permissions}
+     * collection is made immutable by calling
+     * {@link PermissionCollection#setReadOnly()} and it is considered as
+     * granted statically to this {@code ProtectionDomain}.
+     * <p>
+     * The policy will not be consulted by access checks against this {@code
+     * ProtectionDomain}.
+     * <p>
+     * If {@code permissions} is {@code null}, the method {@link
+     * ProtectionDomain#implies(Permission)} always returns {@code false}.
+     *
+     * @param cs
+     *            the code source associated with this domain, maybe {@code
+     *            null}.
+     * @param permissions
+     *            the {@code PermissionCollection} containing all permissions to
+     *            be statically granted to this {@code ProtectionDomain}, maybe
+     *            {@code null}.
+     */
     public ProtectionDomain(CodeSource cs, PermissionCollection permissions) {
         this.codeSource = cs;
         if (permissions != null) {
@@ -65,23 +78,33 @@
         //dynamicPerms = false;
     }
 
-	/**
-	 * Constructs a protection domain from the given code source and the
-	 * permissions that that should be granted to the classes which are
-	 * encapsulated in it. 
-	 * 
-	 * This constructor also allows the association of a ClassLoader and group
-	 * of Principals.
-	 * 
-	 * @param cs
-	 *            the CodeSource associated with this domain
-	 * @param permissions
-	 *            the Permissions associated with this domain
-	 * @param cl
-	 *            the ClassLoader associated with this domain
-	 * @param principals
-	 *            the Principals associated with this domain
-	 */
+    /**
+     * Constructs a new instance of {@code ProtectionDomain} with the specified
+     * code source, the permissions, the class loader and the principals.
+     * <p>
+     * If {@code permissions} is {@code null}, and access checks are performed
+     * against this protection domain, the permissions defined by the policy are
+     * consulted. If {@code permissions} is not {@code null}, the {@code
+     * permissions} collection is made immutable by calling
+     * {@link PermissionCollection#setReadOnly()}. If access checks are
+     * performed, the policy and the provided permission collection are checked.
+     * <p>
+     * External modifications of the provided {@code principals} array has no
+     * impact on this {@code ProtectionDomain}.
+     *
+     * @param cs
+     *            the code source associated with this domain, maybe {@code
+     *            null}.
+     * @param permissions
+     *            the permissions associated with this domain, maybe {@code
+     *            null}.
+     * @param cl
+     *            the class loader associated with this domain, maybe {@code
+     *            null}.
+     * @param principals
+     *            the principals associated with this domain, maybe {@code
+     *            null}.
+     */
     public ProtectionDomain(CodeSource cs, PermissionCollection permissions,
             ClassLoader cl, Principal[] principals) {
         this.codeSource = cs;
@@ -98,41 +121,45 @@
         dynamicPerms = true;
     }
 
-	/**
-	 * Returns the ClassLoader associated with the ProtectionDomain
-	 * 
-	 * @return ClassLoader associated ClassLoader
-	 */
+    /**
+     * Returns the {@code ClassLoader} associated with this {@code
+     * ProtectionDomain}.
+     *
+     * @return the {@code ClassLoader} associated with this {@code
+     *         ProtectionDomain}, maybe {@code null}.
+     */
     public final ClassLoader getClassLoader() {
         return classLoader;
     }
 
-	/**
-	 * Answers the code source of this domain.
-	 * 
-	 * @return java.security.CodeSource the code source of this domain
-	 */
+    /**
+     * Returns the {@code CodeSource} of this {@code ProtectionDomain}.
+     *
+     * @return the {@code CodeSource} of this {@code ProtectionDomain}, maybe
+     *         {@code null}.
+     */
     public final CodeSource getCodeSource() {
         return codeSource;
     }
 
-	/**
-	 * Answers the permissions that should be granted to the classes which are
-	 * encapsulated in this domain.
-	 * 
-	 * @return java.security.PermissionCollection collection of permissions
-	 *         associated with this domain.
-	 */
+    /**
+     * Returns the static permissions that are granted to this {@code
+     * ProtectionDomain}.
+     *
+     * @return the static permissions that are granted to this {@code
+     *         ProtectionDomain}, maybe {@code null}.
+     */
     public final PermissionCollection getPermissions() {
         return permissions;
     }
 
-	/**
-	 * Returns the Principals associated with this ProtectionDomain. A change to
-	 * the returned array will not impact the ProtectionDomain.
-	 * 
-	 * @return Principals[] Principals associated with the ProtectionDomain.
-	 */
+    /**
+     * Returns the principals associated with this {@code ProtectionDomain}.
+     * Modifications of the returned {@code Principal} array has no impact on
+     * this {@code ProtectionDomain}.
+     *
+     * @return the principals associated with this {@code ProtectionDomain}.
+     */
     public final Principal[] getPrincipals() {
         if( principals == null ) {
             return new Principal[0];
@@ -142,16 +169,26 @@
         return tmp;
     }
 
-	/**
-	 * Determines whether the permission collection of this domain implies the
-	 * argument permission.
-	 * 
-	 * 
-	 * @return boolean true if this permission collection implies the argument
-	 *         and false otherwise.
-	 * @param permission
-	 *            java.security.Permission the permission to check.
-	 */
+    /**
+     * Indicates whether the specified permission is implied by this {@code
+     * ProtectionDomain}.
+     * <p>
+     * If this {@code ProtectionDomain} was constructed with
+     * {@link #ProtectionDomain(CodeSource, PermissionCollection)}, the
+     * specified permission is only checked against the permission collection
+     * provided in the constructor. If {@code null} was provided, {@code false}
+     * is returned.
+     * <p>
+     * If this {@code ProtectionDomain} was constructed with
+     * {@link #ProtectionDomain(CodeSource, PermissionCollection, ClassLoader, Principal[])}
+     * , the specified permission is checked against the policy and the
+     * permission collection provided in the constructor.
+     *
+     * @param permission
+     *            the permission to check against the domain.
+     * @return {@code true} if the specified {@code permission} is implied by
+     *         this {@code ProtectionDomain}, {@code false} otherwise.
+     */
     public boolean implies(Permission permission) {
         // First, test with the Policy, as the default Policy.implies() 
         // checks for both dynamic and static collections of the 
@@ -168,12 +205,12 @@
         return permissions == null ? false : permissions.implies(permission);
     }
 
-	/**
-	 * Answers a string containing a concise, human-readable description of the
-	 * receiver.
-	 * 
-	 * @return String a printable representation for the receiver.
-	 */
+    /**
+     * Returns a string containing a concise, human-readable description of the
+     * this {@code ProtectionDomain}.
+     *
+     * @return a printable representation for this {@code ProtectionDomain}.
+     */
     public String toString() {
         //FIXME: 1.5 use StreamBuilder here
         StringBuffer buf = new StringBuffer(200);

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Provider.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Provider.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Provider.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Provider.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.IOException;
@@ -42,6 +37,10 @@
 import org.apache.harmony.security.fortress.Services;
 import org.apache.harmony.security.internal.nls.Messages;
 
+/**
+ * {@code Provider} is the abstract superclass for all security providers in the
+ * Java security infrastructure.
+ */
 public abstract class Provider extends Properties {
     private static final long serialVersionUID = -4298000515446427739L;
 
@@ -92,6 +91,17 @@
     // last Service found by type
     private transient Provider.Service lastServicesByType;
 
+    /**
+     * Constructs a new instance of {@code Provider} with its name, version and
+     * description.
+     *
+     * @param name
+     *            the name of the provider.
+     * @param version
+     *            the version of the provider.
+     * @param info
+     *            a description of the provider.
+     */
     protected Provider(String name, double version, String info) {
         this.name = name;
         this.version = version;
@@ -100,50 +110,56 @@
         putProviderInfo();
     }
 
-	/**
-	 * Returns the name of this provider.
-	 * 
-	 * 
-	 * 
-	 * @return String name of the provider
-	 */
+    /**
+     * Returns the name of this provider.
+     *
+     * @return the name of this provider.
+     */
     public String getName() {
         return name;
     }
 
-	/**
-	 * Returns the version number for the services being provided
-	 * 
-	 * 
-	 * 
-	 * @return double version number for the services being provided
-	 */
+    /**
+     * Returns the version number for the services being provided.
+     *
+     * @return the version number for the services being provided.
+     */
     public double getVersion() {
         return version;
     }
 
-	/**
-	 * Returns the generic information about the services being provided.
-	 * 
-	 * 
-	 * 
-	 * @return String generic description of the services being provided
-	 */
+    /**
+     * Returns a description of the services being provided.
+     *
+     * @return a description of the services being provided.
+     */
     public String getInfo() {
         return info;
     }
 
-	/**
-	 * 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 Provider} including its name and its version.
+     *
+     * @return a printable representation for this {@code Provider}.
+     */
     public String toString() {
         return name + " version " + version; //$NON-NLS-1$
     }
 
+    /**
+     * Clears all properties used to look up services implemented by this
+     * {@code Provider}.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code clearProviderProperties.NAME}
+     * (where NAME is the provider name) to be granted, otherwise a {@code
+     * SecurityException} will be thrown.
+     *
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
+     */
     public synchronized void clear() {
         SecurityManager sm = System.getSecurityManager();
         if (sm != null) {
@@ -179,6 +195,20 @@
         myPutAll(tmp);
     }
 
+    /**
+     * Copies all from the provided map to this {@code Provider}.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code putProviderProperty.NAME} (where
+     * NAME is the provider name) to be granted, otherwise a {@code
+     * SecurityException} will be thrown.
+     *
+     * @param t
+     *            the mappings to copy to this provider.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
+     */
     public synchronized void putAll(Map<?,?> t) {
 
         // Implementation note:
@@ -231,6 +261,25 @@
         return Collections.unmodifiableCollection(super.values());
     }
 
+    /**
+     * Maps the specified {@code key} property name to the specified {@code
+     * value}.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code putProviderProperty.NAME} (where
+     * NAME is the provider name) to be granted, otherwise a {@code
+     * SecurityException} will be thrown.
+     *
+     * @param key
+     *            the name of the property.
+     * @param value
+     *            the value of the property.
+     * @return the value that was previously mapped to the specified {@code key}
+     *         ,or {@code null} if it did not have one.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method.
+     */
     public synchronized Object put(Object key, Object value) {
         SecurityManager sm = System.getSecurityManager();
         if (sm != null) {
@@ -254,6 +303,23 @@
         return super.put(key, value);
     }
 
+    /**
+     * Removes the specified {@code key} and its associated value from this
+     * {@code Provider}.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code removeProviderProperty.NAME} (where
+     * NAME is the provider name) to be granted, otherwise a {@code
+     * SecurityException} will be thrown.
+     *
+     * @param key
+     *            the name of the property
+     * @return the value that was mapped to the specified {@code key} ,or
+     *         {@code null} if no mapping was present
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have the permission to invoke this method.
+     */
     public synchronized Object remove(Object key) {
         SecurityManager sm = System.getSecurityManager();
         if (sm != null) {
@@ -279,13 +345,13 @@
      * attribute name and value.
      * 
      * @param serv
-     *            Crypto service
+     *            Crypto service.
      * @param alg
-     *            Algorithm or type
+     *            Algorithm or type.
      * @param attribute
-     *            The attribute name or null
+     *            The attribute name or {@code null}.
      * @param val
-     *            The attribute value
+     *            The attribute value.
      * @return
      */
     boolean implementsAlg(String serv, String alg, String attribute, String val) {
@@ -369,6 +435,22 @@
         return null;
     }
 
+    /**
+     * Returns the service with the specified {@code type} implementing the
+     * specified {@code algorithm}, or {@code null} if no such implementation
+     * exists.
+     * <p>
+     * If two services match the requested type and algorithm, the one added
+     * with the {@link #putService(Service)} is returned (as opposed to the one
+     * added via {@link #put(Object, Object)}.
+     *
+     * @param type
+     *            the type of the service (for example {@code KeyPairGenerator})
+     * @param algorithm
+     *            the algorithm name (case insensitive)
+     * @return the requested service, or {@code null} if no such implementation
+     *         exists
+     */
     public synchronized Provider.Service getService(String type,
             String algorithm) {
         if (type == null || algorithm == null) {
@@ -407,6 +489,13 @@
         return null;
     }
 
+    /**
+     * Returns an unmodifiable {@code Set} of all services registered by this
+     * provider.
+     *
+     * @return an unmodifiable {@code Set} of all services registered by this
+     *         provider
+     */
     public synchronized Set<Provider.Service> getServices() {
         updatePropertyServiceTable();
         if (lastServicesSet != null) {
@@ -424,6 +513,21 @@
         return lastServicesSet;
     }
 
+    /**
+     * Adds a {@code Service} to this {@code Provider}. If a service with the
+     * same name was registered via this method, it is replace.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code putProviderProperty.NAME} (where
+     * NAME is the provider name) to be granted, otherwise a {@code
+     * SecurityException} will be thrown.
+     *
+     * @param s
+     *            the {@code Service} to register
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method
+     */
     protected synchronized void putService(Provider.Service s) {
         if (s == null) {
             throw new NullPointerException();
@@ -452,6 +556,23 @@
         serviceInfoToProperties(s);
     }
 
+    /**
+     * Removes a previously registered {@code Service} from this {@code
+     * Provider}.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this method needs
+     * the {@code SecurityPermission} {@code removeProviderProperty.NAME} (where
+     * NAME is the provider name) to be granted, otherwise a {@code
+     * SecurityException} will be thrown.
+     *
+     * @param s
+     *            the {@code Service} to remove
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this method
+     * @throws NullPointerException
+     *             if {@code s} is {@code null}
+     */
     protected synchronized void removeService(Provider.Service s) {
         if (s == null) {
             throw new NullPointerException();
@@ -740,6 +861,11 @@
         return null;
     }
 
+    /**
+     * {@code Service} represents a service in the Java Security infrastructure.
+     * Each service describes its type, the algorithm it implements, to which
+     * provider it belongs and other properties.
+     */
     public static class Service {
         // The provider
         private Provider provider;
@@ -765,6 +891,29 @@
         // For newInstance() optimization
         private String lastClassName;
 
+        /**
+         * Constructs a new instance of {@code Service} with the given
+         * attributes.
+         *
+         * @param provider
+         *            the provider to which this service belongs.
+         * @param type
+         *            the type of this service (for example {@code
+         *            KeyPairGenerator}).
+         * @param algorithm
+         *            the algorithm this service implements.
+         * @param className
+         *            the name of the class implementing this service.
+         * @param aliases
+         *            {@code List} of aliases for the algorithm name, or {@code
+         *            null} if the implemented algorithm has no aliases.
+         * @param attributes
+         *            {@code Map} of additional attributes, or {@code null} if
+         *            this {@code Service} has no attributed.
+         * @throws NullPointerException
+         *             if {@code provider, type, algorithm} or {@code className}
+         *             is {@code null}.
+         */
         public Service(Provider provider, String type, String algorithm,
                 String className, List<String> aliases, Map<String, String> attributes) {
             if (provider == null || type == null || algorithm == null
@@ -779,22 +928,55 @@
             this.attributes = attributes;
         }
 
+        /**
+         * Returns the type of this {@code Service}. For example {@code
+         * KeyPairGenerator}.
+         *
+         * @return the type of this {@code Service}.
+         */
         public final String getType() {
             return type;
         }
 
+        /**
+         * Returns the name of the algorithm implemented by this {@code
+         * Service}.
+         *
+         * @return the name of the algorithm implemented by this {@code
+         *         Service}.
+         */
         public final String getAlgorithm() {
             return algorithm;
         }
 
+        /**
+         * Returns the {@code Provider} this {@code Service} belongs to.
+         *
+         * @return the {@code Provider} this {@code Service} belongs to.
+         */
         public final Provider getProvider() {
             return provider;
         }
 
+        /**
+         * Returns the name of the class implementing this {@code Service}.
+         *
+         * @return the name of the class implementing this {@code Service}.
+         */
         public final String getClassName() {
             return className;
         }
 
+        /**
+         * Returns the value of the attribute with the specified {@code name}.
+         *
+         * @param name
+         *            the name of the attribute.
+         * @return the value of the attribute, or {@code null} if no attribute
+         *         with the given name is set.
+         * @throws NullPointerException
+         *             if {@code name} is {@code null}.
+         */
         public final String getAttribute(String name) {
             if (name == null) {
                 throw new NullPointerException();
@@ -812,6 +994,22 @@
             return aliases.iterator();
         }
 
+        /**
+         * Creates and returns a new instance of the implementation described by
+         * this {@code Service}.
+         *
+         * @param constructorParameter
+         *            the parameter that is used by the constructor, or {@code
+         *            null} if the implementation does not declare a constructor
+         *            parameter.
+         * @return a new instance of the implementation described by this
+         *         {@code Service}.
+         * @throws NoSuchAlgorithmException
+         *             if the instance could not be constructed.
+         * @throws InvalidParameterException
+         *             if the implementation does not support the specified
+         *             {@code constructorParameter}.
+         */
         public Object newInstance(Object constructorParameter)
                 throws NoSuchAlgorithmException {
             if (implementation == null || !className.equals(lastClassName)) {
@@ -870,17 +1068,25 @@
             }
         }
 
+        /**
+         * Indicates whether this {@code Service} supports the specified
+         * constructor parameter.
+         *
+         * @param parameter
+         *            the parameter to test.
+         * @return {@code true} if this {@code Service} supports the specified
+         *         constructor parameter, {@code false} otherwise.
+         */
         public boolean supportsParameter(Object parameter) {
             return true;
         }
 
-	/**
-	 * Answers a string containing a concise, human-readable
-	 * description of the receiver.
-	 * 
-	 * 
-	 * @return a printable representation for the receiver.
-	 */
+        /**
+         * Returns a string containing a concise, human-readable description of
+         * this {@code Service}.
+         *
+         * @return a printable representation for this {@code Service}.
+         */
         public String toString() {
             String result = "Provider " + provider.getName() + " Service " //$NON-NLS-1$ //$NON-NLS-2$
                     + type + "." + algorithm + " " + className; //$NON-NLS-1$ //$NON-NLS-2$

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

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PublicKey.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PublicKey.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PublicKey.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/PublicKey.java Tue Apr 28 17:01:41 2009
@@ -15,23 +15,16 @@
  *  limitations under the License.
  */
 
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
 package java.security;
 
 /**
- * Superinterface for all specific public key interfaces
- * 
+ * {@code PublicKey} is the common interface for public keys.
  * 
- * @see PublicKey
  * @see PrivateKey
  */
 public interface PublicKey extends Key {
     /**
-     * @com.intel.drl.spec_ref
+     * The {@code serialVersionUID} to be compatible with JDK1.1.
      */
     public static final long serialVersionUID = 7187392471159151072L;
 }

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecureClassLoader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecureClassLoader.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecureClassLoader.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecureClassLoader.java Tue Apr 28 17:01:41 2009
@@ -15,45 +15,63 @@
  *  limitations under the License.
  */
 
-/**
-* @author Alexander V. Astapchuk
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.nio.ByteBuffer;
 import java.util.HashMap;
 
 /**
- * SecureClassLoaders are used to dynamically load, link and install classes
- * into a running image. Additionally, they (optionally) associate the classes
- * they create with a code source and provide mechanisms to allow the relevant
- * permissions to be retrieved.
- * 
+ * {@code SecureClassLoader} represents a {@code ClassLoader} which associates
+ * the classes it loads with a code source and provide mechanisms to allow the
+ * relevant permissions to be retrieved.
  */
-
 public class SecureClassLoader extends ClassLoader {
 
     // A cache of ProtectionDomains for a given CodeSource
     private HashMap pds = new HashMap();
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Constructs a new instance of {@code SecureClassLoader}. The default
+     * parent {@code ClassLoader} is used.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this constructor
+     * needs the {@code SecurityPermission} {@code checkCreateClassLoader} to be
+     * granted, otherwise a {@code SecurityException} will be thrown.
+     *
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this constructor.
      */
     protected SecureClassLoader() {
         super();
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Constructs a new instance of {@code SecureClassLoader} with the specified
+     * parent {@code ClassLoader}.
+     * <p>
+     * If a {@code SecurityManager} is installed, code calling this constructor
+     * needs the {@code SecurityPermission} {@code checkCreateClassLoader} to be
+     * granted, otherwise a {@code SecurityException} will be thrown.
+     *
+     * @param parent
+     *            the parent {@code ClassLoader}.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and the caller does
+     *             not have permission to invoke this constructor.
      */
     protected SecureClassLoader(ClassLoader parent) {
         super(parent);
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Returns the {@code PermissionCollection} for the specified {@code
+     * CodeSource}.
+     *
+     * @param codesource
+     *            the code source.
+     * @return the {@code PermissionCollection} for the specified {@code
+     *         CodeSource}.
      */
     protected PermissionCollection getPermissions(CodeSource codesource) {
         // Do nothing by default, ProtectionDomain will take care about
@@ -62,7 +80,29 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Constructs a new class from an array of bytes containing a class
+     * definition in class file format with an optional {@code CodeSource}.
+     *
+     * @param name
+     *            the name of the new class.
+     * @param b
+     *            a memory image of a class file.
+     * @param off
+     *            the start offset in b of the class data.
+     * @param len
+     *            the length of the class data.
+     * @param cs
+     *            the {@code CodeSource}, or {@code null}.
+     * @return a new class.
+     * @throws IndexOutOfBoundsException
+     *             if {@code off} or {@code len} are not valid in respect to
+     *             {@code b}.
+     * @throws ClassFormatError
+     *             if the specified data is not valid class data.
+     * @throws SecurityException
+     *             if the package to which this class is to be added, already
+     *             contains classes which were signed by different certificates,
+     *             or if the class name begins with "java."
      */
     protected final Class<?> defineClass(String name, byte[] b, int off, int len,
             CodeSource cs) {
@@ -71,7 +111,22 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref 
+     * Constructs a new class from an array of bytes containing a class
+     * definition in class file format with an optional {@code CodeSource}.
+     *
+     * @param name
+     *            the name of the new class.
+     * @param b
+     *            a memory image of a class file.
+     * @param cs
+     *            the {@code CodeSource}, or {@code null}.
+     * @return a new class.
+     * @throws ClassFormatError
+     *             if the specified data is not valid class data.
+     * @throws SecurityException
+     *             if the package to which this class is to be added, already
+     *             contains classes which were signed by different certificates,
+     *             or if the class name begins with "java."
      */
     protected final Class<?> defineClass(String name, ByteBuffer b, CodeSource cs) {
         //FIXME 1.5 - remove b.array(), call super.defineClass(,ByteBuffer,)

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecureRandom.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecureRandom.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecureRandom.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecureRandom.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.util.Iterator;
@@ -33,16 +28,11 @@
 import org.apache.harmony.security.provider.crypto.SHA1PRNG_SecureRandomImpl;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * {@code SecureRandom} is an engine class which is capable of generating
+ * cryptographically secure pseudo-random numbers.
  */
-
 public class SecureRandom extends Random {
     
-    /**
-     * @com.intel.drl.spec_ref
-     * 
-     */
     private static final long serialVersionUID = 4940670005562187L;
     
     // The service name.
@@ -51,50 +41,27 @@
     // Used to access common engine functionality
     private static transient Engine engine = new Engine(SERVICE);
     
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private Provider provider;
     
-    /**
-     * @com.intel.drl.spec_ref
-     */
-    private SecureRandomSpi secureRandomSpi; 
+    private SecureRandomSpi secureRandomSpi;
     
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private String algorithm;
     
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private byte[] state;
     
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private byte[] randomBytes;
     
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private int randomBytesUsed;
     
-    /**
-     * @com.intel.drl.spec_ref
-     */
     private long counter;
     
     // Internal SecureRandom used for getSeed(int)
     private static transient SecureRandom internalSecureRandom;
     
     /**
-     * Constructs a new instance of this class. Users are encouraged to use
-     * <code>getInstance()</code> instead.
-     * 
-     * An implementation for the highest-priority provider is returned. The
-     * instance returned will not have been seeded.
+     * Constructs a new instance of {@code SecureRandom}. An implementation for
+     * the highest-priority provider is returned. The constructed instance will
+     * not have been seeded.
      */
     public SecureRandom() {
         super(0);
@@ -115,14 +82,12 @@
     }
 
     /**
-     * Constructs a new instance of this class. Users are encouraged to use
-     * <code>getInstance()</code> instead.
-     * 
-     * An implementation for the highest-priority provider is returned. The
-     * instance returned will be seeded with the parameter.
+     * Constructs a new instance of {@code SecureRandom}. An implementation for
+     * the highest-priority provider is returned. The constructed instance will
+     * be seeded with the parameter.
      * 
      * @param seed
-     *            bytes forming the seed for this generator.
+     *            the seed for this generator.
      */
     public SecureRandom(byte[] seed) {
         this();
@@ -143,8 +108,13 @@
     }
     
     /**
-     * @com.intel.drl.spec_ref
+     * Constructs a new instance of {@code SecureRandom} using the given
+     * implementation from the specified provider.
      * 
+     * @param secureRandomSpi
+     *            the implementation.
+     * @param provider
+     *            the security provider.
      */
     protected SecureRandom(SecureRandomSpi secureRandomSpi,
                            Provider provider) {
@@ -162,8 +132,17 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a new instance of {@code SecureRandom} that utilizes the
+     * specified algorithm.
      * 
+     * @param algorithm
+     *            the name of the algorithm to use.
+     * @return a new instance of {@code SecureRandom} that utilizes the
+     *         specified algorithm.
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm is not available.
+     * @throws NullPointerException
+     *             if {@code algorithm} is {@code null}.
      */
     public static SecureRandom getInstance(String algorithm)
                                 throws NoSuchAlgorithmException {
@@ -177,19 +156,21 @@
     }
 
     /**
-     * Answers a new SecureRandom which is capable of running the algorithm
-     * described by the argument. The result will be an instance of a subclass
-     * of SecureRandomSpi which implements that algorithm.
+     * Returns a new instance of {@code SecureRandom} that utilizes the
+     * specified algorithm from the specified provider.
      * 
      * @param algorithm
-     *            java.lang.String Name of the algorithm desired
+     *            the name of the algorithm to use.
      * @param provider
-     *            java.security.Provider Provider which has to implement the
-     *            algorithm
-     * @return SecureRandom a concrete implementation for the algorithm desired.
-     * 
-     * @exception NoSuchAlgorithmException
-     *                If the algorithm cannot be found
+     *            the name of the provider.
+     * @return a new instance of {@code SecureRandom} 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 SecureRandom getInstance(String algorithm, String provider)
                                 throws NoSuchAlgorithmException, NoSuchProviderException {
@@ -205,8 +186,19 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns a new instance of {@code SecureRandom} 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 SecureRandom} 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 SecureRandom getInstance(String algorithm, Provider provider)
                                 throws NoSuchAlgorithmException {
@@ -223,38 +215,42 @@
     }
 
     /**
-     * Returns the Provider of the secure random represented by the receiver.
+     * Returns the provider associated with this {@code SecureRandom}.
      * 
-     * @return Provider an instance of a subclass of java.security.Provider
+     * @return the provider associated with this {@code SecureRandom}.
      */
     public final Provider getProvider() {
         return provider;
     }
     
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the name of the algorithm of this {@code SecureRandom}.
      * 
+     * @return the name of the algorithm of this {@code SecureRandom}.
      */
     public String getAlgorithm() {
         return algorithm;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Reseeds this {@code SecureRandom} instance with the specified {@code
+     * seed}. The seed of this {@code SecureRandom} instance is supplemented,
+     * not replaced.
      * 
+     * @param seed
+     *            the new seed.
      */
     public synchronized void setSeed(byte[] seed) {
         secureRandomSpi.engineSetSeed(seed);
     }
 
     /**
-     * Reseeds this random object with the eight bytes described by the
-     * representation of the long provided.
-     * 
+     * Reseeds this this {@code SecureRandom} instance with the eight bytes
+     * described by the representation of the given {@code long seed}. The seed
+     * of this {@code SecureRandom} instance is supplemented, not replaced.
      * 
      * @param seed
-     *            long Number whose representation to use to reseed the
-     *            receiver.
+     *            the new seed.
      */
     public void setSeed(long seed) {
         if (seed == 0) {    // skip call from Random
@@ -274,16 +270,24 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Generates and stores random bytes in the given {@code byte[]} for each
+     * array element.
      * 
+     * @param bytes
+     *            the {@code byte[]} to be filled with random bytes.
      */
     public synchronized void nextBytes(byte[] bytes) {
         secureRandomSpi.engineNextBytes(bytes);
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Generates and returns an {@code int} containing the specified number of
+     * random bits (right justified, with leading zeros).
      * 
+     * @param numBits
+     *            number of bits to be generated. An input value should be in
+     *            the range [0, 32].
+     * @return an {@code int} containing the specified number of random bits.
      */
     protected final int next(int numBits) {
         if (numBits < 0) {
@@ -306,12 +310,12 @@
     }
 
     /**
-     * Returns the given number of seed bytes, computed using the seed
-     * generation algorithm used by this class.
+     * Generates and returns the specified number of seed bytes, computed using
+     * the seed generation algorithm used by this {@code SecureRandom}.
      * 
      * @param numBytes
-     *            int the given number of seed bytes
-     * @return byte[] The seed bytes generated
+     *            the number of seed bytes.
+     * @return the seed bytes
      */
     public static byte[] getSeed(int numBytes) {
         if (internalSecureRandom == null) {
@@ -321,12 +325,12 @@
     }
 
     /**
-     * Generates a certain number of seed bytes
-     * 
+     * Generates and returns the specified number of seed bytes, computed using
+     * the seed generation algorithm used by this {@code SecureRandom}.
      * 
      * @param numBytes
-     *            int Number of seed bytes to generate
-     * @return byte[] The seed bytes generated
+     *            the number of seed bytes.
+     * @return the seed bytes.
      */
     public byte[] generateSeed(int numBytes) {
         return secureRandomSpi.engineGenerateSeed(numBytes);

Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecureRandomSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecureRandomSpi.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecureRandomSpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecureRandomSpi.java Tue Apr 28 17:01:41 2009
@@ -15,43 +15,46 @@
  *  limitations under the License.
  */
 
-/**
-* @author Boris V. Kuznetsov
-* @version $Revision$
-*/
-
 package java.security;
 
 import java.io.Serializable;
 
 /**
- * This class is a Service Provider Interface (therefore the Spi suffix) for
- * secure random number generation algorithms to be supplied by providers.
+ * {@code SecureRandomSpi} is the <i>Service Provider Interface</i> (<b>SPI</b>) definition
+ * for {@link SecureRandom}.
  * 
+ * @see SecureRandom
  */
 public abstract class SecureRandomSpi implements Serializable {
     
-    /**
-     * @com.intel.drl.spec_ref
-     * 
-     */
     private static final long serialVersionUID = -2991854161009191830L;
                 
     /**
-     * @com.intel.drl.spec_ref
+     * Reseeds this {@code SecureRandomSpi} instance with the specified {@code
+     * seed}. The seed of this {@code SecureRandomSpi} instance is supplemented,
+     * not replaced.
      * 
+     * @param seed
+     *            the new seed.
      */
     protected abstract void engineSetSeed(byte[] seed);
     
     /**
-     * @com.intel.drl.spec_ref
+     * Generates and stores random bytes in the given {@code byte[]} for each
+     * array element.
      * 
+     * @param bytes
+     *            the {@code byte[]} to be filled with random bytes.
      */
     protected abstract void engineNextBytes(byte[] bytes);
     
     /**
-     * @com.intel.drl.spec_ref
+     * Generates and returns the specified number of seed bytes, computed using
+     * the seed generation algorithm used by this {@code SecureRandomSpi}.
      * 
+     * @param numBytes
+     *            the number of seed bytes.
+     * @return the seed bytes
      */
     protected abstract byte[] engineGenerateSeed(int numBytes);
 }



Mime
View raw message