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
|
* This can prevent javac from inlining a constant
|
||||||
* field, e.g.,
|
* 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
|
* This way any jars that refer to this field do not
|
||||||
* have to recompile themselves if the field's value
|
* 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
|
* This can prevent javac from inlining a constant
|
||||||
* field, e.g.,
|
* 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
|
* This way any jars that refer to this field do not
|
||||||
* have to recompile themselves if the field's value
|
* 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
|
* This can prevent javac from inlining a constant
|
||||||
* field, e.g.,
|
* 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
|
* This way any jars that refer to this field do not
|
||||||
* have to recompile themselves if the field's value
|
* 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
|
* This can prevent javac from inlining a constant
|
||||||
* field, e.g.,
|
* 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
|
* This way any jars that refer to this field do not
|
||||||
* have to recompile themselves if the field's value
|
* 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
|
* This can prevent javac from inlining a constant
|
||||||
* field, e.g.,
|
* 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
|
* This way any jars that refer to this field do not
|
||||||
* have to recompile themselves if the field's value
|
* 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
|
* This can prevent javac from inlining a constant
|
||||||
* field, e.g.,
|
* 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
|
* This way any jars that refer to this field do not
|
||||||
* have to recompile themselves if the field's value
|
* 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
|
* This can prevent javac from inlining a constant
|
||||||
* field, e.g.,
|
* 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
|
* This way any jars that refer to this field do not
|
||||||
* have to recompile themselves if the field's value
|
* 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
|
* This can prevent javac from inlining a constant
|
||||||
* field, e.g.,
|
* 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
|
* This way any jars that refer to this field do not
|
||||||
* have to recompile themselves if the field's value
|
* 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
|
* This can prevent javac from inlining a constant
|
||||||
* field, e.g.,
|
* 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
|
* This way any jars that refer to this field do not
|
||||||
* have to recompile themselves if the field's value
|
* 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(float)", 3f, ObjectUtils.CONST(3f), 0);
|
||||||
assertEquals("CONST(double)", 3.0, ObjectUtils.CONST(3.0), 0);
|
assertEquals("CONST(double)", 3.0, ObjectUtils.CONST(3.0), 0);
|
||||||
assertEquals("CONST(Object)", "abc", ObjectUtils.CONST("abc"));
|
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