Apache
/
commons-lang
mirror of https://github.com/apache/commons-lang.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

LANG-816 - followup incorporating ggregory's doc suggestion, some doc fixes, addition of CONST_BYTE() and CONST_SHORT(), and Junit improvements to test doc examples and make sure CONST_BYTE() and CONST_SHORT() throw IllegalArgumentException as required. 

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/lang/trunk@1376829 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Julius Davies 2012-08-24 05:24:35 +00:00
parent 93148a8e5e
commit c7ef0b7eb7
2 changed files with 139 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
src/main/java/org/apache/commons/lang3/ObjectUtils.java
View File

@ -632,7 +632,9 @@ their constant using one of the CONST() utility methods, instead:
* This can prevent javac from inlining a constant
* field, e.g.,
*
* public final static boolean MAGIC_FLAG = CONST(true);
* <pre>
* public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true);
* </pre>
*
* This way any jars that refer to this field do not
* have to recompile themselves if the field's value
@ -648,7 +650,9 @@ their constant using one of the CONST() utility methods, instead:
* This can prevent javac from inlining a constant
* field, e.g.,
*
* public final static byte MAGIC_BYTE = CONST(127);
* <pre>
* public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127);
* </pre>
*
* This way any jars that refer to this field do not
* have to recompile themselves if the field's value
@ -664,7 +668,35 @@ their constant using one of the CONST() utility methods, instead:
* This can prevent javac from inlining a constant
* field, e.g.,
*
* public final static byte MAGIC_CHAR = CONST('a');
* <pre>
* public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127);
* </pre>
*
* This way any jars that refer to this field do not
* have to recompile themselves if the field's value
* changes at some future date.
*
* @param v the byte literal (as an int) value to return
* @throws IllegalArgumentException if the value passed to v
* is larger than a byte, that is, smaller than -128 or
* larger than 127.
* @return the byte v, unchanged
*/
public static byte CONST_BYTE(final int v) throws IllegalArgumentException {
if (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) {
throw new IllegalArgumentException("Supplied value must be a valid byte literal between -128 and 127: [" + v + "]");
}
return (byte) v;
}
/**
* This method returns the provided value unchanged.
* This can prevent javac from inlining a constant
* field, e.g.,
*
* <pre>
* public final static char MAGIC_CHAR = ObjectUtils.CONST('a');
* </pre>
*
* This way any jars that refer to this field do not
* have to recompile themselves if the field's value
@ -680,7 +712,9 @@ their constant using one of the CONST() utility methods, instead:
* This can prevent javac from inlining a constant
* field, e.g.,
*
* public final static byte MAGIC_SHORT = CONST(123);
* <pre>
* public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123);
* </pre>
*
* This way any jars that refer to this field do not
* have to recompile themselves if the field's value
@ -696,7 +730,36 @@ their constant using one of the CONST() utility methods, instead:
* This can prevent javac from inlining a constant
* field, e.g.,
*
* public final static byte MAGIC_INT = CONST(123);
* <pre>
* public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127);
* </pre>
*
* This way any jars that refer to this field do not
* have to recompile themselves if the field's value
* changes at some future date.
*
* @param v the short literal (as an int) value to return
* @throws IllegalArgumentException if the value passed to v
* is larger than a short, that is, smaller than -32768 or
* larger than 32767.
* @return the byte v, unchanged
*/
public static short CONST_SHORT(final int v) throws IllegalArgumentException {
if (v < Short.MIN_VALUE || v > Short.MAX_VALUE) {
throw new IllegalArgumentException("Supplied value must be a valid byte literal between -32768 and 32767: [" + v + "]");
}
return (short) v;
}
/**
* This method returns the provided value unchanged.
* This can prevent javac from inlining a constant
* field, e.g.,
*
* <pre>
* public final static int MAGIC_INT = ObjectUtils.CONST(123);
* </pre>
*
* This way any jars that refer to this field do not
* have to recompile themselves if the field's value
@ -712,7 +775,9 @@ their constant using one of the CONST() utility methods, instead:
* This can prevent javac from inlining a constant
* field, e.g.,
*
* public final static byte MAGIC_LONG = CONST(123L);
* <pre>
* public final static long MAGIC_LONG = ObjectUtils.CONST(123L);
* </pre>
*
* This way any jars that refer to this field do not
* have to recompile themselves if the field's value
@ -728,7 +793,9 @@ their constant using one of the CONST() utility methods, instead:
* This can prevent javac from inlining a constant
* field, e.g.,
*
* public final static byte MAGIC_FLOAT = CONST(1.0f);
* <pre>
* public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f);
* </pre>
*
* This way any jars that refer to this field do not
* have to recompile themselves if the field's value
@ -744,7 +811,9 @@ their constant using one of the CONST() utility methods, instead:
* This can prevent javac from inlining a constant
* field, e.g.,
*
* public final static byte MAGIC_DOUBLE = CONST(1.0);
* <pre>
* public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0);
* </pre>
*
* This way any jars that refer to this field do not
* have to recompile themselves if the field's value
@ -760,7 +829,9 @@ their constant using one of the CONST() utility methods, instead:
* This can prevent javac from inlining a constant
* field, e.g.,
*
* public final static byte MAGIC_STRING = CONST("abc");
* <pre>
* public final static String MAGIC_STRING = ObjectUtils.CONST("abc");
* </pre>
*
* This way any jars that refer to this field do not
* have to recompile themselves if the field's value

59
src/test/java/org/apache/commons/lang3/ObjectUtilsTest.java
View File

@ -466,6 +466,65 @@ public void testConstMethods() {
assertEquals("CONST(float)", 3f, ObjectUtils.CONST(3f), 0);
assertEquals("CONST(double)", 3.0, ObjectUtils.CONST(3.0), 0);
assertEquals("CONST(Object)", "abc", ObjectUtils.CONST("abc"));
// Make sure documentation examples from Javadoc all work
// (this fixed a lot of my bugs when I these!)
//
// My bugs should be in a software engineering textbook
// for "Can you screw this up?" The answer is, yes,
// you can even screw this up. (When you == Julius)
// .
boolean MAGIC_FLAG = ObjectUtils.CONST(true);
byte MAGIC_BYTE1 = ObjectUtils.CONST((byte) 127);
byte MAGIC_BYTE2 = ObjectUtils.CONST_BYTE(127);
char MAGIC_CHAR = ObjectUtils.CONST('a');
short MAGIC_SHORT1 = ObjectUtils.CONST((short) 123);
short MAGIC_SHORT2 = ObjectUtils.CONST_SHORT(127);
int MAGIC_INT = ObjectUtils.CONST(123);
long MAGIC_LONG1 = ObjectUtils.CONST(123L);
long MAGIC_LONG2 = ObjectUtils.CONST(3);
float MAGIC_FLOAT = ObjectUtils.CONST(1.0f);
double MAGIC_DOUBLE = ObjectUtils.CONST(1.0);
String MAGIC_STRING = ObjectUtils.CONST("abc");
assertEquals(true, MAGIC_FLAG);
assertEquals(127, MAGIC_BYTE1);
assertEquals(127, MAGIC_BYTE2);
assertEquals('a', MAGIC_CHAR);
assertEquals(123, MAGIC_SHORT1);
assertEquals(127, MAGIC_SHORT2);
assertEquals(123, MAGIC_INT);
assertEquals(123, MAGIC_LONG1);
assertEquals(3, MAGIC_LONG2);
assertEquals(1.0f, MAGIC_FLOAT, 0.0f);
assertEquals(1.0, MAGIC_DOUBLE, 0.0);
assertEquals("abc", MAGIC_STRING);
try {
ObjectUtils.CONST_BYTE(-129);
fail("CONST_BYTE(-129): IllegalArgumentException should have been thrown.");
} catch (IllegalArgumentException iae) {
}
try {
ObjectUtils.CONST_BYTE(128);
fail("CONST_BYTE(128): IllegalArgumentException should have been thrown.");
} catch (IllegalArgumentException iae) {
}
try {
ObjectUtils.CONST_SHORT(-32769);
fail("CONST_SHORT(-32769): IllegalArgumentException should have been thrown.");
} catch (IllegalArgumentException iae) {
}
try {
ObjectUtils.CONST_BYTE(32768);
fail("CONST_SHORT(32768): IllegalArgumentException should have been thrown.");
} catch (IllegalArgumentException iae) {
}
}
/**