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:
parent
93148a8e5e
commit
c7ef0b7eb7
|
@ -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
|
||||
|
|
|
@ -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) {
|
||||
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
/**
|
||||
|
|
Loading…
Reference in New Issue