Index: modules/security/src/common/javasrc/java/security/cert/CertificateFactory.java =================================================================== --- modules/security/src/common/javasrc/java/security/cert/CertificateFactory.java.orig 2006-03-30 08:31:52.000000000 +0100 +++ modules/security/src/common/javasrc/java/security/cert/CertificateFactory.java 2006-03-30 09:38:04.000000000 +0100 @@ -73,6 +73,8 @@ * * @exception CertificateException * If the type cannot be found + * @exception NullPointerException if type is null (rather than + * CertificateException as in 1.4 release) */ public static final CertificateFactory getInstance(String type) throws CertificateException { @@ -122,6 +124,8 @@ * * @exception CertificateException * If the type cannot be found + * @exception NullPointerException if type is null (rather than + * CertificateException as in 1.4 release) */ public static final CertificateFactory getInstance(String type, Provider provider) throws CertificateException { Index: modules/security/src/common/javasrc/java/security/AccessControlException.java =================================================================== --- modules/security/src/common/javasrc/java/security/AccessControlException.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/AccessControlException.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,10 +21,12 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This runtime exception is thrown when an access control check indicates that + * access should not be granted. + * */ - public class AccessControlException extends SecurityException { private static final long serialVersionUID = 5138225684096988535L; @@ -34,24 +36,39 @@ */ private Permission perm; // Named as demanded by Serialized Form. - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param message + * String The detail message for the exception. + */ public AccessControlException(String message) { super(message); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback, message and + * associated permission all filled in. + * + * + * @param message + * String The detail message for the exception. + * @param perm + * Permission The failed permission. + */ public AccessControlException(String message, Permission perm) { super(message); this.perm = perm; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the receiver's permission. + * + * + * @return Permission the receiver's permission + */ public Permission getPermission() { return perm; } Index: modules/security/src/common/javasrc/java/security/AllPermission.java =================================================================== --- modules/security/src/common/javasrc/java/security/AllPermission.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/AllPermission.java 2006-03-30 10:13:31.000000000 +0100 @@ -28,8 +28,11 @@ import java.util.Enumeration; import java.util.NoSuchElementException; + /** - * @com.intel.drl.spec_ref + * Subclass of Permission whose instances imply all other permissions. Granting + * this permission is equivalent to disabling security. + * */ public final class AllPermission extends Permission { @@ -39,51 +42,87 @@ // Actions name private static final String ALL_ACTIONS = ""; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class. The two argument version is + * provided for class Policy so that it has a consistant call + * pattern across all Permissions. The name and action list are both + * ignored. + * + * @param name + * java.lang.String ignored. + * @param actions + * java.lang.String ignored. + */ public AllPermission(String name, String actions) { super(ALL_PERMISSIONS); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class. + */ public AllPermission() { super(ALL_PERMISSIONS); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Compares the argument to the receiver, and answers true if they represent + * the same object using a class specific comparison. All + * AllPermissions are equal to eachother. + * + * @param obj + * the object to compare with this object + * @return true if the object is the same as this object + * false if it is different from this object + * @see #hashCode + */ public boolean equals(Object obj) { return (obj instanceof AllPermission); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an integer hash code for the receiver. Any two objects which + * answer true when passed to equals must + * answer the same value for this method. + * + * @return the receiver's hash + * + * @see #equals + */ public int hashCode() { return 1; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the actions associated with the receiver. Since AllPermission + * objects allow all actions, answer with the string "". + * + * @return String the actions associated with the receiver. + */ public String getActions() { return ALL_ACTIONS; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Indicates whether the argument permission is implied by the receiver. + * AllPermission objects imply all other permissions. + * + * @return boolean true if the argument permission is implied + * by the receiver, and false if it is not. + * @param permission + * java.security.Permission the permission to check + */ public boolean implies(Permission permission) { return true; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a new PermissionCollection for holding permissions of this class. + * Answer null if any permission collection can be used. + * + * @return a new PermissionCollection or null + * + * @see java.security.BasicPermissionCollection + */ public PermissionCollection newPermissionCollection() { return new AllPermissionCollection(); } @@ -165,9 +204,15 @@ } } - /** - * Returns true if this collection is not empty. - */ + /** + * Indicates whether the argument permission is implied by the receiver. + * AllPermission objects imply all other permissions. + * + * @return boolean true if the argument permission is implied + * by the receiver, and false if it is not. + * @param permission + * java.security.Permission the permission to check + */ public boolean implies(Permission permission) { return all != null; } Index: modules/security/src/common/javasrc/java/security/BasicPermission.java =================================================================== --- modules/security/src/common/javasrc/java/security/BasicPermission.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/BasicPermission.java 2006-03-30 10:13:31.000000000 +0100 @@ -35,24 +35,35 @@ import java.util.Map; /** - * @com.intel.drl.spec_ref + * Superclass of permissions which have names but no action lists. + * */ + public abstract class BasicPermission extends Permission implements Serializable { private static final long serialVersionUID = 6279438298436773498L; - /** - * @com.intel.drl.spec_ref. - */ + /** + * Creates an instance of this class with the given name and action list. + * + * @param name + * String the name of the new permission. + */ public BasicPermission(String name) { super(name); checkName(name); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Creates an instance of this class with the given name and action list. + * The action list is ignored. + * + * @param name + * String the name of the new permission. + * @param action + * String ignored. + */ public BasicPermission(String name, String action) { super(name); checkName(name); @@ -70,9 +81,17 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Compares the argument to the receiver, and answers true if they represent + * the same object using a class specific comparison. In this + * case, the receiver and the object must have the same class and name. + * + * @param obj + * the object to compare with this object + * @return true if the object is the same as this object + * false if it is different from this object + * @see #hashCode + */ public boolean equals(Object obj) { if (obj == this) { return true; @@ -84,23 +103,37 @@ return false; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an integer hash code for the receiver. Any two objects which + * answer true when passed to equals must + * answer the same value for this method. + * + * @return int the receiver's hash + * + * @see #equals + */ public int hashCode() { return getName().hashCode(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the actions associated with the receiver. BasicPermission objects + * have no actions, so answer the empty string. + * + * @return String the actions associated with the receiver. + */ public String getActions() { return ""; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Indicates whether the argument permission is implied by the receiver. + * + * @return boolean true if the argument permission is implied + * by the receiver, and false if it is not. + * @param permission + * java.security.Permission the permission to check + */ public boolean implies(Permission permission) { if (permission != null && permission.getClass() == this.getClass()) { return nameImplies(getName(), permission.getName()); @@ -137,9 +170,21 @@ return true; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a new PermissionCollection for holding permissions of this class. + * Answer null if any permission collection can be used. + *

+ * Note: For BasicPermission (and subclasses which do not override this + * method), the collection which is returned does not invoke the + * .implies method of the permissions which are stored in it when checking + * if the collection implies a permission. Instead, it assumes that if the + * type of the permission is correct, and the name of the permission is + * correct, there is a match. + * + * @return a new PermissionCollection or null + * + * @see java.security.BasicPermissionCollection + */ public PermissionCollection newPermissionCollection() { return new BasicPermissionCollection(); } @@ -229,12 +274,14 @@ return Collections.enumeration(items.values()); } - /** - * Checks if the particular permission is implied by this collection. - * - * @see java.security.BasicPermission - * @see java.security.PermissionCollection#implies(java.security.Permission) - */ + /** + * Indicates whether the argument permission is implied by the receiver. + * + * @return boolean true if the argument permission is implied + * by the receiver, and false if it is not. + * @param permission + * java.security.Permission the permission to check + */ public boolean implies(Permission permission) { if (permission == null || permission.getClass() != permClass) { return false; Index: modules/security/src/common/javasrc/java/security/CodeSource.java =================================================================== --- modules/security/src/common/javasrc/java/security/CodeSource.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/CodeSource.java 2006-03-30 10:13:31.000000000 +0100 @@ -70,9 +70,15 @@ // Cached factory used to build CertPath-s in getCodeSigners(). private transient CertificateFactory factory; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its url and certificates + * fields filled in from the arguments. + * + * @param location + * URL the URL. + * @param certs + * Certificate[] the Certificates. + */ public CodeSource(URL location, Certificate[] certs) { this.location = location; if (certs != null) { @@ -92,9 +98,19 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Compares the argument to the receiver, and answers true if they represent + * the same object using a class specific comparison. In this + * case, the receiver and the object must have the same URL and the same + * collection of certificates. + * + * + * @param obj + * the object to compare with this object + * @return true if the object is the same as this object + * false if it is different from this object + * @see #hashCode + */ public boolean equals(Object obj) { if (obj == this) { return true; @@ -130,9 +146,12 @@ return true; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the certificates held onto by the receiver. + * + * + * @return Certificate[] the receiver's certificates + */ public final Certificate[] getCertificates() { getCertificatesNoClone(); if (certs == null) { @@ -259,16 +278,26 @@ return null; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the receiver's location. + * + * + * @return URL the receiver's URL + */ public final URL getLocation() { return location; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an integer hash code for the receiver. Any two objects which + * answer true when passed to .equals must + * answer the same value for this method. + * + * + * @return int the receiver's hash. + * + * @see #equals + */ public int hashCode() { // // hashCode() is undocumented there. Should we also use certs[i] to @@ -277,9 +306,15 @@ return location == null ? 0 : location.hashCode(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Indicates whether the argument code source is implied by the receiver. + * + * + * @return boolean true if the argument code source is + * implied by the receiver, and false if it is not. + * @param cs + * CodeSource the code source to check + */ public boolean implies(CodeSource cs) { // // Here, javadoc:N refers to the appropriate item in the API spec for @@ -426,9 +461,13 @@ return true; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * + * @return a printable representation for the receiver. + */ public String toString() { //FIXME 1.5 StringBuffer => StringBuilder StringBuffer buf = new StringBuffer(); Index: modules/security/src/common/javasrc/java/security/DigestException.java =================================================================== --- modules/security/src/common/javasrc/java/security/DigestException.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/DigestException.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,8 +21,9 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This class represents exceptions for message digest computation. * */ public class DigestException extends GeneralSecurityException { @@ -32,16 +33,22 @@ */ private static final long serialVersionUID = 5821450303093652515L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public DigestException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public DigestException() { } Index: modules/security/src/common/javasrc/java/security/DigestInputStream.java =================================================================== --- modules/security/src/common/javasrc/java/security/DigestInputStream.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/DigestInputStream.java 2006-03-30 10:13:31.000000000 +0100 @@ -47,23 +47,44 @@ this.digest = digest; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the MessageDigest which the receiver uses when computing the + * hash. + * + * + * @return MessageDigest the digest the receiver uses when computing the + * hash. + * + */ public MessageDigest getMessageDigest() { return digest; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Sets the MessageDigest which the receiver will use when computing the + * hash. + * + * + * @param digest + * MessageDigest the digest to use when computing the hash. + * + * @see MessageDigest + * @see #on + */ public void setMessageDigest(MessageDigest digest) { this.digest = digest; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Reads the next byte and answers it as an int. Updates the digest for the + * byte if this fuction is enabled. + * + * + * @return int the byte which was read or -1 at end of stream. + * + * @exception java.io.IOException + * If reading the source stream causes an IOException. + */ public int read() throws IOException { // read the next byte int byteRead = in.read(); @@ -93,16 +114,27 @@ return bytesRead; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Enables or disables the digest function (default is on). + * + * + * @param on + * boolean true if the digest should be computed, and false + * otherwise. + * + * @see MessageDigest + */ public void on(boolean on) { isOn = on; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * + * @return String a printable representation for the receiver. + */ public String toString() { return super.toString() + ", " + digest.toString() + (isOn ? ", is on" : ", is off"); Index: modules/security/src/common/javasrc/java/security/DigestOutputStream.java =================================================================== --- modules/security/src/common/javasrc/java/security/DigestOutputStream.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/DigestOutputStream.java 2006-03-30 10:13:31.000000000 +0100 @@ -47,16 +47,30 @@ this.digest = digest; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the MessageDigest which the receiver uses when computing the + * hash. + * + * + * @return MessageDigest the digest the receiver uses when computing the + * hash. + */ + public MessageDigest getMessageDigest() { return digest; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Sets the MessageDigest which the receiver will use when computing the + * hash. + * + * + * @param digest + * MessageDigest the digest to use when computing the hash. + * + * @see MessageDigest + * @see #on + */ public void setMessageDigest(MessageDigest digest) { this.digest = digest; } @@ -85,16 +99,27 @@ out.write(b, off, len); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Enables or disables the digest function (default is on). + * + * + * @param on + * boolean true if the digest should be computed, and false + * otherwise. + * + * @see MessageDigest + */ public void on(boolean on) { isOn = on; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * + * @return String a printable representation for the receiver. + */ public String toString() { return super.toString() + ", " + digest.toString() + (isOn ? ", is on" : ", is off"); Index: modules/security/src/common/javasrc/java/security/DomainCombiner.java =================================================================== --- modules/security/src/common/javasrc/java/security/DomainCombiner.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/DomainCombiner.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,8 +21,11 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * A DomainCombiner is a way to update the protection domains from an + * AccessControlContext + * */ public interface DomainCombiner { /** Index: modules/security/src/common/javasrc/java/security/GeneralSecurityException.java =================================================================== --- modules/security/src/common/javasrc/java/security/GeneralSecurityException.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/GeneralSecurityException.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,8 +21,10 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This class represents the general security exception. Subclasses will + * represents specific security problems. * */ public class GeneralSecurityException extends Exception { @@ -31,16 +33,22 @@ */ private static final long serialVersionUID = 894798122053539237L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public GeneralSecurityException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public GeneralSecurityException() { } Index: modules/security/src/common/javasrc/java/security/Guard.java =================================================================== --- modules/security/src/common/javasrc/java/security/Guard.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/Guard.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,8 +21,10 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This interface is implemented by objects which wish to control access to + * other objects. * */ public interface Guard { Index: modules/security/src/common/javasrc/java/security/GuardedObject.java =================================================================== --- modules/security/src/common/javasrc/java/security/GuardedObject.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/GuardedObject.java 2006-03-30 10:13:31.000000000 +0100 @@ -25,7 +25,8 @@ import java.io.Serializable; /** - * @com.intel.drl.spec_ref + * GuardedObject controls access to an object, by checking all requests for the + * object with a Guard. * */ public class GuardedObject implements Serializable { @@ -45,17 +46,31 @@ */ private final Guard guard; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a GuardedObject to protect access to the specified Object + * using the specified Guard. + * + * @param object + * the Object to guard + * @param guard + * the Guard + */ public GuardedObject(Object object, Guard guard) { this.object = object; this.guard = guard; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Checks whether access should be granted to the object. If access is + * granted, this method returns the object. If it is not granted, then a + * SecurityException is thrown. + * + * + * @return the guarded object + * + * @exception java.lang.SecurityException + * If access is not granted to the object + */ public Object getObject() throws SecurityException { if (guard != null) { guard.checkGuard(object); Index: modules/security/src/common/javasrc/java/security/InvalidAlgorithmParameterException.java =================================================================== --- modules/security/src/common/javasrc/java/security/InvalidAlgorithmParameterException.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/InvalidAlgorithmParameterException.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,8 +21,9 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This class represents invalid algorithm parameters to cryprographic services. * */ public class InvalidAlgorithmParameterException extends @@ -32,16 +33,22 @@ */ private static final long serialVersionUID = 2864672297499471472L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public InvalidAlgorithmParameterException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public InvalidAlgorithmParameterException() { } Index: modules/security/src/common/javasrc/java/security/InvalidKeyException.java =================================================================== --- modules/security/src/common/javasrc/java/security/InvalidKeyException.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/InvalidKeyException.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,9 +21,12 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * Used when invalid cryptography keys are used. * + * @see Throwable + * @see Error */ public class InvalidKeyException extends KeyException { @@ -32,16 +35,22 @@ */ private static final long serialVersionUID = 5698479920593359816L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public InvalidKeyException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public InvalidKeyException() { } Index: modules/security/src/common/javasrc/java/security/InvalidParameterException.java =================================================================== --- modules/security/src/common/javasrc/java/security/InvalidParameterException.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/InvalidParameterException.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,8 +21,9 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This exception is thrown when an invalid parameter is passed to a method. * */ public class InvalidParameterException extends IllegalArgumentException { @@ -32,16 +33,22 @@ */ private static final long serialVersionUID = -857968536935667808L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public InvalidParameterException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public InvalidParameterException() { } } \ No newline at end of file Index: modules/security/src/common/javasrc/java/security/Key.java =================================================================== --- modules/security/src/common/javasrc/java/security/Key.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/Key.java 2006-03-30 10:35:17.000000000 +0100 @@ -24,8 +24,9 @@ import java.io.Serializable; /** - * @com.intel.drl.spec_ref + * Defines the basic properties of all key objects. * + * @see PublicKey */ public interface Key extends Serializable { /** @@ -34,17 +35,25 @@ public static final long serialVersionUID = 6603384152749567654L; /** - * @com.intel.drl.spec_ref + * Answers the name of the algorithm that this key will work + * with. If the algorithm is unknown, it answers null. + * + * @return String the receiver's algorithm */ public String getAlgorithm(); /** - * @com.intel.drl.spec_ref + * Answers the name of the format used to encode the key, or null + * if it can not be encoded. + * + * @return String the receiver's encoding format */ public String getFormat(); /** - * @com.intel.drl.spec_ref + * Answers the encoded form of the receiver. + * + * @return byte[] the encoded form of the receiver */ public byte[] getEncoded(); -} \ No newline at end of file +} Index: modules/security/src/common/javasrc/java/security/KeyException.java =================================================================== --- modules/security/src/common/javasrc/java/security/KeyException.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/KeyException.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,9 +21,14 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This class is the superclass of all classes which represent problems with + * keys. + * * + * @see Throwable + * @see Error */ public class KeyException extends GeneralSecurityException { @@ -32,16 +37,22 @@ */ private static final long serialVersionUID = -7483676942812432108L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public KeyException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public KeyException() { } Index: modules/security/src/common/javasrc/java/security/MessageDigest.java =================================================================== --- modules/security/src/common/javasrc/java/security/MessageDigest.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/MessageDigest.java 2006-03-30 10:13:31.000000000 +0100 @@ -96,10 +96,22 @@ return getInstance(algorithm, p); } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Answers a new MessageDigest which is capable of running the algorithm + * described by the argument. The result will be an instance of a subclass + * of MessageDigest which implements that algorithm. + * + * + * @param algorithm + * java.lang.String Name of the algorithm desired + * @param provider + * Provider Provider which has to implement the algorithm + * @return MessageDigest a concrete implementation for the algorithm + * desired. + * + * @exception NoSuchAlgorithmException + * If the algorithm cannot be found + */ public static MessageDigest getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException { if (provider == null) { @@ -124,18 +136,25 @@ } } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Puts the receiver back in an initial state, such that it is ready to + * compute a new hash. + * + * @see java.security.MessageDigest.Wrapper#engineReset() + */ public void reset() { engineReset(); } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Includes the argument in the hash value computed + * by the receiver. + * + * @param arg0 byte + * the byte to feed to the hash algorithm + * + * @see #reset() + */ public void update(byte arg0) { engineUpdate(arg0); } @@ -164,10 +183,14 @@ engineUpdate(input, 0, input.length); } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Computes and answers the final hash value that the receiver represents. + * After the digest is computed the receiver is reset. + * + * @return the hash the receiver computed + * + * @see #reset + */ public byte[] digest() { return engineDigest(); } @@ -194,18 +217,27 @@ return digest(); } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * @return a printable representation for the receiver. + */ public String toString() { return "MESSAGE DIGEST " + algorithm; } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Does a simply byte-per-byte compare of the two digests. + * + * @param digesta + * One of the digests to compare + * @param digestb + * The digest to compare to + * + * @return true if the two hashes are equal + * false if the two hashes are not equal + */ public static boolean isEqual(byte[] digesta, byte[] digestb) { if (digesta.length != digestb.length) { return false; @@ -218,26 +250,31 @@ return true; } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Answers the standard Java Security name for the algorithm being used by + * the receiver. + * + * @return String the name of the algorithm + */ public final String getAlgorithm() { return algorithm; } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Returns the Provider of the digest represented by the receiver. + * + * @return Provider an instance of a subclass of java.security.Provider + */ public final Provider getProvider() { return provider; } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Return the engine digest length in bytes. Default is 0. + * + * @return int the engine digest length in bytes + * + */ public final int getDigestLength() { int l = engineGetDigestLength(); if (l != 0) { Index: modules/security/src/common/javasrc/java/security/MessageDigestSpi.java =================================================================== --- modules/security/src/common/javasrc/java/security/MessageDigestSpi.java.orig 2006-03-28 13:37:01.000000000 +0100 +++ modules/security/src/common/javasrc/java/security/MessageDigestSpi.java 2006-03-30 10:40:56.000000000 +0100 @@ -23,11 +23,16 @@ import java.nio.ByteBuffer; + /** - * @com.intel.drl.spec_ref + * This class is a Service Provider Interface (therefore the Spi suffix) for + * digest algorithms to be supplied by providers. Examples of digest algorithms + * are MD5 and SHA. + * + * A digest is a secure hash function for a stream of bytes, like a fingerprint + * for the stream of bytes. * */ - public abstract class MessageDigestSpi { /** Index: modules/security/src/common/javasrc/java/security/NoSuchAlgorithmException.java =================================================================== --- modules/security/src/common/javasrc/java/security/NoSuchAlgorithmException.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/NoSuchAlgorithmException.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,9 +21,12 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * Instances of this class are thrown when an attempt is made to access an + * algorithm which is not provided by the library. * + * @see Throwable */ public class NoSuchAlgorithmException extends GeneralSecurityException { @@ -32,16 +35,22 @@ */ private static final long serialVersionUID = -7443947487218346562L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public NoSuchAlgorithmException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public NoSuchAlgorithmException() { } Index: modules/security/src/common/javasrc/java/security/NoSuchProviderException.java =================================================================== --- modules/security/src/common/javasrc/java/security/NoSuchProviderException.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/NoSuchProviderException.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,9 +21,13 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * Instances of this class are thrown when an attempt is made to access a + * provider by name which is not currently available. + * * + * @see Throwable */ public class NoSuchProviderException extends GeneralSecurityException { /** @@ -31,16 +35,21 @@ */ private static final long serialVersionUID = 8488111756688534474L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * @param msg + * String The detail message for the exception. + */ public NoSuchProviderException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public NoSuchProviderException() { } } \ No newline at end of file Index: modules/security/src/common/javasrc/java/security/Permission.java =================================================================== --- modules/security/src/common/javasrc/java/security/Permission.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/Permission.java 2006-03-30 10:13:31.000000000 +0100 @@ -23,8 +23,10 @@ import java.io.Serializable; + /** - * @com.intel.drl.spec_ref + * Abstract superclass of all classes which represent permission to access + * system resources. * */ public abstract class Permission implements Guard, Serializable { @@ -41,31 +43,57 @@ */ public abstract boolean equals(Object obj); - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an integer hash code for the receiver. Any two objects which + * answer true when passed to .equals must + * answer the same value for this method. + * + * + * @return int the receiver's hash. + * + * @see #equals + */ public abstract int hashCode(); - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the actions associated with the receiver. Subclasses should + * return their actions in canonical form. If no actions are associated with + * the receiver, the empty string should be returned. + * + * + * @return String the receiver's actions. + */ public abstract String getActions(); - /** - * @com.intel.drl.spec_ref - */ + /** + * Indicates whether the argument permission is implied by the receiver. + * + * + * @return boolean true if the argument permission is implied + * by the receiver, and false if it is not. + * @param permission + * Permission the permission to check. + */ public abstract boolean implies(Permission permission); - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its name set to the + * argument. + * + * + * @param name + * String the name of the permission. + */ public Permission(String name) { this.name = name; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the name of the receiver. + * + * + * @return String the receiver's name. + */ public final String getName() { return name; } @@ -80,16 +108,25 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a new PermissionCollection for holding permissions of this class. + * Answer null if any permission collection can be used. + * + * + * @return PermissionCollection or null a suitable permission collection for + * instances of the class of the receiver. + */ public PermissionCollection newPermissionCollection() { return null; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * + * @return String a printable representation for the receiver. + */ public String toString() { String actions = getActions(); actions = (actions == null || actions.length() == 0) ? "" : " " Index: modules/security/src/common/javasrc/java/security/PermissionCollection.java =================================================================== --- modules/security/src/common/javasrc/java/security/PermissionCollection.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/PermissionCollection.java 2006-03-30 10:13:31.000000000 +0100 @@ -27,7 +27,8 @@ import java.util.List; /** - * @com.intel.drl.spec_ref + * Abstract superclass of classes which are collections of Permission objects. + * */ public abstract class PermissionCollection implements Serializable { @@ -41,38 +42,67 @@ */ private boolean readOnly; // = false; - /** - * @com.intel.drl.spec_ref - */ + /** + * Adds the argument to the collection. + * + * + * @param permission + * java.security.Permission the permission to add to the + * collection. + * @exception IllegalStateException + * if the collection is read only. + */ public abstract void add(Permission permission); - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an enumeration of the permissions in the receiver. + * + * + * @return Enumeration the permissions in the receiver. + */ public abstract Enumeration elements(); - /** - * @com.intel.drl.spec_ref - */ + /** + * Indicates whether the argument permission is implied by the permissions + * contained in the receiver. + * + * + * @return boolean true if the argument permission is implied + * by the permissions in the receiver, and false if + * it is not. + * @param permission + * java.security.Permission the permission to check + */ public abstract boolean implies(Permission permission); - /** - * @com.intel.drl.spec_ref - */ + /** + * Indicates whether new permissions can be added to the receiver. + * + * + * @return boolean true if the receiver is read only + * false if new elements can still be added to the + * receiver. + */ public boolean isReadOnly() { return readOnly; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Marks the receiver as read only, so that no new permissions can be added + * to it. + * + */ public void setReadOnly() { readOnly = true; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * + * @return a printable representation for the receiver. + */ public String toString() { List elist = new ArrayList(100); Enumeration elenum = elements(); Index: modules/security/src/common/javasrc/java/security/Permissions.java =================================================================== --- modules/security/src/common/javasrc/java/security/Permissions.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/Permissions.java 2006-03-30 10:13:31.000000000 +0100 @@ -35,7 +35,8 @@ import java.util.NoSuchElementException; /** - * @com.intel.drl.spec_ref + * A heterogeneous collection of permissions. + * */ public final class Permissions extends PermissionCollection implements Serializable { @@ -57,9 +58,14 @@ */ private boolean allEnabled; // = false; - /** - * @com.intel.drl.spec_ref - */ + /** + * Adds the argument to the collection. + * + * + * @param permission + * java.security.Permission the permission to add to the + * collection + */ public void add(Permission permission) { if (isReadOnly()) { throw new SecurityException("collection is read-only"); @@ -93,9 +99,12 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an enumeration of the permissions in the receiver. + * + * + * @return Enumeration the permissions in the receiver. + */ public Enumeration elements() { return new MetaEnumeration(klasses.values().iterator()); } @@ -157,14 +166,17 @@ } } - /** - * @com.intel.drl.spec_ref - * Before actual implication checking, this method - * tries to resolve UnresolvedPermissions (if any) - * against the passed instance. Successfully - * resolved permissions (if any) are taken into - * account during further processing. - */ + /** + * Indicates whether the argument permission is implied by the permissions + * contained in the receiver. + * + * + * @return boolean true if the argument permission is implied + * by the permissions in the receiver, and false if + * it is not. + * @param permission + * java.security.Permission the permission to check + */ public boolean implies(Permission permission) { if (allEnabled) { return true; @@ -266,27 +278,39 @@ */ private final Hashtable perms = new Hashtable(); - /** - * Adds passed permission (of any type) to the collection. The read-only - * flag is ignored, as this class is used as internal storage only. - */ + /** + * Adds the argument to the collection. + * + * + * @param permission + * java.security.Permission the permission to add to the + * collection + */ public void add(Permission permission) { perms.put(permission, permission); } - /** - * Returns enumeration of contained elements. - */ + /** + * Answers an enumeration of the permissions in the receiver. + * + * + * @return Enumeration the permissions in the receiver. + */ public Enumeration elements() { return perms.elements(); } - /** - * Checks if this collection implies the particular permission. - * - * @return true if some of contained permissions implies the passed - * permission, false otherwise - */ + /** + * Indicates whether the argument permission is implied by the permissions + * contained in the receiver. + * + * + * @return boolean true if the argument permission is implied + * by the permissions in the receiver, and false 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)) { Index: modules/security/src/common/javasrc/java/security/Policy.java =================================================================== --- modules/security/src/common/javasrc/java/security/Policy.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/Policy.java 2006-03-30 10:13:31.000000000 +0100 @@ -28,9 +28,9 @@ /** - * @com.intel.drl.spec_ref + * Abstract superclass of classes which represent the system security policy. + * */ - public abstract class Policy { // Key to security properties, defining default policy provider. @@ -47,20 +47,40 @@ // The policy currently in effect. private static Policy activePolicy; - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a PermissionCollection describing what permissions are available + * to the given CodeSource based on the current security policy. + *

+ * 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 + * CodeSource the code source to compute the permissions for. + * @return PermissionCollection the permissions the code source should have. + */ public abstract PermissionCollection getPermissions(CodeSource cs); - /** - * @com.intel.drl.spec_ref - */ + /** + * Reloads the policy configuration, depending on how the type of source + * location for the policy information. + * + * + */ public abstract void refresh(); - /** - * @com.intel.drl.spec_ref - * The returned collection does not include static permissions of the domain. - */ + /** + * 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. + */ public PermissionCollection getPermissions(ProtectionDomain domain) { if (domain != null) { return getPermissions(domain.getCodeSource()); @@ -68,9 +88,16 @@ return new Permissions(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * 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 + */ public boolean implies(ProtectionDomain domain, Permission permission) { if (domain != null) { PermissionCollection total = getPermissions(domain); @@ -89,11 +116,13 @@ return false; } - /** - * @com.intel.drl.spec_ref - * If policy was set to null, loads default provider, - * so this method never returns null. - */ + /** + * Answers the current system security policy. If no policy has been + * instantiated then this is done using the security property policy.provider + * + * + * @return Policy the current system security policy. + */ public static Policy getPolicy() { SecurityManager sm = System.getSecurityManager(); if (sm != null) { @@ -166,11 +195,13 @@ return current; } - /** - * @com.intel.drl.spec_ref - * Policy assigment is synchronized with default provider loading, to avoid - * non-deterministic behavior. - */ + /** + * 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. + */ public static void setPolicy(Policy policy) { SecurityManager sm = System.getSecurityManager(); if (sm != null) { Index: modules/security/src/common/javasrc/java/security/Principal.java =================================================================== --- modules/security/src/common/javasrc/java/security/Principal.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/Principal.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,10 +21,12 @@ package java.security; -/** - * @com.intel.drl.spec_ref - */ +/** + * Principals are objects which have identities. These can be individuals, + * groups, corporations, unique program executions, etc. + * + */ public interface Principal { /** * @com.intel.drl.spec_ref Index: modules/security/src/common/javasrc/java/security/PrivilegedActionException.java =================================================================== --- modules/security/src/common/javasrc/java/security/PrivilegedActionException.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/PrivilegedActionException.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,8 +21,11 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * Instances of this class are used to wrap exceptions which occur within + * privileged operations. + * */ public class PrivilegedActionException extends Exception { @@ -36,32 +39,41 @@ */ private Exception exception; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its exception filled in. + * @param ex + */ public PrivilegedActionException(Exception ex) { super(ex); this.exception = ex; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the exception which caused the receiver to be thrown. + * @return exception + */ public Exception getException() { return exception; // return ( getCause() instanceof Exception ) ? // getCause() : null; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the cause of this Throwable, or null if there is no cause. + * + * + * @return Throwable The receiver's cause. + */ public Throwable getCause() { return exception; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * + * @return String a printable representation for the receiver. + */ public String toString() { String s = getClass().getName(); return exception == null ? s : s + ": " + exception; Index: modules/security/src/common/javasrc/java/security/ProtectionDomain.java =================================================================== --- modules/security/src/common/javasrc/java/security/ProtectionDomain.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/ProtectionDomain.java 2006-03-30 10:13:31.000000000 +0100 @@ -22,7 +22,11 @@ package java.security; /** - * @com.intel.drl.spec_ref + * 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. + *

+ * Note: a class can only belong to one and only one protection domain. */ public class ProtectionDomain { @@ -42,9 +46,13 @@ // permissions, true otherwise. private boolean dynamicPerms; - /** - * @com.intel.drl.spec_ref - */ + /** + * Contructs 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 + */ public ProtectionDomain(CodeSource cs, PermissionCollection permissions) { this.codeSource = cs; if (permissions != null) { @@ -56,9 +64,23 @@ //dynamicPerms = false; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Contructs 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 + */ public ProtectionDomain(CodeSource cs, PermissionCollection permissions, ClassLoader cl, Principal[] principals) { this.codeSource = cs; @@ -75,30 +97,41 @@ dynamicPerms = true; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Returns the ClassLoader associated with the ProtectionDomain + * + * @return ClassLoader associated ClassLoader + */ public final ClassLoader getClassLoader() { return classLoader; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the code source of this domain. + * + * @return java.security.CodeSource the code source of this domain + */ public final CodeSource getCodeSource() { return codeSource; } - /** - * @com.intel.drl.spec_ref - */ + /** + * 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. + */ public final PermissionCollection getPermissions() { return permissions; } - /** - * @com.intel.drl.spec_ref - */ + /** + * 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. + */ public final Principal[] getPrincipals() { if( principals == null ) { return new Principal[0]; @@ -108,9 +141,16 @@ return tmp; } - /** - * @com.intel.drl.spec_ref - */ + /** + * 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. + */ public boolean implies(Permission permission) { // First, test with the Policy, as the default Policy.implies() // checks for both dynamic and static collections of the @@ -127,9 +167,12 @@ return permissions == null ? false : permissions.implies(permission); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * @return String a printable representation for the receiver. + */ public String toString() { //FIXME: 1.5 use StreamBuilder here StringBuffer buf = new StringBuffer(200); Index: modules/security/src/common/javasrc/java/security/Provider.java =================================================================== --- modules/security/src/common/javasrc/java/security/Provider.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/Provider.java 2006-03-30 10:42:24.000000000 +0100 @@ -119,34 +119,46 @@ putProviderInfo(); } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Returns the name of this provider. + * + * + * + * @return String name of the provider + */ public String getName() { return name; } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Returns the version number for the services being provided + * + * + * + * @return double version number for the services being provided + */ public double getVersion() { return version; } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Returns the generic information about the services being provided. + * + * + * + * @return String generic description of the services being provided + */ public String getInfo() { return info; } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * + * @return a printable representation for the receiver. + */ public String toString() { return name + " provider, Ver. " + version + " " + info; } @@ -979,10 +991,13 @@ return true; } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Answers a string containing a concise, human-readable + * description of the receiver. + * + * + * @return a printable representation for the receiver. + */ public String toString() { String result = "Provider " + provider.getName() + " Service " + type + "." + algorithm + " " + className; @@ -995,4 +1010,4 @@ return result; } } -} \ No newline at end of file +} Index: modules/security/src/common/javasrc/java/security/PublicKey.java =================================================================== --- modules/security/src/common/javasrc/java/security/PublicKey.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/PublicKey.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,9 +21,13 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * Superinterface for all specific public key interfaces + * * + * @see PublicKey + * @see PrivateKey */ public interface PublicKey extends Key { /** Index: modules/security/src/common/javasrc/java/security/SecureClassLoader.java =================================================================== --- modules/security/src/common/javasrc/java/security/SecureClassLoader.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/SecureClassLoader.java 2006-03-30 10:13:31.000000000 +0100 @@ -25,7 +25,11 @@ import java.util.HashMap; /** - * @com.intel.drl.spec_ref + * 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. + * */ public class SecureClassLoader extends ClassLoader { Index: modules/security/src/common/javasrc/java/security/SecureRandom.java =================================================================== --- modules/security/src/common/javasrc/java/security/SecureRandom.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/SecureRandom.java 2006-03-30 10:13:31.000000000 +0100 @@ -85,11 +85,14 @@ // Internal SecureRandom used for getSeed(int) private static transient SecureRandom internalSecureRandom; - - /** - * @com.intel.drl.spec_ref - * - */ + + /** + * Constructs a new instance of this class. Users are encouraged to use + * getInstance() instead. + * + * An implementation for the highest-priority provider is returned. The + * instance returned will not have been seeded. + */ public SecureRandom() { super(0); Provider.Service service = findService(); @@ -108,10 +111,16 @@ } } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Constructs a new instance of this class. Users are encouraged to use + * getInstance() instead. + * + * An implementation for the highest-priority provider is returned. The + * instance returned will be seeded with the parameter. + * + * @param seed + * bytes forming the seed for this generator. + */ public SecureRandom(byte[] seed) { this(); setSeed(seed); @@ -186,10 +195,21 @@ return getInstance(algorithm, p); } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * 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. + * + * @param algorithm + * java.lang.String Name of the algorithm desired + * @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 + */ public static SecureRandom getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException { if (provider == null) { @@ -204,10 +224,11 @@ } } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Returns the Provider of the secure random represented by the receiver. + * + * @return Provider an instance of a subclass of java.security.Provider + */ public final Provider getProvider() { return provider; } @@ -228,10 +249,15 @@ secureRandomSpi.engineSetSeed(seed); } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Reseeds this random object with the eight bytes described by the + * representation of the long provided. + * + * + * @param seed + * long Number whose representation to use to reseed the + * receiver. + */ public void setSeed(long seed) { if (seed == 0) { // skip call from Random return; @@ -281,10 +307,14 @@ return ret; } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Returns the given number of seed bytes, computed using the seed + * generation algorithm used by this class. + * + * @param numBytes + * int the given number of seed bytes + * @return byte[] The seed bytes generated + */ public static byte[] getSeed(int numBytes) { if (internalSecureRandom == null) { internalSecureRandom = new SecureRandom(); @@ -292,10 +322,14 @@ return internalSecureRandom.generateSeed(numBytes); } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Generates a certain number of seed bytes + * + * + * @param numBytes + * int Number of seed bytes to generate + * @return byte[] The seed bytes generated + */ public byte[] generateSeed(int numBytes) { return secureRandomSpi.engineGenerateSeed(numBytes); } Index: modules/security/src/common/javasrc/java/security/SecureRandomSpi.java =================================================================== --- modules/security/src/common/javasrc/java/security/SecureRandomSpi.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/SecureRandomSpi.java 2006-03-30 10:13:31.000000000 +0100 @@ -24,10 +24,10 @@ import java.io.Serializable; /** - * @com.intel.drl.spec_ref + * This class is a Service Provider Interface (therefore the Spi suffix) for + * secure random number generation algorithms to be supplied by providers. * */ - public abstract class SecureRandomSpi implements Serializable { /** Index: modules/security/src/common/javasrc/java/security/Security.java =================================================================== --- modules/security/src/common/javasrc/java/security/Security.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/Security.java 2006-03-30 10:13:31.000000000 +0100 @@ -42,12 +42,9 @@ import org.apache.harmony.security.fortress.SecurityAccess; import org.apache.harmony.security.fortress.Services; - /** - * @com.intel.drl.spec_ref - * + * For access to security providers and properties. */ - public final class Security { // Security properties @@ -133,11 +130,13 @@ // + "No providers registered."); } - /** - * @com.intel.drl.spec_ref - * - * @deprecated Use {@link KeyFactory} and {@link AlgorithmParameters} to get - * algorithm property information. + /** + * Deprecated method which returns null. + * @param algName + * @param propName + * @return null + * + * @deprecated Use AlgorithmParameters and KeyFactory instead */ public static String getAlgorithmProperty(String algName, String propName) { if (algName == null || propName == null) { @@ -179,10 +178,15 @@ return result; } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Adds the extra provider to the collection of providers. + * @param provider + * + * @return int The priority/position of the provider added. + * @exception SecurityException + * If there is a SecurityManager installed and it denies + * adding a new provider. + */ public static int addProvider(Provider provider) { return insertProviderAt(provider, 0); } @@ -231,10 +235,19 @@ return Services.getProvider(name); } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Returns the collection of providers which meet the user supplied string + * filter. + * + * @param filter + * case-insensitive filter + * @return the providers which meet the user supplied string filter + * filter. A null value signifies + * that none of the installed providers meets the filter + * specification + * @exception InvalidParameterException + * if an unusable filter is supplied + */ public static Provider[] getProviders(String filter) { if (filter == null) { throw new NullPointerException("The filter is null"); @@ -317,10 +330,19 @@ } } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Answers the value of the security property named by the argument. + * + * + * @param key + * String The property name + * @return String The property value + * + * @exception SecurityException + * If there is a SecurityManager installed and it will not + * allow the property to be fetched from the current access + * control context. + */ public static String getProperty(String key) { if (key == null) { throw new NullPointerException("The key is null"); @@ -332,10 +354,19 @@ return secprops.getProperty(key); } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Sets a given security property. + * + * + * @param key + * String The property name. + * @param datnum + * String The property value. + * @exception SecurityException + * If there is a SecurityManager installed and it will not + * allow the property to be set from the current access + * control context. + */ public static void setProperty(String key, String datnum) { SecurityManager sm = System.getSecurityManager(); if (sm != null) { Index: modules/security/src/common/javasrc/java/security/SecurityPermission.java =================================================================== --- modules/security/src/common/javasrc/java/security/SecurityPermission.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/SecurityPermission.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,8 +21,10 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * SecurityPermission objects guard access to the mechanisms which implement + * security. Security permissions have names, but not actions. * */ public final class SecurityPermission extends BasicPermission { @@ -32,16 +34,25 @@ */ private static final long serialVersionUID = 5236109936224050470L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Creates an instance of this class with the given name. + * + * @param name + * String the name of the new permission. + */ public SecurityPermission(String name) { super(name); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Creates an instance of this class with the given name and action list. + * The action list is ignored. + * + * @param name + * String the name of the new permission. + * @param action + * String ignored. + */ public SecurityPermission(String name, String action) { super(name, action); } Index: modules/security/src/common/javasrc/java/security/SignatureException.java =================================================================== --- modules/security/src/common/javasrc/java/security/SignatureException.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/SignatureException.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,8 +21,9 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This class represents generic security exceptions. * */ public class SignatureException extends GeneralSecurityException { @@ -31,16 +32,22 @@ */ private static final long serialVersionUID = 7509989324975124438L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public SignatureException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public SignatureException() { } Index: modules/security/src/common/javasrc/java/security/UnrecoverableKeyException.java =================================================================== --- modules/security/src/common/javasrc/java/security/UnrecoverableKeyException.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/UnrecoverableKeyException.java 2006-03-30 10:13:31.000000000 +0100 @@ -21,8 +21,9 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This class represents exceptions if a key cannot be found in the keystore. * */ public class UnrecoverableKeyException extends GeneralSecurityException { @@ -32,16 +33,22 @@ */ private static final long serialVersionUID = 7275063078190151277L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public UnrecoverableKeyException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public UnrecoverableKeyException() { } } \ No newline at end of file Index: modules/security/src/common/javasrc/java/security/UnresolvedPermission.java =================================================================== --- modules/security/src/common/javasrc/java/security/UnresolvedPermission.java.orig 2006-03-20 18:38:23.000000000 +0000 +++ modules/security/src/common/javasrc/java/security/UnresolvedPermission.java 2006-03-30 11:11:36.000000000 +0100 @@ -38,14 +38,13 @@ import org.apache.harmony.security.fortress.PolicyUtils; - /** - * @com.intel.drl.spec_ref - * Technically, the resolution of UnresolvedPermissions - * and substitution by actual permissions takes place in - * implies() method of a - * Permissions collection, right before - * actual checking. + * Holds permissions which are of an unknown type when a policy file is read. + * + * Technically, the resolution of UnresolvedPermissions and + * substitution by actual permissions takes place in the + * implies() method of a Permissions + * collection, right before actual checking. * */ public final class UnresolvedPermission extends Permission @@ -73,9 +72,17 @@ // Cached hash value private transient int hash; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its type, name, and + * certificates set to the arguments by definition, actions are ignored + * + * @param type + * class of permission object + * @param name + * identifies the permission that could not be resolved + * @param actions + * @param certs + */ public UnresolvedPermission(String type, String name, String actions, Certificate[] certs) { super(type); @@ -108,9 +115,19 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Compares the argument to the receiver, and answers true if they represent + * the same object using a class specific comparison. In this + * case, the receiver and the object must have the same class, permission + * name, actions, and certificates + * + * @param obj + * the object to compare with this object + * @return true if the object is the same as this object, + * false otherwise. + * + * @see #hashCode + */ public boolean equals(Object obj) { if (obj == this) { return true; @@ -130,9 +147,15 @@ return false; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an integer hash code for the receiver. Any two objects which + * answer true when passed to equals must + * answer the same value for this method. + * + * @return the receiver's hash + * + * @see #equals + */ public int hashCode() { if (hash == 0) { hash = getName().hashCode(); @@ -146,9 +169,12 @@ return hash; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the actions associated with the receiver. Since + * UnresolvedPermission objects have no actions, answer the empty string. + * + * @return the actions associated with the receiver. + */ public String getActions() { return ""; } @@ -186,30 +212,43 @@ return null; } - /** - * @com.intel.drl.spec_ref - * The enclosed target permission would be resolved - * and consulted for implication if this - * UnresolvedPermission is an element of a - * Permissions collection and the - * collection's implies() method is - * called. - */ + /** + * Indicates whether the argument permission is implied by the + * receiver. UnresolvedPermission objects imply nothing + * because nothing is known about them yet. + * + * Before actual implication checking, this method tries to + * resolve UnresolvedPermissions (if any) against the passed + * instance. Successfully resolved permissions (if any) are + * taken into account during further processing. + * + * @param permission + * the permission to check + * @return always replies false + */ public boolean implies(Permission permission) { return false; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * @return a printable representation for the receiver. + */ public String toString() { return "(unresolved " + getName() + " " + targetName + " " + targetActions + ")"; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a new PermissionCollection for holding permissions of this class. + * Answer null if any permission collection can be used. + * + * @return a new PermissionCollection or null + * + * @see java.security.BasicPermissionCollection + */ public PermissionCollection newPermissionCollection() { return new UnresolvedPermissionCollection(); } Index: modules/security/src/common/javasrc/java/security/KeyStore.java =================================================================== --- modules/security/src/common/javasrc/java/security/KeyStore.java.orig 2006-03-28 13:37:01.000000000 +0100 +++ modules/security/src/common/javasrc/java/security/KeyStore.java 2006-03-30 10:44:42.000000000 +0100 @@ -1047,4 +1047,4 @@ .toString()); } } -} \ No newline at end of file +}