Repository: commons-crypto Updated Branches: refs/heads/master 24719f352 -> e2cc6aeed
CRYPTO-46: Fix javadoc according doclint of Java 8 Project: http://git-wip-us.apache.org/repos/asf/commons-crypto/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-crypto/commit/e2cc6aee Tree: http://git-wip-us.apache.org/repos/asf/commons-crypto/tree/e2cc6aee Diff: http://git-wip-us.apache.org/repos/asf/commons-crypto/diff/e2cc6aee Branch: refs/heads/master Commit: e2cc6aeed7a18047d383e3547d618d93d6d133f8 Parents: 24719f3 Author: Sun Dapeng <s...@apache.org> Authored: Tue May 3 14:16:16 2016 +0800 Committer: Sun Dapeng <s...@apache.org> Committed: Wed May 4 10:56:45 2016 +0800 ---------------------------------------------------------------------- pom.xml | 9 ----- .../crypto/cipher/CipherTransformation.java | 5 ++- .../crypto/cipher/CryptoCipherFactory.java | 5 ++- .../apache/commons/crypto/cipher/Openssl.java | 38 +++++++++++++------- .../commons/crypto/cipher/OpensslCipher.java | 4 +-- .../commons/crypto/cipher/OpensslNative.java | 6 ++++ .../commons/crypto/conf/ConfigurationKeys.java | 2 +- .../crypto/random/OpensslCryptoRandom.java | 34 +++++++++--------- .../commons/crypto/random/OsCryptoRandom.java | 2 +- .../crypto/stream/CTRCryptoInputStream.java | 7 ++-- .../crypto/stream/CTRCryptoOutputStream.java | 6 ++-- .../crypto/stream/CryptoInputStream.java | 3 +- .../stream/PositionedCryptoInputStream.java | 1 + .../commons/crypto/utils/ReflectionUtils.java | 2 ++ .../org/apache/commons/crypto/utils/Utils.java | 20 +++++++---- 15 files changed, 87 insertions(+), 57 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-crypto/blob/e2cc6aee/pom.xml ---------------------------------------------------------------------- diff --git a/pom.xml b/pom.xml index 167a26a..41f3f34 100644 --- a/pom.xml +++ b/pom.xml @@ -241,15 +241,6 @@ Features </plugins> </build> </profile> - <profile> - <id>doclint-java8-disable</id> - <activation> - <jdk>[1.8,)</jdk> - </activation> - <properties> - <additionalparam>-Xdoclint:none</additionalparam> - </properties> - </profile> </profiles> <licenses> <license> http://git-wip-us.apache.org/repos/asf/commons-crypto/blob/e2cc6aee/src/main/java/org/apache/commons/crypto/cipher/CipherTransformation.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/crypto/cipher/CipherTransformation.java b/src/main/java/org/apache/commons/crypto/cipher/CipherTransformation.java index a68a540..72f2f4d 100644 --- a/src/main/java/org/apache/commons/crypto/cipher/CipherTransformation.java +++ b/src/main/java/org/apache/commons/crypto/cipher/CipherTransformation.java @@ -18,8 +18,7 @@ package org.apache.commons.crypto.cipher; /** - * Defines properties of a CipherTransformation. Modeled after the ciphers in - * {@link Cipher}. + * Defines properties of a CipherTransformation. Modeled after the ciphers in Cipher. */ public enum CipherTransformation { @@ -48,7 +47,7 @@ public enum CipherTransformation { /** * Gets the algorithm name of cipher. * - * @return name of cipher transformation, as in {@link Cipher} + * @return name of cipher transformation, as in Cipher */ public String getName() { return name; http://git-wip-us.apache.org/repos/asf/commons-crypto/blob/e2cc6aee/src/main/java/org/apache/commons/crypto/cipher/CryptoCipherFactory.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/crypto/cipher/CryptoCipherFactory.java b/src/main/java/org/apache/commons/crypto/cipher/CryptoCipherFactory.java index 20be0cb..578c962 100644 --- a/src/main/java/org/apache/commons/crypto/cipher/CryptoCipherFactory.java +++ b/src/main/java/org/apache/commons/crypto/cipher/CryptoCipherFactory.java @@ -32,7 +32,7 @@ import org.slf4j.LoggerFactory; */ public class CryptoCipherFactory { - /** LOG instance for {@CipherFactory} */ + /** LOG instance for {@link CryptoCipherFactory} */ public final static Logger LOG = LoggerFactory.getLogger(CryptoCipherFactory.class); private CryptoCipherFactory() {} @@ -46,6 +46,7 @@ public class CryptoCipherFactory { * algorithm/mode/padding * @return CryptoCipher the cipher. Null value will be returned if no * cipher classes with transformation configured. + * @throws GeneralSecurityException if cipher initialize failed */ public static CryptoCipher getInstance(CipherTransformation transformation, Properties props) throws GeneralSecurityException { @@ -74,8 +75,10 @@ public class CryptoCipherFactory { * Gets a cipher for algorithm/mode/padding in config value * commons.crypto.cipher.transformation * + * @param transformation CipherTransformation instance. * @return CryptoCipher the cipher object Null value will be returned if no * cipher classes with transformation configured. + * @throws GeneralSecurityException if JCE cipher initialize failed */ public static CryptoCipher getInstance(CipherTransformation transformation) throws GeneralSecurityException { http://git-wip-us.apache.org/repos/asf/commons-crypto/blob/e2cc6aee/src/main/java/org/apache/commons/crypto/cipher/Openssl.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/crypto/cipher/Openssl.java b/src/main/java/org/apache/commons/crypto/cipher/Openssl.java index 488438b..bdee203 100644 --- a/src/main/java/org/apache/commons/crypto/cipher/Openssl.java +++ b/src/main/java/org/apache/commons/crypto/cipher/Openssl.java @@ -108,12 +108,12 @@ public final class Openssl { } /** - * Return an <code>OpensslCipher<code> object that implements the specified + * Return an <code>OpensslCipher</code> object that implements the specified * transformation. * * @param transformation the name of the transformation, e.g., * AES/CTR/NoPadding. - * @return OpensslCipher an <code>OpensslCipher<code> object + * @return OpensslCipher an <code>OpensslCipher</code> object * @throws NoSuchAlgorithmException if <code>transformation</code> is null, * empty, in an invalid format, or if Openssl doesn't implement the * specified algorithm. @@ -180,20 +180,23 @@ public final class Openssl { } /** + * <p> * Continues a multiple-part encryption or decryption operation. The data * is encrypted or decrypted, depending on how this cipher was initialized. - * <p/> + * </p> * + * <p> * All <code>input.remaining()</code> bytes starting at * <code>input.position()</code> are processed. The result is stored in * the output buffer. - * <p/> + * </p> * + * <p> * Upon return, the input buffer's position will be equal to its limit; * its limit will not have changed. The output buffer's position will have * advanced by n, when n is the value returned by this method; the output * buffer's limit will not have changed. - * <p/> + * </p> * * If <code>output.remaining()</code> bytes are insufficient to hold the * result, a <code>ShortBufferException</code> is thrown. @@ -237,32 +240,43 @@ public final class Openssl { } /** + * <p> * Finishes a multiple-part operation. The data is encrypted or decrypted, * depending on how this cipher was initialized. - * <p/> + * </p> * + * <p> * The result is stored in the output buffer. Upon return, the output buffer's * position will have advanced by n, where n is the value returned by this * method; the output buffer's limit will not have changed. - * <p/> + * </p> * + * <p> * If <code>output.remaining()</code> bytes are insufficient to hold the result, * a <code>ShortBufferException</code> is thrown. - * <p/> + * </p> * + * <p> * Upon finishing, this method resets this cipher object to the state it was * in when previously initialized. That is, the object is available to encrypt * or decrypt more data. - * <p/> + * </p> * * If any exception is thrown, this cipher object need to be reset before it * can be used again. * * @param output the output ByteBuffer * @return int number of bytes stored in <code>output</code> - * @throws ShortBufferException - * @throws IllegalBlockSizeException - * @throws BadPaddingException + * @throws ShortBufferException if the given output byte array is too small + * to hold the result. + * @throws IllegalBlockSizeException if this cipher is a block cipher, + * no padding has been requested (only in encryption mode), and the total + * input length of the data processed by this cipher is not a multiple of + * block size; or if this encryption algorithm is unable to + * process the input data provided. + * @throws BadPaddingException if this cipher is in decryption mode, + * and (un)padding has been requested, but the decrypted data is not + * bounded by the appropriate padding bytes */ public int doFinal(ByteBuffer output) throws ShortBufferException, IllegalBlockSizeException, http://git-wip-us.apache.org/repos/asf/commons-crypto/blob/e2cc6aee/src/main/java/org/apache/commons/crypto/cipher/OpensslCipher.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/crypto/cipher/OpensslCipher.java b/src/main/java/org/apache/commons/crypto/cipher/OpensslCipher.java index 4614d81..0473c85 100644 --- a/src/main/java/org/apache/commons/crypto/cipher/OpensslCipher.java +++ b/src/main/java/org/apache/commons/crypto/cipher/OpensslCipher.java @@ -17,7 +17,6 @@ */ package org.apache.commons.crypto.cipher; -import java.io.IOException; import java.nio.ByteBuffer; import java.security.GeneralSecurityException; import java.security.Key; @@ -86,7 +85,8 @@ public class OpensslCipher implements CryptoCipher { * @param mode {@link #ENCRYPT_MODE} or {@link #DECRYPT_MODE} * @param key crypto key for the cipher * @param params the algorithm parameters - * @throws IOException if cipher initialize fails + * @throws InvalidKeyException If key length is invalid + * @throws InvalidAlgorithmParameterException if IV length is wrong */ @Override public void init(int mode, Key key, AlgorithmParameterSpec params) http://git-wip-us.apache.org/repos/asf/commons-crypto/blob/e2cc6aee/src/main/java/org/apache/commons/crypto/cipher/OpensslNative.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/crypto/cipher/OpensslNative.java b/src/main/java/org/apache/commons/crypto/cipher/OpensslNative.java index c3f7593..f290956 100644 --- a/src/main/java/org/apache/commons/crypto/cipher/OpensslNative.java +++ b/src/main/java/org/apache/commons/crypto/cipher/OpensslNative.java @@ -44,6 +44,12 @@ public class OpensslNative { /** * Declares a native method to initialize the cipher context. * + * @param context The cipher context address + * @param mode ENCRYPT_MODE or DECRYPT_MODE + * @param alg Algorithm Mode of Openssl + * @param padding the padding mode of Openssl cipher + * @param key crypto key + * @param iv crypto iv * @return the context address of cipher */ public native static long init(long context, int mode, int alg, int padding, http://git-wip-us.apache.org/repos/asf/commons-crypto/blob/e2cc6aee/src/main/java/org/apache/commons/crypto/conf/ConfigurationKeys.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/crypto/conf/ConfigurationKeys.java b/src/main/java/org/apache/commons/crypto/conf/ConfigurationKeys.java index d8e6fbd..7bab928 100644 --- a/src/main/java/org/apache/commons/crypto/conf/ConfigurationKeys.java +++ b/src/main/java/org/apache/commons/crypto/conf/ConfigurationKeys.java @@ -42,7 +42,7 @@ public class ConfigurationKeys { * "org.apache.commons.crypto.cipher.JceCipher" and "org.apache.commons.crypto.cipher.OpensslCipher". * And it takes a common separated list. * The "org.apache.commons.crypto.cipher.JceCipher" use jce provider to - * implement {@link CryptoCipher} and + * implement CryptoCipher and * the "org.apache.commons.crypto.cipher.OpensslCipher" use jni into openssl to implement. * Note that for each value,the first value which can be created without exception * will be used (priority by order). http://git-wip-us.apache.org/repos/asf/commons-crypto/blob/e2cc6aee/src/main/java/org/apache/commons/crypto/random/OpensslCryptoRandom.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/crypto/random/OpensslCryptoRandom.java b/src/main/java/org/apache/commons/crypto/random/OpensslCryptoRandom.java index cea0e56..315e259 100644 --- a/src/main/java/org/apache/commons/crypto/random/OpensslCryptoRandom.java +++ b/src/main/java/org/apache/commons/crypto/random/OpensslCryptoRandom.java @@ -28,18 +28,20 @@ import org.apache.commons.crypto.utils.NativeCodeLoader; import org.apache.commons.crypto.utils.Utils; /** - * OpenSSL secure random using JNI. - * This implementation is thread-safe. - * <p/> + * <p> + * OpenSSL secure random using JNI. This implementation is thread-safe. + * </p> * + * <p> * If using an Intel chipset with RDRAND, the high-performance hardware * random number generator will be used and it's much faster than - * {@link SecureRandom}. If RDRAND is unavailable, default - * OpenSSL secure random generator will be used. It's still faster - * and can generate strong random bytes. - * <p/> - * @see https://wiki.openssl.org/index.php/Random_Numbers - * @see http://en.wikipedia.org/wiki/RdRand + * SecureRandom. If RDRAND is unavailable, default OpenSSL secure random + * generator will be used. It's still faster and can generate strong random bytes. + * </p> + * @see <a href="https://wiki.openssl.org/index.php/Random_Numbers";> + * https://wiki.openssl.org/index.php/Random_Numbers</a> + * @see <a href="http://en.wikipedia.org/wiki/RdRand";> + * http://en.wikipedia.org/wiki/RdRand</a> */ public class OpensslCryptoRandom extends Random implements CryptoRandom { private static final long serialVersionUID = -7828193502768789584L; @@ -112,14 +114,14 @@ public class OpensslCryptoRandom extends Random implements CryptoRandom { } /** - * Overrides {@link java.util.Random# next()}. Generates an integer - * containing the user-specified number of random - * bits(right justified, with leading zeros). + * Overrides Random#next(). Generates an integer containing the + * user-specified number of random bits(right justified, with leading + * zeros). * - * @param numBits number of random bits to be generated, where - * 0 <= <code>numBits</code> <= 32. - * @return int an <code>int</code> containing the user-specified number - * of random bits (right justified, with leading zeros). + * @param numBits number of random bits to be generated, where 0 + * {@literal <=} <code>numBits</code> {@literal <=} 32. + * @return int an <code>int</code> containing the user-specified number of + * random bits (right justified, with leading zeros). */ @Override final protected int next(int numBits) { http://git-wip-us.apache.org/repos/asf/commons-crypto/blob/e2cc6aee/src/main/java/org/apache/commons/crypto/random/OsCryptoRandom.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/crypto/random/OsCryptoRandom.java b/src/main/java/org/apache/commons/crypto/random/OsCryptoRandom.java index 17fbfef..7c8bc07 100644 --- a/src/main/java/org/apache/commons/crypto/random/OsCryptoRandom.java +++ b/src/main/java/org/apache/commons/crypto/random/OsCryptoRandom.java @@ -103,7 +103,7 @@ public class OsCryptoRandom extends Random implements CryptoRandom { } /** - * Overrides {@link java.util.Random# next()}. Generates the next pseudorandom number. + * Overrides Random#next(). Generates the next pseudorandom number. * Subclasses should override this, as this is used by all other methods. * * @param nbits random bits. http://git-wip-us.apache.org/repos/asf/commons-crypto/blob/e2cc6aee/src/main/java/org/apache/commons/crypto/stream/CTRCryptoInputStream.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/crypto/stream/CTRCryptoInputStream.java b/src/main/java/org/apache/commons/crypto/stream/CTRCryptoInputStream.java index 7e6ff7b..481b0d6 100644 --- a/src/main/java/org/apache/commons/crypto/stream/CTRCryptoInputStream.java +++ b/src/main/java/org/apache/commons/crypto/stream/CTRCryptoInputStream.java @@ -38,16 +38,18 @@ import org.apache.commons.crypto.stream.input.StreamInput; import org.apache.commons.crypto.utils.Utils; /** + * <p> * CTRCryptoInputStream decrypts data. AES CTR mode is required in order to * ensure that the plain text and cipher text have a 1:1 mapping. CTR crypto * stream has stream characteristic which is useful for implement features * like random seek. The decryption is buffer based. The key points of the * decryption are (1) calculating the counter and (2) padding through stream * position: - * <p/> + * </p> + * <p> * counter = base + pos/(algorithm blocksize); * padding = pos%(algorithm blocksize); - * <p/> + * </p> * The underlying stream offset is maintained as state. It is not thread-safe. */ public class CTRCryptoInputStream extends CryptoInputStream { @@ -501,6 +503,7 @@ public class CTRCryptoInputStream extends CryptoInputStream { * * @param position the given position in the data.. * @return the byte. + * @throws IOException if an I/O error occurs. */ protected byte postDecryption(long position) throws IOException { byte padding = 0; http://git-wip-us.apache.org/repos/asf/commons-crypto/blob/e2cc6aee/src/main/java/org/apache/commons/crypto/stream/CTRCryptoOutputStream.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/crypto/stream/CTRCryptoOutputStream.java b/src/main/java/org/apache/commons/crypto/stream/CTRCryptoOutputStream.java index 11c99f6..1b76db2 100644 --- a/src/main/java/org/apache/commons/crypto/stream/CTRCryptoOutputStream.java +++ b/src/main/java/org/apache/commons/crypto/stream/CTRCryptoOutputStream.java @@ -39,14 +39,16 @@ import org.apache.commons.crypto.stream.output.StreamOutput; import org.apache.commons.crypto.utils.Utils; /** + * <p> * CTRCryptoOutputStream encrypts data. It is not thread-safe. AES CTR mode is * required in order to ensure that the plain text and cipher text have a 1:1 * mapping. The encryption is buffer based. The key points of the encryption are * (1) calculating counter and (2) padding through stream position. - * <p/> + * </p> + * <p> * counter = base + pos/(algorithm blocksize); * padding = pos%(algorithm blocksize); - * <p/> + * </p> * The underlying stream offset is maintained as state. */ public class CTRCryptoOutputStream extends CryptoOutputStream { http://git-wip-us.apache.org/repos/asf/commons-crypto/blob/e2cc6aee/src/main/java/org/apache/commons/crypto/stream/CryptoInputStream.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/crypto/stream/CryptoInputStream.java b/src/main/java/org/apache/commons/crypto/stream/CryptoInputStream.java index 2d62a76..7b4313b 100644 --- a/src/main/java/org/apache/commons/crypto/stream/CryptoInputStream.java +++ b/src/main/java/org/apache/commons/crypto/stream/CryptoInputStream.java @@ -342,7 +342,7 @@ public class CryptoInputStream extends InputStream implements /** * Overrides the {@link InputStream#markSupported()}. * - * @return false,the {@link CTRCipherInputStream} don't support the mark method. + * @return false,the {@link CTRCryptoInputStream} don't support the mark method. */ @Override public boolean markSupported() { @@ -463,6 +463,7 @@ public class CryptoInputStream extends InputStream implements * do final of the cipher to finish all the decrypting of data. * * @return The number of decrypted data. -1 if end of the decrypted stream. + * @throws IOException if an I/O error occurs. */ protected int decryptMore() throws IOException { if(finalDone) { http://git-wip-us.apache.org/repos/asf/commons-crypto/blob/e2cc6aee/src/main/java/org/apache/commons/crypto/stream/PositionedCryptoInputStream.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/crypto/stream/PositionedCryptoInputStream.java b/src/main/java/org/apache/commons/crypto/stream/PositionedCryptoInputStream.java index 7efbec6..255e57e 100644 --- a/src/main/java/org/apache/commons/crypto/stream/PositionedCryptoInputStream.java +++ b/src/main/java/org/apache/commons/crypto/stream/PositionedCryptoInputStream.java @@ -101,6 +101,7 @@ public class PositionedCryptoInputStream extends CTRCryptoInputStream { * @param offset the start offset in the data. * @param position the offset from the start of the stream. * @throws IOException if an I/O error occurs. + * @return int the total number of decrypted data bytes read into the buffer. */ public int read(long position, byte[] buffer, int offset, int length) throws IOException { http://git-wip-us.apache.org/repos/asf/commons-crypto/blob/e2cc6aee/src/main/java/org/apache/commons/crypto/utils/ReflectionUtils.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/crypto/utils/ReflectionUtils.java b/src/main/java/org/apache/commons/crypto/utils/ReflectionUtils.java index b3adcf1..ce077d7 100644 --- a/src/main/java/org/apache/commons/crypto/utils/ReflectionUtils.java +++ b/src/main/java/org/apache/commons/crypto/utils/ReflectionUtils.java @@ -59,6 +59,7 @@ public class ReflectionUtils { * create and initialize a new instance of the constructor's * declaring class, with the specified initialization parameters. * + * @param <T> type for the new instance * @param klass the Class object. * @param args array of objects to be passed as arguments to * the constructor call. @@ -93,6 +94,7 @@ public class ReflectionUtils { * returned.An exception is thrown if the returned class does not * implement the named interface. * + * @param <U> type for the class. * @param name the class name of default implementation. * @param defaultValue default value. * @param xface the interface implemented by the named class. http://git-wip-us.apache.org/repos/asf/commons-crypto/blob/e2cc6aee/src/main/java/org/apache/commons/crypto/utils/Utils.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/crypto/utils/Utils.java b/src/main/java/org/apache/commons/crypto/utils/Utils.java index 4c3d3f9..16ce270 100644 --- a/src/main/java/org/apache/commons/crypto/utils/Utils.java +++ b/src/main/java/org/apache/commons/crypto/utils/Utils.java @@ -53,7 +53,8 @@ public class Utils { /** * For AES, the algorithm block is fixed size of 128 bits. - * @see http://en.wikipedia.org/wiki/Advanced_Encryption_Standard + * @see <a href="http://en.wikipedia.org/wiki/Advanced_Encryption_Standard";> + * http://en.wikipedia.org/wiki/Advanced_Encryption_Standard</a> */ private static final int AES_BLOCK_SIZE = AES_CTR_NOPADDING.getAlgorithmBlockSize(); @@ -233,18 +234,22 @@ public class Utils { } /** + * <p> * This method is only for Counter (CTR) mode. Generally the CryptoCipher calculates the - * IV and maintain encryption context internally.For example a - * {@link Cipher} will maintain its encryption context internally - * when we do encryption/decryption using the CryptoCipher#update interface. - * <p/> + * IV and maintain encryption context internally.For example a Cipher will maintain its + * encryption context internally when we do encryption/decryption using the + * CryptoCipher#update interface. + * </p> + * <p> * Encryption/Decryption is not always on the entire file. For example, * in Hadoop, a node may only decrypt a portion of a file (i.e. a split). * In these situations, the counter is derived from the file position. - * <p/> + * </p> * The IV can be calculated by combining the initial IV and the counter with * a lossless operation (concatenation, addition, or XOR). - * @see http://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_.28CTR.29 + * + * @see <a href="http://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_.28CTR.29";> + * http://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_.28CTR.29</a> * * @param initIV initial IV * @param counter counter for input stream position @@ -318,6 +323,7 @@ public class Utils { * Ensures that an object reference passed as a parameter to the calling * method is not null. * + * @param <T> the type of the object reference to be checked. * @param reference an object reference. * @return the non-null reference that was validated. * @throws NullPointerException if reference is null.
