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 [5/9] - in
/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common:
java/security/ java/security/acl/ java/security/cert/
java/security/interfaces/ java/security/spec/ javax/security/cert/
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Security.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Security.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Security.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Security.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
* limitations under the License.
*/
-/**
-* @author Boris V. Kuznetsov
-* @version $Revision$
-*/
-
package java.security;
import java.io.BufferedInputStream;
@@ -44,7 +39,9 @@
import org.apache.harmony.security.internal.nls.Messages;
/**
- * For access to security providers and properties.
+ * {@code Security} is the central class in the Java Security API. It manages
+ * the list of security {@code Provider} that have been installed into this
+ * runtime environment.
*/
public final class Security {
@@ -131,14 +128,17 @@
secprops.put("security.provider.4", "org.bouncycastle.jce.provider.BouncyCastleProvider"); //$NON-NLS-1$ //$NON-NLS-2$
}
- /**
- * Deprecated method which returns null.
- * @param algName
- * @param propName
- * @return <code>null</code>
- *
- * @deprecated Use AlgorithmParameters and KeyFactory instead
- */
+ /**
+ * Returns value for the specified algorithm with the specified name.
+ *
+ * @param algName
+ * the name of the algorithm.
+ * @param propName
+ * the name of the property.
+ * @return value of the property.
+ * @deprecated Use {@link AlgorithmParameters} and {@link KeyFactory}
+ * instead.
+ */
@Deprecated
public static String getAlgorithmProperty(String algName, String propName) {
if (algName == null || propName == null) {
@@ -159,8 +159,25 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Insert the given {@code Provider} at the specified {@code position}. The
+ * positions define the preference order in which providers are searched for
+ * requested algorithms.
+ * <p>
+ * If a {@code SecurityManager} is installed, code calling this method needs
+ * the {@code SecurityPermission} {@code insertProvider.NAME} (where NAME is
+ * the provider name) to be granted, otherwise a {@code SecurityException}
+ * will be thrown.
+ *
+ * @param provider
+ * the provider to insert.
+ * @param position
+ * the position (starting from 1).
+ * @return the actual position or {@code -1} if the given {@code provider}
+ * was already in the list. The actual position may be different
+ * from the desired position.
+ * @throws SecurityException
+ * if a {@code SecurityManager} is installed and the caller does
+ * not have permission to invoke this method.
*/
public static synchronized int insertProviderAt(Provider provider,
int position) {
@@ -180,22 +197,46 @@
return result;
}
- /**
- * Adds the extra provider to the collection of providers.
- * @param provider
- *
- * @return int The priority/position of the provider added.
- * @exception SecurityException
- * If there is a SecurityManager installed and it denies
- * adding a new provider.
- */
+ /**
+ * Adds the given {@code provider} to the collection of providers at the
+ * next available position.
+ * <p>
+ * If a {@code SecurityManager} is installed, code calling this method needs
+ * the {@code SecurityPermission} {@code insertProvider.NAME} (where NAME is
+ * the provider name) to be granted, otherwise a {@code SecurityException}
+ * will be thrown.
+ *
+ * @param provider
+ * the provider to be added.
+ * @return the actual position or {@code -1} if the given {@code provider}
+ * was already in the list.
+ * @throws SecurityException
+ * if a {@code SecurityManager} is installed and the caller does
+ * not have permission to invoke this method.
+ */
public static int addProvider(Provider provider) {
return insertProviderAt(provider, 0);
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Removes the {@code Provider} with the specified name form the collection
+ * of providers. If the the {@code Provider} with the specified name is
+ * removed, all provider at a greater position are shifted down one
+ * position.
+ * <p>
+ * Returns silently if {@code name} is {@code null} or no provider with the
+ * specified name is installed.
+ * <p>
+ * If a {@code SecurityManager} is installed, code calling this method needs
+ * the {@code SecurityPermission} {@code removeProvider.NAME} (where NAME is
+ * the provider name) to be granted, otherwise a {@code SecurityException}
+ * will be thrown.
+ *
+ * @param name
+ * the name of the provider to remove.
+ * @throws SecurityException
+ * if a {@code SecurityManager} is installed and the caller does
+ * not have permission to invoke this method.
*/
public static synchronized void removeProvider(String name) {
// It is not clear from spec.:
@@ -222,34 +263,51 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Returns an array containing all installed providers. The providers are
+ * ordered according their preference order.
+ *
+ * @return an array containing all installed providers.
*/
public static synchronized Provider[] getProviders() {
return Services.getProviders();
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Returns the {@code Provider} with the specified name. Returns {@code
+ * null} if name is {@code null} or no provider with the specified name is
+ * installed.
+ *
+ * @param name
+ * the name of the requested provider.
+ * @return the provider with the specified name, maybe {@code null}.
*/
public static synchronized Provider getProvider(String name) {
return Services.getProvider(name);
}
- /**
- * Returns the collection of providers which meet the user supplied string
- * filter.
- *
- * @param filter
- * case-insensitive filter
- * @return the providers which meet the user supplied string filter
- * <code>filter</code>. A <code>null</code> value signifies
- * that none of the installed providers meets the filter
- * specification
- * @exception InvalidParameterException
- * if an unusable filter is supplied
- */
+ /**
+ * Returns the array of providers which meet the user supplied string
+ * filter. The specified filter must be supplied in one of two formats:
+ * <nl>
+ * <li> CRYPTO_SERVICE_NAME.ALGORITHM_OR_TYPE
+ * <p>
+ * (for example: "MessageDigest.SHA")
+ * <li> CRYPTO_SERVICE_NAME.ALGORITHM_OR_TYPE
+ * ATTR_NAME:ATTR_VALUE
+ * <p>
+ * (for example: "Signature.MD2withRSA KeySize:512")
+ * </nl>
+ *
+ * @param filter
+ * case-insensitive filter.
+ * @return the providers which meet the user supplied string filter {@code
+ * filter}. A {@code null} value signifies that none of the
+ * installed providers meets the filter specification.
+ * @throws InvalidParameterException
+ * if an unusable filter is supplied.
+ * @throws NullPointerException
+ * if {@code filter} is {@code null}.
+ */
public static Provider[] getProviders(String filter) {
if (filter == null) {
throw new NullPointerException(Messages.getString("security.2A")); //$NON-NLS-1$
@@ -273,8 +331,28 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Returns the array of providers which meet the user supplied set of
+ * filters. The filter must be supplied in one of two formats:
+ * <nl>
+ * <li> CRYPTO_SERVICE_NAME.ALGORITHM_OR_TYPE
+ * <p>
+ * for example: "MessageDigest.SHA" The value associated with the key must
+ * be an empty string. <li> CRYPTO_SERVICE_NAME.ALGORITHM_OR_TYPE
+ * ATTR_NAME:ATTR_VALUE
+ * <p>
+ * for example: "Signature.MD2withRSA KeySize:512" where "KeySize:512" is
+ * the value of the filter map entry.
+ * </nl>
+ *
+ * @param filter
+ * case-insensitive filter.
+ * @return the providers which meet the user supplied string filter {@code
+ * filter}. A {@code null} value signifies that none of the
+ * installed providers meets the filter specification.
+ * @throws InvalidParameterException
+ * if an unusable filter is supplied.
+ * @throws NullPointerException
+ * if {@code filter} is {@code null}.
*/
public static synchronized Provider[] getProviders(Map<String,String> filter) {
if (filter == null) {
@@ -340,19 +418,21 @@
}
}
- /**
- * Answers the value of the security property named by the argument.
- *
- *
- * @param key
- * String The property name
- * @return String The property value
- *
- * @exception SecurityException
- * If there is a SecurityManager installed and it will not
- * allow the property to be fetched from the current access
- * control context.
- */
+ /**
+ * Returns the value of the security property named by the argument.
+ * <p>
+ * If a {@code SecurityManager} is installed, code calling this method needs
+ * the {@code SecurityPermission} {@code getProperty.KEY} (where KEY is the
+ * specified {@code key}) to be granted, otherwise a {@code
+ * SecurityException} will be thrown.
+ *
+ * @param key
+ * the name of the requested security property.
+ * @return the value of the security property.
+ * @throws SecurityException
+ * if a {@code SecurityManager} is installed and the caller does
+ * not have permission to invoke this method.
+ */
public static String getProperty(String key) {
if (key == null) {
throw new NullPointerException(Messages.getString("security.2C")); //$NON-NLS-1$
@@ -368,19 +448,22 @@
return property;
}
- /**
- * Sets a given security property.
- *
- *
- * @param key
- * String The property name.
- * @param datnum
- * String The property value.
- * @exception SecurityException
- * If there is a SecurityManager installed and it will not
- * allow the property to be set from the current access
- * control context.
- */
+ /**
+ * Sets the value of the specified security property.
+ * <p>
+ * If a {@code SecurityManager} is installed, code calling this method needs
+ * the {@code SecurityPermission} {@code setProperty.KEY} (where KEY is the
+ * specified {@code key}) to be granted, otherwise a {@code
+ * SecurityException} will be thrown.
+ *
+ * @param key
+ * the name of the security property.
+ * @param datnum
+ * the value of the security property.
+ * @throws SecurityException
+ * if a {@code SecurityManager} is installed and the caller does
+ * not have permission to invoke this method.
+ */
public static void setProperty(String key, String datnum) {
SecurityManager sm = System.getSecurityManager();
if (sm != null) {
@@ -390,8 +473,16 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Returns a {@code Set} of all registered algorithms for the specified
+ * cryptographic service. {@code "Signature"}, {@code "Cipher"} and {@code
+ * "KeyStore"} are examples for such kind of services.
+ *
+ * @param serviceName
+ * the case-insensitive name of the service.
+ * @return a {@code Set} of all registered algorithms for the specified
+ * cryptographic service, or an empty {@code Set} if {@code
+ * serviceName} is {@code null} or if no registered provider
+ * provides the requested service.
*/
public static Set<String> getAlgorithms(String serviceName) {
Set<String> result = new HashSet<String>();
@@ -409,7 +500,7 @@
/**
*
- * Update sequence numbers of all providers
+ * Update sequence numbers of all providers.
*
*/
private static void renumProviders() {
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecurityPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecurityPermission.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecurityPermission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SecurityPermission.java Tue Apr 28 17:01:41 2009
@@ -15,44 +15,37 @@
* limitations under the License.
*/
-/**
-* @author Alexey V. Varlamov
-* @version $Revision$
-*/
-
package java.security;
/**
- * SecurityPermission objects guard access to the mechanisms which implement
- * security. Security permissions have names, but not actions.
- *
+ * {@code SecurityPermission} objects guard access to the mechanisms which
+ * implement security. Security permissions have names, but not actions.
*/
public final class SecurityPermission extends BasicPermission {
- /**
- * @com.intel.drl.spec_ref
- */
private static final long serialVersionUID = 5236109936224050470L;
- /**
- * Creates an instance of this class with the given name.
- *
- * @param name
- * String the name of the new permission.
- */
+ /**
+ * Constructs a new instance of {@code SecurityPermission} with the given
+ * name.
+ *
+ * @param name
+ * the name of the permission.
+ */
public SecurityPermission(String name) {
super(name);
}
- /**
- * Creates an instance of this class with the given name and action list.
- * The action list is ignored.
- *
- * @param name
- * String the name of the new permission.
- * @param action
- * String ignored.
- */
+ /**
+ * Constructs a new instance of {@code SecurityPermission} with the given
+ * {@code name} and {@code action} list. The action list is ignored - it is
+ * existing for compatibility reasons only.
+ *
+ * @param name
+ * the name of the permission.
+ * @param action
+ * ignored.
+ */
public SecurityPermission(String name, String action) {
super(name, action);
}
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Signature.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Signature.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Signature.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Signature.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
* limitations under the License.
*/
-/**
-* @author Boris V. Kuznetsov
-* @version $Revision$
-*/
-
package java.security;
import java.nio.ByteBuffer;
@@ -34,10 +29,12 @@
/**
- * @com.intel.drl.spec_ref
+ * {@code Signature} is an engine class which is capable of creating and
+ * verifying digital signatures, using different algorithms that have been
+ * registered with the {@link Security} class.
*
+ * @see SignatureSpi
*/
-
public abstract class Signature extends SignatureSpi {
// The service name.
@@ -53,40 +50,53 @@
private String algorithm;
/**
- * @com.intel.drl.spec_ref
- *
+ * Constant that indicates that this {@code Signature} instance has not yet
+ * been initialized.
*/
protected static final int UNINITIALIZED = 0;
/**
- * @com.intel.drl.spec_ref
- *
+ * Constant that indicates that this {@code Signature} instance has been
+ * initialized for signing.
*/
protected static final int SIGN = 2;
/**
- * @com.intel.drl.spec_ref
- *
+ * Constant that indicates that this {@code Signature} instance has been
+ * initialized for verification.
*/
protected static final int VERIFY = 3;
/**
- * @com.intel.drl.spec_ref
- *
+ * Represents the current state of this {@code Signature}. The three
+ * possible states are {@link #UNINITIALIZED}, {@link #SIGN} or
+ * {@link #VERIFY}.
*/
protected int state = UNINITIALIZED;
/**
- * @com.intel.drl.spec_ref
- *
+ * Constructs a new instance of {@code Signature} with the name of
+ * the algorithm to use.
+ *
+ * @param algorithm
+ * the name of algorithm to use.
*/
protected Signature(String algorithm) {
this.algorithm = algorithm;
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Returns a new instance of {@code Signature} that utilizes the specified
+ * algorithm.
+ *
+ * @param algorithm
+ * the name of the algorithm to use.
+ * @return a new instance of {@code Signature} that utilizes the specified
+ * algorithm.
+ * @throws NoSuchAlgorithmException
+ * if the specified algorithm is not available.
+ * @throws NullPointerException
+ * if {@code algorithm} is {@code null}.
*/
public static Signature getInstance(String algorithm)
throws NoSuchAlgorithmException {
@@ -109,8 +119,21 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Returns a new instance of {@code Signature} that utilizes the specified
+ * algorithm from the specified provider.
+ *
+ * @param algorithm
+ * the name of the algorithm to use.
+ * @param provider
+ * the name of the provider.
+ * @return a new instance of {@code Signature} that utilizes the specified
+ * algorithm from the specified provider.
+ * @throws NoSuchAlgorithmException
+ * if the specified algorithm is not available.
+ * @throws NoSuchProviderException
+ * if the specified provider is not available.
+ * @throws NullPointerException
+ * if {@code algorithm} is {@code null}.
*/
public static Signature getInstance(String algorithm, String provider)
throws NoSuchAlgorithmException, NoSuchProviderException {
@@ -129,8 +152,19 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Returns a new instance of {@code Signature} that utilizes the specified
+ * algorithm from the specified provider.
+ *
+ * @param algorithm
+ * the name of the algorithm to use.
+ * @param provider
+ * the security provider.
+ * @return a new instance of {@code Signature} that utilizes the specified
+ * algorithm from the specified provider.
+ * @throws NoSuchAlgorithmException
+ * if the specified algorithm is not available.
+ * @throws NullPointerException
+ * if {@code algorithm} is {@code null}.
*/
public static Signature getInstance(String algorithm, Provider provider)
throws NoSuchAlgorithmException {
@@ -161,24 +195,32 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Returns the provider associated with this {@code Signature}.
+ *
+ * @return the provider associated with this {@code Signature}.
*/
public final Provider getProvider() {
return provider;
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Returns the name of the algorithm of this {@code Signature}.
+ *
+ * @return the name of the algorithm of this {@code Signature}.
*/
public final String getAlgorithm() {
return algorithm;
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Initializes this {@code Signature} instance for signature verification,
+ * using the public key of the identity whose signature is going to be
+ * verified.
+ *
+ * @param publicKey
+ * the public key.
+ * @throws InvalidKeyException
+ * if {@code publicKey} is not valid.
*/
public final void initVerify(PublicKey publicKey)
throws InvalidKeyException {
@@ -187,8 +229,19 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Initializes this {@code Signature} instance for signature verification,
+ * using the certificate of the identity whose signature is going to be
+ * verified.
+ * <p>
+ * If the given certificate is an instance of {@link X509Certificate} and
+ * has a key usage parameter that indicates, that this certificate is not to
+ * be used for signing, an {@code InvalidKeyException} is thrown.
+ *
+ * @param certificate
+ * the certificate used to verify a signature.
+ * @throws InvalidKeyException
+ * if the publicKey in the certificate is not valid or not to be
+ * used for signing.
*/
public final void initVerify(Certificate certificate)
throws InvalidKeyException {
@@ -224,8 +277,13 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Initializes this {@code Signature} instance for signing, using the
+ * private key of the identity whose signature is going to be generated.
+ *
+ * @param privateKey
+ * the private key.
+ * @throws InvalidKeyException
+ * if {@code privateKey} is not valid.
*/
public final void initSign(PrivateKey privateKey)
throws InvalidKeyException {
@@ -234,8 +292,16 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Initializes this {@code Signature} instance for signing, using the
+ * private key of the identity whose signature is going to be generated and
+ * the specified source of randomness.
+ *
+ * @param privateKey
+ * the private key.
+ * @param random
+ * the {@code SecureRandom} to use.
+ * @throws InvalidKeyException
+ * if {@code privateKey} is not valid.
*/
public final void initSign(PrivateKey privateKey, SecureRandom random)
throws InvalidKeyException {
@@ -244,8 +310,16 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Generates and returns the signature of all updated data.
+ * <p>
+ * This {@code Signature} instance is reset to the state of its last
+ * initialization for signing and thus can be used for another signature
+ * from the same identity.
+ *
+ * @return the signature of all updated data.
+ * @throws SignatureException
+ * if this {@code Signature} instance is not initialized
+ * properly.
*/
public final byte[] sign() throws SignatureException {
if (state != SIGN) {
@@ -256,8 +330,26 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Generates and stores the signature of all updated data in the provided
+ * {@code byte[]} at the specified position with the specified length.
+ * <p>
+ * This {@code Signature} instance is reset to the state of its last
+ * initialization for signing and thus can be used for another signature
+ * from the same identity.
+ *
+ * @param outbuf
+ * the buffer to store the signature.
+ * @param offset
+ * the index of the first byte in {@code outbuf} to store.
+ * @param len
+ * the number of bytes allocated for the signature.
+ * @return the number of bytes stored in {@code outbuf}.
+ * @throws SignatureException
+ * if this {@code Signature} instance is not initialized
+ * properly.
+ * @throws IllegalArgumentException
+ * if {@code offset} or {@code len} are not valid in respect to
+ * {@code outbuf}.
*/
public final int sign(byte[] outbuf, int offset, int len)
throws SignatureException {
@@ -274,8 +366,20 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Indicates whether the given {@code signature} can be verified using the
+ * public key or a certificate of the signer.
+ * <p>
+ * This {@code Signature} instance is reset to the state of its last
+ * initialization for verifying and thus can be used to verify another
+ * signature of the same signer.
+ *
+ * @param signature
+ * the signature to verify.
+ * @return {@code true} if the signature was verified, {@code false}
+ * otherwise.
+ * @throws SignatureException
+ * if this {@code Signature} instance is not initialized
+ * properly.
*/
public final boolean verify(byte[] signature) throws SignatureException {
if (state != VERIFY) {
@@ -286,8 +390,28 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Indicates whether the given {@code signature} starting at index {@code
+ * offset} with {@code length} bytes can be verified using the public key or
+ * a certificate of the signer.
+ * <p>
+ * This {@code Signature} instance is reset to the state of its last
+ * initialization for verifying and thus can be used to verify another
+ * signature of the same signer.
+ *
+ * @param signature
+ * the {@code byte[]} containing the signature to verify.
+ * @param offset
+ * the start index in {@code signature} of the signature.
+ * @param length
+ * the number of bytes allocated for the signature.
+ * @return {@code true} if the signature was verified, {@code false}
+ * otherwise.
+ * @throws SignatureException
+ * if this {@code Signature} instance is not initialized
+ * properly.
+ * @throws IllegalArgumentException
+ * if {@code offset} or {@code length} are not valid in respect
+ * to {@code signature}.
*/
public final boolean verify(byte[] signature, int offset, int length)
throws SignatureException {
@@ -304,8 +428,14 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Updates the data to be verified or to be signed, using the specified
+ * {@code byte}.
+ *
+ * @param b
+ * the byte to update with.
+ * @throws SignatureException
+ * if this {@code Signature} instance is not initialized
+ * properly.
*/
public final void update(byte b) throws SignatureException {
if (state == UNINITIALIZED) {
@@ -316,8 +446,14 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Updates the data to be verified or to be signed, using the specified
+ * {@code byte[]}.
+ *
+ * @param data
+ * the byte array to update with.
+ * @throws SignatureException
+ * if this {@code Signature} instance is not initialized
+ * properly.
*/
public final void update(byte[] data) throws SignatureException {
if (state == UNINITIALIZED) {
@@ -328,8 +464,18 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Updates the data to be verified or to be signed, using the given {@code
+ * byte[]}, starting form the specified index for the specified length.
+ *
+ * @param data
+ * the byte array to update with.
+ * @param off
+ * the start index in {@code data} of the data.
+ * @param len
+ * the number of bytes to use.
+ * @throws SignatureException
+ * if this {@code Signature} instance is not initialized
+ * properly.
*/
public final void update(byte[] data, int off, int len)
throws SignatureException {
@@ -346,8 +492,14 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Updates the data to be verified or to be signed, using the specified
+ * {@code ByteBuffer}.
+ *
+ * @param data
+ * the {@code ByteBuffer} to update with.
+ * @throws SignatureException
+ * if this {@code Signature} instance is not initialized
+ * properly.
*/
public final void update(ByteBuffer data) throws SignatureException {
if (state == UNINITIALIZED) {
@@ -358,8 +510,10 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Returns a string containing a concise, human-readable description of this
+ * {@code Signature} including its algorithm and its state.
+ *
+ * @return a printable representation for this {@code Signature}.
*/
public String toString() {
return "SIGNATURE " + algorithm + " state: " + stateToString(state); //$NON-NLS-1$ //$NON-NLS-2$
@@ -380,9 +534,16 @@
}
/**
- * @com.intel.drl.spec_ref
- *
- * @deprecated Use {@link Signature#setParameter(AlgorithmParameterSpec) setParameter}
+ * Sets the specified parameter to the given value.
+ *
+ * @param param
+ * the name of the parameter.
+ * @param value
+ * the parameter value.
+ * @throws InvalidParameterException
+ * if the parameter is invalid, already set or is not allowed to
+ * be changed.
+ * @deprecated Use {@link #setParameter(AlgorithmParameterSpec)}
*/
@Deprecated
public final void setParameter(String param, Object value)
@@ -391,8 +552,13 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Sets the specified {@code AlgorithmParameterSpec}.
+ *
+ * @param params
+ * the parameter to set.
+ * @throws InvalidAlgorithmParameterException
+ * if the parameter is invalid, already set or is not allowed to
+ * be changed.
*/
public final void setParameter(AlgorithmParameterSpec params)
throws InvalidAlgorithmParameterException {
@@ -400,16 +566,26 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Returns the {@code AlgorithmParameters} of this {@link Signature}
+ * instance.
+ *
+ * @return the {@code AlgorithmParameters} of this {@link Signature}
+ * instance, maybe {@code null}.
*/
public final AlgorithmParameters getParameters() {
return engineGetParameters();
}
/**
- * @com.intel.drl.spec_ref
+ * Returns the value of the parameter with the specified name.
*
+ * @param param
+ * the name of the requested parameter value
+ * @return the value of the parameter with the specified name, maybe {@code
+ * null}.
+ * @throws InvalidParameterException
+ * if {@code param} is not a valid parameter for this {@code
+ * Signature} or an other error occures.
* @deprecated There is no generally accepted parameter naming convention.
*/
@Deprecated
@@ -418,10 +594,6 @@
return engineGetParameter(param);
}
- /**
- * @com.intel.drl.spec_ref
- *
- */
public Object clone() throws CloneNotSupportedException {
if (this instanceof Cloneable) {
return super.clone();
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignatureException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignatureException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignatureException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignatureException.java Tue Apr 28 17:01:41 2009
@@ -15,51 +15,53 @@
* limitations under the License.
*/
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
package java.security;
/**
- * This class represents generic security exceptions.
+ *{@code SignatureException} is a general {@code Signature} exception.
*
+ * @see Signature
*/
public class SignatureException extends GeneralSecurityException {
- /**
- * @com.intel.drl.spec_ref
- */
+
private static final long serialVersionUID = 7509989324975124438L;
- /**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
- *
- *
- * @param msg
- * String The detail message for the exception.
- */
+ /**
+ * Constructs a new instance of {@code SignatureException} with the
+ * given message.
+ *
+ * @param msg
+ * the detail message for this exception.
+ */
public SignatureException(String msg) {
super(msg);
}
- /**
- * Constructs a new instance of this class with its walkback filled in.
- *
- */
+ /**
+ * Constructs a new instance of {@code SignatureException}.
+ */
public SignatureException() {
}
/**
- * @com.intel.drl.spec_ref
+ * Constructs a new instance of {@code SignatureException} with the
+ * given message and the cause.
+ *
+ * @param message
+ * the detail message for this exception
+ * @param cause
+ * the exception which is the cause for this exception
*/
public SignatureException(String message, Throwable cause) {
super(message, cause);
}
/**
- * @com.intel.drl.spec_ref
+ * Constructs a new instance of {@code SignatureException} with the
+ * cause.
+ *
+ * @param cause
+ * the exception which is the cause for this exception
*/
public SignatureException(Throwable cause) {
super(cause);
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignatureSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignatureSpi.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignatureSpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignatureSpi.java Tue Apr 28 17:01:41 2009
@@ -14,10 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/**
-* @author Boris V. Kuznetsov
-* @version $Revision$
-*/
package java.security;
@@ -27,35 +23,54 @@
import org.apache.harmony.security.internal.nls.Messages;
/**
- * @com.intel.drl.spec_ref
+ * {@code SignatureSpi} is the <i>Service Provider Interface</i> (<b>SPI</b>)
+ * definition for {@link Signature}.
*
+ * @see Signature
*/
-
public abstract class SignatureSpi {
/**
- * @com.intel.drl.spec_ref
- *
+ * Implementation specific source of randomness.
*/
protected SecureRandom appRandom;
/**
- * @com.intel.drl.spec_ref
- *
+ * Initializes this {@code SignatureSpi} instance for signature
+ * verification, using the public key of the identity whose signature is
+ * going to be verified.
+ *
+ * @param publicKey
+ * the public key.
+ * @throws InvalidKeyException
+ * if {@code publicKey} is not valid.
*/
protected abstract void engineInitVerify(PublicKey publicKey)
throws InvalidKeyException;
/**
- * @com.intel.drl.spec_ref
- *
+ * Initializes this {@code SignatureSpi} instance for signing, using the
+ * private key of the identity whose signature is going to be generated.
+ *
+ * @param privateKey
+ * the private key.
+ * @throws InvalidKeyException
+ * if {@code privateKey} is not valid.
*/
protected abstract void engineInitSign(PrivateKey privateKey)
throws InvalidKeyException;
/**
- * @com.intel.drl.spec_ref
- *
+ * Initializes this {@code SignatureSpi} instance for signing, using the
+ * private key of the identity whose signature is going to be generated and
+ * the specified source of randomness.
+ *
+ * @param privateKey
+ * the private key.
+ * @param random
+ * the {@code SecureRandom} to use.
+ * @throws InvalidKeyException
+ * if {@code privateKey} is not valid.
*/
protected void engineInitSign(PrivateKey privateKey, SecureRandom random)
throws InvalidKeyException {
@@ -64,24 +79,45 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Updates the data to be verified or to be signed, using the specified
+ * {@code byte}.
+ *
+ * @param b
+ * the byte to update with.
+ * @throws SignatureException
+ * if this {@code SignatureSpi} instance is not initialized
+ * properly.
*/
protected abstract void engineUpdate(byte b) throws SignatureException;
/**
- * @com.intel.drl.spec_ref
- *
+ * Updates the data to be verified or to be signed, using the given {@code
+ * byte[]}, starting form the specified index for the specified length.
+ *
+ * @param b
+ * the byte array to update with.
+ * @param off
+ * the start index in {@code b} of the data.
+ * @param len
+ * the number of bytes to use.
+ * @throws SignatureException
+ * if this {@code SignatureSpi} instance is not initialized
+ * properly.
*/
protected abstract void engineUpdate(byte[] b, int off, int len)
throws SignatureException;
/**
- * @com.intel.drl.spec_ref
+ * Updates the data to be verified or to be signed, using the specified
+ * {@code ByteBuffer}.
*
- * The SignatureException is not specified for this method.
- * So throw RuntimeException if underlying engineUpdate(byte[] b, int off, int len)
- * throws SignatureException.
+ * @param input
+ * the {@code ByteBuffer} to update with.
+ * @throws RuntimeException
+ * since {@code SignatureException} is not specified for this
+ * method it throws a {@code RuntimeException} if underlying
+ * {@link #engineUpdate(byte[], int, int)} throws {@code
+ * SignatureException}.
*/
protected void engineUpdate(ByteBuffer input) {
if (!input.hasRemaining()) {
@@ -111,14 +147,40 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Generates and returns the signature of all updated data.
+ * <p>
+ * This {@code SignatureSpi} instance is reset to the state of its last
+ * initialization for signing and thus can be used for another signature
+ * from the same identity.
+ *
+ * @return the signature of all updated data.
+ * @throws SignatureException
+ * if this {@code SignatureSpi} instance is not initialized
+ * properly.
*/
protected abstract byte[] engineSign() throws SignatureException;
/**
- * @com.intel.drl.spec_ref
- *
+ * Generates and stores the signature of all updated data in the provided
+ * {@code byte[]} at the specified position with the specified length.
+ * <p>
+ * This {@code SignatureSpi} instance is reset to the state of its last
+ * initialization for signing and thus can be used for another signature
+ * from the same identity.
+ *
+ * @param outbuf
+ * the buffer to store the signature.
+ * @param offset
+ * the index of the first byte in {@code outbuf} to store.
+ * @param len
+ * the number of bytes allocated for the signature.
+ * @return the number of bytes stored in {@code outbuf}.
+ * @throws SignatureException
+ * if this {@code SignatureSpi} instance is not initialized
+ * properly.
+ * @throws IllegalArgumentException
+ * if {@code offset} or {@code len} are not valid in respect to
+ * {@code outbuf}.
*/
protected int engineSign(byte[] outbuf, int offset, int len)
throws SignatureException {
@@ -140,15 +202,47 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Indicates whether the given {@code sigBytes} can be verified using the
+ * public key or a certificate of the signer.
+ * <p>
+ * This {@code SignatureSpi} instance is reset to the state of its last
+ * initialization for verifying and thus can be used to verify another
+ * signature of the same signer.
+ *
+ * @param sigBytes
+ * the signature to verify.
+ * @return {@code true} if the signature was verified, {@code false}
+ * otherwise.
+ * @throws SignatureException
+ * if this {@code SignatureSpi} instance is not initialized
+ * properly.
*/
protected abstract boolean engineVerify(byte[] sigBytes)
throws SignatureException;
/**
- * @com.intel.drl.spec_ref
- *
+ * Indicates whether the given {@code sigBytes} starting at index {@code
+ * offset} with {@code length} bytes can be verified using the public key or
+ * a certificate of the signer.
+ * <p>
+ * This {@code SignatureSpi} instance is reset to the state of its last
+ * initialization for verifying and thus can be used to verify another
+ * signature of the same signer.
+ *
+ * @param sigBytes
+ * the {@code byte[]} containing the signature to verify.
+ * @param offset
+ * the start index in {@code sigBytes} of the signature
+ * @param length
+ * the number of bytes allocated for the signature.
+ * @return {@code true} if the signature was verified, {@code false}
+ * otherwise.
+ * @throws SignatureException
+ * if this {@code SignatureSpi} instance is not initialized
+ * properly.
+ * @throws IllegalArgumentException
+ * if {@code offset} or {@code length} are not valid in respect
+ * to {@code sigBytes}.
*/
protected boolean engineVerify(byte[] sigBytes, int offset, int length)
throws SignatureException {
@@ -158,18 +252,29 @@
}
/**
- * @com.intel.drl.spec_ref
- *
- * @deprecated Use
- * {@link SignatureSpi#engineSetParameter(AlgorithmParameterSpec) engineSetParameter}
- */
+ * Sets the specified parameter to the given value.
+ *
+ * @param param
+ * the name of the parameter.
+ * @param value
+ * the parameter value.
+ * @throws InvalidParameterException
+ * if the parameter is invalid, already set or is not allowed to
+ * be changed.
+ * @deprecated Use {@link #engineSetParameter(AlgorithmParameterSpec)}
+ */
@Deprecated
protected abstract void engineSetParameter(String param, Object value)
throws InvalidParameterException;
/**
- * @com.intel.drl.spec_ref
- *
+ * Sets the specified {@code AlgorithmParameterSpec}.
+ *
+ * @param params
+ * the parameter to set.
+ * @throws InvalidAlgorithmParameterException
+ * if the parameter is invalid, already set or is not allowed to
+ * be changed.
*/
protected void engineSetParameter(AlgorithmParameterSpec params)
throws InvalidAlgorithmParameterException {
@@ -177,26 +282,32 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Returns the {@code AlgorithmParameters} of this {@link SignatureSpi}
+ * instance.
+ *
+ * @return the {@code AlgorithmParameters} of this {@link SignatureSpi}
+ * instance, maybe {@code null}.
*/
protected AlgorithmParameters engineGetParameters() {
throw new UnsupportedOperationException();
}
/**
- * @com.intel.drl.spec_ref
- *
- * @deprecated There is no generally accepted parameter naming convention.
- */
+ * Returns the value of the parameter with the specified name.
+ *
+ * @param param
+ * the name of the requested parameter value.
+ * @return the value of the parameter with the specified name, maybe {@code
+ * null}.
+ * @throws InvalidParameterException
+ * if {@code param} is not a valid parameter for this {@code
+ * SignatureSpi} or an other error occurs.
+ * @deprecated There is no generally accepted parameter naming convention.
+ */
@Deprecated
protected abstract Object engineGetParameter(String param)
throws InvalidParameterException;
- /**
- * @com.intel.drl.spec_ref
- *
- */
public Object clone() throws CloneNotSupportedException {
if (this instanceof Cloneable) {
return super.clone();
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignedObject.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignedObject.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignedObject.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/SignedObject.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
* limitations under the License.
*/
-/**
-* @author Boris V. Kuznetsov
-* @version $Revision$
-*/
-
package java.security;
import java.io.ByteArrayInputStream;
@@ -30,35 +25,20 @@
import java.io.Serializable;
/**
- * @com.intel.drl.spec_ref
- *
+ * A {@code SignedObject} instance acts as a container for another object. The
+ * {@code SignedObject} contains the target in serialized form along with a
+ * digital signature of the serialized data.
*/
public final class SignedObject implements Serializable {
- /**
- * @com.intel.drl.spec_ref
- */
private static final long serialVersionUID = 720502720485447167L;
- /**
- * @com.intel.drl.spec_ref
- */
private byte[] content;
- /**
- * @com.intel.drl.spec_ref
- */
private byte[] signature;
- /**
- * @com.intel.drl.spec_ref
- */
private String thealgorithm;
- /**
- * @com.intel.drl.spec_ref
- *
- */
private void readObject(ObjectInputStream s) throws IOException,
ClassNotFoundException {
@@ -72,8 +52,22 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Constructs a new instance of {@code SignedObject} with the target object,
+ * the private key and the engine to compute the signature. The given
+ * {@code object} is signed with the specified key and engine.
+ *
+ * @param object
+ * the object to bes signed.
+ * @param signingKey
+ * the private key, used to sign the {@code object}.
+ * @param signingEngine
+ * the engine that performs the signature generation.
+ * @throws IOException
+ * if a serialization error occurs.
+ * @throws InvalidKeyException
+ * if the private key is not valid.
+ * @throws SignatureException
+ * if signature generation failed.
*/
public SignedObject(Serializable object, PrivateKey signingKey,
Signature signingEngine) throws IOException, InvalidKeyException,
@@ -96,8 +90,14 @@
}
/**
- * @com.intel.drl.spec_ref
+ * Returns the encapsulated object. Each time this method is invoked, the
+ * encapsulated object is deserialized before it is returned.
*
+ * @return the encapsulated object.
+ * @throws IOException
+ * if deserialization failed.
+ * @throws ClassNotFoundException
+ * if the class of the encapsulated object can not be found.
*/
public Object getObject() throws IOException, ClassNotFoundException {
// deserialize our object
@@ -111,8 +111,9 @@
}
/**
- * @com.intel.drl.spec_ref
+ * Returns the signature data of the encapsulated serialized object.
*
+ * @return the signature data of the encapsulated serialized object.
*/
public byte[] getSignature() {
byte[] sig = new byte[signature.length];
@@ -121,16 +122,28 @@
}
/**
- * @com.intel.drl.spec_ref
+ * Returns the name of the algorithm of this {@code SignedObject}.
*
+ * @return the name of the algorithm of this {@code SignedObject}.
*/
public String getAlgorithm() {
return thealgorithm;
}
/**
- * @com.intel.drl.spec_ref
+ * Indicates whether the contained signature for the encapsulated object is
+ * valid.
*
+ * @param verificationKey
+ * the public key to verify the signature.
+ * @param verificationEngine
+ * the signature engine.
+ * @return {@code true} if the contained signature for the encapsulated
+ * object is valid, {@code false} otherwise.
+ * @throws InvalidKeyException
+ * if the public key is invalid.
+ * @throws SignatureException
+ * if signature verification failed.
*/
public boolean verify(PublicKey verificationKey,
Signature verificationEngine) throws InvalidKeyException,
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Signer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Signer.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Signer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Signer.java Tue Apr 28 17:01:41 2009
@@ -15,49 +15,51 @@
* limitations under the License.
*/
-/**
- * @author Aleksei Y. Semenov
- * @version $Revision$
- */
-
package java.security;
/**
- * @com.intel.drl.spec_ref
+ * {@link Signer} represents an identity (individual or corporation) that owns a
+ * private key and the corresponding public key.
*
- * @deprecated Replaced by behavior in
- * {@link java.security.cert java.security.cert} package and
- * {@link java.security.Principal Principal}
+ * @deprecated Replaced by behavior in {@link java.security.cert
+ * java.security.cert} package and {@link java.security.Principal
+ * Principal}
*/
@Deprecated
public abstract class Signer extends Identity {
- /**
- * @com.intel.drl.spec_ref
- */
private static final long serialVersionUID = -1763464102261361480L;
- /**
- * @com.intel.drl.spec_ref
- */
private PrivateKey privateKey;
/**
- * @com.intel.drl.spec_ref
+ * Constructs a new instance of {@code Signer}.
*/
protected Signer() {
super();
}
/**
- * @com.intel.drl.spec_ref
+ * Constructs a new instance of {@code Signer} with the given name.
+ *
+ * @param name
+ * the name of the signer.
*/
public Signer(String name) {
super(name);
}
/**
- * @com.intel.drl.spec_ref
+ * Constructs a new instance of {@code Signer} with the given name in the
+ * given scope.
+ *
+ * @param name
+ * the name of the signer.
+ * @param scope
+ * the scope of the signer.
+ * @throws KeyManagementException
+ * if a signer with the specified name already exists in the
+ * provided scope.
*/
public Signer(String name, IdentityScope scope)
throws KeyManagementException {
@@ -65,7 +67,15 @@
}
/**
- * @com.intel.drl.spec_ref
+ * Returns the private key of this {@code Signer}. If a {@code
+ * SecurityManager} is installed, code calling this method needs the {@code
+ * SecurityPermission} {@code "getSignerPrivateKey"} to be granted, otherwise
+ * a {@code SecurityException} will be thrown.
+ *
+ * @return the private key of this {@code Signer}.
+ * @throws SecurityException
+ * if a {@code SecurityManager} is installed and the caller does
+ * not have permission to invoke this method.
*/
public PrivateKey getPrivateKey() {
SecurityManager sm = System.getSecurityManager();
@@ -77,7 +87,20 @@
}
/**
- * @com.intel.drl.spec_ref
+ * Associates the specified key pair with this {@code Signer}. If a {@code
+ * SecurityManager} is installed, code calling this method needs the {@code
+ * SecurityPermission} {@code getSignerPrivateKey} to be granted, otherwise
+ * a {@code SecurityException} will be thrown.
+ *
+ * @param pair
+ * the key pair to associate with this {@code Signer}.
+ * @throws InvalidParameterException
+ * if the key pair is invalid.
+ * @throws KeyException
+ * if any other key related problem occurs.
+ * @throws SecurityException
+ * if a {@code SecurityManager} is installed and the caller does
+ * not have permission to invoke this method.
*/
public final void setKeyPair(KeyPair pair)
throws InvalidParameterException, KeyException {
@@ -108,7 +131,10 @@
}
/**
- * @com.intel.drl.spec_ref
+ * Returns a string containing a concise, human-readable description of this
+ * {@code Signer} including its name and its scope if present.
+ *
+ * @return a printable representation for this {@code Signer}.
*/
public String toString() {
String s = "[Signer]" + getName(); //$NON-NLS-1$
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Timestamp.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Timestamp.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Timestamp.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Timestamp.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
* limitations under the License.
*/
-/**
-* @author Alexander V. Astapchuk
-* @version $Revision$
-*/
-
package java.security;
import java.io.Serializable;
@@ -29,14 +24,11 @@
import org.apache.harmony.security.internal.nls.Messages;
/**
- * @com.intel.drl.spec_ref
+ * {@code Timestamp} represents a signed time stamp. {@code Timestamp} is
+ * immutable.
*/
-
public final class Timestamp implements Serializable {
- /**
- * @com.intel.drl.spec_ref
- */
private static final long serialVersionUID = -5502683707821851294L;
private Date timestamp;
@@ -47,7 +39,16 @@
private transient int hash;
/**
- * @com.intel.drl.spec_ref
+ * Constructs a new instance of {@code Timestamp} with the specified {@code
+ * timestamp} and the given certificate path.
+ *
+ * @param timestamp
+ * date and time.
+ * @param signerCertPath
+ * the certificate path.
+ * @throws NullPointerException
+ * if {@code timestamp} is {@code null} or if {@code
+ * signerCertPath} is {@code null}.
*/
public Timestamp(Date timestamp, CertPath signerCertPath) {
if (timestamp == null) {
@@ -62,7 +63,18 @@
}
/**
- * @com.intel.drl.spec_ref
+ * Compares the specified object with this {@code Timestamp} for equality
+ * and returns {@code true} if the specified object is equal, {@code false}
+ * otherwise. The given object is equal to this {@code Timestamp}, if it is
+ * an instance of {@code Timestamp}, the two timestamps have an equal date
+ * and time and their certificate paths are equal.
+ *
+ * @param obj
+ * object to be compared for equality with this {@code
+ * Timestamp}.
+ * @return {@code true} if the specified object is equal to this {@code
+ * Timestamp}, otherwise {@code false}.
+ * @see #hashCode
*/
public boolean equals(Object obj) {
if (obj == this) {
@@ -77,21 +89,31 @@
}
/**
- * @com.intel.drl.spec_ref
+ * Returns the certificate path of this {@code Timestamp}.
+ *
+ * @return the certificate path of this {@code Timestamp}.
*/
public CertPath getSignerCertPath() {
return signerCertPath;
}
/**
- * @com.intel.drl.spec_ref
+ * Returns the date and time of this {@code Timestamp}.
+ *
+ * @return the date and time of this {@code Timestamp}.
*/
public Date getTimestamp() {
return (Date) timestamp.clone();
}
/**
- * @com.intel.drl.spec_ref
+ * Returns the hash code value for this {@code Timestamp}. Returns the same
+ * hash code for {@code Timestamp}s that are equal to each other as
+ * required by the general contract of {@link Object#hashCode}.
+ *
+ * @return the hash code value for this {@code Timestamp}.
+ * @see Object#equals(Object)
+ * @see Timestamp#equals(Object)
*/
public int hashCode() {
if (hash == 0) {
@@ -101,7 +123,10 @@
}
/**
- * @com.intel.drl.spec_ref
+ * Returns a string containing a concise, human-readable description of this
+ * {@code Timestamp}.
+ *
+ * @return a printable representation for this {@code Timestamp}.
*/
public String toString() {
StringBuffer buf = new StringBuffer(256);
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnrecoverableEntryException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnrecoverableEntryException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnrecoverableEntryException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnrecoverableEntryException.java Tue Apr 28 17:01:41 2009
@@ -15,32 +15,31 @@
* limitations under the License.
*/
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
package java.security;
/**
- * @com.intel.drl.spec_ref
+ * {@code UnrecoverableEntryException} indicates, that a {@code KeyStore.Entry}
+ * cannot be recovered from a {@code KeyStore}.
*
+ * @see KeyStore
+ * @see KeyStore.Entry
*/
-
public class UnrecoverableEntryException extends GeneralSecurityException {
- /**
- * @com.intel.drl.spec_ref
- */
+
private static final long serialVersionUID = -4527142945246286535L;
/**
- * @com.intel.drl.spec_ref
+ * Constructs a new instance of {@code UnrecoverableEntryException}.
*/
public UnrecoverableEntryException() {
}
/**
- * @com.intel.drl.spec_ref
+ * Constructs a new instance of {@code UnrecoverableEntryException} with the
+ * given message.
+ *
+ * @param msg
+ * the detail message for this exception.
*/
public UnrecoverableEntryException(String msg) {
super(msg);
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnrecoverableKeyException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnrecoverableKeyException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnrecoverableKeyException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnrecoverableKeyException.java Tue Apr 28 17:01:41 2009
@@ -15,40 +15,32 @@
* limitations under the License.
*/
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
package java.security;
/**
- * This class represents exceptions if a key cannot be found in the keystore.
+ * {@code UnrecoverableKeyException} indicates, that a key cannot be recovered
+ * from a {@code KeyStore}.
*
+ * @see KeyStore
*/
public class UnrecoverableKeyException extends GeneralSecurityException {
- /**
- * @com.intel.drl.spec_ref
- */
private static final long serialVersionUID = 7275063078190151277L;
- /**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
- *
- *
- * @param msg
- * String The detail message for the exception.
- */
+ /**
+ * Constructs a new instance of {@code UnrecoverableKeyException} with the
+ * given message.
+ *
+ * @param msg
+ * the detail message for this exception
+ */
public UnrecoverableKeyException(String msg) {
super(msg);
}
- /**
- * Constructs a new instance of this class with its walkback filled in.
- *
- */
+ /**
+ * Constructs a new instance of {@code UnrecoverableKeyException}.
+ */
public UnrecoverableKeyException() {
}
}
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnresolvedPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnresolvedPermission.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnresolvedPermission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnresolvedPermission.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
* limitations under the License.
*/
-/**
-* @author Alexey V. Varlamov
-* @version $Revision$
-*/
-
package java.security;
import java.io.ByteArrayInputStream;
@@ -37,20 +32,15 @@
import org.apache.harmony.security.internal.nls.Messages;
/**
- * Holds permissions which are of an unknown type when a policy file is read.
- *
- * Technically, the resolution of UnresolvedPermissions and
- * substitution by actual permissions takes place in the
- * <code>implies()</code> method of a <code>Permissions</code>
- * collection, right before actual checking.
- *
+ * An {@code UnresolvedPermission} represents a {@code Permission} whose type
+ * should be resolved lazy and not during initialization time of the {@code
+ * Policy}. {@code UnresolvedPermission}s contain all information to be replaced
+ * by a concrete typed {@code Permission} right before the access checks are
+ * performed.
*/
public final class UnresolvedPermission extends Permission
implements Serializable {
- /**
- * @com.intel.drl.spec_ref
- */
private static final long serialVersionUID = -4821973115467008846L;
private String type;
@@ -65,17 +55,26 @@
// Cached hash value
private transient int hash;
- /**
- * Constructs a new instance of this class with its type, name, and
- * certificates set to the arguments by definition, actions are ignored
- *
- * @param type
- * class of permission object
- * @param name
- * identifies the permission that could not be resolved
- * @param actions
- * @param certs
- */
+ /**
+ * Constructs a new instance of {@code UnresolvedPermission}. The supplied
+ * parameters are used when this instance is resolved to the concrete
+ * {@code Permission}.
+ *
+ * @param type
+ * the fully qualified class name of the permission this class is
+ * resolved to.
+ * @param name
+ * the name of the permission this class is resolved to, maybe
+ * {@code null}.
+ * @param actions
+ * the actions of the permission this class is resolved to, maybe
+ * {@code null}.
+ * @param certs
+ * the certificates of the permission this class is resolved to,
+ * maybe {@code null}.
+ * @throws NullPointerException
+ * if type is {@code null}.
+ */
public UnresolvedPermission(String type, String name, String actions,
Certificate[] certs) {
super(type);
@@ -105,19 +104,20 @@
// }
}
- /**
- * Compares the argument to the receiver, and answers true if they represent
- * the <em>same</em> object using a class specific comparison. In this
- * case, the receiver and the object must have the same class, permission
- * name, actions, and certificates
- *
- * @param obj
- * the object to compare with this object
- * @return <code>true</code> if the object is the same as this object,
- * <code>false</code> otherwise.
- *
- * @see #hashCode
- */
+ /**
+ * Compares the specified object with this {@code UnresolvedPermission} for
+ * equality and returns {@code true} if the specified object is equal,
+ * {@code false} otherwise. To be equal, the specified object needs to be an
+ * instance of {@code UnresolvedPermission}, the two {@code
+ * UnresolvedPermission}s must refer to the same type and must have the same
+ * name, the same actions and certificates.
+ *
+ * @param obj
+ * object to be compared for equality with this {@code
+ * UnresolvedPermission}.
+ * @return {@code true} if the specified object is equal to this {@code
+ * UnresolvedPermission}, otherwise {@code false}.
+ */
public boolean equals(Object obj) {
if (obj == this) {
return true;
@@ -191,14 +191,15 @@
}
/**
- * Answers an integer hash code for the receiver. Any two objects which
- * answer <code>true</code> when passed to <code>equals</code> must
- * answer the same value for this method.
- *
- * @return the receiver's hash
- *
- * @see #equals
- */
+ * Returns the hash code value for this {@code UnresolvedPermission}.
+ * Returns the same hash code for {@code UnresolvedPermission}s that are
+ * equal to each other as required by the general contract of
+ * {@link Object#hashCode}.
+ *
+ * @return the hash code value for this {@code UnresolvedPermission}.
+ * @see Object#equals(Object)
+ * @see UnresolvedPermission#equals(Object)
+ */
public int hashCode() {
if (hash == 0) {
hash = getName().hashCode();
@@ -212,39 +213,56 @@
return hash;
}
- /**
- * Answers the actions associated with the receiver. Since
- * UnresolvedPermission objects have no actions, answer the empty string.
- *
- * @return the actions associated with the receiver.
- */
+ /**
+ * Returns an empty string since there are no actions allowed for {@code
+ * UnresolvedPermission}. The actions, specified in the constructor, are
+ * used when the concrete permission is resolved and created.
+ *
+ * @return an empty string, indicating that there are no actions.
+ */
public String getActions() {
return ""; //$NON-NLS-1$
}
- /**
- * @com.intel.drl.spec_ref
+ /**
+ * Returns the name of the permission this {@code UnresolvedPermission} is
+ * resolved to.
+ *
+ * @return the name of the permission this {@code UnresolvedPermission} is
+ * resolved to.
*/
public String getUnresolvedName() {
return name;
}
- /**
- * @com.intel.drl.spec_ref
+ /**
+ * Returns the actions of the permission this {@code UnresolvedPermission}
+ * is resolved to.
+ *
+ * @return the actions of the permission this {@code UnresolvedPermission}
+ * is resolved to.
*/
public String getUnresolvedActions() {
return actions;
}
- /**
- * @com.intel.drl.spec_ref
+ /**
+ * Returns the fully qualified class name of the permission this {@code
+ * UnresolvedPermission} is resolved to.
+ *
+ * @return the fully qualified class name of the permission this {@code
+ * UnresolvedPermission} is resolved to.
*/
public String getUnresolvedType() {
return super.getName();
}
- /**
- * @com.intel.drl.spec_ref
+ /**
+ * Returns the certificates of the permission this {@code
+ * UnresolvedPermission} is resolved to.
+ *
+ * @return the certificates of the permission this {@code
+ * UnresolvedPermission} is resolved to.
*/
public Certificate[] getUnresolvedCerts() {
if (targetCerts != null) {
@@ -255,61 +273,62 @@
return null;
}
- /**
- * Indicates whether the argument permission is implied by the
- * receiver. UnresolvedPermission objects imply nothing
- * because nothing is known about them yet.
- *
- * Before actual implication checking, this method tries to
- * resolve UnresolvedPermissions (if any) against the passed
- * instance. Successfully resolved permissions (if any) are
- * taken into account during further processing.
- *
- * @param permission
- * the permission to check
- * @return always replies false
- */
+ /**
+ * Indicates whether the specified permission is implied by this {@code
+ * UnresolvedPermission}. {@code UnresolvedPermission} objects imply nothing
+ * since nothing is known about them yet.
+ * <p>
+ * Before actual implication checking, this method tries to resolve
+ * UnresolvedPermissions (if any) against the passed instance. Successfully
+ * resolved permissions (if any) are taken into account during further
+ * processing.
+ *
+ * @param permission
+ * the permission to check.
+ * @return always {@code false}
+ */
public boolean implies(Permission permission) {
return false;
}
- /**
- * Answers a string containing a concise, human-readable description of the
- * receiver.
- *
- * @return a printable representation for the receiver.
- */
+ /**
+ * Returns a string containing a concise, human-readable description of this
+ * {@code UnresolvedPermission} including its target name and its target
+ * actions.
+ *
+ * @return a printable representation for this {@code UnresolvedPermission}.
+ */
public String toString() {
return "(unresolved " + type + " " + name + " " //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$
+ actions + ")"; //$NON-NLS-1$
}
- /**
- * Answers a new PermissionCollection for holding permissions of this class.
- * Answer null if any permission collection can be used.
- *
- * @return a new PermissionCollection or null
- *
- * @see java.security.BasicPermissionCollection
- */
+ /**
+ * Returns a new {@code PermissionCollection} for holding {@code
+ * UnresolvedPermission} objects.
+ *
+ * @return a new PermissionCollection for holding {@code
+ * UnresolvedPermission} objects.
+ */
public PermissionCollection newPermissionCollection() {
return new UnresolvedPermissionCollection();
}
/**
- * Tries to resolve this permission into the specified class. It is assumed
- * that the class has a proper name (as returned by <code>getName()</code>
- * of this unresolved permission), so no check is performed to verify this.
- * However, the class must have all required certificates (as per
- * <code>getUnresolvedCerts()</code>) among the passed collection of
- * signers. If it does, a zero, one, and/or two-argument constructor is
- * tried to instantiate a new permission, which is then returned. <br>
- * If an appropriate constructor is not available or the class is
- * improperly signed, <code>null</code> is returned.
- *
- * @param targetType - a target class instance, must not be
- * <code>null</code>
- * @param signers - actual signers of the targetType
+ * Tries to resolve this permission into the specified class.
+ * <p>
+ * It is assumed that the class has a proper name (as returned by {@code
+ * getName()} of this unresolved permission), so no check is performed to
+ * verify this. However, the class must have all required certificates (as
+ * per {@code getUnresolvedCerts()}) among the passed collection of signers.
+ * If it does, a zero, one, and/or two-argument constructor is tried to
+ * instantiate a new permission, which is then returned.
+ * <p>
+ * If an appropriate constructor is not available or the class is improperly
+ * signed, {@code null} is returned.
+ *
+ * @param targetType
+ * - a target class instance, must not be {@code null}
* @return resolved permission or null
*/
Permission resolve(Class targetType) {
@@ -329,7 +348,7 @@
/**
* @com.intel.drl.spec_ref
*
- * Outputs <code>type</code>,<code>name</code>,<code>actions</code>
+ * Outputs {@code type},{@code name},{@code actions}
* fields via default mechanism; next manually writes certificates in the
* following format: <br>
*
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnresolvedPermissionCollection.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnresolvedPermissionCollection.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnresolvedPermissionCollection.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/UnresolvedPermissionCollection.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
* limitations under the License.
*/
-/**
-* @author Alexey V. Varlamov
-* @version $Revision$
-*/
-
package java.security;
import java.io.IOException;
@@ -41,15 +36,12 @@
import org.apache.harmony.security.internal.nls.Messages;
/**
- * Specific PermissionCollection for storing UnresolvedPermissions. Contained
- * elements are grouped by their target type.
- *
+ * {@code UnresolvedPermissionCollection} represents a specific {@code
+ * PermissionCollection} for storing {@link UnresolvedPermission} instances.
+ * Contained elements are grouped by their target type.
*/
final class UnresolvedPermissionCollection extends PermissionCollection {
- /**
- * @com.intel.drl.spec_ref
- */
private static final long serialVersionUID = -7176153071733132400L;
private static final ObjectStreamField[] serialPersistentFields = {
@@ -59,9 +51,16 @@
private transient Map klasses = new HashMap();
/**
- * Adds an unresolved permission to the collection.
+ * Adds an unresolved permission to this {@code
+ * UnresolvedPermissionCollection}.
*
- * @see java.security.PermissionCollection#add(java.security.Permission)
+ * @param permission
+ * the permission to be added.
+ * @throws SecurityException
+ * if this collection is read only.
+ * @throws IllegalArgumentException
+ * if {@code permission} is {@code null} or not an {@code
+ * UnresolvedPermission}.
*/
public void add(Permission permission) {
if (isReadOnly()) {
@@ -83,11 +82,6 @@
}
}
- /**
- * Returns enumeration over collection elements.
- *
- * @see java.security.PermissionCollection#elements()
- */
public Enumeration elements() {
Collection all = new ArrayList();
for (Iterator iter = klasses.values().iterator(); iter.hasNext();) {
@@ -97,9 +91,10 @@
}
/**
- * Always returns false.
+ * Always returns {@code false}.
*
- * @see java.security.UnresolvedPermission#implies(Permission)
+ * @return always {@code false}
+ * @see UnresolvedPermission#implies(Permission).
*/
public boolean implies(Permission permission) {
return false;
@@ -116,13 +111,15 @@
/**
* Resolves all permissions of the same class as the specified target
* permission and adds them to the specified collection. If passed
- * collection is <code>null</code> and some unresolved permissions were
- * resolved, an appropriate new collection is instantiated and used. All
- * resolved permissions are removed from this unresolved collection, and
- * collection with resolved ones is returned.
- *
- * @param target - a kind of permissions to be resolved
- * @param holder - an existing collection for storing resolved permissions
+ * collection is {@code null} and some unresolved permissions were resolved,
+ * an appropriate new collection is instantiated and used. All resolved
+ * permissions are removed from this unresolved collection, and collection
+ * with resolved ones is returned.
+ *
+ * @param target
+ * a kind of permissions to be resolved.
+ * @param holder
+ * an existing collection for storing resolved permissions.
* @return a collection containing resolved permissions (if any found)
*/
PermissionCollection resolveCollection(Permission target,
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Acl.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Acl.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Acl.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/acl/Acl.java Tue Apr 28 17:01:41 2009
@@ -15,61 +15,153 @@
* limitations under the License.
*/
-/**
-* @author Aleksei Y. Semenov
-* @version $Revision$
-*/
-
package java.security.acl;
import java.security.Principal;
import java.util.Enumeration;
/**
- * @com.intel.drl.spec_ref
- *
- *
+ * The <i>Access Control List</i> (<b>ACL</b>) interface definition.
+ * <p>
+ * An ACL is a set of {@link AclEntry} objects.
+ * <p>
+ * An {@code AclEntry} is a list of {@link Permission}s that are granted
+ * (<i>positive</i>) or denied
+ * (<i>negative</i>) to a {@link Principal}.
+ * <p>
+ * An {@code Acl} has a list of owners ({@link Owner}) which are principals as
+ * well {@code Principal}. Only those principals which are the {@code Acl}'s
+ * owners are allowed to modify the {@code
+ * Acl}.
+ * <p>
+ * The <i>ACL</i> has to conform to the following rules:
+ * <ul>
+ * <li>For each {@code Principal} there can be only one <i>positive</i> and one
+ * <i>negative</i> {@code AclEntry}.</li>
+ * <li>If the two {@code AclEntry}'s (<i>positive</i> and <i>negative</i>) for a
+ * specific {@code Principal} grant and deny the same {@code Permission} to that
+ * {@code Principal}, then that {@code Permission} is treated as
+ * neither granted nor denied to that {@code Principal}.</li>
+ * <li>Permissions associated with an individual {@code Principal} always
+ * override permissions of the group(s) to which the individual belongs.</li>
+ * <li>If there is no {@code AclEntry} associated with a specific {@code
+ * Principal}, then it is interpreted as an empty list of permissions.</li>
+ * </ul>
*/
public interface Acl extends Owner {
/**
- * @com.intel.drl.spec_ref
+ * Sets the name of this <i>ACL</i> instance.
+ *
+ * @param caller
+ * the invoking {@code Principal}.
+ * @param name
+ * the name to be set.
+ * @throws NotOwnerException
+ * if the invoking {@code Principal} is not an owner of this
+ * <i>ACL</i>.
*/
void setName(Principal caller, String name) throws NotOwnerException;
/**
- * @com.intel.drl.spec_ref
+ * Returns the name of this <i>ACL</i> instance.
+ *
+ * @return the name of this <i>ACL</i> instance.
*/
String getName();
/**
- * @com.intel.drl.spec_ref
+ * Adds an {@code AclEntry} to this <i>ACL</i> instance.
+ * <p>
+ * If the <i>ACL</i> already has an {@code AclEntry} of the same type (<i>
+ * positive</i> or <i>negative</i>) and principal, then the new entry is not added.
+ *
+ * @param caller
+ * the invoking {@code Principal}.
+ * @param entry
+ * the ACL entry to add.
+ * @return {@code true} if the entry is added, {@code false} if there is
+ * already an entry of the same type for the same principal
+ * @throws NotOwnerException
+ * if the invoking {@code Principal} is not an owner of this
+ * <i>ACL</i>.
*/
boolean addEntry(Principal caller, AclEntry entry) throws NotOwnerException;
/**
- * @com.intel.drl.spec_ref
+ * Removes an {@code AclEntry} from this <i>ACL</i> instance.
+ *
+ * @param caller
+ * the invoking {@code Principal}.
+ * @param entry
+ * the ACL entry to remove.
+ * @return {@code true} if the entry is removed, {@code false} if the entry
+ * is not in this <i>ACL</i>.
+ * @throws NotOwnerException
+ * if the invoking {@code Principal} is not an owner of this
+ * <i>ACL</i>.
*/
boolean removeEntry(Principal caller, AclEntry entry)
throws NotOwnerException;
/**
- * @com.intel.drl.spec_ref
+ * Returns the set of allowed permissions for the specified {@code
+ * Principal}.
+ * <p>
+ * If the specified principal has no entry in this ACL, an empty set is
+ * returned.
+ * <p>
+ * The allowed permissions are collected according to the following rules:
+ * <ul>
+ * <li>The two permission lists (<i>positive</i> and <i>negative</i>) of the
+ * principal's groups ({@link Group}) are collected. The positive (granted)
+ * permissions are the union of all group's positive permissions that the
+ * principal belongs to, the negative (denied) permissions are the union of
+ * all group's negative permissions that the principal belongs to. If a
+ * specific permission is in both the positive and the negative list, it is
+ * removed from both lists.</li>
+ * <li>The individual permissions (<i>positive</i> and <i>negative</i>) of
+ * the principal override the group permissions. The positive individual
+ * permissions override the group's negative permissions and the negative
+ * individual permissions override the grpup's positive permissions.</li>
+ * </ul>
+ *
+ * @param user
+ * the principal to get the allowed permissions for.
+ * @return the set of allowed permissions for the specified principal.
*/
Enumeration<Permission> getPermissions(Principal user);
/**
- * @com.intel.drl.spec_ref
+ * Returns an {@code Enumeration} of the {@code AclEntry} of this
+ * <i>ACL</i>.
+ *
+ * @return an {@code Enumeration} of the {@code AclEntry} of this
+ * <i>ACL</i>.
*/
Enumeration<AclEntry> entries();
/**
- * @com.intel.drl.spec_ref
+ * Checks whether the specified principal is granted the specified
+ * permission.
+ * <p>
+ * The list of granted permissions is determined according to the rules
+ * specified by {@code getPermissions}.
+ *
+ * @param principal
+ * the principal the check the permissions for.
+ * @param permission
+ * the permission to check for the principal.
+ * @return {@code true} if the principal is granted the permission,
+ * otherwise {@code false}.
+ * @see #getPermissions(Principal)
*/
boolean checkPermission(Principal principal, Permission permission);
/**
- * @com.intel.drl.spec_ref
+ * Returns the string representation of this ACL.
+ *
+ * @return the string representation of this ACL.
*/
String toString();
}