Return-Path: Delivered-To: apmail-harmony-commits-archive@www.apache.org Received: (qmail 12823 invoked from network); 26 Apr 2009 12:31:11 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 26 Apr 2009 12:31:11 -0000 Received: (qmail 44942 invoked by uid 500); 26 Apr 2009 12:31:11 -0000 Delivered-To: apmail-harmony-commits-archive@harmony.apache.org Received: (qmail 44902 invoked by uid 500); 26 Apr 2009 12:31:11 -0000 Mailing-List: contact commits-help@harmony.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@harmony.apache.org Delivered-To: mailing list commits@harmony.apache.org Received: (qmail 44887 invoked by uid 99); 26 Apr 2009 12:31:11 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 26 Apr 2009 12:31:11 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 26 Apr 2009 12:30:58 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id CB4A92388C95; Sun, 26 Apr 2009 12:30:13 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r768698 [6/18] - in /harmony/enhanced/classlib/branches/java6: ./ modules/annotation/src/main/java/java/lang/annotation/ modules/archive/src/main/java/java/util/jar/ modules/archive/src/main/java/java/util/zip/ modules/auth/src/main/java/co... Date: Sun, 26 Apr 2009 12:30:06 -0000 To: commits@harmony.apache.org From: qiuxx@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20090426123013.CB4A92388C95@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DESKeySpec.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DESKeySpec.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DESKeySpec.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DESKeySpec.java Sun Apr 26 12:30:01 2009 @@ -23,12 +23,12 @@ import org.apache.harmony.crypto.internal.nls.Messages; /** - * @com.intel.drl.spec_ref + * The key specification for a DES key. */ public class DESKeySpec implements KeySpec { /** - * @com.intel.drl.spec_ref + * The length of a DES key in bytes. */ public static final int DES_KEY_LEN = 8; @@ -92,14 +92,29 @@ }; /** - * @com.intel.drl.spec_ref + * Creates a new DESKeySpec from the first 8 bytes of the + * specified key data. + * + * @param key + * the key data. + * @throws InvalidKeyException + * if the length of the specified key data is less than 8. */ public DESKeySpec(byte[] key) throws InvalidKeyException { this(key, 0); } /** - * @com.intel.drl.spec_ref + * Creates a new DESKeySpec from the first 8 bytes of the + * specified key data starting at offset. + * + * @param key + * the key data + * @param offset + * the offset to start at. + * @throws InvalidKeyException + * if the length of the specified key data starting at offset is + * less than 8. */ public DESKeySpec(byte[] key, int offset) throws InvalidKeyException { @@ -115,7 +130,9 @@ } /** - * @com.intel.drl.spec_ref + * Returns a copy of the key. + * + * @return a copy of the key. */ public byte[] getKey() { byte[] result = new byte[DES_KEY_LEN]; @@ -124,7 +141,18 @@ } /** - * @com.intel.drl.spec_ref + * Returns whether the specified key data starting at offset is + * parity-adjusted. + * + * @param key + * the key data. + * @param offset + * the offset to start checking at. + * @return {@code true} if the specified key data is parity-adjusted, + * {@code false} otherwise. + * @throws InvalidKeyException + * if the length of the key data starting at offset is less than + * 8, or the key is null. */ public static boolean isParityAdjusted(byte[] key, int offset) throws InvalidKeyException { @@ -153,7 +181,17 @@ } /** - * @com.intel.drl.spec_ref + * Returns whether the specified key data starting at offset is + * weak or semi-weak. + * + * @param key + * the key data. + * @param offset + * the offset to start checking at. + * @return {@code true} if the specified key data is weak or semi-weak. + * @throws InvalidKeyException + * if the length of the key data starting at offset is less than + * 8, or it is null. */ public static boolean isWeak(byte[] key, int offset) throws InvalidKeyException { Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DESedeKeySpec.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DESedeKeySpec.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DESedeKeySpec.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DESedeKeySpec.java Sun Apr 26 12:30:01 2009 @@ -27,19 +27,27 @@ import org.apache.harmony.crypto.internal.nls.Messages; /** - * @com.intel.drl.spec_ref + * The key specification for a triple-DES (DES-EDE) key. */ public class DESedeKeySpec implements KeySpec { /** - * @com.intel.drl.spec_ref + * The length of a DES-EDE key in bytes. */ public static final int DES_EDE_KEY_LEN = 24; private final byte[] key; /** - * @com.intel.drl.spec_ref + * Creates a new DESedeKeySpec instance from the first 24 ( + * {@link #DES_EDE_KEY_LEN}) bytes of the specified key data. + * + * @param key + * the key data. + * @throws InvalidKeyException + * if the length of the key data is less than 24. + * @throws NullPointerException + * if the key data is null. */ public DESedeKeySpec(byte[] key) throws InvalidKeyException { @@ -55,7 +63,19 @@ } /** - * @com.intel.drl.spec_ref + * Creates a new DESedeKeySpec instance from the first 24 ( + * {@link #DES_EDE_KEY_LEN} ) bytes of the specified key data starting at + * offset. + * + * @param key + * the key data + * @param offset + * the offset to start at. + * @throws InvalidKeyException + * if the length of the key data starting at offset is less than + * 24. + * @throws NullPointerException + * if the key data is null. */ public DESedeKeySpec(byte[] key, int offset) throws InvalidKeyException { @@ -71,7 +91,9 @@ } /** - * @com.intel.drl.spec_ref + * Returns a copy of the key. + * + * @return a copy of the key. */ public byte[] getKey() { byte[] result = new byte [DES_EDE_KEY_LEN]; @@ -80,7 +102,18 @@ } /** - * @com.intel.drl.spec_ref + * Returns whether the specified key data starting at offset is + * parity-adjusted. + * + * @param key + * the key data. + * @param offset + * the offset to start checking at. + * @return {@code true} if the specified key data is parity-adjusted, + * {@code false} otherwise. + * @throws InvalidKeyException + * if the length of the key data starting at offset is less than + * 24. */ public static boolean isParityAdjusted(byte[] key, int offset) throws InvalidKeyException { Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DHGenParameterSpec.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DHGenParameterSpec.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DHGenParameterSpec.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DHGenParameterSpec.java Sun Apr 26 12:30:01 2009 @@ -25,7 +25,8 @@ import java.security.spec.AlgorithmParameterSpec; /** - * @com.intel.drl.spec_ref + * The algorithm parameter specification for generating Diffie-Hellman + * parameters used in Diffie-Hellman key agreement. */ public class DHGenParameterSpec implements AlgorithmParameterSpec { @@ -33,7 +34,13 @@ private final int exponentSize; /** - * @com.intel.drl.spec_ref + * Creates a new DHGenParameterSpec instance with the specified + * parameters. + * + * @param primeSize + * the size of the prime modulus in bits. + * @param exponentSize + * the size of the random exponent in bits. */ public DHGenParameterSpec(int primeSize, int exponentSize) { this.primeSize = primeSize; @@ -41,14 +48,18 @@ } /** - * @com.intel.drl.spec_ref + * Returns the size of the prime modulus in bits. + * + * @return the size of the prime modulus in bits. */ public int getPrimeSize() { return primeSize; } /** - * @com.intel.drl.spec_ref + * Returns the size of the random exponent in bits. + * + * @return the size of the random exponent in bits. */ public int getExponentSize() { return exponentSize; Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DHParameterSpec.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DHParameterSpec.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DHParameterSpec.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DHParameterSpec.java Sun Apr 26 12:30:01 2009 @@ -26,7 +26,7 @@ import java.security.spec.AlgorithmParameterSpec; /** - * @com.intel.drl.spec_ref + * The algorithm parameter specification for the Diffie-Hellman algorithm. */ public class DHParameterSpec implements AlgorithmParameterSpec { @@ -35,7 +35,13 @@ private final int l; /** - * @com.intel.drl.spec_ref + * Creates a new DHParameterSpec instance with the specified + * prime modulus and base generator. + * + * @param p + * the prime modulus. + * @param g + * the base generator. */ public DHParameterSpec(BigInteger p, BigInteger g) { this.p = p; @@ -44,7 +50,16 @@ } /** - * @com.intel.drl.spec_ref + * Creates a new DHParameterSpec instance with the specified + * prime modulus, base generator and size (in bits) of the + * random exponent. + * + * @param p + * the prime modulus. + * @param g + * the base generator. + * @param l + * the size of the random exponent (in bits). */ public DHParameterSpec(BigInteger p, BigInteger g, int l) { this.p = p; @@ -53,21 +68,27 @@ } /** - * @com.intel.drl.spec_ref + * Returns the prime modulus of this parameter specification. + * + * @return the prime modulus. */ public BigInteger getP() { return p; } /** - * @com.intel.drl.spec_ref + * Returns the base generator of this parameter specification. + * + * @return the base generator. */ public BigInteger getG() { return g; } /** - * @com.intel.drl.spec_ref + * Returns the size (in bits) of the random exponent. + * + * @return the size (in bits) of the random exponent. */ public int getL() { return l; Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DHPrivateKeySpec.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DHPrivateKeySpec.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DHPrivateKeySpec.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DHPrivateKeySpec.java Sun Apr 26 12:30:01 2009 @@ -26,7 +26,7 @@ import java.security.spec.KeySpec; /** - * @com.intel.drl.spec_ref + * The key specification for a Diffie-Hellman private key. */ public class DHPrivateKeySpec implements KeySpec { @@ -35,7 +35,16 @@ private final BigInteger g; /** - * @com.intel.drl.spec_ref + * Creates a new DHPrivateKeySpec with the specified private + * value x. prime modulus p and base + * generator g. + * + * @param x + * the private value. + * @param p + * the prime modulus. + * @param g + * the base generator. */ public DHPrivateKeySpec(BigInteger x, BigInteger p, BigInteger g) { this.x = x; @@ -44,21 +53,27 @@ } /** - * @com.intel.drl.spec_ref + * Returns the private value x. + * + * @return the private value x. */ public BigInteger getX() { return x; } /** - * @com.intel.drl.spec_ref + * Returns the prime modulus p. + * + * @return the prime modulus p. */ public BigInteger getP() { return p; } /** - * @com.intel.drl.spec_ref + * Returns the base generator g. + * + * @return the base generator g. */ public BigInteger getG() { return g; Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DHPublicKeySpec.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DHPublicKeySpec.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DHPublicKeySpec.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/DHPublicKeySpec.java Sun Apr 26 12:30:01 2009 @@ -26,7 +26,7 @@ import java.security.spec.KeySpec; /** - * @com.intel.drl.spec_ref + * The key specification for a Diffie-Hellman public key. */ public class DHPublicKeySpec implements KeySpec { @@ -35,7 +35,16 @@ private final BigInteger g; /** - * @com.intel.drl.spec_ref + * Creates a new DHPublicKeySpec instance with the specified + * public value y, the prime modulus + * p and the base generator g. + * + * @param y + * the public value. + * @param p + * the prime modulus. + * @param g + * the base generator. */ public DHPublicKeySpec(BigInteger y, BigInteger p, BigInteger g) { this.y = y; @@ -44,21 +53,27 @@ } /** - * @com.intel.drl.spec_ref + * Returns the public value y. + * + * @return the public value y. */ public BigInteger getY() { return y; } /** - * @com.intel.drl.spec_ref + * Returns the prime modulus p. + * + * @return the prime modulus p. */ public BigInteger getP() { return p; } /** - * @com.intel.drl.spec_ref + * Returns the base generator g; + * + * @return the base generator g; */ public BigInteger getG() { return g; Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/IvParameterSpec.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/IvParameterSpec.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/IvParameterSpec.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/IvParameterSpec.java Sun Apr 26 12:30:01 2009 @@ -26,14 +26,20 @@ import org.apache.harmony.crypto.internal.nls.Messages; /** - * @com.intel.drl.spec_ref + * The algorithm parameter specification for an initialization vector. */ public class IvParameterSpec implements AlgorithmParameterSpec { private final byte[] iv; /** - * @com.intel.drl.spec_ref + * Creates a new IvParameterSpec instance with the bytes from + * the specified buffer iv used as initialization vector. + * + * @param iv + * the buffer used as initialization vector. + * @throws NullPointerException + * if the specified buffer is null. */ public IvParameterSpec(byte[] iv) { if (iv == null) { @@ -44,7 +50,22 @@ } /** - * @com.intel.drl.spec_ref + * Creates a new IvParameterSpec instance with len + * bytes from the specified buffer iv starting at + * offset. + * + * @param iv + * the buffer used as initialization vector. + * @param offset + * the offset to start in the buffer. + * @param len + * the length of the data. + * @throws IllegalArgumentException + * if the specified buffer is null or offset and + * len do not specify a valid chunk in the + * specified buffer. + * @throws ArrayIndexOutOfBoundsException + * if offset or len are negative. */ public IvParameterSpec(byte[] iv, int offset, int len) { if ((iv == null) || (iv.length - offset < len)) { @@ -59,7 +80,9 @@ } /** - * @com.intel.drl.spec_ref + * Returns a copy of the initialization vector data. + * + * @return a copy of the initialization vector data. */ public byte[] getIV() { byte[] res = new byte[iv.length]; Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/OAEPParameterSpec.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/OAEPParameterSpec.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/OAEPParameterSpec.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/OAEPParameterSpec.java Sun Apr 26 12:30:01 2009 @@ -27,7 +27,10 @@ import javax.crypto.spec.PSource; /** - * @com.intel.drl.spec_ref + * The algorithm parameter specification for the OAEP Padding algorithm. + *

+ * This padding algorithm is defined in the PKCS #1 standard. */ public class OAEPParameterSpec implements AlgorithmParameterSpec { @@ -37,7 +40,14 @@ private final PSource pSrc; /** - * @com.intel.drl.spec_ref + * The algorithm parameter instance with default values. + *

+ * It uses the following parameters: + *

  • message digest : "SHA-1"
    • + *
  • mask generation function (mgf) : "MGF1"
    • + *
  • parameters for the mgf : "SHA-1" {@link MGF1ParameterSpec#SHA1}
    • + *
  • the source of the label L: {@link PSource.PSpecified#DEFAULT}
    • + *
*/ public static final OAEPParameterSpec DEFAULT = new OAEPParameterSpec(); @@ -49,7 +59,23 @@ } /** - * @com.intel.drl.spec_ref + * Creates a new OAEPParameterSpec instance with the specified + * message digest algorithm name, mask generation function + * (mgf) algorithm name, parameters for the mgf + * algorithm and the source of the label L. + * + * @param mdName + * the message digest algorithm name. + * @param mgfName + * the mask generation function algorithm name. + * @param mgfSpec + * the algorithm parameter specification for the mask generation + * function algorithm. + * @param pSrc + * the source of the label L. + * @throws NullPointerException + * if one of mdName, mgfName or + * pSrc is null. */ public OAEPParameterSpec(String mdName, String mgfName, AlgorithmParameterSpec mgfSpec, PSource pSrc) { @@ -63,28 +89,38 @@ } /** - * @com.intel.drl.spec_ref + * Returns the algorithm name of the message digest. + * + * @return the algorithm name of the message digest. */ public String getDigestAlgorithm() { return mdName; } /** - * @com.intel.drl.spec_ref + * Returns the algorithm name of the mask generation function. + * + * @return the algorithm name of the mask generation function. */ public String getMGFAlgorithm() { return mgfName; } /** - * @com.intel.drl.spec_ref + * Returns the algorithm parameter specification for the mask generation + * function algorithm. + * + * @return the algorithm parameter specification for the mask generation + * function algorithm. */ public AlgorithmParameterSpec getMGFParameters() { return mgfSpec; } /** - * @com.intel.drl.spec_ref + * Returns the source of the label L. + * + * @return the source of the label L. */ public PSource getPSource() { return pSrc; Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/PBEKeySpec.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/PBEKeySpec.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/PBEKeySpec.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/PBEKeySpec.java Sun Apr 26 12:30:01 2009 @@ -28,7 +28,10 @@ import org.apache.harmony.crypto.internal.nls.Messages; /** - * @com.intel.drl.spec_ref + * The key specification for a password based encryption key. + *

+ * Password based encryption is described in PKCS #5. */ public class PBEKeySpec implements KeySpec { @@ -38,7 +41,10 @@ private final int keyLength; /** - * @com.intel.drl.spec_ref + * Creates a new PBEKeySpec with the specified password. + * + * @param password + * the password. */ public PBEKeySpec(char[] password) { if (password == null) { @@ -53,7 +59,22 @@ } /** - * @com.intel.drl.spec_ref + * Creates a new PBEKeySpec with the specified password, salt, + * iteration count and the desired length of the derived key. + * + * @param password + * the password. + * @param salt + * the salt. + * @param iterationCount + * the iteration count. + * @param keyLength + * the desired key length of the derived key, + * @throws NullPointerException + * if the salt is null. + * @throws IllegalArgumentException + * if the salt is empty, iteration count is zero or negative or + * the key length is zero or negative. */ public PBEKeySpec(char[] password, byte[] salt, int iterationCount, int keyLength) { @@ -84,7 +105,19 @@ } /** - * @com.intel.drl.spec_ref + * Creates a new PBEKeySpec with the specified password, salt + * and iteration count. + * + * @param password + * the password. + * @param salt + * the salt. + * @param iterationCount + * the iteration count. + * @throws NullPointerException + * if salt is null. + * @throws IllegalArgumentException + * if the salt is empty or iteration count is zero or negative. */ public PBEKeySpec(char[] password, byte[] salt, int iterationCount) { if (salt == null) { @@ -111,7 +144,7 @@ } /** - * @com.intel.drl.spec_ref + * Clears the password by overwriting it. */ public final void clearPassword() { Arrays.fill(password, '?'); @@ -119,7 +152,11 @@ } /** - * @com.intel.drl.spec_ref + * Returns a copy of the password of this key specification. + * + * @return a copy of the password of this key specification. + * @throws IllegalStateException + * if the password has been cleared before. */ public final char[] getPassword() { if (password == null) { @@ -131,7 +168,10 @@ } /** - * @com.intel.drl.spec_ref + * Returns a copy of the salt of this key specification. + * + * @return a copy of the salt of this key specification or null if none is + * specified. */ public final byte[] getSalt() { if (salt == null) { @@ -143,14 +183,18 @@ } /** - * @com.intel.drl.spec_ref + * Returns the iteration count of this key specification. + * + * @return the iteration count of this key specification. */ public final int getIterationCount() { return iterationCount; } /** - * @com.intel.drl.spec_ref + * Returns the desired key length of the derived key. + * + * @return the desired key length of the derived key. */ public final int getKeyLength() { return keyLength; Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/PBEParameterSpec.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/PBEParameterSpec.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/PBEParameterSpec.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/PBEParameterSpec.java Sun Apr 26 12:30:01 2009 @@ -27,7 +27,12 @@ import org.apache.harmony.crypto.internal.nls.Messages; /** - * @com.intel.drl.spec_ref + * The algorithm parameter specification for a password based encryption + * algorithm. + *

+ * Password based encryption is described in PKCS #5. + * */ public class PBEParameterSpec implements AlgorithmParameterSpec { @@ -35,7 +40,15 @@ private final int iterationCount; /** - * @com.intel.drl.spec_ref + * Creates a new PBEParameterSpec with the specified salt and + * iteration count. + * + * @param salt + * the salt. + * @param iterationCount + * the iteration count. + * @throws NullPointerException + * if salt is null. */ public PBEParameterSpec(byte[] salt, int iterationCount) { if (salt == null) { @@ -47,7 +60,9 @@ } /** - * @com.intel.drl.spec_ref + * Returns a copy to the salt. + * + * @return a copy to the salt. */ public byte[] getSalt() { byte[] result = new byte[salt.length]; @@ -56,7 +71,9 @@ } /** - * @com.intel.drl.spec_ref + * Returns the iteration count. + * + * @return the iteration count. */ public int getIterationCount() { return iterationCount; Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/PSource.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/PSource.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/PSource.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/PSource.java Sun Apr 26 12:30:01 2009 @@ -25,7 +25,8 @@ import org.apache.harmony.crypto.internal.nls.Messages; /** - * @com.intel.drl.spec_ref + * The source of the label L as specified in PKCS #1. */ public class PSource { @@ -34,7 +35,13 @@ private PSource() {} /** - * @com.intel.drl.spec_ref + * Creates a new PSource instance with the specified source + * algorithm identifier. + * + * @param pSrcName + * the source algorithm identifier. + * @throws NullPointerException + * if pSrcName is null. */ protected PSource(String pSrcName) { if (pSrcName == null) { @@ -44,21 +51,25 @@ } /** - * @com.intel.drl.spec_ref + * Returns the source algorithm identifier. + * + * @return the source algorithm identifier. */ public String getAlgorithm() { return pSrcName; } /** - * @com.intel.drl.spec_ref + * The explicit specification of the parameter P used in the + * source algorithm. */ public static final class PSpecified extends PSource { private final byte[] p; /** - * @com.intel.drl.spec_ref + * The instance of PSpecified with the default value + * byte[0] for P */ public static final PSpecified DEFAULT = new PSpecified(); @@ -68,7 +79,13 @@ } /** - * @com.intel.drl.spec_ref + * Creates a new instance of PSpecified with the specified + * parameter P. + * + * @param p + * the parameter P. + * @throws NullPointerException + * if p is null. */ public PSpecified(byte[] p) { super("PSpecified"); //$NON-NLS-1$ @@ -82,7 +99,9 @@ } /** - * @com.intel.drl.spec_ref + * Returns a copy of the value of the parameter P. + * + * @return a copy of the value of the parameter P */ public byte[] getValue() { byte[] result = new byte[p.length]; Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/RC2ParameterSpec.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/RC2ParameterSpec.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/RC2ParameterSpec.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/RC2ParameterSpec.java Sun Apr 26 12:30:01 2009 @@ -28,7 +28,8 @@ import org.apache.harmony.crypto.internal.nls.Messages; /** - * @com.intel.drl.spec_ref + * The algorithm parameter specification for the RC2 algorithm. */ public class RC2ParameterSpec implements AlgorithmParameterSpec { @@ -36,7 +37,11 @@ private final byte[] iv; /** - * @com.intel.drl.spec_ref + * Creates a new RC2ParameterSpec instance with the specified + * effective key length (in bits), + * + * @param effectiveKeyBits + * the effective key length (in bits). */ public RC2ParameterSpec(int effectiveKeyBits) { this.effectiveKeyBits = effectiveKeyBits; @@ -44,7 +49,18 @@ } /** - * @com.intel.drl.spec_ref + * Creates a new RC2ParameterSpec instance with the specified + * effective key length (in bits) and initialization vector. + *

+ * The size of the initialization vector must be at least 8 bytes + * which are copied to protect them against modification. + * + * @param effectiveKeyBits + * the effective key length (in bits). + * @param iv + * the initialization vector. + * @throws IllegalArgumentException + * if the initialization vector is null or shorter than 8 bytes. */ public RC2ParameterSpec(int effectiveKeyBits, byte[] iv) { if (iv == null) { @@ -59,7 +75,22 @@ } /** - * @com.intel.drl.spec_ref + * Creates a new RC2ParameterSpec instance with the specified + * effective key length (in bits) and initialization vector. + *

+ * The size of the initialization vector starting at + * offset must be at least 8 bytes which are copied to protect + * them against modification. + * + * @param effectiveKeyBits + * the effective key length (in bits). + * @param iv + * the initialization vector. + * @param offset + * the offset in the initialization vector to start at. + * @throws IllegalArgumentException + * if the initialization vector is null or starting at + * offset is shorter than 8 bytes. */ public RC2ParameterSpec(int effectiveKeyBits, byte[] iv, int offset) { if (iv == null) { @@ -74,14 +105,18 @@ } /** - * @com.intel.drl.spec_ref + * Returns the effective key length (in bits). + * + * @return the effective key length (in bits). */ public int getEffectiveKeyBits() { return effectiveKeyBits; } /** - * @com.intel.drl.spec_ref + * Returns a copy of the initialization vector. + * + * @return a copy of the initialization vector, or null if none specified. */ public byte[] getIV() { if (iv == null) { @@ -93,7 +128,13 @@ } /** - * @com.intel.drl.spec_ref + * Compares the specified object to this RC2ParameterSpec + * instance. + * + * @param obj + * the object to compare. + * @return true if the effective key length and the initialization vector of + * both objects are equal, otherwise false. */ @Override public boolean equals(Object obj) { @@ -109,7 +150,9 @@ } /** - * @com.intel.drl.spec_ref + * Returns the hash code of this RC2ParameterSpec instance. + * + * @return the hash code. */ @Override public int hashCode() { Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/RC5ParameterSpec.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/RC5ParameterSpec.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/RC5ParameterSpec.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/RC5ParameterSpec.java Sun Apr 26 12:30:01 2009 @@ -28,7 +28,8 @@ import org.apache.harmony.crypto.internal.nls.Messages; /** - * @com.intel.drl.spec_ref + * The algorithm parameter specification for the RC5 algorithm. */ public class RC5ParameterSpec implements AlgorithmParameterSpec { @@ -38,7 +39,15 @@ private final byte[] iv; /** - * @com.intel.drl.spec_ref + * Creates a new RC5ParameterSpec instance with the specified + * version, round count an word size (in bits). + * + * @param version + * the version. + * @param rounds + * the round count. + * @param wordSize + * the word size (in bits). */ public RC5ParameterSpec(int version, int rounds, int wordSize) { this.version = version; @@ -48,7 +57,25 @@ } /** - * @com.intel.drl.spec_ref + * Creates a new RC5ParameterSpec instance with the specified + * version, round count, word size (in bits) and an initialization + * vector. + *

+ * The size of the initialization vector must be at least + * 2 * (wordSize / 8) bytes which are copied to protect them + * against modification. + * + * @param version + * the version. + * @param rounds + * the round count. + * @param wordSize + * the word size (in bits). + * @param iv + * the initialization vector. + * @throws IllegalArgumentException + * if the initialization vector is null or shorter than 2 + * * (wordSize / 8). */ public RC5ParameterSpec(int version, int rounds, int wordSize, byte[] iv) { if (iv == null) { @@ -66,7 +93,29 @@ } /** - * @com.intel.drl.spec_ref + * Creates a new RC5ParameterSpec instance with the specified + * version, round count, wordSize (in bits), an initialization vector + * and an offset. + *

+ * The size of the initialization vector must be at least + * offset + (2 * (wordSize / 8)) bytes. The bytes starting at + * offset are copied to protect them against modification. + * + * @param version + * the version. + * @param rounds + * the round count. + * @param wordSize + * the word size (in bits). + * @param iv + * the initialization vector. + * @param offset + * the offset in the initialization vector. + * @throws IllegalArgumentException + * if the initialization vector is null of shorter than + * offset + (2 * (wordSize / 8)). + * @throws ArrayIndexOutOfBoundsException + * if offset is negative. */ public RC5ParameterSpec(int version, int rounds, int wordSize, byte[] iv, int offset) { @@ -88,28 +137,36 @@ } /** - * @com.intel.drl.spec_ref + * Returns the version. + * + * @return the version. */ public int getVersion() { return version; } /** - * @com.intel.drl.spec_ref + * Returns the round count. + * + * @return the round count. */ public int getRounds() { return rounds; } /** - * @com.intel.drl.spec_ref + * Returns the word size (in bits). + * + * @return the word size (in bits). */ public int getWordSize() { return wordSize; } /** - * @com.intel.drl.spec_ref + * Returns a copy of the initialization vector. + * + * @return a copy of the initialization vector, or null if none specified. */ public byte[] getIV() { if (iv == null) { @@ -121,7 +178,13 @@ } /** - * @com.intel.drl.spec_ref + * Compares the specified object with this RC5ParameterSpec + * instance. + * + * @param obj + * the object to compare. + * @return true if version, round count, word size and initializaion vector + * of both objects are equal, otherwise false. */ @Override public boolean equals(Object obj) { @@ -139,7 +202,9 @@ } /** - * @com.intel.drl.spec_ref + * Returns the hash code of this RC5ParameterSpec instance. + * + * @return the hash code. */ @Override public int hashCode() { Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/SecretKeySpec.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/SecretKeySpec.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/SecretKeySpec.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/spec/SecretKeySpec.java Sun Apr 26 12:30:01 2009 @@ -30,7 +30,9 @@ import org.apache.harmony.crypto.internal.nls.Messages; /** - * @com.intel.drl.spec_ref + * A key specification for a SecretKey and also a secret key + * implementation that is provider-independent. It can be used for raw secret + * keys that can be specified as byte[]. */ public class SecretKeySpec implements SecretKey, KeySpec, Serializable { @@ -44,15 +46,24 @@ private final String format = "RAW"; //$NON-NLS-1$ /** - * @com.intel.drl.spec_ref + * Creates a new SecretKeySpec for the specified key data and + * algorithm name. + * + * @param key + * the key data. + * @param algorithm + * the algorithm name. + * @throws IllegalArgumentException + * if the key data or the algorithm name is null or if the key + * data is empty. */ public SecretKeySpec(byte[] key, String algorithm) { - if (key == null) { - throw new IllegalArgumentException(Messages.getString("crypto.05")); //$NON-NLS-1$ - } - if (key.length == 0) { - throw new IllegalArgumentException(Messages.getString("crypto.35")); //$NON-NLS-1$ - } + if (key == null) { + throw new IllegalArgumentException(Messages.getString("crypto.05")); //$NON-NLS-1$ + } + if (key.length == 0) { + throw new IllegalArgumentException(Messages.getString("crypto.35")); //$NON-NLS-1$ + } if (algorithm == null) { throw new IllegalArgumentException(Messages.getString("crypto.02")); //$NON-NLS-1$ } @@ -63,21 +74,38 @@ } /** - * @com.intel.drl.spec_ref + * Creates a new SecretKeySpec for the key data from the + * specified buffer key starting at offset with + * length len and the specified algorithm name. + * + * @param key + * the key data. + * @param offset + * the offset. + * @param len + * the size of the key data. + * @param algorithm + * the algorithm name. + * @throws IllegalArgumentException + * if the key data or the algorithm name is null, the key data + * is empty or offset and len do not + * specify a valid chunk in the buffer key. + * @throws ArrayIndexOutOfBoundsException + * if offset or len is negative. */ public SecretKeySpec(byte[] key, int offset, int len, String algorithm) { - if (key == null) { - throw new IllegalArgumentException(Messages.getString("crypto.05")); //$NON-NLS-1$ - } - if (key.length == 0) { - throw new IllegalArgumentException(Messages.getString("crypto.35")); //$NON-NLS-1$ - } + if (key == null) { + throw new IllegalArgumentException(Messages.getString("crypto.05")); //$NON-NLS-1$ + } + if (key.length == 0) { + throw new IllegalArgumentException(Messages.getString("crypto.35")); //$NON-NLS-1$ + } if (len < 0) { throw new ArrayIndexOutOfBoundsException(Messages.getString("crypto.36")); //$NON-NLS-1$ } - if ((key.length - offset < len)) { - throw new IllegalArgumentException(Messages.getString("crypto.37")); //$NON-NLS-1$ - } + if ((key.length - offset < len)) { + throw new IllegalArgumentException(Messages.getString("crypto.37")); //$NON-NLS-1$ + } if (algorithm == null) { throw new IllegalArgumentException(Messages.getString("crypto.02")); //$NON-NLS-1$ } @@ -87,21 +115,27 @@ } /** - * @com.intel.drl.spec_ref + * Returns the algorithm name. + * + * @return the algorithm name. */ public String getAlgorithm() { return algorithm; } /** - * @com.intel.drl.spec_ref + * Returns the name of the format used to encode the key. + * + * @return the format name "RAW". */ public String getFormat() { return format; } /** - * @com.intel.drl.spec_ref + * Returns the encoded form of this secret key. + * + * @return the encoded form of this secret key. */ public byte[] getEncoded() { byte[] result = new byte[key.length]; @@ -110,7 +144,9 @@ } /** - * @com.intel.drl.spec_ref + * Returns the hash code of this SecretKeySpec object. + * + * @return the hash code. */ @Override public int hashCode() { @@ -122,7 +158,13 @@ } /** - * @com.intel.drl.spec_ref + * Compares the specified object with this SecretKeySpec + * instance. + * + * @param obj + * the object to compare. + * @return true if the algorithm name and key of both object are equal, + * otherwise false. */ @Override public boolean equals(Object obj) { Modified: harmony/enhanced/classlib/branches/java6/modules/lang-management/src/main/java/java/lang/management/MemoryNotificationInfo.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/lang-management/src/main/java/java/lang/management/MemoryNotificationInfo.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/lang-management/src/main/java/java/lang/management/MemoryNotificationInfo.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/lang-management/src/main/java/java/lang/management/MemoryNotificationInfo.java Sun Apr 26 12:30:01 2009 @@ -37,11 +37,14 @@ *

* * @param cd The CompositeDate object to retrieve data from. - * @return A MemoryNotificationInfo instance. + * @return A MemoryNotificationInfo instance or {@code null} if {@code cd} is {@code null} * @throws IllegalArgumentException if cd does not contain * MemoryUsage data. */ public static MemoryNotificationInfo from(CompositeData cd) { + if (cd == null) { + return null; + } String poolName = (String) cd.get("poolName"); MemoryUsage usage = MemoryUsage.from((CompositeData) cd.get("usage")); long count = ((Long) cd.get("count")).longValue(); @@ -62,9 +65,19 @@ * @param poolName The memory pool name. * @param usage The memory usage snapshot. * @param count The threshold crossing count. + * + * @throws NullPointerException if {@code poolName} or {@code usage} is {@code null} */ public MemoryNotificationInfo(String poolName, MemoryUsage usage, long count) { super(); + if (poolName == null) { + throw new NullPointerException("pooName is null"); //$NON-NLS-1$ + } + + if (usage == null) { + throw new NullPointerException("usage is null"); //$NON-NLS-1$ + } + this.poolName = poolName; this.usage = usage; this.count = count; Modified: harmony/enhanced/classlib/branches/java6/modules/lang-management/src/main/java/java/lang/management/MemoryUsage.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/lang-management/src/main/java/java/lang/management/MemoryUsage.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/lang-management/src/main/java/java/lang/management/MemoryUsage.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/lang-management/src/main/java/java/lang/management/MemoryUsage.java Sun Apr 26 12:30:01 2009 @@ -39,6 +39,9 @@ * MemoryUsage data. */ public static MemoryUsage from(CompositeData cd) { + if (cd == null) { + return null; + } try { long init = ((Long) cd.get("init")).longValue(); long used = ((Long) cd.get("used")).longValue(); Modified: harmony/enhanced/classlib/branches/java6/modules/lang-management/src/test/api/java/org/apache/harmony/lang/management/tests/java/lang/management/MemoryUsageTest.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/lang-management/src/test/api/java/org/apache/harmony/lang/management/tests/java/lang/management/MemoryUsageTest.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/lang-management/src/test/api/java/org/apache/harmony/lang/management/tests/java/lang/management/MemoryUsageTest.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/lang-management/src/test/api/java/org/apache/harmony/lang/management/tests/java/lang/management/MemoryUsageTest.java Sun Apr 26 12:30:01 2009 @@ -90,6 +90,10 @@ } } + public void test_from_NullCompositeData() { + assertNull(MemoryUsage.from(null)); + } + public void testConstructor() { try { new MemoryUsage(-2, 2048, 4096, 8128); Modified: harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/ConsoleHandler.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/ConsoleHandler.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/ConsoleHandler.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/ConsoleHandler.java Sun Apr 26 12:30:01 2009 @@ -19,42 +19,39 @@ /** * A handler that writes log messages to the standard output stream - * System.err. + * {@code System.err}. *

* This handler reads the following properties from the log manager to * initialize itself: *

    *
  • java.util.logging.ConsoleHandler.level specifies the logging level, - * defaults to Level.INFO if this property is not found or has an - * invalid value; + * defaults to {@code Level.INFO} if this property is not found or has an + * invalid value. *
  • java.util.logging.ConsoleHandler.filter specifies the name of the filter - * class to be associated with this handler, defaults to null if - * this property is not found or has an invalid value; + * class to be associated with this handler, defaults to {@code null} if this + * property is not found or has an invalid value. *
  • java.util.logging.ConsoleHandler.formatter specifies the name of the * formatter class to be associated with this handler, defaults to - * java.util.logging.SimpleFormatter if this property is not - * found or has an invalid value; + * {@code java.util.logging.SimpleFormatter} if this property is not found or + * has an invalid value. *
  • java.util.logging.ConsoleHandler.encoding specifies the encoding this - * handler will use to encode log messages, defaults to null if - * this property is not found or has an invalid value. + * handler will use to encode log messages, defaults to {@code null} if this + * property is not found or has an invalid value. *
- *

*

* This class is not thread-safe. - *

*/ public class ConsoleHandler extends StreamHandler { /** - * Constructs a ConsoleHandler object. + * Constructs a {@code ConsoleHandler} object. */ public ConsoleHandler() { super(System.err); } /** - * Closes this handler. The System.err is flushed but not - * closed. + * Closes this handler. The {@code System.err} is flushed but not closed. */ @Override public void close() { @@ -65,7 +62,7 @@ * Logs a record if necessary. A flush operation will be done. * * @param record - * the log record to be logged + * the log record to be logged. */ @Override public void publish(LogRecord record) { Modified: harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/ErrorManager.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/ErrorManager.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/ErrorManager.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/ErrorManager.java Sun Apr 26 12:30:01 2009 @@ -21,9 +21,9 @@ /** * An error reporting facility for {@link Handler} implementations to record any - * error that may happen during logging. Handlers should report - * errors to an ErrorManager, instead of throwing exceptions, - * which would interfere with the log issuer's execution. + * error that may happen during logging. {@code Handlers} should report errors + * to an {@code ErrorManager}, instead of throwing exceptions, which would + * interfere with the log issuer's execution. */ public class ErrorManager { @@ -70,7 +70,7 @@ private boolean called; /** - * Constructs an instance of ErrorManager. + * Constructs an instance of {@code ErrorManager}. */ public ErrorManager() { super(); @@ -83,13 +83,13 @@ * should override this method. * * @param message - * The error message, which may be null. + * the error message, which may be {@code null}. * @param exception - * The exception associated with the error, which may be - * null. + * the exception associated with the error, which may be + * {@code null}. * @param errorCode - * The error code that identifies the type of error; see the - * constant fields on this class. + * the error code that identifies the type of error; see the + * constant fields of this class for possible values. */ public void error(String message, Exception exception, int errorCode) { synchronized (this) { Modified: harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/FileHandler.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/FileHandler.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/FileHandler.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/FileHandler.java Sun Apr 26 12:30:01 2009 @@ -32,75 +32,68 @@ import org.apache.harmony.logging.internal.nls.Messages; /** - * A FileHandler is a Handler that writes logging events to one - * or more files. - * + * A {@code FileHandler} writes logging records into a specified file or a + * rotating set of files. *

- * If multiple files are used, when a given amount of data has been written to - * one file, this file is closed, and the next file is opened. The names of - * these files are generated by the given name pattern, see below for details. - * When all the files have all been filled the Handler returns to the first one - * and goes through the set again. - *

- * + * When a set of files is used and a given amount of data has been written to + * one file, then this file is closed and another file is opened. The name of + * these files are generated by given name pattern, see below for details. + * When the files have all been filled the Handler returns to the first and goes + * through the set again. *

- * FileHandler defines the following configuration properties, - * which are read by the LogManager on initialization. If the - * properties have not been specified then defaults will be used. The properties - * and defaults are as follows: + * By default, the I/O buffering mechanism is enabled, but when each log record + * is complete, it is flushed out. + *

+ * {@code XMLFormatter} is the default formatter for {@code FileHandler}. + *

+ * {@code FileHandler} reads the following {@code LogManager} properties for + * initialization; if a property is not defined or has an invalid value, a + * default value is used. *

    - *
  • java.util.logging.FileHandler.append - If true then this - * FileHandler appends to a file's existing content, if false it - * overwrites it. Default is false.
    • - *
  • java.util.logging.FileHandler.count - the number of output files to - * rotate. Default is 1.
    • - *
  • java.util.logging.FileHandler.filter - the name of the - * Filter class. No Filter is used by default.
    • - *
  • java.util.logging.FileHandler.formatter - the name of the - * Formatter class. Default is - * java.util.logging.XMLFormatter.
    • - *
  • java.util.logging.FileHandler.encoding - the name of the character set - * encoding. Default is the encoding used by the current platform.
    • - *
  • java.util.logging.FileHandler.level - the log level for this - * Handler. Default is Level.ALL.
    • - *
  • java.util.logging.FileHandler.limit - the limit at which no more bytes - * should be written to the current file. Default is no limit.
    • - *
  • java.util.logging.FileHandler.pattern - the pattern for the name of log - * files. Default is "%h/java%u.log".
    • + *
  • java.util.logging.FileHandler.append specifies whether this + * {@code FileHandler} should append onto existing files, defaults to + * {@code false}.
    • + *
  • java.util.logging.FileHandler.count specifies how many output files to + * rotate, defaults to 1.
    • + *
  • java.util.logging.FileHandler.filter specifies the {@code Filter} class + * name, defaults to no {@code Filter}.
    • + *
  • java.util.logging.FileHandler.formatter specifies the {@code Formatter} + * class, defaults to {@code java.util.logging.XMLFormatter}.
    • + *
  • java.util.logging.FileHandler.encoding specifies the character set + * encoding name, defaults to the default platform encoding.
    • + *
  • java.util.logging.FileHandler.level specifies the level for this + * {@code Handler}, defaults to {@code Level.ALL}.
    • + *
  • java.util.logging.FileHandler.limit specifies the maximum number of + * bytes to write to any one file, defaults to zero, which means no limit.
    • + *
  • java.util.logging.FileHandler.pattern specifies name pattern for the + * output files. See below for details. Defaults to "%h/java%u.log".
    • *
- *

- * *

- * The name pattern is a String that can contain some of the following - * sub-strings, which will be replaced to generate the output file names: + * Name pattern is a string that may include some special substrings, which will + * be replaced to generate output files: *

    - *
  • "/" represents the local path separator
    • - *
  • "%g" represents the generation number used to enumerate log files
    • + *
  • "/" represents the local pathname separator
    • + *
  • "%g" represents the generation number to distinguish rotated logs
    • *
  • "%h" represents the home directory of the current user, which is - * specified by the "user.home" system property
    • + * specified by "user.home" system property *
  • "%t" represents the system's temporary directory
    • - *
  • "%u" represents a unique number added to the file name if the original - * file required is in use
    • + *
  • "%u" represents a unique number to resolve conflicts
    • *
  • "%%" represents the percent sign character '%'
    • *
- *

- * *

- * The generation numbers, denoted by "%g" in the filename pattern will be - * created in ascending numerical order from 0, i.e. 0,1,2,3... If "%g" was not - * present in the pattern and more than one file is being used then a dot and a - * generation number is appended to the filename at the end. This is equivalent - * to appending ".%g" to the pattern. - *

- * + * Normally, the generation numbers are not larger than the given file count and + * follow the sequence 0, 1, 2.... If the file count is larger than one, but the + * generation field("%g") has not been specified in the pattern, then the + * generation number after a dot will be added to the end of the file name. *

- * The unique identifier, denoted by "%u" in the filename pattern will always be - * 0 unless the FileHandler is unable to open the file. In that - * case 1 is tried, then 2, and so on until a file is found that can be opened. - * If "%u" was not present in the pattern but a unique number is required then a - * dot and a unique number is added to the end of the filename, equivalent to - * appending ".%u" to the pattern. - *

+ * The "%u" unique field is used to avoid conflicts and is set to 0 at first. If + * one {@code FileHandler} tries to open the filename which is currently in use + * by another process, it will repeatedly increment the unique number field and + * try again. If the "%u" component has not been included in the file name + * pattern and some contention on a file does occur, then a unique numerical + * value will be added to the end of the filename in question immediately to the + * right of a dot. The generation of unique IDs for avoiding conflicts is only + * guaranteed to work reliably when using a local disk file system. */ public class FileHandler extends StreamHandler { @@ -149,17 +142,17 @@ int uniqueID = -1; /** - * Construct a FileHandler using LogManager - * properties or their default value + * Construct a {@code FileHandler} using {@code LogManager} properties or + * their default value. * * @throws IOException - * if any IO exception happened + * if any I/O error occurs. * @throws SecurityException - * if security manager exists and it determines that caller does - * not have the required permissions to control this handler, - * required permissions include - * LogPermission("control") and other permission - * like FilePermission("write"), etc. + * if a security manager exists and it determines that the + * caller does not have the required permissions to control this + * handler; required permissions include + * {@code LogPermission("control")}, + * {@code FilePermission("write")} etc. */ public FileHandler() throws IOException { init(null, null, null, null); @@ -386,27 +379,26 @@ } /** - * Construct a FileHandler, the given name pattern is used - * as output filename, the file limit is set to zero(no limit), and the file - * count is set to one, other configuration using LogManager - * properties or their default value - * - * This handler write to only one file and no amount limit. - * + * Constructs a new {@code FileHandler}. The given name pattern is used as + * output filename, the file limit is set to zero (no limit), the file count + * is set to one; the remaining configuration is done using + * {@code LogManager} properties or their default values. This handler + * writes to only one file with no size limit. + * * @param pattern - * the name pattern of output file + * the name pattern for the output file. * @throws IOException - * if any IO exception happened + * if any I/O error occurs. * @throws SecurityException - * if security manager exists and it determines that caller does - * not have the required permissions to control this handler, - * required permissions include - * LogPermission("control") and other permission - * like FilePermission("write"), etc. - * @throws NullPointerException - * if the pattern is null. + * if a security manager exists and it determines that the + * caller does not have the required permissions to control this + * handler; required permissions include + * {@code LogPermission("control")}, + * {@code FilePermission("write")} etc. * @throws IllegalArgumentException * if the pattern is empty. + * @throws NullPointerException + * if the pattern is {@code null}. */ public FileHandler(String pattern) throws IOException { if (pattern.equals("")) { //$NON-NLS-1$ @@ -418,30 +410,29 @@ } /** - * Construct a FileHandler, the given name pattern is used - * as output filename, the file limit is set to zero(i.e. no limit applies), - * the file count is initialized to one, and the value of - * append becomes the new instance's append mode. Other - * configuration is done using LogManager properties. - * - * This handler write to only one file and no amount limit. - * + * Construct a new {@code FileHandler}. The given name pattern is used as + * output filename, the file limit is set to zero (no limit), the file count + * is initialized to one and the value of {@code append} becomes the new + * instance's append mode. The remaining configuration is done using + * {@code LogManager} properties. This handler writes to only one file + * with no size limit. + * * @param pattern - * the name pattern of output file + * the name pattern for the output file. * @param append - * the append mode + * the append mode. * @throws IOException - * if any IO exception happened + * if any I/O error occurs. * @throws SecurityException - * if security manager exists and it determines that caller does - * not have the required permissions to control this handler, - * required permissions include - * LogPermission("control") and other permission - * like FilePermission("write"), etc. - * @throws NullPointerException - * if the pattern is null. + * if a security manager exists and it determines that the + * caller does not have the required permissions to control this + * handler; required permissions include + * {@code LogPermission("control")}, + * {@code FilePermission("write")} etc. * @throws IllegalArgumentException - * if the pattern is empty. + * if {@code pattern} is empty. + * @throws NullPointerException + * if {@code pattern} is {@code null}. */ public FileHandler(String pattern, boolean append) throws IOException { if (pattern.equals("")) { //$NON-NLS-1$ @@ -453,34 +444,33 @@ } /** - * Construct a FileHandler, the given name pattern is used - * as output filename, the file limit is set to given limit argument, and - * the file count is set to given count argument, other configuration using - * LogManager properties or their default value - * - * This handler is configured to write to a rotating set of count files, - * when the limit of bytes has been written to one output file, another file - * will be opened instead. - * + * Construct a new {@code FileHandler}. The given name pattern is used as + * output filename, the maximum file size is set to {@code limit} and the + * file count is initialized to {@code count}. The remaining configuration + * is done using {@code LogManager} properties. This handler is configured + * to write to a rotating set of count files, when the limit of bytes has + * been written to one output file, another file will be opened instead. + * * @param pattern - * the name pattern of output file + * the name pattern for the output file. * @param limit - * the data amount limit in bytes of one output file, cannot less - * than one + * the data amount limit in bytes of one output file, can not be + * negative. * @param count - * the maximum number of files can be used, cannot less than one + * the maximum number of files to use, can not be less than one. * @throws IOException - * if any IO exception happened + * if any I/O error occurs. * @throws SecurityException - * if security manager exists and it determines that caller does - * not have the required permissions to control this handler, - * required permissions include - * LogPermission("control") and other permission - * like FilePermission("write"), etc. - * @throws NullPointerException - * if pattern is null. + * if a security manager exists and it determines that the + * caller does not have the required permissions to control this + * handler; required permissions include + * {@code LogPermission("control")}, + * {@code FilePermission("write")} etc. * @throws IllegalArgumentException - * if count<1, or limit<0 + * if {@code pattern} is empty, {@code limit < 0} or + * {@code count < 1}. + * @throws NullPointerException + * if {@code pattern} is {@code null}. */ public FileHandler(String pattern, int limit, int count) throws IOException { if (pattern.equals("")) { //$NON-NLS-1$ @@ -495,37 +485,36 @@ } /** - * Construct a FileHandler, the given name pattern is used - * as output filename, the file limit is set to given limit argument, the - * file count is set to given count argument, and the append mode is set to - * given append argument, other configuration using LogManager - * properties or their default value - * - * This handler is configured to write to a rotating set of count files, - * when the limit of bytes has been written to one output file, another file - * will be opened instead. - * + * Construct a new {@code FileHandler}. The given name pattern is used as + * output filename, the maximum file size is set to {@code limit}, the file + * count is initialized to {@code count} and the append mode is set to + * {@code append}. The remaining configuration is done using + * {@code LogManager} properties. This handler is configured to write to a + * rotating set of count files, when the limit of bytes has been written to + * one output file, another file will be opened instead. + * * @param pattern - * the name pattern of output file + * the name pattern for the output file. * @param limit - * the data amount limit in bytes of one output file, cannot less - * than one + * the data amount limit in bytes of one output file, can not be + * negative. * @param count - * the maximum number of files can be used, cannot less than one + * the maximum number of files to use, can not be less than one. * @param append - * the append mode + * the append mode. * @throws IOException - * if any IO exception happened + * if any I/O error occurs. * @throws SecurityException - * if security manager exists and it determines that caller does - * not have the required permissions to control this handler, - * required permissions include - * LogPermission("control") and other permission - * like FilePermission("write"), etc. - * @throws NullPointerException - * if pattern is null. + * if a security manager exists and it determines that the + * caller does not have the required permissions to control this + * handler; required permissions include + * {@code LogPermission("control")}, + * {@code FilePermission("write")} etc. * @throws IllegalArgumentException - * if count<1, or limit<0 + * if {@code pattern} is empty, {@code limit < 0} or + * {@code count < 1}. + * @throws NullPointerException + * if {@code pattern} is {@code null}. */ public FileHandler(String pattern, int limit, int count, boolean append) throws IOException { @@ -542,14 +531,14 @@ } /** - * Flush and close all opened files. + * Flushes and closes all opened files. * * @throws SecurityException - * if security manager exists and it determines that caller does - * not have the required permissions to control this handler, - * required permissions include - * LogPermission("control") and other permission - * like FilePermission("write"), etc. + * if a security manager exists and it determines that the + * caller does not have the required permissions to control this + * handler; required permissions include + * {@code LogPermission("control")}, + * {@code FilePermission("write")} etc. */ @Override public void close() { @@ -568,10 +557,10 @@ } /** - * Publish a LogRecord + * Publish a {@code LogRecord}. * * @param record - * the log record to be published + * the log record to publish. */ @Override public void publish(LogRecord record) { @@ -588,9 +577,9 @@ } /** - * This output stream use decorator pattern to add measure feature to - * OutputStream which can detect the total size(in bytes) of output, the - * initial size can be set + * This output stream uses the decorator pattern to add measurement features + * to OutputStream which can detect the total size(in bytes) of output, the + * initial size can be set. */ static class MeasureOutputStream extends OutputStream { Modified: harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Filter.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Filter.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Filter.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Filter.java Sun Apr 26 12:30:01 2009 @@ -18,18 +18,18 @@ package java.util.logging; /** - * A Filter provides a mechanism for exercising fine-grained control over what - * records get logged. + * A {@code Filter} provides a mechanism for exercising fine-grained control + * over which records get logged. */ public interface Filter { /** - * Checks the {@link LogRecord} to determine if it should be logged. + * Checks {@code record} to determine if it should be logged. * * @param record - * The {@link LogRecord} to be checked. - * @return true if the supplied log record needs to be - * logged, otherwise false + * the {@link LogRecord} to be checked. + * @return {@code true} if the supplied log record needs to be logged, + * {@code false} otherwise. */ boolean isLoggable(LogRecord record); } Modified: harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Formatter.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Formatter.java?rev=768698&r1=768697&r2=768698&view=diff ============================================================================== --- harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Formatter.java (original) +++ harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Formatter.java Sun Apr 26 12:30:01 2009 @@ -21,44 +21,45 @@ import java.util.ResourceBundle; /** - * Formatter objects are used to format LogRecord - * objects into a string representation. Head and tail strings are sometime used - * to wrap a set of records. The getHead and getTail - * methods are presented for this purpose. + * {@code Formatter} objects are used to format {@link LogRecord} objects into a + * string representation. Head and tail strings are sometimes used to wrap a set + * of records. The {@code getHead} and {@code getTail} methods are used for this + * purpose. */ public abstract class Formatter { /** - * Constructs a Formatter object. + * Constructs a {@code Formatter} object. */ protected Formatter() { super(); } /** - * Formats a LogRecord object into a string representation. - * The resulted string is usually localized and includes the message field - * of the supplied LogRecord object. + * Converts a {@link LogRecord} object into a string representation. The + * resulted string is usually localized and includes the message field of + * the record. * * @param r - * the log record to be formatted into a string - * @return the string resulted from the formatting + * the log record to be formatted into a string. + * @return the formatted string. */ public abstract String format(LogRecord r); /** - * Formats a LogRecord object into a localized string - * representation. This method can be regarded as a convenience for - * subclasses of Formatter to use. + * Formats a {@code LogRecord} object into a localized string + * representation. This is a convenience method for subclasses of {@code + * Formatter}. *

- * The message string is firstly localized using the - * ResourceBundle object associated with the supplied - * LogRecord. - *

- * + * The message string is firstly localized using the {@code ResourceBundle} + * object associated with the supplied {@code LogRecord}. + *

+ * Notice : if message contains "{0", then java.text.MessageFormat is used. + * Otherwise no formatting is performed. + * * @param r - * the log record to be formatted - * @return the string resulted from the formatting + * the log record to be formatted. + * @return the string resulted from the formatting. */ public String formatMessage(LogRecord r) { String pattern = r.getMessage(); @@ -91,11 +92,12 @@ /** * Gets the head string used to wrap a set of log records. This base class - * always returns the empty string. + * always returns an empty string. * * @param h - * the target handler - * @return the head string used to wrap a set of log records + * the target handler. + * @return the head string used to wrap a set of log records, empty in this + * implementation. */ @SuppressWarnings("unused") public String getHead(Handler h) { @@ -107,8 +109,9 @@ * always returns the empty string. * * @param h - * the target handler - * @return the tail string used to wrap a set of log records + * the target handler. + * @return the tail string used to wrap a set of log records, empty in this + * implementation. */ @SuppressWarnings("unused") public String getTail(Handler h) {