Author: julius
Date: Fri Aug 24 05:24:35 2012
New Revision: 1376829
URL: http://svn.apache.org/viewvc?rev=1376829&view=rev
Log:
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.
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/ObjectUtils.java
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/ObjectUtilsTest.java
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/ObjectUtils.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/ObjectUtils.java?rev=1376829&r1=1376828&r2=1376829&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/ObjectUtils.java
(original)
+++
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/ObjectUtils.java
Fri Aug 24 05:24:35 2012
@@ -632,7 +632,9 @@ public class ObjectUtils {
* 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 @@ public class ObjectUtils {
* 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 @@ public class ObjectUtils {
* 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 @@ public class ObjectUtils {
* 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 @@ public class ObjectUtils {
* 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 @@ public class ObjectUtils {
* 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 @@ public class ObjectUtils {
* 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 @@ public class ObjectUtils {
* 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 @@ public class ObjectUtils {
* 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
Modified:
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/ObjectUtilsTest.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/ObjectUtilsTest.java?rev=1376829&r1=1376828&r2=1376829&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/ObjectUtilsTest.java
(original)
+++
commons/proper/lang/trunk/src/test/java/org/apache/commons/lang3/ObjectUtilsTest.java
Fri Aug 24 05:24:35 2012
@@ -466,6 +466,65 @@ public class ObjectUtilsTest {
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) {
+
+ }
+
}
/**
