You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/04/28 19:01:47 UTC
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/
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 "neutral"
+ * 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 "neutral"
* 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);
}