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

Javadoc fixes. Shouldn't have been anything other than javadoc changes in this. 

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/lang/trunk@137416 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Henri Yandell 2003-07-14 22:25:06 +00:00
parent 99a9ac4d5e
commit eadb45d1a7
38 changed files with 1448 additions and 1071 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
src/java/org/apache/commons/lang/ArrayUtils.java
View File

@ -70,47 +70,85 @@
* @author Nikolay Metchev
* @author Matthew Hawthorne
* @since 2.0
* @version $Id: ArrayUtils.java,v 1.17 2003/07/12 10:09:40 scolebourne Exp $
* @version $Id: ArrayUtils.java,v 1.18 2003/07/14 22:25:02 bayard Exp $
*/
public class ArrayUtils {
/** An empty immutable object array */
/**
* An empty immutable <code>Object</code> array.
*/
public static final Object[] EMPTY_OBJECT_ARRAY = new Object[0];
/** An empty immutable class array */
/**
* An empty immutable <code>Class</code> array.
*/
public static final Class[] EMPTY_CLASS_ARRAY = new Class[0];
/** An empty immutable string array */
/**
* An empty immutable <code>String</code> array.
*/
public static final String[] EMPTY_STRING_ARRAY = new String[0];
/** An empty immutable long array */
/**
* An empty immutable <code>long</code> array.
*/
public static final long[] EMPTY_LONG_ARRAY = new long[0];
/** An empty immutable Long array */
/**
* An empty immutable <code>Long</code> array.
*/
public static final Long[] EMPTY_LONG_OBJECT_ARRAY = new Long[0];
/** An empty immutable int array */
/**
* An empty immutable <code>int</code> array.
*/
public static final int[] EMPTY_INT_ARRAY = new int[0];
/** An empty immutable Integer array */
/**
* An empty immutable <code>Integer</code> array.
*/
public static final Integer[] EMPTY_INTEGER_OBJECT_ARRAY = new Integer[0];
/** An empty immutable short array */
/**
* An empty immutable <code>short</code> array.
*/
public static final short[] EMPTY_SHORT_ARRAY = new short[0];
/** An empty immutable Short array */
/**
* An empty immutable <code>Short</code> array.
*/
public static final Short[] EMPTY_SHORT_OBJECT_ARRAY = new Short[0];
/** An empty immutable byte array */
/**
* An empty immutable <code>byte</code> array.
*/
public static final byte[] EMPTY_BYTE_ARRAY = new byte[0];
/** An empty immutable Byte array */
/**
* An empty immutable <code>Byte</code> array.
*/
public static final Byte[] EMPTY_BYTE_OBJECT_ARRAY = new Byte[0];
/** An empty immutable double array */
/**
* An empty immutable <code>double</code> array.
*/
public static final double[] EMPTY_DOUBLE_ARRAY = new double[0];
/** An empty immutable Double array */
/**
* An empty immutable <code>Double</code> array.
*/
public static final Double[] EMPTY_DOUBLE_OBJECT_ARRAY = new Double[0];
/** An empty immutable float array */
/**
* An empty immutable <code>float</code> array.
*/
public static final float[] EMPTY_FLOAT_ARRAY = new float[0];
/** An empty immutable Float array */
/**
* An empty immutable <code>Float</code> array.
*/
public static final Float[] EMPTY_FLOAT_OBJECT_ARRAY = new Float[0];
/** An empty immutable boolean array */
/**
* An empty immutable <code>boolean</code> array.
*/
public static final boolean[] EMPTY_BOOLEAN_ARRAY = new boolean[0];
/** An empty immutable Boolean array */
/**
* An empty immutable <code>Boolean</code> array.
*/
public static final Boolean[] EMPTY_BOOLEAN_OBJECT_ARRAY = new Boolean[0];
/** An empty immutable char array */
/**
* An empty immutable <code>char</code> array.
*/
public static final char[] EMPTY_CHAR_ARRAY = new char[0];
/** An empty immutable Character array */
/**
* An empty immutable <code>Character</code> array.
*/
public static final Character[] EMPTY_CHARACTER_OBJECT_ARRAY = new Character[0];
/**
@ -131,7 +169,7 @@ public ArrayUtils() {
* <p>Multi-dimensional arrays are handled correctly, including
* multi-dimensional primitive arrays.</p>
*
* <p>The format is that of Java source code, for example {a,b}.</p>
* <p>The format is that of Java source code, for example <code>{a,b}</code>.</p>
*
* @param array the array to get a toString for, may be <code>null</code>
* @return a String representation of the array, '{}' if <code>null</code> passed in
@ -146,7 +184,7 @@ public static String toString(final Object array) {
* <p>Multi-dimensional arrays are handled correctly, including
* multi-dimensional primitive arrays.</p>
*
* <p>The format is that of Java source code, for example {a,b}.</p>
* <p>The format is that of Java source code, for example <code>{a,b}</code>.</p>
*
* @param array the array to get a toString for, may be <code>null</code>
* @param stringIfNull the String to return if the array is <code>null</code>
@ -801,7 +839,7 @@ public static void reverse(final boolean[] array) {
*
* @param array the array to search through for the object, may be <code>null</code>
* @param objectToFind the object to find, may be <code>null</code>
* @return the index of the object within the array, or -1 if not found
* @return the index of the object within the array, or <code>-1</code> if not found
*/
public static int indexOf(final Object[] array, final Object objectToFind) {
return indexOf(array, objectToFind, 0);
@ -813,13 +851,13 @@ public static int indexOf(final Object[] array, final Object objectToFind) {
* <p>This method returns <code>-1</code> if <code>null</code> array input.</p>
*
* <p>A negative startIndex is treated as zero. A startIndex larger than the array
* length will return -1.</p>
* length will return <code>-1</code>.</p>
*
* @param array the array to search through for the object, may be <code>null</code>
* @param objectToFind the object to find, may be <code>null</code>
* @param startIndex the index to start searching at
* @return the index of the object within the array starting at the
* given index, or -1 if not found
* given index, or <code>-1</code> if not found
*/
public static int indexOf(final Object[] array, final Object objectToFind, int startIndex) {
if (array == null) {
@ -851,7 +889,7 @@ public static int indexOf(final Object[] array, final Object objectToFind, int s
*
* @param array the array to travers backwords looking for the object, may be <code>null</code>
* @param objectToFind the object to find, may be <code>null</code>
* @return the last index of the object to find, or -1 if not found
* @return the last index of the object to find, or <code>-1</code> if not found
*/
public static int lastIndexOf(final Object[] array, final Object objectToFind) {
return lastIndexOf(array, objectToFind, Integer.MAX_VALUE);
@ -862,14 +900,14 @@ public static int lastIndexOf(final Object[] array, final Object objectToFind) {
*
* <p>This method returns <code>-1</code> if <code>null</code> array input.</p>
*
* <p>A negative startIndex will return -1. A startIndex larger than the array
* length will search from the end of the array.</p>
* <p>A negative startIndex will return <code>-1</code>. A startIndex larger than
* the array length will search from the end of the array.</p>
*
* @param array the array to traverse for looking for the object, may be <code>null</code>
* @param objectToFind the object to find, may be <code>null</code>
* @param startIndex the start index to travers backwards from
* @return the last index of the object within the array starting at the given index,
* or -1 if not found
* or <code>-1</code> if not found
*/
public static int lastIndexOf(final Object[] array, final Object objectToFind, int startIndex) {
if (array == null) {
@ -1644,7 +1682,7 @@ public static boolean[] toPrimitive(final Boolean[] array) {
}
/**
* <p>Converts an array of object Booleans to primitives handling null.</p>
* <p>Converts an array of object Booleans to primitives handling <code>null</code>.</p>
*
* <p>This method returns <code>null</code> if <code>null</code> array input.</p>
*
@ -1712,7 +1750,7 @@ public static byte[] toPrimitive(final Byte[] array) {
}
/**
* <p>Converts an array of object Bytes to primitives handling null.</p>
* <p>Converts an array of object Bytes to primitives handling <code>null</code>.</p>
*
* <p>This method returns <code>null</code> if <code>null</code> array input.</p>
*
@ -1780,7 +1818,7 @@ public static short[] toPrimitive(final Short[] array) {
}
/**
* <p>Converts an array of object Short to primitives handling null.</p>
* <p>Converts an array of object Short to primitives handling <code>null</code>.</p>
*
* <p>This method returns <code>null</code> if <code>null</code> array input.</p>
*
@ -1848,7 +1886,7 @@ public static int[] toPrimitive(final Integer[] array) {
}
/**
* <p>Converts an array of object Integer to primitives handling null.</p>
* <p>Converts an array of object Integer to primitives handling <code>null</code>.</p>
*
* <p>This method returns <code>null</code> if <code>null</code> array input.</p>
*
@ -1916,7 +1954,7 @@ public static long[] toPrimitive(final Long[] array) {
}
/**
* <p>Converts an array of object Long to primitives handling null.</p>
* <p>Converts an array of object Long to primitives handling <code>null</code>.</p>
*
* <p>This method returns <code>null</code> if <code>null</code> array input.</p>
*
@ -1984,7 +2022,7 @@ public static float[] toPrimitive(final Float[] array) {
}
/**
* <p>Converts an array of object Floats to primitives handling null.</p>
* <p>Converts an array of object Floats to primitives handling <code>null</code>.</p>
*
* <p>This method returns <code>null</code> if <code>null</code> array input.</p>
*
@ -2052,7 +2090,7 @@ public static double[] toPrimitive(final Double[] array) {
}
/**
* <p>Converts an array of object Doubles to primitives handling null.</p>
* <p>Converts an array of object Doubles to primitives handling <code>null</code>.</p>
*
* <p>This method returns <code>null</code> if <code>null</code> array input.</p>
*

199
src/java/org/apache/commons/lang/BooleanUtils.java
View File

@ -62,7 +62,7 @@
* @author Stephen Colebourne
* @author Matthew Hawthorne
* @since 2.0
* @version $Id: BooleanUtils.java,v 1.6 2003/06/28 18:16:03 scolebourne Exp $
* @version $Id: BooleanUtils.java,v 1.7 2003/07/14 22:25:02 bayard Exp $
*/
public class BooleanUtils {
@ -108,10 +108,11 @@ public static Boolean toBooleanObject(boolean bool) {
}
/**
* <p>Converts a Boolean to a boolean handling null by returning false.</p>
* <p>Converts a Boolean to a boolean handling <code>null</code>
* by returning <code>false</code>.</p>
*
* @param bool the boolean to convert
* @return true or false
* @return <code>true</code> or <code>false</code>
*/
public static boolean toBoolean(Boolean bool) {
if (bool == null) {
@ -121,11 +122,11 @@ public static boolean toBoolean(Boolean bool) {
}
/**
* <p>Converts a Boolean to a boolean handling null.</p>
* <p>Converts a Boolean to a boolean handling <code>null</code>.</p>
*
* @param bool the boolean to convert
* @param valueIfNull the boolean value to return if null
* @return true or false
* @param valueIfNull the boolean value to return if <code>null</code>
* @return <code>true</code> or <code>false</code>
*/
public static boolean toBooleanDefaultIfNull(Boolean bool, boolean valueIfNull) {
if (bool == null) {
@ -137,32 +138,38 @@ public static boolean toBooleanDefaultIfNull(Boolean bool, boolean valueIfNull)
// Integer to Boolean methods
//--------------------------------------------------------------------------
/**
* <p>Convert an int to a boolean using the convention that zero is false.</p>
* <p>Convert an int to a boolean using the convention that <code>zero</code>
* is <code>false</code>.</p>
*
* @param value the int to convert
* @return true if non-zero, false if zero
* @return <code>true</code> if non-zero, <code>false</code>
* if zero
*/
public static boolean toBoolean(int value) {
return (value == 0 ? false : true);
}
/**
* <p>Convert an int to a Boolean using the convention that zero is false.</p>
* <p>Convert an int to a Boolean using the convention that <code>zero</code>
* is <code>false</code>.</p>
*
* @param value the int to convert
* @return Boolean.TRUE if non-zero, Boolean.FALSE if zero, null if null
* @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
* <code>null</code> if <code>null</code>
*/
public static Boolean toBooleanObject(int value) {
return (value == 0 ? Boolean.FALSE : Boolean.TRUE);
}
/**
* <p>Convert an Integer to a Boolean using the convention that zero is false.</p>
* <p>Convert an Integer to a Boolean using the convention that <code>zero</code>
* is <code>false</code>.</p>
*
* <p>null will be converted to null.</p>
* <p><code>null</code> will be converted to <code>null</code>.</p>
*
* @param value the Integer to convert
* @return Boolean.TRUE if non-zero, Boolean.FALSE if zero, null if null
* @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
* <code>null</code> if <code>null</code>
*/
public static Boolean toBooleanObject(Integer value) {
if (value == null) {
@ -175,9 +182,9 @@ public static Boolean toBooleanObject(Integer value) {
* <p>Convert an int to a boolean specifying the conversion values.</p>
*
* @param value the Integer to convert
* @param trueValue the value to match for true
* @param falseValue the value to match for false
* @return true or false
* @param trueValue the value to match for <code>true</code>
* @param falseValue the value to match for <code>false</code>
* @return <code>true</code> or <code>false</code>
* @throws IllegalArgumentException if no match
*/
public static boolean toBoolean(int value, int trueValue, int falseValue) {
@ -194,9 +201,11 @@ public static boolean toBoolean(int value, int trueValue, int falseValue) {
* <p>Convert an Integer to a boolean specifying the conversion values.</p>
*
* @param value the Integer to convert
* @param trueValue the value to match for true, may be null
* @param falseValue the value to match for false, may be null
* @return true or false
* @param trueValue the value to match for <code>true</code>,
* may be <code>null</code>
* @param falseValue the value to match for <code>false</code>,
* may be <code>null</code>
* @return <code>true</code> or <code>false</code>
* @throws IllegalArgumentException if no match
*/
public static boolean toBoolean(Integer value, Integer trueValue, Integer falseValue) {
@ -219,10 +228,10 @@ public static boolean toBoolean(Integer value, Integer trueValue, Integer falseV
* <p>Convert an int to a Boolean specifying the conversion values.</p>
*
* @param value the Integer to convert
* @param trueValue the value to match for true
* @param falseValue the value to match for false
* @param nullValue the value to to match for null
* @return Boolean.TRUE, Boolean.FALSE, or null
* @param trueValue the value to match for <code>true</code>
* @param falseValue the value to match for <code>false</code>
* @param nullValue the value to to match for <code>null</code>
* @return Boolean.TRUE, Boolean.FALSE, or <code>null</code>
* @throws IllegalArgumentException if no match
*/
public static Boolean toBooleanObject(int value, int trueValue, int falseValue, int nullValue) {
@ -241,10 +250,13 @@ public static Boolean toBooleanObject(int value, int trueValue, int falseValue,
* <p>Convert an Integer to a Boolean specifying the conversion values.</p>
*
* @param value the Integer to convert
* @param trueValue the value to match for true, may be null
* @param falseValue the value to match for false, may be null
* @param nullValue the value to to match for null, may be null
* @return Boolean.TRUE, Boolean.FALSE, or null
* @param trueValue the value to match for <code>true</code>,
* may be <code>null</code>
* @param falseValue the value to match for <code>false</code>,
* may be <code>null</code>
* @param nullValue the value to to match for <code>null</code>,
* may be <code>null</code>
* @return Boolean.TRUE, Boolean.FALSE, or <code>null</code>
* @throws IllegalArgumentException if no match
*/
public static Boolean toBooleanObject(Integer value, Integer trueValue, Integer falseValue, Integer nullValue) {
@ -270,32 +282,35 @@ public static Boolean toBooleanObject(Integer value, Integer trueValue, Integer
// Boolean to Integer methods
//--------------------------------------------------------------------------
/**
* <p>Convert a boolean to an int using the convention that zero is false.</p>
* <p>Convert a boolean to an int using the convention that
* <code>zero</code> is <code>false</code>.</p>
*
* @param bool the boolean to convert
* @return one if true, zero if false
* @return one if <code>true</code>, zero if <code>false</code>
*/
public static int toInteger(boolean bool) {
return (bool ? 1 : 0);
}
/**
* <p>Convert a boolean to an Integer using the convention that zero is false.</p>
* <p>Convert a boolean to an Integer using the convention that
* <code>zero</code> is <code>false</code>.</p>
*
* @param bool the boolean to convert
* @return one if true, zero if false
* @return one if <code>true</code>, zero if <code>false</code>
*/
public static Integer toIntegerObject(boolean bool) {
return (bool ? NumberUtils.INTEGER_ONE : NumberUtils.INTEGER_ZERO);
}
/**
* <p>Convert a Boolean to a Integer using the convention that zero is false.</p>
* <p>Convert a Boolean to a Integer using the convention that
* <code>zero</code> is <code>false</code>.</p>
*
* <p>null will be converted to null.</p>
* <p><code>null</code> will be converted to <code>null</code>.</p>
*
* @param bool the Boolean to convert
* @return one if Boolean.TRUE, zero if Boolean.FALSE, null if null
* @return one if Boolean.TRUE, zero if Boolean.FALSE, <code>null</code> if <code>null</code>
*/
public static Integer toIntegerObject(Boolean bool) {
if (bool == null) {
@ -308,8 +323,8 @@ public static Integer toIntegerObject(Boolean bool) {
* <p>Convert a boolean to an int specifying the conversion values.</p>
*
* @param bool the to convert
* @param trueValue the value to return if true
* @param falseValue the value to return if false
* @param trueValue the value to return if <code>true</code>
* @param falseValue the value to return if <code>false</code>
* @return the appropriate value
*/
public static int toInteger(boolean bool, int trueValue, int falseValue) {
@ -320,9 +335,9 @@ public static int toInteger(boolean bool, int trueValue, int falseValue) {
* <p>Convert a Boolean to an int specifying the conversion values.</p>
*
* @param bool the Boolean to convert
* @param trueValue the value to return if true
* @param falseValue the value to return if false
* @param nullValue the value to return if null
* @param trueValue the value to return if <code>true</code>
* @param falseValue the value to return if <code>false</code>
* @param nullValue the value to return if <code>null</code>
* @return the appropriate value
*/
public static int toInteger(Boolean bool, int trueValue, int falseValue, int nullValue) {
@ -336,8 +351,10 @@ public static int toInteger(Boolean bool, int trueValue, int falseValue, int nul
* <p>Convert a boolean to an Integer specifying the conversion values.</p>
*
* @param bool the to convert
* @param trueValue the value to return if true, may be null
* @param falseValue the value to return if false, may be null
* @param trueValue the value to return if <code>true</code>,
* may be <code>null</code>
* @param falseValue the value to return if <code>false</code>,
* may be <code>null</code>
* @return the appropriate value
*/
public static Integer toIntegerObject(boolean bool, Integer trueValue, Integer falseValue) {
@ -348,9 +365,12 @@ public static Integer toIntegerObject(boolean bool, Integer trueValue, Integer f
* <p>Convert a Boolean to an Integer specifying the conversion values.</p>
*
* @param bool the Boolean to convert
* @param trueValue the value to return if true, may be null
* @param falseValue the value to return if false, may be null
* @param nullValue the value to return if null, may be null
* @param trueValue the value to return if <code>true</code>,
* may be <code>null</code>
* @param falseValue the value to return if <code>false</code>,
* may be <code>null</code>
* @param nullValue the value to return if <code>null</code>,
* may be <code>null</code>
* @return the appropriate value
*/
public static Integer toIntegerObject(Boolean bool, Integer trueValue, Integer falseValue, Integer nullValue) {
@ -365,12 +385,15 @@ public static Integer toIntegerObject(Boolean bool, Integer trueValue, Integer f
/**
* <p>Converts a String to a Boolean.</p>
*
* <p>'true', 'on' or 'yes' (case insensitive) will return true.
* 'false', 'off' or 'no' (case insensitive) will return false.
* Otherwise, null is returned.</p>
* <p><code>'true'</code>, <code>'on'</code> or <code>'yes'</code>
* (case insensitive) will return <code>true</code>.
* <code>'false'</code>, <code>'off'</code> or <code>'no'</code>
* (case insensitive) will return <code>false</code>.
* Otherwise, <code>null</code> is returned.</p>
*
* @param str the String to check
* @return the Boolean value of the string, null if no match or null input
* @return the Boolean value of the string, <code>null</code>
* if no match or <code>null</code> input
*/
public static Boolean toBooleanObject(String str) {
if ("true".equalsIgnoreCase(str)) {
@ -394,10 +417,14 @@ public static Boolean toBooleanObject(String str) {
* <p>Converts a String to a Boolean throwing an exception if no match.</p>
*
* @param str the String to check
* @param trueString the String to match for true (case sensitive), may be null
* @param falseString the String to match for false (case sensitive), may be null
* @param nullString the String to match for null (case sensitive), may be null
* @return the Boolean value of the string, null if no match or null input
* @param trueString the String to match for <code>true</code>
* (case sensitive), may be <code>null</code>
* @param falseString the String to match for <code>false</code>
* (case sensitive), may be <code>null</code>
* @param nullString the String to match for <code>null</code>
* (case sensitive), may be <code>null</code>
* @return the Boolean value of the string, <code>null</code>
* if no match or <code>null</code> input
*/
public static Boolean toBooleanObject(String str, String trueString, String falseString, String nullString) {
if (str == null) {
@ -424,11 +451,12 @@ public static Boolean toBooleanObject(String str, String trueString, String fals
/**
* <p>Converts a String to a boolean.</p>
*
* <p>'true', 'on' or 'yes' (case insensitive) will return true.
* Otherwise, false is returned.</p>
* <p><code>'true'</code>, <code>'on'</code> or <code>'yes'</code>
* (case insensitive) will return <code>true</code>. Otherwise,
* <code>false</code> is returned.</p>
*
* @param str the String to check
* @return the boolean value of the string, false if no match
* @return the boolean value of the string, <code>false</code> if no match
*/
public static boolean toBoolean(String str) {
if ("true".equalsIgnoreCase(str)) {
@ -448,8 +476,10 @@ public static boolean toBoolean(String str) {
* <p>null is returned if there is no match.</p>
*
* @param str the String to check
* @param trueString the String to match for true (case sensitive), may be null
* @param falseString the String to match for false (case sensitive), may be null
* @param trueString the String to match for <code>true</code>
* (case sensitive), may be <code>null</code>
* @param falseString the String to match for <code>false</code>
* (case sensitive), may be <code>null</code>
* @return the boolean value of the string
* @throws IllegalArgumentException if the String doesn't match
*/
@ -472,30 +502,36 @@ public static boolean toBoolean(String str, String trueString, String falseStrin
// Boolean to String methods
//--------------------------------------------------------------------------
/**
* <p>Converts a Boolean to a String returning 'true', 'false', or <code>null</code>.</p>
* <p>Converts a Boolean to a String returning <code>'true'</code>,
* <code>'false'</code>, or <code>null</code>.</p>
*
* @param bool the Boolean to check
* @return 'true', 'false', or <code>null</code>
* @return <code>'true'</code>, <code>'false'</code>,
* or <code>null</code>
*/
public static String toStringTrueFalse(Boolean bool) {
return toString(bool, "true", "false", null);
}
/**
* <p>Converts a Boolean to a String returning 'on', 'off', or <code>null</code>.</p>
* <p>Converts a Boolean to a String returning <code>'on'</code>,
* <code>'off'</code>, or <code>null</code>.</p>
*
* @param bool the Boolean to check
* @return 'on', 'off', or <code>null</code>
* @return <code>'on'</code>, <code>'off'</code>,
* or <code>null</code>
*/
public static String toStringOnOff(Boolean bool) {
return toString(bool, "on", "off", null);
}
/**
* <p>Converts a Boolean to a String returning 'yes', 'no', or <code>null</code>.</p>
* <p>Converts a Boolean to a String returning <code>'yes'</code>,
* <code>'no'</code>, or <code>null</code>.</p>
*
* @param bool the Boolean to check
* @return 'yes', 'no', or <code>null</code>
* @return <code>'yes'</code>, <code>'no'</code>,
* or <code>null</code>
*/
public static String toStringYesNo(Boolean bool) {
return toString(bool, "yes", "no", null);
@ -505,9 +541,12 @@ public static String toStringYesNo(Boolean bool) {
* <p>Converts a Boolean to a String returning one of the input Strings.</p>
*
* @param bool the Boolean to check
* @param trueString the String to return if true, may be null
* @param falseString the String to return if false, may be null
* @param nullString the String to return if null, may be null
* @param trueString the String to return if <code>true</code>,
* may be <code>null</code>
* @param falseString the String to return if <code>false</code>,
* may be <code>null</code>
* @param nullString the String to return if <code>null</code>,
* may be <code>null</code>
* @return one of the three input Strings
*/
public static String toString(Boolean bool, String trueString, String falseString, String nullString) {
@ -520,30 +559,36 @@ public static String toString(Boolean bool, String trueString, String falseStrin
// boolean to String methods
//--------------------------------------------------------------------------
/**
* <p>Converts a boolean to a String returning 'true' or 'false'.</p>
* <p>Converts a boolean to a String returning <code>'true'</code>
* or <code>'false'</code>.</p>
*
* @param bool the Boolean to check
* @return 'true', 'false', or <code>null</code>
* @return <code>'true'</code>, <code>'false'</code>,
* or <code>null</code>
*/
public static String toStringTrueFalse(boolean bool) {
return toString(bool, "true", "false");
}
/**
* <p>Converts a boolean to a String returning 'on' or 'off'.</p>
* <p>Converts a boolean to a String returning <code>'on'</code>
* or <code>'off'</code>.</p>
*
* @param bool the Boolean to check
* @return 'on', 'off', or <code>null</code>
* @return <code>'on'</code>, <code>'off'</code>,
* or <code>null</code>
*/
public static String toStringOnOff(boolean bool) {
return toString(bool, "on", "off");
}
/**
* <p>Converts a boolean to a String returning 'yes' or 'no'.</p>
* <p>Converts a boolean to a String returning <code>'yes'</code>
* or <code>'no'</code>.</p>
*
* @param bool the Boolean to check
* @return 'yes', 'no', or <code>null</code>
* @return <code>'yes'</code>, <code>'no'</code>,
* or <code>null</code>
*/
public static String toStringYesNo(boolean bool) {
return toString(bool, "yes", "no");
@ -553,8 +598,10 @@ public static String toStringYesNo(boolean bool) {
* <p>Converts a boolean to a String returning one of the input Strings.</p>
*
* @param bool the Boolean to check
* @param trueString the String to return if true, may be null
* @param falseString the String to return if false, may be null
* @param trueString the String to return if <code>true</code>,
* may be <code>null</code>
* @param falseString the String to return if <code>false</code>,
* may be <code>null</code>
* @return one of the two input Strings
*/
public static String toString(boolean bool, String trueString, String falseString) {
@ -564,7 +611,7 @@ public static String toString(boolean bool, String trueString, String falseStrin
// xor methods
// --------------------------------------------------------------------------
/**
* Performs an xor on a set of booleans.
* <p>Performs an xor on a set of booleans.</p>
*
* @param array an array of <code>boolean<code>s
* @return <code>true</code> if the xor is successful.
@ -598,7 +645,7 @@ public static boolean xor(boolean[] array) {
}
/**
* Performs an xor on an array of Booleans.
* <p>Performs an xor on an array of Booleans.</p>
*
* @param array an array of <code>Boolean<code>s
* @return <code>true</code> if the xor is successful.

4
src/java/org/apache/commons/lang/CharRange.java
View File

@ -62,12 +62,12 @@
* @author <a href="bayard@generationjava.com">Henri Yandell</a>
* @author Stephen Colebourne
* @since 1.0
* @version $Id: CharRange.java,v 1.5 2003/03/23 17:59:09 scolebourne Exp $
* @version $Id: CharRange.java,v 1.6 2003/07/14 22:25:02 bayard Exp $
*/
class CharRange {
/**
* Used internally to represent null in a char.
* <p>Used internally to represent <code>null</code> in a char.</p>
*/
private static char UNSET;

33
src/java/org/apache/commons/lang/CharSetUtils.java
View File

@ -59,7 +59,7 @@
* @author <a href="bayard@generationjava.com">Henri Yandell</a>
* @author Stephen Colebourne
* @since 1.0
* @version $Id: CharSetUtils.java,v 1.11 2003/04/09 00:07:50 ggregory Exp $
* @version $Id: CharSetUtils.java,v 1.12 2003/07/14 22:25:02 bayard Exp $
*/
public class CharSetUtils {
@ -78,10 +78,10 @@ public CharSetUtils() {
* set logic to be performed.</p>
* <p>The syntax is:</p>
* <ul>
* <li>"aeio" which implies 'a','e',..
* <li>"^e" implies not e. However it only negates, it's not
* a set in itself due to the size of that set in unicode.
* <li>"ej-m" implies e,j->m. e,j,k,l,m.
* <li>&quot;aeio&quot; which implies 'a','e',..</li>
* <li>&quot;^e&quot; implies not e. However it only negates, it's not
* a set in itself due to the size of that set in unicode.</li>
* <li>&quot;ej-m&quot; implies e,j->m. e,j,k,l,m.</li>
* </ul>
*
* @param set
@ -98,7 +98,7 @@ public static CharSet evaluateSet(String[] set) {
*
* <p>An example is:</p>
* <ul>
* <li>squeeze("hello", "el") => "helo"
* <li>squeeze(&quot;hello&quot;, &quot;el&quot;) => &quot;helo&quot;</li>
* </ul>
* @see #evaluateSet(java.lang.String[]) for set-syntax.
*
@ -117,7 +117,7 @@ public static String squeeze(String str, String set) {
*
* <p>An example is:</p>
* <ul>
* <li>squeeze("hello", {"el"}) => "helo"
* <li>squeeze(&quot;hello&quot;, {&quot;el&quot;}) => &quot;helo&quot;</li>
* </ul>
* @see #evaluateSet(java.lang.String[]) for set-syntax.
*
@ -152,7 +152,7 @@ public static String squeeze(String str, String[] set) {
*
* <p>An example would be:</p>
* <ul>
* <li>count("hello", {"c-f","o"}) returns 2.
* <li>count(&quot;hello&quot;, {&quot;c-f&quot;, &quot;o&quot;}) returns 2.</li>
* </ul>
*
* @param str String target to count characters in
@ -168,9 +168,9 @@ public static int count(String str, String set) {
* <p>Takes an argument in set-syntax, see evaluateSet,
* and returns the number of characters present in the specified string.</p>
*
* An example would be:</p>
* <p>An example would be:</p>
* <ul>
* <li>count("hello", {"c-f","o"}) returns 2.
* <li>count(&quot;hello&quot;, {&quot;c-f&quot;, &quot;o&quot;}) returns 2.</li>
* </ul>
*
* @param str String target to count characters in
@ -195,7 +195,7 @@ public static int count(String str, String[] set) {
*
* <p>An example would be:</p>
* <ul>
* <li>keep("hello", {"c-fo"}) returns "hll"
* <li>keep(&quot;hello&quot;, {&quot;c-fo&quot;}) returns &quot;hll&quot;</li>
* </ul>
*
* @param str String target to keep characters from
@ -213,7 +213,8 @@ public static String keep(String str, String set) {
*
* <p>An example would be:</p>
* <ul>
* <li>keep("hello", {"c-f","o"}) returns "hll"
* <li>keep(&quot;hello&quot;, {&quot;c-f&quot;, &quot;o&quot;})
* returns &quot;hll&quot;</li>
* </ul>
*
* @param str String target to keep characters from
@ -231,7 +232,7 @@ public static String keep(String str, String[] set) {
*
* <p>An example would be:</p>
* <ul>
* <li>delete("hello", {"c-fo"}) returns "hll"
* <li>delete(&quot;hello&quot;, {&quot;c-fo&quot;}) returns &quot;hll&quot;</li>
* </ul>
*
* @param str String target to delete characters from
@ -249,7 +250,8 @@ public static String delete(String str, String set) {
*
* <p>An example would be:</p>
* <ul>
* <li>delete("hello", {"c-f","o"}) returns "hll"
* <li>delete(&quot;hello&quot;, {&quot;c-f&quot;, &quot;o&quot;}) returns
* &quot;hll&quot;</li>
* </ul>
*
* @param str String target to delete characters from
@ -280,7 +282,8 @@ private static String modify(String str, String[] set, boolean expect) {
*
* <p>An example is:</p>
* <ul>
* <li>translate("hello", "ho", "jy") => jelly
* <li>translate(&quot;hello&quot;, &quot;ho&quot;, &quot;jy&quot;)
* => jelly</li>
* </ul>
*
* <p>If the length of characters to search for is greater than the

19
src/java/org/apache/commons/lang/ClassUtils.java
View File

@ -62,27 +62,27 @@
* @author Stephen Colebourne
* @author <a href="mailto:ggregory@seagullsw.com">Gary Gregory</a>
* @since 2.0
* @version $Id: ClassUtils.java,v 1.12 2003/05/29 21:02:53 ggregory Exp $
* @version $Id: ClassUtils.java,v 1.13 2003/07/14 22:25:02 bayard Exp $
*/
public class ClassUtils {
/**
* The package separator character: <code>&#x2e;</code>
* <p>The package separator character: <code>&#x2e;</code>.</p>
*/
public static final char PACKAGE_SEPARATOR_CHAR = '.';
/**
* The package separator String: <code>&#x2e;</code>
* <p>The package separator String: <code>&#x2e;</code>.</p>
*/
public static final String PACKAGE_SEPARATOR = String.valueOf(PACKAGE_SEPARATOR_CHAR);
/**
* The inner class separator character: <code>$</code>
* <p>The inner class separator character: <code>$</code>.</p>
*/
public static final char INNER_CLASS_SEPARATOR_CHAR = '$';
/**
* The inner class separator String: <code>$</code>
* <p>The inner class separator String: <code>$</code>.</p>
*/
public static final String INNER_CLASS_SEPARATOR = String.valueOf(INNER_CLASS_SEPARATOR_CHAR);
@ -319,9 +319,9 @@ public static List getAllInterfaces(Class cls) {
// -------------------------------------------------------------------------
/**
* <p>Given a <code>List</code> of class names, this method converts them into classes.
* <p>Given a <code>List</code> of class names, this method converts them into classes.</p>
*
* A new <code>List</code> is returned. If the class name cannot be found, <code>null</code>
* <p>A new <code>List</code> is returned. If the class name cannot be found, <code>null</code>
* is stored in the <code>List</code>. If the class name in the <code>List</code> is
* <code>null</code>, <code>null</code> is stored in the output <code>List</code>.</p>
*
@ -348,8 +348,9 @@ public static List convertClassNamesToClasses(List classNames) {
/**
* <p>Given a <code>List</code> of <code>Class</code> objects, this method converts
* them into class names.
* A new <code>List</code> is returned. <code>null</code> objects will be copied into
* them into class names.</p>
*
* <p>A new <code>List</code> is returned. <code>null</code> objects will be copied into
* the returned list as <code>null</code>.</p>
*
* @param classes the classes to change

11
src/java/org/apache/commons/lang/IllegalClassException.java
View File

@ -54,17 +54,17 @@
package org.apache.commons.lang;
/**
* Thrown when an object is an instance of an unexpected type (a class or interface).
* <p>Thrown when an object is an instance of an unexpected type (a class or interface).</p>
*
* @author Matthew Hawthorne
* @author Gary Gregory
* @since 2.0
* @version $Id: IllegalClassException.java,v 1.3 2003/06/03 20:49:59 ggregory Exp $
* @version $Id: IllegalClassException.java,v 1.4 2003/07/14 22:25:02 bayard Exp $
*/
public class IllegalClassException extends IllegalArgumentException {
/**
* Instantiates with the specified types (classes or interfaces).
* <p>Instantiates with the specified types (classes or interfaces).</p>
*
* @param expected the expected type
* @param actual the actual type
@ -78,7 +78,7 @@ public IllegalClassException(Class expected, Class actual) {
}
/**
* Instantiates with the specified message.
* <p>Instantiates with the specified message.</p>
*
* @param message the exception message
*/
@ -87,7 +87,8 @@ public IllegalClassException(String message) {
}
/**
* Returns the class name or <code>null</code> if the class is <code>null</code>.
* <p>Returns the class name or <code>null</code> if the class is
* <code>null</code>.</p>
*
* @param cls a <code>Class</code>
* @return the name of <code>cls</code>, or <code>null</code> if if <code>cls</code> is <code>null</code>.

10
src/java/org/apache/commons/lang/IncompleteArgumentException.java
View File

@ -56,16 +56,16 @@
import java.util.Arrays;
/**
* Thrown to indicate an incomplete argument to a method.
* <p>Thrown to indicate an incomplete argument to a method.</p>
*
* @author Matthew Hawthorne
* @since 2.0
* @version $Id: IncompleteArgumentException.java,v 1.2 2003/05/16 16:14:17 scolebourne Exp $
* @version $Id: IncompleteArgumentException.java,v 1.3 2003/07/14 22:25:02 bayard Exp $
*/
public class IncompleteArgumentException extends IllegalArgumentException {
/**
* Instantiates with the specified description.
* <p>Instantiates with the specified description.</p>
*
* @param argName a description of the incomplete argument
*/
@ -74,7 +74,7 @@ public IncompleteArgumentException(String argName) {
}
/**
* Instantiates with the specified description.
* <p>Instantiates with the specified description.</p>
*
* @param argName a description of the incomplete argument
* @param items an array describing the arguments missing
@ -87,7 +87,7 @@ public IncompleteArgumentException(String argName, String[] items) {
}
/**
* Converts an array to a string without throwing an exception.
* <p>7Converts an array to a string without throwing an exception.</p>
*
* @param array an array
* @return the array as a string

77
src/java/org/apache/commons/lang/IntHashMap.java
View File

@ -58,14 +58,15 @@
package org.apache.commons.lang;
/**
* A hash map that uses primitive ints for the key rather than objects.
* Note that this class is for internal optimization purposes only, and may
* <p>A hash map that uses primitive ints for the key rather than objects.</p>
*
* <p>Note that this class is for internal optimization purposes only, and may
* not be supported in future releases of Jakarta Commons Lang. Utilities of
* this sort may be included in future releases of Jakarta Commons Collections.
* this sort may be included in future releases of Jakarta Commons Collections.</p>
*
* @author Justin Couch
* @author Alex Chaffee (alex@apache.org)
* @version $Revision: 1.1 $
* @version $Revision: 1.2 $
* @see java.util.HashMap
*/
public class IntHashMap
@ -96,8 +97,8 @@ public class IntHashMap
private float loadFactor;
/**
* Innerclass that acts as a datastructure to create a new entry in the
* table.
* <p>Innerclass that acts as a datastructure to create a new entry in the
* table.</p>
*/
private static class Entry
{
@ -107,7 +108,7 @@ private static class Entry
Entry next;
/**
* Create a new entry with the given values.
* <p>Create a new entry with the given values.</p>
*
* @param hash The code used to hash the object with
* @param key The key used to enter this in the table
@ -124,8 +125,8 @@ protected Entry(int hash, int key, Object value, Entry next)
}
/**
* Constructs a new, empty hashtable with a default capacity and load
* factor, which is <tt>20</tt> and <tt>0.75</tt> respectively.
* <p>Constructs a new, empty hashtable with a default capacity and load
* factor, which is <code>20</code> and <code>0.75</code> respectively.</p>
*/
public IntHashMap()
{
@ -133,8 +134,8 @@ public IntHashMap()
}
/**
* Constructs a new, empty hashtable with the specified initial capacity
* and default load factor, which is <tt>0.75</tt>.
* <p>Constructs a new, empty hashtable with the specified initial capacity
* and default load factor, which is <code>0.75</code>.</p>
*
* @param initialCapacity the initial capacity of the hashtable.
* @throws IllegalArgumentException if the initial capacity is less
@ -146,8 +147,8 @@ public IntHashMap(int initialCapacity)
}
/**
* Constructs a new, empty hashtable with the specified initial
* capacity and the specified load factor.
* <p>Constructs a new, empty hashtable with the specified initial
* capacity and the specified load factor.</p>
*
* @param initialCapacity the initial capacity of the hashtable.
* @param loadFactor the load factor of the hashtable.
@ -171,7 +172,7 @@ public IntHashMap(int initialCapacity, float loadFactor)
}
/**
* Returns the number of keys in this hashtable.
* <p>Returns the number of keys in this hashtable.</p>
*
* @return the number of keys in this hashtable.
*/
@ -181,7 +182,7 @@ public int size()
}
/**
* Tests if this hashtable maps no keys to values.
* <p>Tests if this hashtable maps no keys to values.</p>
*
* @return <code>true</code> if this hashtable maps no keys to values;
* <code>false</code> otherwise.
@ -192,12 +193,12 @@ public boolean isEmpty()
}
/**
* Tests if some key maps into the specified value in this hashtable.
* <p>Tests if some key maps into the specified value in this hashtable.
* This operation is more expensive than the <code>containsKey</code>
* method.<p>
* method.</p>
*
* Note that this method is identical in functionality to containsValue,
* (which is part of the Map interface in the collections framework).
* <p>Note that this method is identical in functionality to containsValue,
* (which is part of the Map interface in the collections framework).</p>
*
* @param value a value to search for.
* @return <code>true</code> if and only if some key maps to the
@ -231,10 +232,11 @@ public boolean contains(Object value)
}
/**
* Returns true if this HashMap maps one or more keys to this value.<p>
* <p>Returns <code>true</code> if this HashMap maps one or more keys
* to this value.</p>
*
* Note that this method is identical in functionality to contains
* (which predates the Map interface).
* <p>Note that this method is identical in functionality to contains
* (which predates the Map interface).</p>
*
* @param value value whose presence in this HashMap is to be tested.
* @see java.util.Map
@ -246,7 +248,7 @@ public boolean containsValue(Object value)
}
/**
* Tests if the specified object is a key in this hashtable.
* <p>Tests if the specified object is a key in this hashtable.</p>
*
* @param key possible key.
* @return <code>true</code> if and only if the specified object is a
@ -270,7 +272,7 @@ public boolean containsKey(int key)
}
/**
* Returns the value to which the specified key is mapped in this map.
* <p>Returns the value to which the specified key is mapped in this map.</p>
*
* @param key a key in the hashtable.
* @return the value to which the key is mapped in this hashtable;
@ -294,11 +296,13 @@ public Object get(int key)
}
/**
* Increases the capacity of and internally reorganizes this
* <p>Increases the capacity of and internally reorganizes this
* hashtable, in order to accommodate and access its entries more
* efficiently. This method is called automatically when the
* number of keys in the hashtable exceeds this hashtable's capacity
* and load factor.
* efficiently.</p>
*
* <p>This method is called automatically when the number of keys
* in the hashtable exceeds this hashtable's capacity and load
* factor.</p>
*/
protected void rehash()
{
@ -326,12 +330,12 @@ protected void rehash()
}
/**
* Maps the specified <code>key</code> to the specified
* <p>Maps the specified <code>key</code> to the specified
* <code>value</code> in this hashtable. The key cannot be
* <code>null</code>. <p>
* <code>null</code>. </p>
*
* The value can be retrieved by calling the <code>get</code> method
* with a key that is equal to the original key.
* <p>The value can be retrieved by calling the <code>get</code> method
* with a key that is equal to the original key.</p>
*
* @param key the hashtable key.
* @param value the value.
@ -373,8 +377,11 @@ public Object put(int key, Object value)
}
/**
* Removes the key (and its corresponding value) from this
* hashtable. This method does nothing if the key is not in the hashtable.
* <p>Removes the key (and its corresponding value) from this
* hashtable.</p>
*
* <p>This method does nothing if the key is not present in the
* hashtable.</p>
*
* @param key the key that needs to be removed.
* @return the value to which the key had been mapped in this hashtable,
@ -407,7 +414,7 @@ public Object remove(int key)
}
/**
* Clears this hashtable so that it contains no keys.
* <p>Clears this hashtable so that it contains no keys.</p>
*/
public synchronized void clear()
{

8
src/java/org/apache/commons/lang/NotImplementedException.java
View File

@ -54,16 +54,16 @@
package org.apache.commons.lang;
/**
* Thrown to indicate that a method has not been implemented.
* <p>Thrown to indicate that a method has not been implemented.</p>
*
* @author Matthew Hawthorne
* @since 2.0
* @version $Id: NotImplementedException.java,v 1.2 2003/05/16 16:14:17 scolebourne Exp $
* @version $Id: NotImplementedException.java,v 1.3 2003/07/14 22:25:02 bayard Exp $
*/
public class NotImplementedException extends UnsupportedOperationException {
/**
* Constructes the exception with the specified class.
* <p>Constructes the exception with the specified class.</p>
*
* @param clazz the <code>Class</code> that has not implemented the method
*/
@ -74,7 +74,7 @@ public NotImplementedException(Class clazz) {
}
/**
* Constructs the exception with the specified message.
* <p>Constructs the exception with the specified message.</p>
*
* @param msg the exception message.
*/

11
src/java/org/apache/commons/lang/NullArgumentException.java
View File

@ -54,18 +54,19 @@
package org.apache.commons.lang;
/**
* Thrown to indicate that an argument was null and should not have been.
* <p>Thrown to indicate that an argument was <code>null</code> and should
* not have been.</p>
*
* @author Matthew Hawthorne
* @since 2.0
* @version $Id: NullArgumentException.java,v 1.2 2003/05/16 16:14:17 scolebourne Exp $
* @version $Id: NullArgumentException.java,v 1.3 2003/07/14 22:25:02 bayard Exp $
*/
public class NullArgumentException extends IllegalArgumentException {
/**
* Instantiates with the given argument name.
*
* @param argName the name of the argument that was null.
* <p>Instantiates with the given argument name.</p>
*
* @param argName the name of the argument that was <code>null</code>.
*/
public NullArgumentException(String argName) {
super(argName + " cannot be null.");

15
src/java/org/apache/commons/lang/NumberRange.java
View File

@ -63,7 +63,7 @@
* @author <a href="mailto:chrise@esha.com">Christopher Elkins</a>
* @author Stephen Colebourne
* @since 1.0
* @version $Revision: 1.8 $ $Date: 2003/06/08 14:10:54 $
* @version $Revision: 1.9 $ $Date: 2003/07/14 22:25:03 $
*
* @deprecated Use one of the Range classes in org.apache.commons.lang.math.
* Class will be removed in Commons Lang 3.0.
@ -79,8 +79,9 @@ public final class NumberRange {
/**
* <p>Constructs a new <code>NumberRange</code> using the specified
* number as both the minimum and maximum in this range.</p>
* <p>Constructs a new <code>NumberRange</code> using
* <code>number</code> as both the minimum and maximum in
* this range.</p>
*
* @param num the number to use for this range
* @throws NullPointerException if the number is <code>null</code>
@ -98,8 +99,8 @@ public NumberRange(Number num) {
* <p>Constructs a new <code>NumberRange</code> with the specified
* minimum and maximum numbers.</p>
*
* <p>If the maximum is less than the minimum, the range will be constructed
* from the minimum value to the minimum value, not what you would expect!.</p>
* <p><em>If the maximum is less than the minimum, the range will be constructed
* from the minimum value to the minimum value, not what you would expect!.</em></p>
*
* @param min the minimum number in this range
* @param max the maximum number in this range
@ -190,8 +191,8 @@ public boolean overlaps(NumberRange range) {
}
/**
* <p>Indicates whether some other <code>Object</code> is "equal" to
* this one.</p>
* <p>Indicates whether some other <code>Object</code> is
* &quot;equal&quot; to this one.</p>
*
* @param obj the reference object with which to compare
* @return <code>true</code> if this object is the same as the obj

7
src/java/org/apache/commons/lang/ObjectUtils.java
View File

@ -62,7 +62,7 @@
* @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
* @author Stephen Colebourne
* @since 1.0
* @version $Id: ObjectUtils.java,v 1.8 2003/02/22 20:19:16 scolebourne Exp $
* @version $Id: ObjectUtils.java,v 1.9 2003/07/14 22:25:03 bayard Exp $
*/
public class ObjectUtils {
@ -149,7 +149,8 @@ public static String identityToString(Object object) {
}
/**
* <p>Class used as a null placeholder where null has another meaning.</p>
* <p>Class used as a null placeholder where <code>null</code>
* has another meaning.</p>
*
* <p>For example, in a <code>HashMap</code> the
* {@link java.util.HashMap#get(java.lang.Object)} method returns
@ -166,7 +167,7 @@ public static class Null implements Serializable {
private static final long serialVersionUID = 7092611880189329093L;
/**
* Restricted constructor - singleton
* Restricted constructor - singleton.
*/
Null() {
}

138
src/java/org/apache/commons/lang/builder/CompareToBuilder.java
View File

@ -68,7 +68,7 @@
* {@link HashCodeBuilder}.</p>
*
* <p>Two object that compare equal using equals should normally compare
* equals using compareTo</p>.
* equals using <code>compareTo</code></p>.
*
* <p>All relevant fields should be included in the calculation of the
* comparison. Derived fields may be ignored. The same fields, in the same
@ -76,6 +76,7 @@
* <code>equals</code>.</p>
*
* <p>Typical use for the code is as follows:</p>
*
* <pre>
* public int compareTo(Object o) {
* MyClass rhs = (MyClass) o;
@ -106,7 +107,7 @@
* @author Stephen Colebourne
* @author Gary Gregory
* @since 1.0
* @version $Id: CompareToBuilder.java,v 1.15 2003/06/24 21:14:50 scolebourne Exp $
* @version $Id: CompareToBuilder.java,v 1.16 2003/07/14 22:25:03 bayard Exp $
*/
public class CompareToBuilder {
@ -234,8 +235,8 @@ public static int reflectionCompare(Object lhs, Object rhs, boolean testTransien
}
/**
* Appends the fields and values defined by the given object of the
* given Class.
* <p>Appends the fields and values defined by the given object of the
* given Class.</p>
*
* @param lhs the left hand object
* @param rhs the right hand object
@ -287,14 +288,15 @@ public CompareToBuilder appendSuper(int superHashCode) {
/**
* <p>Comparison of two Object references.</p>
*
* <ol>
* <li>Check if Objects are same using <code>==</code>
* <li>Check if either is null, a null object is less than a non-null
* <li>Check the object contents
* <li>Check if Objects are same using <code>==</code></li>
* <li>Check if either is null, a null object is less than a non-null</li>
* <li>Check the object contents</li>
* </ol>
*
* <p>The first parameter to be compared must either be an array or implement
* Comparable.</p>
* <code>Comparable</code>.</p>
*
* @param lhs the Object from <code>this</code> object
* @param rhs the Object from the other object
@ -309,14 +311,14 @@ public CompareToBuilder append(Object lhs, Object rhs) {
/**
* <p>Comparison of two Object references.</p>
* <ol>
* <li>Check if Objects are same using <code>==</code>
* <li>Check if either is null, a null object is less than a non-null
* <li>Check the object contents
* <li>Check if Objects are same using <code>==</code></li>
* <li>Check if either is null, a null object is less than a non-null</li>
* <li>Check the object contents</li>
* </ol>
*
* <p>If the first parameter to be compared is an array, the array methods will
* be used. Otherwise the comparator will be used. If the comparator is null,
* the <code>lhs</code> will be cast to Comparable.</p>
* the <code>lhs</code> will be cast to <code>Comparable</code>.</p>
*
* @param lhs the Object from <code>this</code> object
* @param rhs the Object from the other object
@ -379,7 +381,7 @@ public CompareToBuilder append(Object lhs, Object rhs, Comparator comparator) {
}
/**
* <p>Test if two <code>long</code>s are <, > or ==.</p>
* <p>Test if two <code>long</code>s are &lt;, &gt; or ==.</p>
*
* @param lhs the <code>long</code> from <code>this</code> object
* @param rhs the <code>long</code> from the other object
@ -394,7 +396,7 @@ public CompareToBuilder append(long lhs, long rhs) {
}
/**
* <p>Test if two <code>int</code>s are <, > or ==.</p>
* <p>Test if two <code>int</code>s are &lt;, &gt; or ==.</p>
*
* @param lhs the <code>int</code> from <code>this</code> object
* @param rhs the <code>int</code> from the other object
@ -409,7 +411,7 @@ public CompareToBuilder append(int lhs, int rhs) {
}
/**
* <p>Test if two <code>short</code>s are <, > or ==.</p>
* <p>Test if two <code>short</code>s are &lt;, &gt; or ==.</p>
*
* @param lhs the <code>short</code> from <code>this</code> object
* @param rhs the <code>short</code> from the other object
@ -424,7 +426,7 @@ public CompareToBuilder append(short lhs, short rhs) {
}
/**
* <p>Test if two <code>char</code>s are <, > or ==.</p>
* <p>Test if two <code>char</code>s are &lt;, &gt; or ==.</p>
*
* @param lhs the <code>char</code> from <code>this</code> object
* @param rhs the <code>char</code> from the other object
@ -439,7 +441,7 @@ public CompareToBuilder append(char lhs, char rhs) {
}
/**
* <p>Test if two <code>byte</code>s are <, > or ==.</p>
* <p>Test if two <code>byte</code>s are &lt, &gt; or ==.</p>
*
* @param lhs the <code>byte</code> from <code>this</code> object
* @param rhs the <code>byte</code> from the other object
@ -454,7 +456,7 @@ public CompareToBuilder append(byte lhs, byte rhs) {
}
/**
* <p>Test if two <code>double</code>s are <, > or ==.</p>
* <p>Test if two <code>double</code>s are &lt;, &gt; or ==.</p>
*
* <p>This handles NaNs, Infinties, and <code>-0.0</code>.</p>
*
@ -474,7 +476,7 @@ public CompareToBuilder append(double lhs, double rhs) {
}
/**
* <p>Test if two <code>float</code>s are <, > or ==.</p>
* <p>Test if two <code>float</code>s are &lt;, &gt; or ==.</p>
*
* <p>This handles NaNs, Infinties, and <code>-0.0</code>.</p>
*
@ -494,7 +496,7 @@ public CompareToBuilder append(float lhs, float rhs) {
}
/**
* <p>Test if two <code>booleans</code>s are <, > or ==.</p>
* <p>Test if two <code>booleans</code>s are &lt;, &gt; or ==.</p>
*
* @param lhs the <code>boolean</code> from <code>this</code> object
* @param rhs the <code>boolean</code> from the other object
@ -517,11 +519,12 @@ public CompareToBuilder append(boolean lhs, boolean rhs) {
/**
* <p>Deep comparison of an <code>Object</code> array.</p>
*
* <ol>
* <li>Check if arrays are same using <code>==</code>
* <li>Check if either is null, a null array is less than a non-null
* <li>Check array length, a short length array is less than a long length array
* <li>Check array contents element by element using {@link #append(long, long)}
* <li>Check if arrays are same using <code>==</code></li>
* <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
* <li>Check array length, a short length array is less than a long length array</li>
* <li>Check array contents element by element using {@link #append(long, long)}</li>
* </ol>
*
* <p>This method will also will be called for the top level of multi-dimensional,
@ -539,11 +542,12 @@ public CompareToBuilder append(Object[] lhs, Object[] rhs) {
/**
* <p>Deep comparison of an <code>Object</code> array.</p>
*
* <ol>
* <li>Check if arrays are same using <code>==</code>
* <li>Check if either is null, a null array is less than a non-null
* <li>Check array length, a shorter length array is less than a longer length array
* <li>Check array contents element by element using {@link #append(Object, Object, Comparator)}
* <li>Check if arrays are same using <code>==</code></li>
* <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(Object, Object, Comparator)}</li>
* </ol>
*
* <p>This method will also will be called for the top level of multi-dimensional,
@ -584,11 +588,12 @@ public CompareToBuilder append(Object[] lhs, Object[] rhs, Comparator comparator
/**
* <p>Deep comparison of a <code>long</code> array.</p>
*
* <ol>
* <li>Check if arrays are same using <code>==</code>
* <li>Check if either is null, a null array is less than a non-null
* <li>Check array length, a shorter length array is less than a longer length array
* <li>Check array contents element by element using {@link #append(long, long)}
* <li>Check if arrays are same using <code>==</code></li>
* <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(long, long)}</li>
* </ol>
*
* @param lhs array from <code>this</code> object
@ -622,11 +627,12 @@ public CompareToBuilder append(long[] lhs, long[] rhs) {
/**
* <p>Deep comparison of an <code>int</code> array.</p>
*
* <ol>
* <li>Check if arrays are same using <code>==</code>
* <li>Check if either is null, a null array is less than a non-null
* <li>Check array length, a shorter length array is less than a longer length array
* <li>Check array contents element by element using {@link #append(int, int)}
* <li>Check if arrays are same using <code>==</code></li>
* <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(int, int)}</li>
* </ol>
*
* @param lhs array from <code>this</code> object
@ -660,11 +666,12 @@ public CompareToBuilder append(int[] lhs, int[] rhs) {
/**
* <p>Deep comparison of a <code>short</code> array.</p>
*
* <ol>
* <li>Check if arrays are same using <code>==</code>
* <li>Check if either is null, a null array is less than a non-null
* <li>Check array length, a shorter length array is less than a longer length array
* <li>Check array contents element by element using {@link #append(short, short)}
* <li>Check if arrays are same using <code>==</code></li>
* <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(short, short)}</li>
* </ol>
*
* @param lhs array from <code>this</code> object
@ -698,11 +705,12 @@ public CompareToBuilder append(short[] lhs, short[] rhs) {
/**
* <p>Deep comparison of a <code>char</code> array.</p>
*
* <ol>
* <li>Check if arrays are same using <code>==</code>
* <li>Check if either is null, a null array is less than a non-null
* <li>Check array length, a shorter length array is less than a longer length array
* <li>Check array contents element by element using {@link #append(char, char)}
* <li>Check if arrays are same using <code>==</code></li>
* <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(char, char)}</li>
* </ol>
*
* @param lhs array from <code>this</code> object
@ -736,11 +744,12 @@ public CompareToBuilder append(char[] lhs, char[] rhs) {
/**
* <p>Deep comparison of a <code>byte</code> array.</p>
*
* <ol>
* <li>Check if arrays are same using <code>==</code>
* <li>Check if either is null, a null array is less than a non-null
* <li>Check array length, a shorter length array is less than a longer length array
* <li>Check array contents element by element using {@link #append(byte, byte)}
* <li>Check if arrays are same using <code>==</code></li>
* <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(byte, byte)}</li>
* </ol>
*
* @param lhs array from <code>this</code> object
@ -774,11 +783,12 @@ public CompareToBuilder append(byte[] lhs, byte[] rhs) {
/**
* <p>Deep comparison of a <code>double</code> array.</p>
*
* <ol>
* <li>Check if arrays are same using <code>==</code>
* <li>Check if either is null, a null array is less than a non-null
* <li>Check array length, a shorter length array is less than a longer length array
* <li>Check array contents element by element using {@link #append(double, double)}
* <li>Check if arrays are same using <code>==</code></li>
* <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(double, double)}</li>
* </ol>
*
* @param lhs array from <code>this</code> object
@ -812,11 +822,12 @@ public CompareToBuilder append(double[] lhs, double[] rhs) {
/**
* <p>Deep comparison of a <code>float</code> array.</p>
*
* <ol>
* <li>Check if arrays are same using <code>==</code>
* <li>Check if either is null, a null array is less than a non-null
* <li>Check array length, a shorter length array is less than a longer length array
* <li>Check array contents element by element using {@link #append(float, float)}
* <li>Check if arrays are same using <code>==</code></li>
* <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(float, float)}
* </ol>
*
* @param lhs array from <code>this</code> object
@ -850,11 +861,12 @@ public CompareToBuilder append(float[] lhs, float[] rhs) {
/**
* <p>Deep comparison of a <code>boolean/code> array.</p>
*
* <ol>
* <li>Check if arrays are same using <code>==</code>
* <li>Check if either is null, a null array is less than a non-null
* <li>Check array length, a shorter length array is less than a longer length array
* <li>Check array contents element by element using {@link #append(boolean, boolean)}
* <li>Check if arrays are same using <code>==</code></li>
* <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(boolean, boolean)}</li>
* </ol>
*
* @param lhs array from <code>this</code> object
@ -887,9 +899,9 @@ public CompareToBuilder append(boolean[] lhs, boolean[] rhs) {
}
/**
* <p>Return a negative integer if the Object is less than, a positive
* integer if the Object is greater than, or <code>0</code> if the
* Object is equal.
* <p>Return a negative integer if the <code>Object</code> is less
* than, a positive integer if the <code>Object</code> is greater than,
* or <code>0</code> if the <code>Object</code> is equal.</p>
*
* @return int - a negative integer, zero, or a positive integer as this
* Object is less than, equal to, or greater than the specified Object.

58
src/java/org/apache/commons/lang/builder/EqualsBuilder.java
View File

@ -108,7 +108,7 @@
* @author Stephen Colebourne
* @author Gary Gregory
* @since 1.0
* @version $Id: EqualsBuilder.java,v 1.13 2003/04/18 09:12:16 ggregory Exp $
* @version $Id: EqualsBuilder.java,v 1.14 2003/07/14 22:25:03 bayard Exp $
*/
public class EqualsBuilder {
/**
@ -130,7 +130,8 @@ public EqualsBuilder() {
//-------------------------------------------------------------------------
/**
* <p>This method uses reflection to determine if the two Object are equal.</p>
* <p>This method uses reflection to determine if the two <code>Object</code>s
* are equal.</p>
*
* <p>It uses <code>Field.setAccessible</code> to gain access to private
* fields. This means that it will throw a security exception if run under
@ -151,7 +152,8 @@ public static boolean reflectionEquals(Object lhs, Object rhs) {
}
/**
* <p>This method uses reflection to determine if the two Object are equal.</p>
* <p>This method uses reflection to determine if the two <code>Object</code>s
* are equal.</p>
*
* <p>It uses <code>Field.setAccessible</code> to gain access to private
* fields. This means that it will throw a security exception if run under
@ -160,7 +162,7 @@ public static boolean reflectionEquals(Object lhs, Object rhs) {
*
* <p>If the TestTransients parameter is set to <code>true</code>, transient
* members will be tested, otherwise they are ignored, as they are likely
* derived fields, and not part of the value of the Object.</p>
* derived fields, and not part of the value of the <code>Object</code>.</p>
*
* <p>Static fields will not be tested. Superclass fields will be included.</p>
*
@ -174,7 +176,8 @@ public static boolean reflectionEquals(Object lhs, Object rhs, boolean testTrans
}
/**
* <p>This method uses reflection to determine if the two Object are equal.</p>
* <p>This method uses reflection to determine if the two <code>Object</code>s
* are equal.</p>
*
* <p>It uses <code>Field.setAccessible</code> to gain access to private
* fields. This means that it will throw a security exception if run under
@ -183,7 +186,7 @@ public static boolean reflectionEquals(Object lhs, Object rhs, boolean testTrans
*
* <p>If the testTransients parameter is set to <code>true</code>, transient
* members will be tested, otherwise they are ignored, as they are likely
* derived fields, and not part of the value of the Object.</p>
* derived fields, and not part of the value of the <code>Object</code>.</p>
*
* <p>Static fields will not be included. Superclass fields will be appended
* up to and including the specified superclass. A null superclass is treated
@ -192,7 +195,8 @@ public static boolean reflectionEquals(Object lhs, Object rhs, boolean testTrans
* @param lhs <code>this</code> object
* @param rhs the other object
* @param testTransients whether to include transient fields
* @param reflectUpToClass the superclass to reflect up to (inclusive), may be null
* @param reflectUpToClass the superclass to reflect up to (inclusive),
* may be <code>null</code>
* @return <code>true</code> if the two Objects have tested equals.
*/
public static boolean reflectionEquals(Object lhs, Object rhs, boolean testTransients, Class reflectUpToClass) {
@ -244,8 +248,8 @@ public static boolean reflectionEquals(Object lhs, Object rhs, boolean testTrans
}
/**
* Appends the fields and values defined by the given object of the
* given Class.
* <p>Appends the fields and values defined by the given object of the
* given Class.</p>
*
* @param lhs the left hand object
* @param rhs the right hand object
@ -280,7 +284,7 @@ private static void reflectionAppend(
//-------------------------------------------------------------------------
/**
* <p>Adds the result of super.equals() to this builder.</p>
* <p>Adds the result of <code>super.equals()</code> to this builder.</p>
*
* @param superEquals the result of calling <code>super.equals()</code>
* @return EqualsBuilder - used to chain calls.
@ -476,7 +480,7 @@ public EqualsBuilder append(boolean lhs, boolean rhs) {
}
/**
* <p>Performs a deep comparison of two Object arrays.</p>
* <p>Performs a deep comparison of two <code>Object</code> arrays.</p>
*
* <p>This also will be called for the top level of
* multi-dimensional, ragged, and multi-typed arrays.</p>
@ -512,8 +516,8 @@ public EqualsBuilder append(Object[] lhs, Object[] rhs) {
}
/**
* <p>Deep comparison of array of <code>long</code> Length and all values
* are compared.</p>
* <p>Deep comparison of array of <code>long</code>. Length and all
* values are compared.</p>
*
* <p>The method {@link #append(long, long)} is used.</p>
*
@ -543,8 +547,8 @@ public EqualsBuilder append(long[] lhs, long[] rhs) {
}
/**
* <p>Deep comparison of array of <code>int</code> Length and all values
* are compared.</p>
* <p>Deep comparison of array of <code>int</code>. Length and all
* values are compared.</p>
*
* <p>The method {@link #append(int, int)} is used.</p>
*
@ -574,8 +578,8 @@ public EqualsBuilder append(int[] lhs, int[] rhs) {
}
/**
* <p>Deep comparison of array of <code>short</code> Length and all values
* are compared.</p>
* <p>Deep comparison of array of <code>short</code>. Length and all
* values are compared.</p>
*
* <p>The method {@link #append(short, short)} is used.</p>
*
@ -605,8 +609,8 @@ public EqualsBuilder append(short[] lhs, short[] rhs) {
}
/**
* <p>Deep comparison of array of <code>char</code> Length and all values
* are compared.</p>
* <p>Deep comparison of array of <code>char</code>. Length and all
* values are compared.</p>
*
* <p>The method {@link #append(char, char)} is used.</p>
*
@ -636,8 +640,8 @@ public EqualsBuilder append(char[] lhs, char[] rhs) {
}
/**
* <p>Deep comparison of array of <code>byte</code> Length and all values
* are compared.</p>
* <p>Deep comparison of array of <code>byte</code>. Length and all
* values are compared.</p>
*
* <p>The method {@link #append(byte, byte)} is used.</p>
*
@ -667,8 +671,8 @@ public EqualsBuilder append(byte[] lhs, byte[] rhs) {
}
/**
* <p>Deep comparison of array of <code>double</code> Length and all values
* are compared.</p>
* <p>Deep comparison of array of <code>double</code>. Length and all
* values are compared.</p>
*
* <p>The method {@link #append(double, double)} is used.</p>
*
@ -698,8 +702,8 @@ public EqualsBuilder append(double[] lhs, double[] rhs) {
}
/**
* <p>Deep comparison of array of <code>float</code> Length and all values
* are compared.</p>
* <p>Deep comparison of array of <code>float</code>. Length and all
* values are compared.</p>
*
* <p>The method {@link #append(float, float)} is used.</p>
*
@ -729,8 +733,8 @@ public EqualsBuilder append(float[] lhs, float[] rhs) {
}
/**
* <p>Deep comparison of array of <code>boolean</code> Length and all values
* are compared.</p>
* <p>Deep comparison of array of <code>boolean</code>. Length and all
* values are compared.</p>
*
* <p>The method {@link #append(boolean, boolean)} is used.</p>
*

25
src/java/org/apache/commons/lang/builder/HashCodeBuilder.java
View File

@ -64,7 +64,7 @@
* , by Joshua Bloch. Writing a good <code>hashCode</code> is actually quite
* difficult. This class aims to simplify the process.</p>
*
* <p> All relevant fields from the object should be included in the
* <p>All relevant fields from the object should be included in the
* <code>hashCode</code>. Derived fields may be excluded. In general, any
* field used in the equals method must be used in the <code>hashCode</code>
* method.</p>
@ -108,16 +108,16 @@
* @author Stephen Colebourne
* @author Gary Gregory
* @since 1.0
* @version $Id: HashCodeBuilder.java,v 1.12 2003/04/18 09:12:16 ggregory Exp $
* @version $Id: HashCodeBuilder.java,v 1.13 2003/07/14 22:25:03 bayard Exp $
*/
public class HashCodeBuilder {
/**
* Constant to use in building the hashCode
* Constant to use in building the hashCode.
*/
private final int iConstant;
/**
* Running total of the hashCode
* Running total of the hashCode.
*/
private int iTotal = 0;
@ -178,7 +178,7 @@ public HashCodeBuilder(int initialNonZeroOddNumber, int multiplierNonZeroOddNumb
* also not as efficient as testing explicitly.</p>
*
* <p>Transient members will be not be used, as they are likely derived
* fields, and not part of the value of the Object.</p>
* fields, and not part of the value of the <code>Object</code>.</p>
*
* <p>Static fields will not be tested. Superclass fields will be included.</p>
*
@ -203,7 +203,7 @@ public static int reflectionHashCode(Object object) {
*
* <P>If the TestTransients parameter is set to <code>true</code>, transient
* members will be tested, otherwise they are ignored, as they are likely
* derived fields, and not part of the value of the Object.</p>
* derived fields, and not part of the value of the <code>Object</code>.</p>
*
* <p>Static fields will not be tested. Superclass fields will be included.</p>
*
@ -225,7 +225,7 @@ public static int reflectionHashCode(Object object, boolean testTransients) {
* also not as efficient as testing explicitly.</p>
*
* <p>Transient members will be not be used, as they are likely derived
* fields, and not part of the value of the Object.</p>
* fields, and not part of the value of the <code>Object</code>.</p>
*
* <p>Static fields will not be tested. Superclass fields will be included.</p>
*
@ -255,7 +255,7 @@ public static int reflectionHashCode(
*
* <p>If the TestTransients parameter is set to <code>true</code>, transient
* members will be tested, otherwise they are ignored, as they are likely
* derived fields, and not part of the value of the Object.</p>
* derived fields, and not part of the value of the <code>Object</code>.</p>
*
* <p>Static fields will not be tested. Superclass fields will be included.</p>
*
@ -287,7 +287,7 @@ public static int reflectionHashCode(
*
* <p>If the TestTransients parameter is set to <code>true</code>, transient
* members will be tested, otherwise they are ignored, as they are likely
* derived fields, and not part of the value of the Object.</p>
* derived fields, and not part of the value of the <code>Object</code>.</p>
*
* <p>Static fields will not be included. Superclass fields will be included
* up to and including the specified superclass. A null superclass is treated
@ -301,7 +301,8 @@ public static int reflectionHashCode(
* @param multiplierNonZeroOddNumber a non-zero, odd number used as the multiplier
* @param object the Object to create a <code>hashCode</code> for
* @param testTransients whether to include transient fields
* @param reflectUpToClass the superclass to reflect up to (inclusive), may be null
* @param reflectUpToClass the superclass to reflect up to (inclusive),
* may be <code>null</code>
* @return int hash code
* @throws IllegalArgumentException if the Object is <code>null</code>
* @throws IllegalArgumentException if the number is zero or even
@ -327,8 +328,8 @@ public static int reflectionHashCode(
}
/**
* Appends the fields and values defined by the given object of the
* given Class.
* <p>Appends the fields and values defined by the given object of the
* given <code>Class</code>.</p>
*
* @param object the object to append details of
* @param clazz the class to append details of

58
src/java/org/apache/commons/lang/builder/ReflectionToStringBuilder.java
View File

@ -30,8 +30,8 @@
*
* <p>A subclass can control field output by overriding the methods:
* <ul>
* <li>{@link #accept(java.lang.reflect.Field)}</li>
* <li>{@link #getValue(java.lang.reflect.Field)}</li>
* <li>{@link #accept(java.lang.reflect.Field)}</li>
* <li>{@link #getValue(java.lang.reflect.Field)}</li>
* </ul>
* </p>
*
@ -41,13 +41,13 @@
* @author <a href="mailto:ggregory@seagullsw.com">Gary Gregory</a>
* @author Stephen Colebourne
* @since 2.0
* @version $Id: ReflectionToStringBuilder.java,v 1.1 2003/06/03 03:51:56 ggregory Exp $
* @version $Id: ReflectionToStringBuilder.java,v 1.2 2003/07/14 22:25:03 bayard Exp $
*/
public class ReflectionToStringBuilder extends ToStringBuilder {
/**
* A registry of objects used by <code>reflectionToString</code> methods to detect cyclical object references
* and avoid infinite loops.
* A registry of objects used by <code>reflectionToString</code> methods to detect
* cyclical object references and avoid infinite loops.
*/
private static ThreadLocal registry = new ThreadLocal() {
protected synchronized Object initialValue() {
@ -58,8 +58,9 @@ protected synchronized Object initialValue() {
};
/**
* Returns the registry of objects being traversed by the
* <code>reflectionToString</code> methods in the current thread.
* <p>Returns the registry of objects being traversed by the
* <code>reflectionToString</code> methods in the current thread.</p>
*
* @return Set the registry of objects being traversed
*/
static Set getRegistry() {
@ -67,8 +68,8 @@ static Set getRegistry() {
}
/**
* Returns <code>true</code> if the registry contains the given object.
* Used by the reflection methods to avoid infinite loops.
* <p>Returns <code>true</code> if the registry contains the given object.
* Used by the reflection methods to avoid infinite loops.</p>
*
* @param value The object to lookup in the registry.
* @return boolean <code>true</code> if the registry contains the given object.
@ -149,8 +150,7 @@ public static String toString(Object object, ToStringStyle style) {
*
* <p>Static fields will not be included. Superclass fields will be appended.</p>
*
* <p>
* If the style is <code>null</code>, the default
* <p>If the style is <code>null</code>, the default
* <code>ToStringStyle</code> is used.</p>
*
* @param object the Object to be output
@ -202,8 +202,9 @@ public static String toString(
}
/**
* Unregisters the given object.
* Used by the reflection methods to avoid infinite loops.
* <p>Unregisters the given object.</p>
*
* <p>Used by the reflection methods to avoid infinite loops.</p>
*
* @param value The object to unregister.
*/
@ -296,9 +297,9 @@ public ReflectionToStringBuilder(
/**
* Returns whether or not to append the given <code>Field</code>.
* <ul>
* <li>Static fields are not appended.</li>
* <li>Transient fields are appended only if {@link #isAppendTransients()} returns <code>true</code>.
* <li>Inner class fields are not appened.</li>
* <li>Static fields are not appended.</li>
* <li>Transient fields are appended only if {@link #isAppendTransients()} returns <code>true</code>.
* <li>Inner class fields are not appened.</li>
* </ul>
* @param field The Field to test.
* @return Whether or not to append the given <code>Field</code>.
@ -311,10 +312,12 @@ protected boolean accept(Field field) {
}
/**
* Appends the fields and values defined by the given object of the
* given Class. If a cycle is detected as an objects is "toString()'ed",
* <p>Appends the fields and values defined by the given object of the
* given Class.</p>
*
* <p>If a cycle is detected as an objects is &quot;toString()'ed&quot;,
* such an object is rendered as if <code>Object.toString()</code>
* had been called and not implemented by the object.
* had been called and not implemented by the object.</p>
*
* @param clazz The class of object parameter
*/
@ -370,7 +373,7 @@ protected void appendFieldsIn(Class clazz) {
}
/**
* Gets the last super class to stop appending fields for.
* <p>Gets the last super class to stop appending fields for.</p>
*
* @return The last super class to stop appending fields for.
*/
@ -379,7 +382,8 @@ public Class getUpToClass() {
}
/**
* Calls <code>java.lang.reflect.Field.get(Object)</code>
* <p>Calls <code>java.lang.reflect.Field.get(Object)</code></p>
*
* @see java.lang.reflect.Field#get(Object)
* @throws IllegalArgumentException
* @throws IllegalAccessException
@ -389,7 +393,7 @@ protected Object getValue(Field field) throws IllegalArgumentException, IllegalA
}
/**
* Returns whether or not to append transient fields.
* <p>Returns whether or not to append transient fields.</p>
*
* @return Whether or not to append transient fields.
*/
@ -410,14 +414,15 @@ public ToStringBuilder reflectionAppendArray(Object array) {
}
/**
* Registers this builder's source object to avoid infinite loops processing circular object references.
* <p>Registers this builder's source object to avoid infinite
* loops processing circular object references.</p>
*/
void registerObject() {
register(this.getObject());
}
/**
* Sets whether or not to append transient fields.
* <p>Sets whether or not to append transient fields.</p>
*
* @param appendTransients Whether or not to append transient fields.
*/
@ -426,7 +431,7 @@ public void setAppendTransients(boolean appendTransients) {
}
/**
* Sets the last super class to stop appending fields for.
* <p>Sets the last super class to stop appending fields for.</p>
*
* @param clazz The last super class to stop appending fields for.
*/
@ -448,7 +453,8 @@ public String toString() {
}
/**
* Unegisters this builder's source object to avoid infinite loops processing circular object references.
* <p>Unegisters this builder's source object to avoid infinite
* loops processing circular object references.</p>
*/
void unregisterObject() {
unregister(this.getObject());

4
src/java/org/apache/commons/lang/builder/StandardToStringStyle.java
View File

@ -65,7 +65,7 @@
*
* @author Stephen Colebourne
* @since 1.0
* @version $Id: StandardToStringStyle.java,v 1.8 2003/03/23 17:54:16 scolebourne Exp $
* @version $Id: StandardToStringStyle.java,v 1.9 2003/07/14 22:25:03 bayard Exp $
*/
public class StandardToStringStyle extends ToStringStyle {
@ -419,7 +419,7 @@ public String getNullText() {
* <p><code>Null</code> is accepted, but will be converted
* to a empty String.</p>
*
* @param nullText the new text to output when null found
* @param nullText the new text to output when <code>null</code> found
*/
public void setNullText(String nullText) {
super.setNullText(nullText);

38
src/java/org/apache/commons/lang/builder/ToStringBuilder.java
View File

@ -61,15 +61,16 @@
* <p>This class enables a good and consistent <code>toString()</code> to be built for any
* class or object. This class aims to simplify the process by:</p>
* <ul>
* <li>allowing field names
* <li>handling all types consistently
* <li>handling nulls consistently
* <li>outputting arrays and multi-dimensional arrays
* <li>enabling the detail level to be controlled for Objects and Collections
* <li>handling class hierarchies
* <li>allowing field names</li>
* <li>handling all types consistently</li>
* <li>handling nulls consistently</li>
* <li>outputting arrays and multi-dimensional arrays</li>
* <li>enabling the detail level to be controlled for Objects and Collections</li>
* <li>handling class hierarchies</li>
* </ul>
*
* <p>To use this class write code as follows:
* <p>To use this class write code as follows:</p>
*
* <pre>
* public class Person {
* String name;
@ -87,6 +88,7 @@
* }
* }
* </pre>
*
* <p>This will produce a toString of the format:
* <code>Person@7f54[name=Stephen,age=29,smoker=false]</code></p>
*
@ -102,6 +104,7 @@
* slower than testing explicitly.</p>
*
* <p>A typical invocation for this method would look like:</p>
*
* <pre>
* public String toString() {
* return ToStringBuilder.reflectionToString(this);
@ -109,6 +112,7 @@
* </pre>
*
* <p>You can also use the builder to debug 3rd party objects:</p>
*
* <pre>
* System.out.println("An object: " + ToStringBuilder.reflectionToString(anObject));
* </pre>
@ -119,12 +123,12 @@
* @author Stephen Colebourne
* @author Gary Gregory
* @since 1.0
* @version $Id: ToStringBuilder.java,v 1.23 2003/06/23 17:04:39 ggregory Exp $
* @version $Id: ToStringBuilder.java,v 1.24 2003/07/14 22:25:03 bayard Exp $
*/
public class ToStringBuilder {
/**
* The default style of output to use
* The default style of output to use.
*/
private static ToStringStyle defaultStyle = ToStringStyle.DEFAULT_STYLE;
@ -147,7 +151,7 @@ public static ToStringStyle getDefaultStyle() {
}
/**
* Forwards to ReflectionToStringBuilder.
* <p>Forwards to <code>ReflectionToStringBuilder</code>.</p>
*
* @see ReflectionToStringBuilder#toString(Object)
*/
@ -156,7 +160,7 @@ public static String reflectionToString(Object object) {
}
/**
* Forwards to ReflectionToStringBuilder.
* <p>Forwards to <code>ReflectionToStringBuilder</code>.</p>
*
* @see ReflectionToStringBuilder#toString(Object,ToStringStyle)
*/
@ -165,7 +169,7 @@ public static String reflectionToString(Object object, ToStringStyle style) {
}
/**
* Forwards to ReflectionToStringBuilder.
* <p>Forwards to <code>ReflectionToStringBuilder</code>.</p>
*
* @see ReflectionToStringBuilder#toString(Object,ToStringStyle,boolean)
*/
@ -174,7 +178,7 @@ public static String reflectionToString(Object object, ToStringStyle style, bool
}
/**
* Forwards to ReflectionToStringBuilder.
* <p>Forwards to <code>ReflectionToStringBuilder</code>.</p>
*
* @see ReflectionToStringBuilder#toString(Object,ToStringStyle,boolean,Class)
*/
@ -997,8 +1001,8 @@ public ToStringBuilder appendSuper(String superToString) {
* <p>Append the <code>toString</code> from another object.</p>
*
* <p>This method is useful where a class delegates most of the implementation of
* it's properties to another class. You can then call toString() on the other
* class and pass the result into this method.</p>
* it's properties to another class. You can then call <code>toString()</code> on
* the other class and pass the result into this method.</p>
*
* <pre>
* private AnotherObject delegate;
@ -1014,7 +1018,7 @@ public ToStringBuilder appendSuper(String superToString) {
* <p>This method asumes that the other object uses the same <code>ToStringStyle</code>
* as this one.</p>
*
* <p>If the <code>toString</code> is null, no change is made.</p>
* <p>If the <code>toString</code> is <code>null</code>, no change is made.</p>
*
* @param toString the result of <code>toString()</code> on another object
* @return this
@ -1060,7 +1064,7 @@ public String toString() {
}
/**
* Returns the object being output.
* <p>Returns the <code>Object</code> being output.</p>
*
* @return The object being output.
*/

17
src/java/org/apache/commons/lang/builder/ToStringStyle.java
View File

@ -83,7 +83,7 @@
* @author Stephen Colebourne
* @author <a href="mailto:ggregory@seagullsw.com">Gary Gregory</a>
* @since 1.0
* @version $Id: ToStringStyle.java,v 1.14 2003/06/03 03:51:56 ggregory Exp $
* @version $Id: ToStringStyle.java,v 1.15 2003/07/14 22:25:04 bayard Exp $
*/
public abstract class ToStringStyle implements Serializable {
@ -175,15 +175,15 @@ public abstract class ToStringStyle implements Serializable {
*/
private String sizeStartText = "<size=";
/**
* The summary size text start <code>'>'</code>.
* The summary size text start <code>'&gt;'</code>.
*/
private String sizeEndText = ">";
/**
* The summary object text start <code>'<'</code>.
* The summary object text start <code>'&lt;'</code>.
*/
private String summaryObjectStartText = "<";
/**
* The summary object text start <code>'>'</code>.
* The summary object text start <code>'&gt;'</code>.
*/
private String summaryObjectEndText = ">";
@ -201,7 +201,7 @@ protected ToStringStyle() {
/**
* <p>Append the superclass toString.</p>
*
* <p>A null <code>super.toString()</code> is ignored.</p>
* <p>A <code>null</code> <code>super.toString()</code> is ignored.</p>
*
* @param buffer the <code>StringBuffer</code> to populate
* @param superToString the <code>super.toString()</code>
@ -213,7 +213,7 @@ public void appendSuper(StringBuffer buffer, String superToString) {
/**
* <p>Append a toString.</p>
*
* <p>A null <code>toString()</code> is ignored.</p>
* <p>A <code>null</code> <code>toString()</code> is ignored.</p>
*
* @param buffer the <code>StringBuffer</code> to populate
* @param toString the <code>super.toString()</code>
@ -321,7 +321,8 @@ public void append(StringBuffer buffer, String fieldName, Object value, Boolean
*
* <p>Either detail or summary views can be specified.</p>
*
* <p>If a cycle is detected, an object will be appended with the Object.toString() format.</p>
* <p>If a cycle is detected, an object will be appended with the
* <code>Object.toString()</code> format.</p>
*
* @param buffer the <code>StringBuffer</code> to populate
* @param fieldName the field name, typically not used as already appended
@ -459,7 +460,7 @@ protected void appendDetail(StringBuffer buffer, String fieldName, Map map) {
/**
* <p>Append to the <code>toString</code> an <code>Object</code>
* value, printing a summary of the Object.</P>
* value, printing a summary of the <code>Object</code>.</P>
*
* @param buffer the <code>StringBuffer</code> to populate
* @param fieldName the field name, typically not used as already appended

75
src/java/org/apache/commons/lang/enum/EnumUtils.java
View File

@ -58,85 +58,98 @@
import java.util.Map;
/**
* Utility class for accessing and manipulating Enums.
* <p>Utility class for accessing and manipulating {@link Enum}s.</p>
*
* @see Enum
* @see ValuedEnum
* @author Stephen Colebourne
* @since 1.0
* @version $Id: EnumUtils.java,v 1.6 2003/03/06 22:50:21 scolebourne Exp $
* @version $Id: EnumUtils.java,v 1.7 2003/07/14 22:25:04 bayard Exp $
*/
public class EnumUtils {
/**
* Restricted constructor
* Restricted constructor.
*/
private EnumUtils() {
}
/**
* Gets an Enum object by class and name.
* <p>Gets an <code>Enum</code> object by class and name.</p>
*
* @param enumClass the class of the Enum to get
* @param name the name of the Enum to get, may be null
* @param enumClass the class of the <code>Enum</code> to get
* @param name the name of the Enum to get, may be <code>null</code>
* @return the enum object
* @throws IllegalArgumentException if the enum class is null
* @throws IllegalArgumentException if the enum class is <code>null</code>
*/
public static Enum getEnum(Class enumClass, String name) {
return Enum.getEnum(enumClass, name);
}
/**
* Gets a ValuedEnum object by class and value.
* <p>Gets a <code>ValuedEnum</code> object by class and value.</p>
*
* @param enumClass the class of the Enum to get
* @param value the value of the Enum to get
* @param enumClass the class of the <code>Enum</code> to get
* @param value the value of the <code>Enum</code> to get
* @return the enum object, or null if the enum does not exist
* @throws IllegalArgumentException if the enum class is null
* @throws IllegalArgumentException if the enum class is <code>null</code>
*/
public static ValuedEnum getEnum(Class enumClass, int value) {
return (ValuedEnum) ValuedEnum.getEnum(enumClass, value);
}
/**
* Gets the Map of Enum objects by name using the Enum class.
* If the requested class has no enum objects an empty Map is returned.
* The Map is unmodifiable.
* <p>Gets the <code>Map</code> of <code>Enum</code> objects by
* name using the <code>Enum</code> class.</p>
*
* <p>If the requested class has no enum objects an empty
* <code>Map</code> is returned. The <code>Map</code> is unmodifiable.</p>
*
* @param enumClass the class of the Enum to get
* @param enumClass the class of the <code>Enum</code> to get
* @return the enum object Map
* @throws IllegalArgumentException if the enum class is null
* @throws IllegalArgumentException if the enum class is not a subclass of Enum
* @throws IllegalArgumentException if the enum class is <code>null</code>
* @throws IllegalArgumentException if the enum class is not a subclass
* of <code>Enum</code>
*/
public static Map getEnumMap(Class enumClass) {
return Enum.getEnumMap(enumClass);
}
/**
* Gets the List of Enum objects using the Enum class.
* The list is in the order that the objects were created (source code order).
* If the requested class has no enum objects an empty List is returned.
* The List is unmodifiable.
* <p>Gets the <code>List</code> of <code>Enum</code> objects using
* the <code>Enum</code> class.</p>
*
* <p>The list is in the order that the objects were created
* (source code order).</p>
*
* <p>If the requested class has no enum objects an empty
* <code>List</code> is returned. The <code>List</code> is unmodifiable.</p>
*
* @param enumClass the class of the Enum to get
* @return the enum object Map
* @throws IllegalArgumentException if the enum class is null
* @throws IllegalArgumentException if the enum class is not a subclass of Enum
* @throws IllegalArgumentException if the enum class is <code>null</code>
* @throws IllegalArgumentException if the enum class is not a subclass
* of <code>Enum</code>
*/
public static List getEnumList(Class enumClass) {
return Enum.getEnumList(enumClass);
}
/**
* Gets an iterator over the Enum objects in an Enum class.
* The iterator is in the order that the objects were created (source code order).
* If the requested class has no enum objects an empty Iterator is returned.
* The Iterator is unmodifiable.
* <p>Gets an <code>Iterator</code> over the <code>Enum</code> objects
* in an <code>Enum</code> class.</p>
*
* <p>The iterator is in the order that the objects were created
* (source code order).</p>
*
* <p>If the requested class has no enum objects an empty
* <code>Iterator</code> is returned. The <code>Iterator</code>
* is unmodifiable.</p>
*
* @param enumClass the class of the Enum to get
* @return an iterator of the Enum objects
* @throws IllegalArgumentException if the enum class is null
* @throws IllegalArgumentException if the enum class is not a subclass of Enum
* @param enumClass the class of the <code>Enum</code> to get
* @return an <code>Iterator</code> of the <code>Enum</code> objects
* @throws IllegalArgumentException if the enum class is <code>null</code>
* @throws IllegalArgumentException if the enum class is not a subclass of <code>Enum</code>
*/
public static Iterator iterator(Class enumClass) {
return Enum.getEnumList(enumClass).iterator();

76
src/java/org/apache/commons/lang/enum/ValuedEnum.java
View File

@ -56,14 +56,15 @@
import java.util.Iterator;
import java.util.List;
/**
* Abstract superclass for type-safe enums with integer values suitable
* for use in <code>switch</code> statements.
* <p>
* <em>NOTE:</em>Due to the way in which Java ClassLoaders work, comparing Enum objects
* should always be done using the equals() method, not ==. The equals() method will
* try == first so in most cases the effect is the same.
* <p>
* To use this class, it must be subclassed. For example:
* <p>Abstract superclass for type-safe enums with integer values suitable
* for use in <code>switch</code> statements.</p>
*
* <p><em>NOTE:</em>Due to the way in which Java ClassLoaders work, comparing
* <code>Enum</code> objects should always be done using the equals() method,
* not <code>==</code>. The equals() method will try <code>==</code> first so
* in most cases the effect is the same.</p>
*
* <p>To use this class, it must be subclassed. For example:</p>
*
* <pre>
* public final class JavaVersionEnum extends ValuedEnum {
@ -103,7 +104,8 @@
* }
* </pre>
*
* The above class could then be used as follows:
* <p>The above class could then be used as follows:</p>
*
* <pre>
* public void doSomething(JavaVersion ver) {
* switch (ver.getValue()) {
@ -117,20 +119,19 @@
* }
* }
* </pre>
* <p>
* As shown, each enum has a name and a value. These can be accessed using
* <code>getName</code> and <code>getValue</code>.
* <p>
* The <code>getEnum</code> and <code>iterator</code> methods are recommended.
*
* <p>As shown, each enum has a name and a value. These can be accessed using
* <code>getName</code> and <code>getValue</code>.</p>
*
* <p>The <code>getEnum</code> and <code>iterator</code> methods are recommended.
* Unfortunately, Java restrictions require these to be coded as shown in each subclass.
* An alternative choice is to use the {@link EnumUtils} class.
* <p>
* <em>NOTE:</em> This class originated in the Jakarta Avalon project.
* </p>
* An alternative choice is to use the {@link EnumUtils} class.</p>
*
* <p><em>NOTE:</em> This class originated in the Jakarta Avalon project.</p>
*
* @author Stephen Colebourne
* @since 1.0
* @version $Id: ValuedEnum.java,v 1.5 2003/02/04 18:30:07 scolebourne Exp $
* @version $Id: ValuedEnum.java,v 1.6 2003/07/14 22:25:04 bayard Exp $
*/
public abstract class ValuedEnum extends Enum {
/**
@ -150,14 +151,16 @@ protected ValuedEnum(String name, int value) {
}
/**
* Gets an Enum object by class and value.
* This method loops through the list of Enums, thus if there
* are many Enums this will be slow.
* <p>Gets an <code>Enum</code> object by class and value.</p>
*
* <p>This method loops through the list of <code>Enum</code>,
* thus if there are many <code>Enum</code>s this will be
* slow.</p>
*
* @param enumClass the class of the Enum to get
* @param value the value of the Enum to get
* @param enumClass the class of the <code>Enum</code> to get
* @param value the value of the <code>Enum</code> to get
* @return the enum object, or null if the enum does not exist
* @throws IllegalArgumentException if the enum class is null
* @throws IllegalArgumentException if the enum class is <code>null</code>
*/
protected static Enum getEnum(Class enumClass, int value) {
if (enumClass == null) {
@ -174,7 +177,7 @@ protected static Enum getEnum(Class enumClass, int value) {
}
/**
* Get value of enum item.
* <p>Get value of enum item.</p>
*
* @return the enum item's value.
*/
@ -183,25 +186,30 @@ public final int getValue() {
}
/**
* Tests for order. The default ordering is numeric by value, but this
* can be overridden by subclasses.
* <p>Tests for order.</p>
*
* <p>The default ordering is numeric by value, but this
* can be overridden by subclasses.</p>
*
* @see java.lang.Comparable#compareTo(Object)
* @param other the other object to compare to
* @return -ve if this is less than the other object, +ve if greater than, 0 of equal
* @throws ClassCastException if other is not an Enum
* @throws NullPointerException if other is null
* @return -ve if this is less than the other object, +ve if greater than,
* <code>0</code> of equal
* @throws ClassCastException if other is not an <code>Enum</code>
* @throws NullPointerException if other is <code>null</code>
*/
public int compareTo(Object other) {
return iValue - ((ValuedEnum) other).iValue;
}
/**
* Human readable description of this Enum item. For use when debugging.
* <p>Human readable description of this <code>Enum</code> item.</p>
*
* <p>For use when debugging.</p>
*
* @return String in the form <code>type[name=value]</code>, for example:
* <code>JavaVersion[Java 1.0=100]</code>. Note that the package name is
* stripped from the type name.
* <code>JavaVersion[Java 1.0=100]</code>. Note that the package name is
* stripped from the type name.
*/
public String toString() {
String shortName = Enum.getEnumClass(getClass()).getName();

29
src/java/org/apache/commons/lang/math/DoubleRange.java
View File

@ -60,24 +60,36 @@
*
* @author Stephen Colebourne
* @since 2.0
* @version $Id: DoubleRange.java,v 1.2 2003/03/23 17:51:15 scolebourne Exp $
* @version $Id: DoubleRange.java,v 1.3 2003/07/14 22:25:04 bayard Exp $
*/
public final class DoubleRange extends Range implements Serializable {
private static final long serialVersionUID = 71849363892740L;
/* The minimum number in this range (inclusive). */
/**
* The minimum number in this range (inclusive).
*/
private final double min;
/* The maximum number in this range (inclusive). */
/**
* The maximum number in this range (inclusive).
*/
private final double max;
/** Cached output minObject (class is immutable) */
/**
* Cached output minObject (class is immutable).
*/
private transient Double minObject = null;
/** Cached output maxObject (class is immutable) */
/**
* Cached output maxObject (class is immutable).
*/
private transient Double maxObject = null;
/** Cached output hashCode (class is immutable) */
/**
* Cached output hashCode (class is immutable).
*/
private transient int hashCode = 0;
/** Cached output toString (class is immutable) */
/**
* Cached output toString (class is immutable).
*/
private transient String toString = null;
/**
@ -100,7 +112,8 @@ public DoubleRange(double number) {
* <p>Constructs a new <code>DoubleRange</code> using the specified
* number as both the minimum and maximum in this range.</p>
*
* @param number the number to use for this range, must not be null
* @param number the number to use for this range, must not
* be <code>null</code>
* @throws IllegalArgumentException if the number is <code>null</code>
* @throws IllegalArgumentException if the number is <code>NaN</code>
*/

29
src/java/org/apache/commons/lang/math/FloatRange.java
View File

@ -60,24 +60,36 @@
*
* @author Stephen Colebourne
* @since 2.0
* @version $Id: FloatRange.java,v 1.2 2003/03/23 17:51:15 scolebourne Exp $
* @version $Id: FloatRange.java,v 1.3 2003/07/14 22:25:04 bayard Exp $
*/
public final class FloatRange extends Range implements Serializable {
private static final long serialVersionUID = 71849363892750L;
/* The minimum number in this range (inclusive). */
/**
* The minimum number in this range (inclusive).
*/
private final float min;
/* The maximum number in this range (inclusive). */
/**
* The maximum number in this range (inclusive).
*/
private final float max;
/** Cached output minObject (class is immutable) */
/**
* Cached output minObject (class is immutable).
*/
private transient Float minObject = null;
/** Cached output maxObject (class is immutable) */
/**
* Cached output maxObject (class is immutable).
*/
private transient Float maxObject = null;
/** Cached output hashCode (class is immutable) */
/**
* Cached output hashCode (class is immutable).
*/
private transient int hashCode = 0;
/** Cached output toString (class is immutable) */
/**
* Cached output toString (class is immutable).
*/
private transient String toString = null;
/**
@ -100,7 +112,8 @@ public FloatRange(float number) {
* <p>Constructs a new <code>FloatRange</code> using the specified
* number as both the minimum and maximum in this range.</p>
*
* @param number the number to use for this range, must not be null
* @param number the number to use for this range, must not
* be <code>null</code>
* @throws IllegalArgumentException if the number is <code>null</code>
* @throws IllegalArgumentException if the number is <code>NaN</code>
*/

225
src/java/org/apache/commons/lang/math/Fraction.java
View File

@ -58,53 +58,63 @@
/**
* <p><code>Fraction</code> is a <code>Number</code> implementation that
* stores fractions accurately.</p>
*
*
* <p>This class is immutable, and interoperable with most methods that accept
* a <code>Number</code>.</p>
*
* @author Travis Reeder
* @author Stephen Colebourne
* @since 2.0
* @version $Id: Fraction.java,v 1.3 2003/04/09 01:08:30 ggregory Exp $
* @version $Id: Fraction.java,v 1.4 2003/07/14 22:25:05 bayard Exp $
*/
public final class Fraction extends Number implements Serializable, Comparable {
private static final long serialVersionUID = 65382027393090L;
public static final Fraction ZERO = new Fraction(0, 1);
public static final Fraction ONE = new Fraction(1, 1);
public static final Fraction ONE_HALF = new Fraction(1, 2);
public static final Fraction ONE_THIRD = new Fraction(1, 3);
public static final Fraction TWO_THIRDS = new Fraction(2, 3);
public static final Fraction ONE_QUARTER = new Fraction(1, 4);
public static final Fraction TWO_QUARTERS = new Fraction(2, 4);
public static final Fraction THREE_QUARTERS = new Fraction(3, 4);
public static final Fraction ONE_FIFTH = new Fraction(1, 5);
public static final Fraction TWO_FIFTHS = new Fraction(2, 5);
public static final Fraction THREE_FIFTHS = new Fraction(3, 5);
public static final Fraction FOUR_FIFTHS = new Fraction(4, 5);
/** The numerator number part of the fraction (the three in three sevenths) */
/**
* The numerator number part of the fraction (the three in three sevenths).
*/
private final int numerator;
/** The denominator number part of the fraction (the seven in three sevenths) */
/**
* The denominator number part of the fraction (the seven in three sevenths).
*/
private final int denominator;
/** Cached output hashCode (class is immutable) */
private transient int hashCode = 0;
/** Cached output toString (class is immutable) */
private transient String toString = null;
/** Cached output toProperString (class is immutable) */
private transient String toProperString = null;
/**
* <p>Constructs a <code>Fraction</code> instance with the 2 parts
* Cached output hashCode (class is immutable).
*/
private transient int hashCode = 0;
/**
* Cached output toString (class is immutable).
*/
private transient String toString = null;
/**
* Cached output toProperString (class is immutable).
*/
private transient String toProperString = null;
/**
* <p>Constructs a <code>Fraction</code> instance with the 2 parts
* of a fraction Y/Z.</p>
*
*
* @param numerator the numerator, for example the three in 'three sevenths'
* @param denominator the denominator, for example the seven in 'three sevenths'
*/
@ -113,17 +123,17 @@ private Fraction(int numerator, int denominator) {
this.numerator = numerator;
this.denominator = denominator;
}
/**
* <p>Creates a <code>Fraction</code> instance with the 2 parts
* <p>Creates a <code>Fraction</code> instance with the 2 parts
* of a fraction Y/Z.</p>
*
*
* <p>Any negative signs are resolved to be on the numerator.</p>
*
*
* @param numerator the numerator, for example the three in 'three sevenths'
* @param denominator the denominator, for example the seven in 'three sevenths'
* @return a new fraction instance
* @throws ArithmeticException if the denomiator is zero
* @throws ArithmeticException if the denomiator is <code>zero</code>
*/
public static Fraction getFraction(int numerator, int denominator) {
if (denominator == 0) {
@ -137,16 +147,16 @@ public static Fraction getFraction(int numerator, int denominator) {
}
/**
* <p>Creates a <code>Fraction</code> instance with the 3 parts
* <p>Creates a <code>Fraction</code> instance with the 3 parts
* of a fraction X Y/Z.</p>
*
*
* <p>The negative sign must be passed in on the whole number part.</p>
*
*
* @param whole the whole number, for example the one in 'one and three sevenths'
* @param numerator the numerator, for example the three in 'one and three sevenths'
* @param denominator the denominator, for example the seven in 'one and three sevenths'
* @return a new fraction instance
* @throws ArithmeticException if the denomiator is zero
* @throws ArithmeticException if the denomiator is <code>zero</code>
* @throws ArithmeticException if the denomiator is negative
* @throws ArithmeticException if the numerator is negative
*/
@ -156,7 +166,7 @@ public static Fraction getFraction(int whole, int numerator, int denominator) {
}
if (denominator < 0) {
throw new ArithmeticException("The denominator must not be negative");
}
}
if (numerator < 0) {
throw new ArithmeticException("The numerator must not be negative");
}
@ -169,15 +179,15 @@ public static Fraction getFraction(int whole, int numerator, int denominator) {
}
/**
* <p>Creates a <code>Fraction</code> instance with the 2 parts
* <p>Creates a <code>Fraction</code> instance with the 2 parts
* of a fraction Y/Z.</p>
*
*
* <p>Any negative signs are resolved to be on the numerator.</p>
*
*
* @param numerator the numerator, for example the three in 'three sevenths'
* @param denominator the denominator, for example the seven in 'three sevenths'
* @return a new fraction instance, with the numerator and denominator reduced
* @throws ArithmeticException if the denomiator is zero
* @throws ArithmeticException if the denomiator is <code>zero</code>
*/
public static Fraction getReducedFraction(int numerator, int denominator) {
if (denominator == 0) {
@ -193,16 +203,16 @@ public static Fraction getReducedFraction(int numerator, int denominator) {
}
return new Fraction(numerator / gcd, denominator / gcd);
}
/**
* <p>Creates a <code>Fraction</code> instance from a <code>double</code> value.</p>
*
*
* <p>This method uses the continued fraction algorithm.</p>
*
* @param value the double value to convert
* @return a new fraction instance that is close to the value
* @throws ArithmeticException if the value is infinite or NaN
* @throws ArithmeticException if the calculated denomiator is zero
* @throws ArithmeticException if the value is infinite or <code>NaN</code>
* @throws ArithmeticException if the calculated denomiator is <code>zero</code>
*/
public static Fraction getFraction(double value) {
if (Double.isInfinite(value) || Double.isNaN(value)) {
@ -212,7 +222,7 @@ public static Fraction getFraction(double value) {
value = Math.abs(value);
int wholeNumber = (int) value;
value -= wholeNumber;
// http://archives.math.utk.edu/articles/atuyl/confrac/
int numer0 = 0; // the pre-previous
int denom0 = 1; // the pre-previous
@ -258,17 +268,20 @@ public static Fraction getFraction(double value) {
/**
* <p>Creates a Fraction from a <code>String</code>.</p>
*
*
* <p>The formats accepted are:</p>
*
* <p>
* <ol>
* <li><code>double</code> String containing a dot
* <li>'X Y/Z'
* <li>'Y/Z'
* </ol> and a .</p>
*
* <li><code>double</code> String containing a dot</li>
* <li>'X Y/Z'</li>
* <li>'Y/Z'</li>
* </ol>
* and a .</p>
*
* @param str the string to parse, must not be <code>null</code>
* @return the new <code>Fraction</code> instance
* @throws IllegalArgumentException if the string is null
* @throws IllegalArgumentException if the string is <code>null</code>
* @throws NumberFormatException if the number format is invalid
*/
public static Fraction getFraction(String str) {
@ -280,7 +293,7 @@ public static Fraction getFraction(String str) {
if (pos >= 0) {
return getFraction(Double.parseDouble(str));
}
// parse X Y/Z format
pos = str.indexOf(' ');
if (pos > 0) {
@ -297,7 +310,7 @@ public static Fraction getFraction(String str) {
);
}
}
// parse Y/Z format
pos = str.indexOf('/');
if (pos < 0) {
@ -316,10 +329,10 @@ public static Fraction getFraction(String str) {
/**
* <p>Gets the numerator part of the fraction.</p>
*
*
* <p>This method may return a value greater than the denominator, an
* improper fraction, such as the seven in 7/8.</p>
*
*
* @return the numerator fraction part
*/
public int getNumerator() {
@ -328,22 +341,22 @@ public int getNumerator() {
/**
* <p>Gets the denominator part of the fraction.</p>
*
*
* @return the denominator fraction part
*/
public int getDenominator() {
return denominator;
}
/**
* <p>Gets the proper numerator, always positive.</p>
*
*
* <p>An improper fraction 7/8 can be resolved into a proper one, 1 3/4.
* This method returns the 3 from the proper fraction.</p>
*
*
* <p>If the fraction is negative such as -7/8, it can be resolved into
* -1 3/4, so this method returns the positive proper numerator, 3.</p>
*
*
* @return the numerator fraction part of a proper fraction, always positive
*/
public int getProperNumerator() {
@ -352,13 +365,13 @@ public int getProperNumerator() {
/**
* <p>Gets the proper whole part of the fraction.</p>
*
*
* <p>An improper fraction 7/8 can be resolved into a proper one, 1 3/4.
* This method returns the 1 from the proper fraction.</p>
*
*
* <p>If the fraction is negative such as -7/8, it can be resolved into
* -1 3/4, so this method returns the positive whole part -1.</p>
*
*
* @return the whole fraction part of a proper fraction, that includes the sign
*/
public int getProperWhole() {
@ -371,7 +384,7 @@ public int getProperWhole() {
/**
* <p>Gets the fraction as an <code>int</code>. This returns the whole number
* part of the fraction.</p>
*
*
* @return the whole number fraction part
*/
public int intValue() {
@ -381,7 +394,7 @@ public int intValue() {
/**
* <p>Gets the fraction as a <code>long</code>. This returns the whole number
* part of the fraction.</p>
*
*
* @return the whole number fraction part
*/
public long longValue() {
@ -391,7 +404,7 @@ public long longValue() {
/**
* <p>Gets the fraction as a <code>float</code>. This calculates the fraction
* as the numerator divided by denominator.</p>
*
*
* @return the fraction as a <code>float</code>
*/
public float floatValue() {
@ -401,7 +414,7 @@ public float floatValue() {
/**
* <p>Gets the fraction as a <code>double</code>. This calculates the fraction
* as the numerator divided by denominator.</p>
*
*
* @return the fraction as a <code>double</code>
*/
public double doubleValue() {
@ -412,9 +425,9 @@ public double doubleValue() {
//-------------------------------------------------------------------
/**
* <p>Reduce the fraction to the smallest values for the numerator and
* <p>Reduce the fraction to the smallest values for the numerator and
* denominator, returning the result..</p>
*
*
* @return a new reduce fraction instance, or this if no simplification possible
*/
public Fraction reduce() {
@ -424,14 +437,14 @@ public Fraction reduce() {
}
return Fraction.getFraction(numerator / gcd, denominator / gcd);
}
/**
* <p>Gets a fraction that is the invert (1/fraction) of this one.</p>
*
*
* <p>The returned fraction is not reduced.</p>
*
*
* @return a new fraction instance with the numerator and denominator inverted
* @throws ArithmeticException if the numerator is zero
* @throws ArithmeticException if the numerator is <code>zero</code>
*/
public Fraction invert() {
if (numerator == 0) {
@ -439,24 +452,24 @@ public Fraction invert() {
}
return getFraction(denominator, numerator);
}
/**
* <p>Gets a fraction that is the negative (-fraction) of this one.</p>
*
*
* <p>The returned fraction is not reduced.</p>
*
*
* @return a new fraction instance with the opposite signed numerator
*/
public Fraction negate() {
return getFraction(-numerator, denominator);
}
/**
* <p>Gets a fraction that is the positive equivalent of this one.</p>
* <p>More precisely: <pre>(fraction >= 0 ? this : -fraction)</pre></p>
*
*
* <p>The returned fraction is not reduced.</p>
*
*
* @return <code>this</code> if it is positive, or a new positive fraction
* instance with the opposite signed numerator
*/
@ -469,11 +482,11 @@ public Fraction abs() {
/**
* <p>Gets a fraction that is raised to the passed in power.</p>
*
*
* <p>The returned fraction is not reduced.</p>
*
*
* @param power the power to raise the fraction to
* @return <code>this</code> if the power is one, <code>ONE</code> if the power
* @return <code>this</code> if the power is one, <code>ONE</code> if the power
* is zero or a new fraction instance raised to the appropriate power
*/
public Fraction pow(int power) {
@ -489,7 +502,7 @@ public Fraction pow(int power) {
/**
* <p>Gets the greatest common denominator of two numbers.</p>
*
*
* @param number1 a positive number
* @param number2 a positive number
* @return the greatest common denominator
@ -509,14 +522,14 @@ private static int greatestCommonDenominator(int number1, int number2) {
/**
* <p>Adds the value of this fraction to another, returning the result.</p>
*
* <p>The implementation spots common cases of zero numerators and equal
*
* <p>The implementation spots common cases of zero numerators and equal
* denominators. Otherwise, it uses <code>(a/b) + (c/d) = (a*d + b*c) / (b*d)</code>
* and then reduces the result.</p>
*
* @param the fraction to add, must not be <code>null</code>
*
* @param fraction the fraction to add, must not be <code>null</code>
* @return a <code>Fraction</code> instance with the resulting values
* @throws IllegalArgumentException if the fraction is null
* @throws IllegalArgumentException if the fraction is <code>null</code>
*/
public Fraction add(Fraction fraction) {
if (fraction == null) {
@ -538,16 +551,16 @@ public Fraction add(Fraction fraction) {
}
/**
* <p>Subtracts the value of another fraction from the value of this one,
* <p>Subtracts the value of another fraction from the value of this one,
* returning the result.</p>
*
* <p>The implementation spots common cases of zero numerators and equal
*
* <p>The implementation spots common cases of zero numerators and equal
* denominators. Otherwise, it uses <code>(a/b) - (c/d) = (a*d - b*c) / (b*d)</code>
* and then reduces the result.</p>
*
* @param the fraction to subtract, must not be <code>null</code>
*
* @param fraction the fraction to subtract, must not be <code>null</code>
* @return a <code>Fraction</code> instance with the resulting values
* @throws IllegalArgumentException if the fraction is null
* @throws IllegalArgumentException if the fraction is <code>null</code>
*/
public Fraction subtract(Fraction fraction) {
if (fraction == null) {
@ -567,16 +580,16 @@ public Fraction subtract(Fraction fraction) {
denominator * fraction.denominator
);
}
/**
* <p>Multiplies the value of this fraction by another, returning the result.</p>
*
*
* <p>The implementation uses <code>(a/b)*(c/d) = (a*c)/(b*d)</code>
* and then reduces the result.</p>
*
* @param the fraction to multipy by, must not be <code>null</code>
*
* @param fraction the fraction to multipy by, must not be <code>null</code>
* @return a <code>Fraction</code> instance with the resulting values
* @throws IllegalArgumentException if the fraction is null
* @throws IllegalArgumentException if the fraction is <code>null</code>
*/
public Fraction multiplyBy(Fraction fraction) {
if (fraction == null) {
@ -590,16 +603,16 @@ public Fraction multiplyBy(Fraction fraction) {
denominator * fraction.denominator
);
}
/**
* <p>Divide the value of this fraction by another, returning the result.</p>
*
*
* <p>The implementation uses <code>(a/b)/(c/d) = a/b * d/c = (a*d)/(b*c)</code>
* and then reduces the result.</p>
*
* @param the fraction to divide by, must not be <code>null</code>
*
* @param fraction the fraction to divide by, must not be <code>null</code>
* @return a <code>Fraction</code> instance with the resulting values
* @throws IllegalArgumentException if the fraction is null
* @throws IllegalArgumentException if the fraction is <code>null</code>
* @throws ArithmeticException if the fraction to divide by is zero
*/
public Fraction divideBy(Fraction fraction) {
@ -623,7 +636,7 @@ public Fraction divideBy(Fraction fraction) {
/**
* <p>Compares this fraction to another object to test if they are equal.</p>.
*
*
* <p>To be equal, both values must be equal. Thus 2/4 is not equal to 1/2.</p>
*
* @param obj the reference object with which to compare
@ -657,7 +670,7 @@ public int hashCode() {
/**
* <p>Compares this object to another based on size.</p>
*
*
* @param object the object to compare to
* @return -ve if this is less, 0 if equal, +ve if greater
* @throws ClassCastException if the object is not a <code>Fraction</code>
@ -683,9 +696,9 @@ public int compareTo(Object object) {
/**
* <p>Gets the fraction as a <code>String</code>.</p>
*
*
* <p>The format used is '<i>numerator</i>/<i>denominator</i>' always.
*
*
* @return a <code>String</code> form of the fraction
*/
public String toString() {
@ -700,11 +713,11 @@ public String toString() {
/**
* <p>Gets the fraction as a proper <code>String</code> in the format X Y/Z.</p>
*
*
* <p>The format used in '<i>wholeNumber</i> <i>numerator</i>/<i>denominator</i>'.
* If the whole number is zero it will be ommitted. If the numerator is zero,
* only the whole number is returned.</p>
*
*
* @return a <code>String</code> form of the fraction
*/
public String toProperString() {
@ -731,5 +744,5 @@ public String toProperString() {
}
return toProperString;
}
}

28
src/java/org/apache/commons/lang/math/IntRange.java
View File

@ -60,24 +60,36 @@
*
* @author Stephen Colebourne
* @since 2.0
* @version $Id: IntRange.java,v 1.2 2003/03/23 17:51:15 scolebourne Exp $
* @version $Id: IntRange.java,v 1.3 2003/07/14 22:25:05 bayard Exp $
*/
public final class IntRange extends Range implements Serializable {
private static final long serialVersionUID = 71849363892730L;
/* The minimum number in this range (inclusive). */
/**
* The minimum number in this range (inclusive).
*/
private final int min;
/* The maximum number in this range (inclusive). */
/**
* The maximum number in this range (inclusive).
*/
private final int max;
/** Cached output minObject (class is immutable) */
/**
* Cached output minObject (class is immutable)
*/
private transient Integer minObject = null;
/** Cached output maxObject (class is immutable) */
/**
* Cached output maxObject (class is immutable).
*/
private transient Integer maxObject = null;
/** Cached output hashCode (class is immutable) */
/**
* Cached output hashCode (class is immutable).
*/
private transient int hashCode = 0;
/** Cached output toString (class is immutable) */
/**
* Cached output toString (class is immutable).
*/
private transient String toString = null;
/**
@ -96,7 +108,7 @@ public IntRange(int number) {
* <p>Constructs a new <code>IntRange</code> using the specified
* number as both the minimum and maximum in this range.</p>
*
* @param number the number to use for this range, must not be null
* @param number the number to use for this range, must not be <code>null</code>
* @throws IllegalArgumentException if the number is <code>null</code>
*/
public IntRange(Number number) {

60
src/java/org/apache/commons/lang/math/JVMRandom.java
View File

@ -57,42 +57,50 @@
/**
* <p><code>JVMRandom</code> is a wrapper that supports all possible
* Random methods via the java.lang.Math.random() method and its system-wide
* Random object.
* Random methods via the {@link java.lang.Math#random()} method
* and its system-wide {@link Random} object.</p>
*
* @author Henri Yandell
* @since 2.0
* @version $Id: JVMRandom.java,v 1.6 2003/06/16 02:26:41 bayard Exp $
* @version $Id: JVMRandom.java,v 1.7 2003/07/14 22:25:05 bayard Exp $
*/
public final class JVMRandom extends Random {
/** ensures that only the constructor can call reseed */
/**
* Ensures that only the constructor can call reseed.
*/
private boolean constructed = false;
public JVMRandom() {
this.constructed = true;
}
/** Unsupported in 2.0 */
/**
* Unsupported in 2.0.
*/
public synchronized void setSeed(long seed) {
if (this.constructed) {
throw new UnsupportedOperationException();
}
}
/** Unsupported in 2.0 */
/**
* Unsupported in 2.0.
*/
public synchronized double nextGaussian() {
throw new UnsupportedOperationException();
}
/** Unsupported in 2.0 */
/**
* Unsupported in 2.0.
*/
public void nextBytes(byte[] byteArray) {
throw new UnsupportedOperationException();
}
/**
* Returns the next pseudorandom, uniformly distributed int value
* from the Math.random() sequence.
* <p>Returns the next pseudorandom, uniformly distributed int value
* from the Math.random() sequence.</p>
*
* @return the random int
*/
@ -100,14 +108,13 @@ public int nextInt() {
return nextInt(Integer.MAX_VALUE);
}
/**
* Returns a pseudorandom, uniformly distributed int value between 0
* (inclusive) and the specified value (exclusive), from the
* Math.random() sequence.
* <p>Returns a pseudorandom, uniformly distributed int value between
* <code>0</code> (inclusive) and the specified value (exclusive), from
* the Math.random() sequence.</p>
*
* @param n the specified exclusive max-value
* @throws IllegalArgumentException when n <= 0
*
* @return the random int
* @throws IllegalArgumentException when <code>n &lt;= 0</code>
*/
public int nextInt(int n) {
if (n <= 0) {
@ -119,9 +126,8 @@ public int nextInt(int n) {
return (int)(Math.random() * n);
}
/**
* Returns the next pseudorandom, uniformly distributed long value
* from the Math.random() sequence.
*
* <p>Returns the next pseudorandom, uniformly distributed long value
* from the Math.random() sequence.</p>
* @return the random long
*/
public long nextLong() {
@ -131,14 +137,13 @@ public long nextLong() {
/**
* Returns a pseudorandom, uniformly distributed long value between 0
* (inclusive) and the specified value (exclusive), from the
* Math.random() sequence.
* <p>Returns a pseudorandom, uniformly distributed long value between
* <code>0</code> (inclusive) and the specified value (exclusive), from
* the Math.random() sequence.</p>
*
* @param n the specified exclusive max-value
* @throws IllegalArgumentException when n <= 0
*
* @return the random long
* @throws IllegalArgumentException when <code>n &lt;= 0</code>
*/
public static long nextLong(long n) {
if (n <= 0) {
@ -151,8 +156,8 @@ public static long nextLong(long n) {
}
/**
* Returns the next pseudorandom, uniformly distributed boolean value
* from the Math.random() sequence.
* <p>Returns the next pseudorandom, uniformly distributed boolean value
* from the Math.random() sequence.</p>
*
* @return the random boolean
*/
@ -160,8 +165,9 @@ public boolean nextBoolean() {
return (Math.random() > 0.5);
}
/**
* Returns the next pseudorandom, uniformly distributed float value
* between 0.0 and 1.0 from the Math.random() sequence.
* <p>Returns the next pseudorandom, uniformly distributed float value
* between <code>0.0</code> and <code>1.0</code> from the Math.random()
* sequence.</p>
*
* @return the random float
*/
@ -169,7 +175,7 @@ public float nextFloat() {
return (float)Math.random();
}
/**
* Synonymous to the Math.random() call.
* <p>Synonymous to the Math.random() call.</p>
*
* @return the random double
*/

29
src/java/org/apache/commons/lang/math/LongRange.java
View File

@ -60,24 +60,36 @@
*
* @author Stephen Colebourne
* @since 2.0
* @version $Id: LongRange.java,v 1.2 2003/03/23 17:51:15 scolebourne Exp $
* @version $Id: LongRange.java,v 1.3 2003/07/14 22:25:05 bayard Exp $
*/
public final class LongRange extends Range implements Serializable {
private static final long serialVersionUID = 71849363892720L;
/* The minimum number in this range (inclusive). */
/**
* The minimum number in this range (inclusive).
*/
private final long min;
/* The maximum number in this range (inclusive). */
/**
* The maximum number in this range (inclusive).
*/
private final long max;
/** Cached output minObject (class is immutable) */
/**
* Cached output minObject (class is immutable).
*/
private transient Long minObject = null;
/** Cached output maxObject (class is immutable) */
/**
* Cached output maxObject (class is immutable).
*/
private transient Long maxObject = null;
/** Cached output hashCode (class is immutable) */
/**
* Cached output hashCode (class is immutable).
*/
private transient int hashCode = 0;
/** Cached output toString (class is immutable) */
/**
* Cached output toString (class is immutable).
*/
private transient String toString = null;
/**
@ -96,7 +108,8 @@ public LongRange(long number) {
* <p>Constructs a new <code>LongRange</code> using the specified
* number as both the minimum and maximum in this range.</p>
*
* @param number the number to use for this range, must not be null
* @param number the number to use for this range, must not
* be <code>null</code>
* @throws IllegalArgumentException if the number is <code>null</code>
*/
public LongRange(Number number) {

20
src/java/org/apache/commons/lang/math/NumberRange.java
View File

@ -57,25 +57,33 @@
/**
* <p><code>NumberRange</code> represents an inclusive range of
* {@link java.lang.Number Number} objects of the same type.</p>
* {@link java.lang.Number} objects of the same type.</p>
*
* @author <a href="mailto:chrise@esha.com">Christopher Elkins</a>
* @author Stephen Colebourne
* @since 2.0 (previously in org.apache.commons.lang)
* @version $Id: NumberRange.java,v 1.3 2003/04/09 01:04:47 ggregory Exp $
* @version $Id: NumberRange.java,v 1.4 2003/07/14 22:25:05 bayard Exp $
*/
public final class NumberRange extends Range implements Serializable {
private static final long serialVersionUID = 71849363892710L;
/* The minimum number in this range. */
/**
* The minimum number in this range.
*/
private final Number min;
/* The maximum number in this range. */
/**
* The maximum number in this range.
*/
private final Number max;
/** Cached output hashCode (class is immutable) */
/**
* Cached output hashCode (class is immutable).
*/
private transient int hashCode = 0;
/** Cached output toString (class is immutable) */
/**
* Cached output toString (class is immutable).
*/
private transient String toString = null;
/**

50
src/java/org/apache/commons/lang/math/NumberUtils.java
View File

@ -69,7 +69,7 @@
* @author Phil Steitz
* @author Matthew Hawthorne
* @since 2.0
* @version $Id: NumberUtils.java,v 1.2 2003/06/28 18:42:03 scolebourne Exp $
* @version $Id: NumberUtils.java,v 1.3 2003/07/14 22:25:05 bayard Exp $
*/
public final class NumberUtils {
@ -443,7 +443,7 @@ public static BigDecimal createBigDecimal(String val) {
// Min in array
//--------------------------------------------------------------------
/**
* Returns the minimum value in an array.
* <p>Returns the minimum value in an array.</p>
*
* @param array an array
* @return the minimum value in the array
@ -470,7 +470,7 @@ public static long min(long[] array) {
}
/**
* Returns the minimum value in an array.
* <p>Returns the minimum value in an array.</p>
*
* @param array an array
* @return the minimum value in the array
@ -497,7 +497,7 @@ public static int min(int[] array) {
}
/**
* Returns the minimum value in an array.
* <p>Returns the minimum value in an array.</p>
*
* @param array an array
* @return the minimum value in the array
@ -524,7 +524,7 @@ public static short min(short[] array) {
}
/**
* Returns the minimum value in an array.
* <p>Returns the minimum value in an array.</p>
*
* @param array an array
* @return the minimum value in the array
@ -551,7 +551,7 @@ public static double min(double[] array) {
}
/**
* Returns the minimum value in an array.
* <p>Returns the minimum value in an array.</p>
*
* @param array an array
* @return the minimum value in the array
@ -580,7 +580,7 @@ public static float min(float[] array) {
// Max in array
//--------------------------------------------------------------------
/**
* Returns the maximum value in an array.
* <p>Returns the maximum value in an array.</p>
*
* @param array an array
* @return the minimum value in the array
@ -607,7 +607,7 @@ public static long max(long[] array) {
}
/**
* Returns the maximum value in an array.
* <p>Returns the maximum value in an array.</p>
*
* @param array an array
* @return the minimum value in the array
@ -634,7 +634,7 @@ public static int max(int[] array) {
}
/**
* Returns the maximum value in an array.
* <p>Returns the maximum value in an array.</p>
*
* @param array an array
* @return the minimum value in the array
@ -661,7 +661,7 @@ public static short max(short[] array) {
}
/**
* Returns the maximum value in an array.
* <p>Returns the maximum value in an array.</p>
*
* @param array an array
* @return the minimum value in the array
@ -688,7 +688,7 @@ public static double max(double[] array) {
}
/**
* Returns the maximum value in an array.
* <p>Returns the maximum value in an array.</p>
*
* @param array an array
* @return the minimum value in the array
@ -791,7 +791,8 @@ public static byte min(byte a, byte b, byte c) {
/**
* <p>Gets the minimum of three <code>double</code> values.</p>
*
* <p>If any value is NaN, NaN is returned. Infinity is handled.</p>
* <p>If any value is <code>NaN</code>, <code>NaN</code> is
* returned. Infinity is handled.</p>
*
* @param a value 1
* @param b value 2
@ -805,8 +806,9 @@ public static double min(double a, double b, double c) {
/**
* <p>Gets the minimum of three <code>float</code> values.</p>
*
* <p>If any value is NaN, NaN is returned. Infinity is handled.</p>
*
* <p>If any value is <code>NaN</code>, <code>NaN</code> is
* returned. Infinity is handled.</p>
*
* @param a value 1
* @param b value 2
* @param c value 3
@ -893,8 +895,9 @@ public static byte max(byte a, byte b, byte c) {
/**
* <p>Gets the maximum of three <code>double</code> values.</p>
*
* <p>If any value is NaN, NaN is returned. Infinity is handled.</p>
*
* <p>If any value is <code>NaN</code>, <code>NaN</code> is
* returned. Infinity is handled.</p>
*
* @param a value 1
* @param b value 2
* @param c value 3
@ -907,8 +910,9 @@ public static double max(double a, double b, double c) {
/**
* <p>Gets the maximum of three <code>float</code> values.</p>
*
* <p>If any value is NaN, NaN is returned. Infinity is handled.</p>
*
* <p>If any value is <code>NaN</code>, <code>NaN</code> is
* returned. Infinity is handled.</p>
*
* @param a value 1
* @param b value 2
* @param c value 3
@ -925,9 +929,9 @@ public static float max(float a, float b, float c) {
* <p>This method is more comprehensive than the standard Java greater
* than, less than and equals operators.</p>
* <ul>
* <li>It returns <code>-1</code> if the first value is less than the second.
* <li>It returns <code>+1</code> if the first value is greater than the second.
* <li>It returns <code>0</code> if the values are equal.
* <li>It returns <code>-1</code> if the first value is less than the second.</li>
* <li>It returns <code>+1</code> if the first value is greater than the second.</li>
* <li>It returns <code>0</code> if the values are equal.</li>
* </ul>
*
* <p>
@ -940,7 +944,7 @@ public static float max(float a, float b, float c) {
* <li>+0.0
* <li>-0.0
* <li>Normal negative numbers
* <li>Minimum double (-Double.MAX_VALUE)
* <li>Minimum double (<code>-Double.MAX_VALUE</code>)
* <li>Negative infinity
* </ul>
* </p>
@ -1002,7 +1006,7 @@ public static int compare(double lhs, double rhs) {
* <li>+0.0
* <li>-0.0
* <li>Normal negative numbers
* <li>Minimum float (-Float.MAX_VALUE)
* <li>Minimum float (<code>-Float.MAX_VALUE</code>)
* <li>Negative infinity
* </ul>
*

31
src/java/org/apache/commons/lang/math/RandomUtils.java
View File

@ -57,12 +57,12 @@
/**
* <p><code>RandomUtils</code> is a wrapper that supports all possible
* Random methods via the java.lang.Math.random() method and its system-wide
* Random object.
* {@link java.util.Random} methods via the {@link java.lang.Math#random()}
* method and its system-wide <code>Random</code> object.
*
* @author Henri Yandell
* @since 2.0
* @version $Id: RandomUtils.java,v 1.2 2003/05/07 15:09:19 bayard Exp $
* @version $Id: RandomUtils.java,v 1.3 2003/07/14 22:25:05 bayard Exp $
*/
public final class RandomUtils {
@ -74,8 +74,8 @@ public final class RandomUtils {
// }
/**
* Returns the next pseudorandom, uniformly distributed int value
* from the Math.random() sequence.
* <p>Returns the next pseudorandom, uniformly distributed int value
* from the Math.random() sequence.</p>
*
* @return the random int
*/
@ -86,9 +86,9 @@ public static int nextInt(Random rnd) {
return rnd.nextInt();
}
/**
* Returns a pseudorandom, uniformly distributed int value between 0
* (inclusive) and the specified value (exclusive), from the
* Math.random() sequence.
* <p>Returns a pseudorandom, uniformly distributed int value
* between <code>0</code> (inclusive) and the specified value
* (exclusive), from the Math.random() sequence.</p>
*
* @param n the specified exclusive max-value
*
@ -102,8 +102,8 @@ public static int nextInt(Random rnd, int n) {
return rnd.nextInt(n);
}
/**
* Returns the next pseudorandom, uniformly distributed long value
* from the Math.random() sequence.
* <p>Returns the next pseudorandom, uniformly distributed long value
* from the Math.random() sequence.</p>
*
* @return the random long
*/
@ -114,8 +114,8 @@ public static long nextLong(Random rnd) {
return rnd.nextLong();
}
/**
* Returns the next pseudorandom, uniformly distributed boolean value
* from the Math.random() sequence.
* <p>Returns the next pseudorandom, uniformly distributed boolean value
* from the Math.random() sequence.</p>
*
* @return the random boolean
*/
@ -126,8 +126,9 @@ public static boolean nextBoolean(Random rnd) {
return rnd.nextBoolean();
}
/**
* Returns the next pseudorandom, uniformly distributed float value
* between 0.0 and 1.0 from the Math.random() sequence.
* <p>Returns the next pseudorandom, uniformly distributed float value
* between <code>0.0</code> and <code>1.0</code> from the Math.random()
* sequence.</p>
*
* @return the random float
*/
@ -138,7 +139,7 @@ public static float nextFloat(Random rnd) {
return rnd.nextFloat();
}
/**
* Synonymous to the Math.random() call.
* <p>Synonymous to the Math.random() call.</p>
*
* @return the random double
*/

62
src/java/org/apache/commons/lang/time/DateFormatUtils.java
View File

@ -58,17 +58,17 @@
import java.util.TimeZone;
/**
* Date and time formatting utilites and constants.
* <p>
* Formatting is performed using the
* {@link org.apache.commons.lang.time.FastDateFormat} class.
* <p>Date and time formatting utilites and constants.</p>
*
* <p>Formatting is performed using the
* {@link org.apache.commons.lang.time.FastDateFormat} class.</p>
*
* @author Apache Ant - DateUtils
* @author <a href="mailto:sbailliez@apache.org">Stephane Bailliez</a>
* @author <a href="mailto:stefan.bodewig@epost.de">Stefan Bodewig</a>
* @author Stephen Colebourne
* @since 2.0
* @version $Id: DateFormatUtils.java,v 1.2 2003/06/09 21:22:31 scolebourne Exp $
* @version $Id: DateFormatUtils.java,v 1.3 2003/07/14 22:25:05 bayard Exp $
*/
public class DateFormatUtils {
@ -143,16 +143,16 @@ public class DateFormatUtils {
//-----------------------------------------------------------------------
/**
* DateFormatUtils instances should NOT be constructed in standard programming.
* <p>
* This constructor is public to permit tools that require a JavaBean instance
* to operate.
* <p>DateFormatUtils instances should NOT be constructed in standard programming.</p>
*
* <p>This constructor is public to permit tools that require a JavaBean instance
* to operate.</p>
*/
public DateFormatUtils() {
}
/**
* Format a date/time into a specific pattern using the UTC timezone.
* <p>Format a date/time into a specific pattern using the UTC timezone.</p>
*
* @param millis the date to format expressed in milliseconds
* @param pattern the pattern to use to format the date
@ -163,7 +163,7 @@ public static String formatUTC(long millis, String pattern) {
}
/**
* Format a date/time into a specific pattern using the UTC timezone.
* <p>Format a date/time into a specific pattern using the UTC timezone.</p>
*
* @param date the date to format
* @param pattern the pattern to use to format the date
@ -174,11 +174,11 @@ public static String formatUTC(Date date, String pattern) {
}
/**
* Format a date/time into a specific pattern using the UTC timezone.
* <p>Format a date/time into a specific pattern using the UTC timezone.</p>
*
* @param millis the date to format expressed in milliseconds
* @param pattern the pattern to use to format the date
* @param locale the locale to use, may be null
* @param locale the locale to use, may be <code>null</code>
* @return the formatted date
*/
public static String formatUTC(long millis, String pattern, Locale locale) {
@ -186,11 +186,11 @@ public static String formatUTC(long millis, String pattern, Locale locale) {
}
/**
* Format a date/time into a specific pattern using the UTC timezone.
* <p>Format a date/time into a specific pattern using the UTC timezone.</p>
*
* @param date the date to format
* @param pattern the pattern to use to format the date
* @param locale the locale to use, may be null
* @param locale the locale to use, may be <code>null</code>
* @return the formatted date
*/
public static String formatUTC(Date date, String pattern, Locale locale) {
@ -198,7 +198,7 @@ public static String formatUTC(Date date, String pattern, Locale locale) {
}
/**
* Format a date/time into a specific pattern.
* <p>Format a date/time into a specific pattern.</p>
*
* @param millis the date to format expressed in milliseconds
* @param pattern the pattern to use to format the date
@ -209,7 +209,7 @@ public static String format(long millis, String pattern) {
}
/**
* Format a date/time into a specific pattern.
* <p>Format a date/time into a specific pattern.</p>
*
* @param date the date to format
* @param pattern the pattern to use to format the date
@ -220,11 +220,11 @@ public static String format(Date date, String pattern) {
}
/**
* Format a date/time into a specific pattern in a timezone.
* <p>Format a date/time into a specific pattern in a timezone.</p>
*
* @param millis the time expressed in milliseconds
* @param pattern the pattern to use to format the date
* @param timeZone the timezone to use, may be null
* @param timeZone the timezone to use, may be <code>null</code>
* @return the formatted date
*/
public static String format(long millis, String pattern, TimeZone timeZone) {
@ -232,11 +232,11 @@ public static String format(long millis, String pattern, TimeZone timeZone) {
}
/**
* Format a date/time into a specific pattern in a timezone.
* <p>Format a date/time into a specific pattern in a timezone.</p>
*
* @param date the date to format
* @param pattern the pattern to use to format the date
* @param timeZone the timezone to use, may be null
* @param timeZone the timezone to use, may be <code>null</code>
* @return the formatted date
*/
public static String format(Date date, String pattern, TimeZone timeZone) {
@ -244,11 +244,11 @@ public static String format(Date date, String pattern, TimeZone timeZone) {
}
/**
* Format a date/time into a specific pattern in a locale.
* <p>Format a date/time into a specific pattern in a locale.</p>
*
* @param millis the date to format expressed in milliseconds
* @param pattern the pattern to use to format the date
* @param locale the locale to use, may be null
* @param locale the locale to use, may be <code>null</code>
* @return the formatted date
*/
public static String format(long millis, String pattern, Locale locale) {
@ -256,11 +256,11 @@ public static String format(long millis, String pattern, Locale locale) {
}
/**
* Format a date/time into a specific pattern in a locale.
* <p>Format a date/time into a specific pattern in a locale.</p>
*
* @param date the date to format
* @param pattern the pattern to use to format the date
* @param locale the locale to use, may be null
* @param locale the locale to use, may be <code>null</code>
* @return the formatted date
*/
public static String format(Date date, String pattern, Locale locale) {
@ -268,12 +268,12 @@ public static String format(Date date, String pattern, Locale locale) {
}
/**
* Format a date/time into a specific pattern in a timezone and locale.
* <p>Format a date/time into a specific pattern in a timezone and locale.</p>
*
* @param millis the date to format expressed in milliseconds
* @param pattern the pattern to use to format the date
* @param timeZone the timezone to use, may be null
* @param locale the locale to use, may be null
* @param timeZone the timezone to use, may be <code>null</code>
* @param locale the locale to use, may be <code>null</code>
* @return the formatted date
*/
public static String format(long millis, String pattern, TimeZone timeZone, Locale locale) {
@ -281,12 +281,12 @@ public static String format(long millis, String pattern, TimeZone timeZone, Loca
}
/**
* Format a date/time into a specific pattern in a timezone and locale.
* <p>Format a date/time into a specific pattern in a timezone and locale.</p>
*
* @param date the date to format
* @param pattern the pattern to use to format the date
* @param timeZone the timezone to use, may be null
* @param locale the locale to use, may be null
* @param timeZone the timezone to use, may be <code>null</code>
* @param locale the locale to use, may be <code>null</code>
* @return the formatted date
*/
public static String format(Date date, String pattern, TimeZone timeZone, Locale locale) {

171
src/java/org/apache/commons/lang/time/DateUtils.java
View File

@ -66,13 +66,14 @@
import java.util.TimeZone;
/**
* A suite of utilities surrounding the use of the Calendar and Date object.
* <p>A suite of utilities surrounding the use of the
* {@link java.util.Calendar} and {@link java.util.Date} object.</p>
*
* @author <a href="mailto:sergek@lokitech.com">Serge Knystautas</a>
* @author Stephen Colebourne
* @author Janek Bogucki
* @since 2.0
* @version $Id: DateUtils.java,v 1.5 2003/06/28 17:49:53 scolebourne Exp $
* @version $Id: DateUtils.java,v 1.6 2003/07/14 22:25:05 bayard Exp $
*/
public class DateUtils {
@ -164,16 +165,19 @@ public DateUtils() {
//-----------------------------------------------------------------------
/**
* Round this date, leaving the field specified as the most significant
* field. For example, if you had the datetime of 28 Mar 2002
* 13:45:01.231, if this was passed with HOUR, it would return 28 Mar
* 2002 14:00:00.000. If this was passed with MONTH, it would return
* 1 April 2002 0:00:00.000.
* <p>Round this date, leaving the field specified as the most
* significant field.</p>
*
* <p>For example, if you had the datetime of 28 Mar 2002
* 13:45:01.231, if this was passed with HOUR, it would return
* 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it
* would return 1 April 2002 0:00:00.000.</p>
*
* @param date the date to work with
* @param field the field from <code>Calendar</code> or SEMI_MONTH
* @param field the field from <code>Calendar</code>
* or <code>SEMI_MONTH</code>
* @return the rounded date
* @throws IllegalArgumentException if the date is null
* @throws IllegalArgumentException if the date is <code>null</code>
*/
public static Date round(Date date, int field) {
if (date == null) {
@ -186,16 +190,19 @@ public static Date round(Date date, int field) {
}
/**
* Round this date, leaving the field specified as the most significant
* field. For example, if you had the datetime of 28 Mar 2002
* 13:45:01.231, if this was passed with HOUR, it would return 28 Mar
* 2002 14:00:00.000. If this was passed with MONTH, it would return
* 1 April 2002 0:00:00.000.
* <p>Round this date, leaving the field specified as the most
* significant field.</p>
*
* <p>For example, if you had the datetime of 28 Mar 2002
* 13:45:01.231, if this was passed with HOUR, it would return
* 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it
* would return 1 April 2002 0:00:00.000.</p>
*
* @param date the date to work with
* @param field the field from <code>Calendar</code> or SEMI_MONTH
* @param field the field from <code>Calendar</code>
* or <code>SEMI_MONTH</code>
* @return the rounded date (a different object)
* @throws IllegalArgumentException if the date is null
* @throws IllegalArgumentException if the date is <code>null</code>
*/
public static Calendar round(Calendar date, int field) {
if (date == null) {
@ -207,17 +214,21 @@ public static Calendar round(Calendar date, int field) {
}
/**
* Round this date, leaving the field specified as the most significant
* field. For example, if you had the datetime of 28 Mar 2002
* 13:45:01.231, if this was passed with HOUR, it would return 28 Mar
* 2002 14:00:00.000. If this was passed with MONTH, it would return
* 1 April 2002 0:00:00.000.
* <p>Round this date, leaving the field specified as the most
* significant field.</p>
*
* <p>For example, if you had the datetime of 28 Mar 2002
* 13:45:01.231, if this was passed with HOUR, it would return
* 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it
* would return 1 April 2002 0:00:00.000.</p>
*
* @param date the date to work with, either Date or Calendar
* @param field the field from <code>Calendar</code> or SEMI_MONTH
* @param field the field from <code>Calendar</code>
* or <code>SEMI_MONTH</code>
* @return the rounded date
* @throws IllegalArgumentException if the date is null
* @throws ClassCastException if the object type is not a Date or Calendar
* @throws IllegalArgumentException if the date is <code>null</code>
* @throws ClassCastException if the object type is not a <code>Date</code>
* or <code>Calendar</code>
*/
public static Date round(Object date, int field) {
if (date == null) {
@ -234,16 +245,19 @@ public static Date round(Object date, int field) {
//-----------------------------------------------------------------------
/**
* Truncate this date, leaving the field specified as the most significant
* field. For example, if you had the datetime of 28 Mar 2002
* <p>Truncate this date, leaving the field specified as the most
* significant field.</p>
*
* <p>For example, if you had the datetime of 28 Mar 2002
* 13:45:01.231, if you passed with HOUR, it would return 28 Mar
* 2002 13:00:00.000. If this was passed with MONTH, it would return
* 1 Mar 2002 0:00:00.000.
* 2002 13:00:00.000. If this was passed with MONTH, it would
* return 1 Mar 2002 0:00:00.000.</p>
*
* @param date the date to work with
* @param field the field from <code>Calendar</code> or SEMI_MONTH
* @param field the field from <code>Calendar</code>
* or <code>SEMI_MONTH</code>
* @return the rounded date
* @throws IllegalArgumentException if the date is null
* @throws IllegalArgumentException if the date is <code>null</code>
*/
public static Date truncate(Date date, int field) {
if (date == null) {
@ -256,16 +270,19 @@ public static Date truncate(Date date, int field) {
}
/**
* Truncate this date, leaving the field specified as the most significant
* field. For example, if you had the datetime of 28 Mar 2002
* <p>Truncate this date, leaving the field specified as the most
* significant field.</p>
*
* <p>For example, if you had the datetime of 28 Mar 2002
* 13:45:01.231, if you passed with HOUR, it would return 28 Mar
* 2002 13:00:00.000. If this was passed with MONTH, it would return
* 1 Mar 2002 0:00:00.000.
* 2002 13:00:00.000. If this was passed with MONTH, it would
* return 1 Mar 2002 0:00:00.000.</p>
*
* @param date the date to work with
* @param field the field from <code>Calendar</code> or SEMI_MONTH
* @param field the field from <code>Calendar</code>
* or <code>SEMI_MONTH</code>
* @return the rounded date (a different object)
* @throws IllegalArgumentException if the date is null
* @throws IllegalArgumentException if the date is <code>null</code>
*/
public static Calendar truncate(Calendar date, int field) {
if (date == null) {
@ -277,17 +294,23 @@ public static Calendar truncate(Calendar date, int field) {
}
/**
* Truncate this date, leaving the field specified as the most significant
* field. For example, if you had the datetime of 28 Mar 2002
* <p>Truncate this date, leaving the field specified as the most
* significant field.</p>
*
* <p>For example, if you had the datetime of 28 Mar 2002
* 13:45:01.231, if you passed with HOUR, it would return 28 Mar
* 2002 13:00:00.000. If this was passed with MONTH, it would return
* 1 Mar 2002 0:00:00.000.
* 2002 13:00:00.000. If this was passed with MONTH, it would
* return 1 Mar 2002 0:00:00.000.</p>
*
* @param date the date to work with, either Date or Calendar
* @param field the field from <code>Calendar</code> or SEMI_MONTH
* @param date the date to work with, either <code>Date</code>
* or <code>Calendar</code>
* @param field the field from <code>Calendar</code>
* or <code>SEMI_MONTH</code>
* @return the rounded date
* @throws IllegalArgumentException if the date is null
* @throws ClassCastException if the object type is not a Date or Calendar
* @throws IllegalArgumentException if the date
* is <code>null</code>
* @throws ClassCastException if the object type is not a
* <code>Date</code> or <code>Calendar</code>
*/
public static Date truncate(Object date, int field) {
if (date == null) {
@ -304,7 +327,7 @@ public static Date truncate(Object date, int field) {
//-----------------------------------------------------------------------
/**
* Internal calculation method
* <p>Internal calculation method.</p>
*
* @param val the calendar
* @param field the field constant
@ -387,7 +410,7 @@ private static void modify(Calendar val, int field, boolean round) {
//-----------------------------------------------------------------------
/**
* Parses a date string formatted in CVS format.
* <p>Parses a date string formatted in CVS format.</p>
*
* @param dateStr the date to parse
* @return the parsed date
@ -398,7 +421,7 @@ public static Calendar parseCVS(String dateStr) {
}
/**
* Parses a date string formatted in CVS format.
* <p>Parses a date string formatted in CVS format.</p>
*
* @param dateStr the date to parse
* @param locale the locale to parse in
@ -517,16 +540,19 @@ public static Calendar parseCVS(String dateStr, Locale locale) {
//-----------------------------------------------------------------------
/**
* This constructs an Iterator that will start and stop over a date
* range based on the focused date and the range style. For instance,
* passing Thursday, July 4, 2002 and a RANGE_MONTH_SUNDAY will return
* an Iterator that starts with Sunday, June 30, 2002 and ends with
* Saturday, August 3, 2002.
* <p>This constructs an <code>Iterator</code> that will
* start and stop over a date range based on the focused
* date and the range style.</p>
*
* <p>For instance, passing Thursday, July 4, 2002 and a
* <code>RANGE_MONTH_SUNDAY</code> will return an
* <code>Iterator</code> that starts with Sunday, June 30,
* 2002 and ends with Saturday, August 3, 2002.
*
* @param focus the date to work with
* @param rangeStyle the style constant to use
* @return the date iterator
* @throws IllegalArgumentException if the date is null
* @throws IllegalArgumentException if the date is <code>null</code>
*/
public static Iterator iterator(Date focus, int rangeStyle) {
if (focus == null) {
@ -538,16 +564,19 @@ public static Iterator iterator(Date focus, int rangeStyle) {
}
/**
* This constructs an Iterator that will start and stop over a date
* range based on the focused date and the range style. For instance,
* passing Thursday, July 4, 2002 and a RANGE_MONTH_SUNDAY will return
* an Iterator that starts with Sunday, June 30, 2002 and ends with
* Saturday, August 3, 2002.
* <p>This constructs an <code>Iterator</code> that will
* start and stop over a date range based on the focused
* date and the range style.</p>
*
* <p>For instance, passing Thursday, July 4, 2002 and a
* <code>RANGE_MONTH_SUNDAY</code> will return an
* <code>Iterator</code> that starts with Sunday, June 30,
* 2002 and ends with Saturday, August 3, 2002.
*
* @param focus the date to work with
* @param rangeStyle the style constant to use
* @return the date iterator
* @throws IllegalArgumentException if the date is null
* @throws IllegalArgumentException if the date is <code>null</code>
*/
public static Iterator iterator(Calendar focus, int rangeStyle) {
if (focus == null) {
@ -622,17 +651,23 @@ public static Iterator iterator(Calendar focus, int rangeStyle) {
}
/**
* This constructs an Iterator that will start and stop over a date
* range based on the focused date and the range style. For instance,
* passing Thursday, July 4, 2002 and a RANGE_MONTH_SUNDAY will return
* an Iterator that starts with Sunday, June 30, 2002 and ends with
* Saturday, August 3, 2002.
* <p>This constructs an <code>Iterator</code> that will
* start and stop over a date range based on the focused
* date and the range style.</p>
*
* <p>For instance, passing Thursday, July 4, 2002 and a
* <code>RANGE_MONTH_SUNDAY</code> will return an
* <code>Iterator</code> that starts with Sunday, June 30,
* 2002 and ends with Saturday, August 3, 2002.</p>
*
* @param focus the date to work with, either Date or Calendar
* @param focus the date to work with, either
* <code>Date</code> or <code>Calendar</code>
* @param rangeStyle the style constant to use
* @return the date iterator
* @throws IllegalArgumentException if the date is null
* @throws ClassCastException if the object type is not a Date or Calendar
* @throws IllegalArgumentException if the date
* is <code>null</code>
* @throws ClassCastException if the object type is
* not a <code>Date</code> or <code>Calendar</code>
*/
public static Iterator iterator(Object focus, int rangeStyle) {
if (focus == null) {
@ -648,7 +683,7 @@ public static Iterator iterator(Object focus, int rangeStyle) {
}
/**
* Date iterator.
* <p>Date iterator.</p>
*/
static class DateIterator implements Iterator {
private final Calendar endFinal;

27
src/java/org/apache/commons/lang/time/DurationFormatUtils.java
View File

@ -54,36 +54,39 @@
package org.apache.commons.lang.time;
/**
* Duration formatting utilites and constants.
* <p>Duration formatting utilites and constants.</p>
*
* @author Apache Ant - DateUtils
* @author <a href="mailto:sbailliez@apache.org">Stephane Bailliez</a>
* @author <a href="mailto:stefan.bodewig@epost.de">Stefan Bodewig</a>
* @author Stephen Colebourne
* @since 2.0
* @version $Id: DurationFormatUtils.java,v 1.2 2003/06/09 21:23:14 scolebourne Exp $
* @version $Id: DurationFormatUtils.java,v 1.3 2003/07/14 22:25:05 bayard Exp $
*/
class DurationFormatUtils {
// TODO: Make class public once methods can fully select which fields to output
/**
* DurationFormatUtils instances should NOT be constructed in standard programming.
* <p>
* This constructor is public to permit tools that require a JavaBean instance
* to operate.
* <p>DurationFormatUtils instances should NOT be constructed in standard programming.</p>
*
* <p>This constructor is public to permit tools that require a JavaBean instance
* to operate.</p>
*/
public DurationFormatUtils() {
}
/**
* Format an elapsed time into a plurialization correct string.
* <p>Format an elapsed time into a plurialization correct string.
* It is limited only to report elapsed time in minutes and
* seconds and has the following behavior.
* seconds and has the following behavior.</p>
*
* <ul>
* <li>minutes are not displayed when 0. (ie: "45 seconds")</li>
* <li>seconds are always displayed in plural form (ie "0 seconds" or
* "10 seconds") except for 1 (ie "1 second")</li>
* </ul>
* <li>minutes are not displayed when <code>0</code>. (ie:
* &quot;45 seconds&quot;)</li>
* <li>seconds are always displayed in plural form (ie
* &quot;0 seconds&quot; or &quot;10 seconds&quot;) except
* for <code>1</code> (ie &quot;1 second&quot;)</li>
* </ul>
*
* @param millis the elapsed time to report in milliseconds
* @return the formatted text in minutes/seconds

268
src/java/org/apache/commons/lang/time/FastDateFormat.java
View File

@ -70,27 +70,29 @@
import java.util.TimeZone;
/**
* FastDateFormat is a fast and thread-safe version of {@link java.text.SimpleDateFormat}.
* <p>
* Only formatting is supported, but all patterns are compatible with
* SimpleDateFormat (except timezones - see below).
* <p>
* Java 1.4 introduced a new pattern letter, 'Z', to represent time zones in
* RFC822 format (eg. +0800 or -1100). This pattern letter can be used here (on
* all JDK versions).
* <p>
* In addition, the pattern 'ZZ' has been made to represent ISO8601 full format
* time zones (eg. +08:00 or -11:00). This introduces a minor incompatability with
* Java 1.4, but at a gain of useful functionality.
* <p>
* NOTE: Code originally taken from the open source TeaTrove project.
* <p>FastDateFormat is a fast and thread-safe version of
* {@link java.text.SimpleDateFormat}.</p>
*
* <p>Only formatting is supported, but all patterns are compatible with
* SimpleDateFormat (except timezones - see below).</p>
*
* <p>Java 1.4 introduced a new pattern letter, <code>'Z'</code>, to represent
* time zones in RFC822 format (eg. <code>+0800</code> or <code>-1100</code>).
* This pattern letter can be used here (on all JDK versions).</p>
*
* <p>In addition, the pattern <code>'ZZ'</code> has been made to represent
* ISO8601 full format time zones (eg. <code>+08:00</code> or <code>-11:00</code>).
* This introduces a minor incompatability with Java 1.4, but at a gain of
* useful functionality.</p>
*
* <p>NOTE: Code originally taken from the open source TreeTrove project.</p>
*
* @author Brian S O'Neill
* @author Sean Schofield
* @author Gary Gregory
* @author Stephen Colebourne
* @since 2.0
* @version $Id: FastDateFormat.java,v 1.7 2003/07/12 08:26:22 scolebourne Exp $
* @version $Id: FastDateFormat.java,v 1.8 2003/07/14 22:25:05 bayard Exp $
*/
public class FastDateFormat extends Format {
// A lot of the speed in this class comes from caching, but some comes
@ -105,13 +107,21 @@ public class FastDateFormat extends Format {
// taking the value and adding (mathematically) the ASCII value for '0'.
// So, don't change this code! It works and is very fast.
/** FULL locale dependent date or time style */
/**
* FULL locale dependent date or time style.
*/
public static final int FULL = SimpleDateFormat.FULL;
/** LONG locale dependent date or time style */
/**
* LONG locale dependent date or time style
*/
public static final int LONG = SimpleDateFormat.LONG;
/** MEDIUM locale dependent date or time style */
/**
* MEDIUM locale dependent date or time style
*/
public static final int MEDIUM = SimpleDateFormat.MEDIUM;
/** SHORT locale dependent date or time style */
/**
* SHORT locale dependent date or time style
*/
public static final int SHORT = SimpleDateFormat.SHORT;
// package scoped as used by inner class
@ -125,24 +135,39 @@ public class FastDateFormat extends Format {
private static Map cDateTimeInstanceCache = new HashMap(7);
private static Map cTimeZoneDisplayCache = new HashMap(7);
/** The pattern */
/**
* The pattern.
*/
private final String mPattern;
/** The time zone */
/**
* The time zone.
*/
private final TimeZone mTimeZone;
/** Whether the time zone overrides any on Calendars */
/**
* Whether the time zone overrides any on Calendars.
*/
private final boolean mTimeZoneForced;
/** The locale */
/**
* The locale.
*/
private final Locale mLocale;
/** Whether the locale overrides the default */
/**
* Whether the locale overrides the default.
*/
private final boolean mLocaleForced;
/** The parsed rules */
/**
* The parsed rules.
*/
private Rule[] mRules;
/** The estimated maximum length */
/**
* The estimated maximum length.
*/
private int mMaxLengthEstimate;
//-----------------------------------------------------------------------
/**
* Gets a formatter instance using the default pattern in the default locale.
* <p>Gets a formatter instance using the default pattern in the
* default locale.</p>
*
* @return a date/time formatter
*/
@ -151,9 +176,11 @@ public static FastDateFormat getInstance() {
}
/**
* Gets a formatter instance using the specified pattern in the default locale.
* <p>Gets a formatter instance using the specified pattern in the
* default locale.</p>
*
* @param pattern {@link java.text.SimpleDateFormat} compatible pattern
* @param pattern {@link java.text.SimpleDateFormat} compatible
* pattern
* @return a pattern based date/time formatter
* @throws IllegalArgumentException if pattern is invalid
*/
@ -162,10 +189,13 @@ public static FastDateFormat getInstance(String pattern) {
}
/**
* Gets a formatter instance using the specified pattern and time zone.
* <p>Gets a formatter instance using the specified pattern and
* time zone.</p>
*
* @param pattern {@link java.text.SimpleDateFormat} compatible pattern
* @param timeZone optional time zone, overrides time zone of formatted date
* @param pattern {@link java.text.SimpleDateFormat} compatible
* pattern
* @param timeZone optional time zone, overrides time zone of
* formatted date
* @return a pattern based date/time formatter
* @throws IllegalArgumentException if pattern is invalid
*/
@ -174,9 +204,11 @@ public static FastDateFormat getInstance(String pattern, TimeZone timeZone) {
}
/**
* Gets a formatter instance using the specified pattern and locale.
* <p>Gets a formatter instance using the specified pattern and
* locale.</p>
*
* @param pattern {@link java.text.SimpleDateFormat} compatible pattern
* @param pattern {@link java.text.SimpleDateFormat} compatible
* pattern
* @param locale optional locale, overrides system locale
* @return a pattern based date/time formatter
* @throws IllegalArgumentException if pattern is invalid
@ -186,13 +218,17 @@ public static FastDateFormat getInstance(String pattern, Locale locale) {
}
/**
* Gets a formatter instance using the specified pattern, time zone and locale.
* <p>Gets a formatter instance using the specified pattern, time zone
* and locale.</p>
*
* @param pattern {@link java.text.SimpleDateFormat} compatible pattern
* @param timeZone optional time zone, overrides time zone of formatted date
* @param pattern {@link java.text.SimpleDateFormat} compatible
* pattern
* @param timeZone optional time zone, overrides time zone of
* formatted date
* @param locale optional locale, overrides system locale
* @return a pattern based date/time formatter
* @throws IllegalArgumentException if pattern is invalid or null
* @throws IllegalArgumentException if pattern is invalid
* or <code>null</code>
*/
public static synchronized FastDateFormat getInstance(String pattern, TimeZone timeZone, Locale locale) {
FastDateFormat emptyFormat = new FastDateFormat(pattern, timeZone, locale);
@ -206,13 +242,16 @@ public static synchronized FastDateFormat getInstance(String pattern, TimeZone t
}
/**
* Gets a date formatter instance using the specified style, time zone and locale.
* <p>Gets a date formatter instance using the specified style, time
* zone and locale.</p>
*
* @param style date style: FULL, LONG, MEDIUM, or SHORT
* @param timeZone optional time zone, overrides time zone of formatted date
* @param timeZone optional time zone, overrides time zone of
* formatted date
* @param locale optional locale, overrides system locale
* @return a localized standard date formatter
* @throws IllegalArgumentException if the Locale has no date pattern defined
* @throws IllegalArgumentException if the Locale has no date
* pattern defined
*/
public static synchronized FastDateFormat getDateInstance(int style, TimeZone timeZone, Locale locale) {
Object key = new Integer(style);
@ -243,13 +282,16 @@ public static synchronized FastDateFormat getDateInstance(int style, TimeZone ti
}
/**
* Gets a time formatter instance using the specified style, time zone and locale.
* <p>Gets a time formatter instance using the specified style, time
* zone and locale.</p>
*
* @param style time style: FULL, LONG, MEDIUM, or SHORT
* @param timeZone optional time zone, overrides time zone of formatted time
* @param timeZone optional time zone, overrides time zone of
* formatted time
* @param locale optional locale, overrides system locale
* @return a localized standard time formatter
* @throws IllegalArgumentException if the Locale has no time pattern defined
* @throws IllegalArgumentException if the Locale has no time
* pattern defined
*/
public static synchronized FastDateFormat getTimeInstance(int style, TimeZone timeZone, Locale locale) {
Object key = new Integer(style);
@ -280,14 +322,17 @@ public static synchronized FastDateFormat getTimeInstance(int style, TimeZone ti
}
/**
* Gets a date/time formatter instance using the specified style, time zone and locale.
* <p>Gets a date/time formatter instance using the specified style,
* time zone and locale.</p>
*
* @param dateStyle date style: FULL, LONG, MEDIUM, or SHORT
* @param timeStyle time style: FULL, LONG, MEDIUM, or SHORT
* @param timeZone optional time zone, overrides time zone of formatted date
* @param timeZone optional time zone, overrides time zone of
* formatted date
* @param locale optional locale, overrides system locale
* @return a localized standard date/time formatter
* @throws IllegalArgumentException if the Locale has no date/time pattern defined
* @throws IllegalArgumentException if the Locale has no date/time
* pattern defined
*/
public static synchronized FastDateFormat getDateTimeInstance(
int dateStyle, int timeStyle, TimeZone timeZone, Locale locale) {
@ -321,11 +366,12 @@ public static synchronized FastDateFormat getDateTimeInstance(
//-----------------------------------------------------------------------
/**
* Gets the time zone display name, using a cache for performance.
* <p>Gets the time zone display name, using a cache for performance.</p>
*
* @param tz the zone to query
* @param daylight true if daylight savings
* @param style the style to use TimeZone.LONG or TimeZone.SHORT
* @param style the style to use <code>TimeZone.LONG</code>
* or <code>TimeZone.SHORT</code>
* @param locale the locale to use
* @return the textual name of the time zone
*/
@ -341,7 +387,7 @@ static synchronized String getTimeZoneDisplay(TimeZone tz, boolean daylight, int
}
/**
* Gets the default pattern.
* <p>Gets the default pattern.</p>
*
* @return the default pattern
*/
@ -355,13 +401,17 @@ private static synchronized String getDefaultPattern() {
// Constructor
//-----------------------------------------------------------------------
/**
* Constructs a new FastDateFormat.
* <p>Constructs a new FastDateFormat.</p>
*
* @param pattern {@link java.text.SimpleDateFormat} compatible pattern
* @param timeZone time zone to use, null means use default for Date and
* value within for Calendar
* @param locale locale, null means use system default
* @throws IllegalArgumentException if pattern is invalid or null
* @param pattern {@link java.text.SimpleDateFormat} compatible
* pattern
* @param timeZone time zone to use, <code>null</code> means use
* default for <code>Date</code> and value within for
* <code>Calendar</code>
* @param locale locale, <code>null</code> means use system
* default
* @throws IllegalArgumentException if pattern is invalid or
* <code>null</code>
*/
protected FastDateFormat(String pattern, TimeZone timeZone, Locale locale) {
super();
@ -384,7 +434,7 @@ protected FastDateFormat(String pattern, TimeZone timeZone, Locale locale) {
}
/**
* Initialise the instance for first use.
* <p>Initialise the instance for first use.</p>
*/
protected void init() {
List rulesList = parsePattern();
@ -401,9 +451,9 @@ protected void init() {
// Parse the pattern
//-----------------------------------------------------------------------
/**
* Returns a list of Rules given a pattern.
* <p>Returns a list of Rules given a pattern.</p>
*
* @return a List of Rule objects
* @return a <code>List</code> of Rule objects
* @throws IllegalArgumentException if pattern is invalid
*/
protected List parsePattern() {
@ -530,7 +580,7 @@ protected List parsePattern() {
}
/**
* Performs the parsing of tokens.
* <p>Performs the parsing of tokens.</p>
*
* @param pattern the pattern
* @param indexRef index references
@ -589,7 +639,7 @@ protected String parseToken(String pattern, int[] indexRef) {
}
/**
* Gets an appropriate rule for the padding required.
* <p>Gets an appropriate rule for the padding required.</p>
*
* @param field the field to get a rule for
* @param padding the padding required
@ -609,7 +659,8 @@ protected NumberRule selectNumberRule(int field, int padding) {
// Format methods
//-----------------------------------------------------------------------
/**
* Format either a Date or a Calendar object.
* <p>Format either a <code>Date</code> or a
* <code>Calendar</code> object.</p>
*
* @param obj the object to format
* @param toAppendTo the buffer to append to
@ -628,7 +679,7 @@ public StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition po
}
/**
* Formats a Date object.
* <p>Formats a <code>Date</code> object.</p>
*
* @param date the date to format
* @return the formatted string
@ -640,7 +691,7 @@ public String format(Date date) {
}
/**
* Formats a Calendar object.
* <p>Formats a <code>Calendar</code> object.</p>
*
* @param calendar the calendar to format
* @return the formatted string
@ -650,7 +701,8 @@ public String format(Calendar calendar) {
}
/**
* Formats a Date object into the supplied StringBuffer.
* <p>Formats a <code>Date</code> object into the
* supplied <code>StringBuffer</code>.</p>
*
* @param date the date to format
* @param buf the buffer to format into
@ -663,7 +715,8 @@ public StringBuffer format(Date date, StringBuffer buf) {
}
/**
* Formats a Calendar object into the supplied StringBuffer.
* <p>Formats a <code>Calendar</code> object into the
* supplied <code>StringBuffer</code>.</p>
*
* @param calendar the calendar to format
* @param buf the buffer to format into
@ -678,7 +731,8 @@ public StringBuffer format(Calendar calendar, StringBuffer buf) {
}
/**
* Performs the formatting by applying the rules to the specified calendar.
* <p>Performs the formatting by applying the rules to the
* specified calendar.</p>
*
* @param calendar the calendar to format
* @param buf the buffer to format into
@ -696,11 +750,11 @@ protected StringBuffer applyRules(Calendar calendar, StringBuffer buf) {
// Parsing
//-----------------------------------------------------------------------
/**
* Parsing not supported.
* <p>Parsing not supported.</p>
*
* @param source the string to parse
* @param pos the parsing position
* @return null as not supported
* @return <code>null</code> as not supported
*/
public Object parseObject(String source, ParsePosition pos) {
pos.setIndex(0);
@ -711,7 +765,7 @@ public Object parseObject(String source, ParsePosition pos) {
// Accessors
//-----------------------------------------------------------------------
/**
* Gets the pattern used by this formatter.
* <p>Gets the pattern used by this formatter.</p>
*
* @return the pattern, {@link java.text.SimpleDateFormat} compatible
*/
@ -720,11 +774,12 @@ public String getPattern() {
}
/**
* Gets the time zone used by this formatter.
* <p>
* This zone is always used for Date formatting.
* If a Calendar is passed in to be formatted, the time zone on that may
* be used depending on {@link #getTimeZoneOverridesCalendar()}.
* <p>Gets the time zone used by this formatter.</p>
*
* <p>This zone is always used for <code>Date</code> formatting.
* If a <code>Calendar</code> is passed in to be formatted, the
* time zone on that may be used depending on
* {@link #getTimeZoneOverridesCalendar()}.</p>
*
* @return the time zone
*/
@ -733,17 +788,18 @@ public TimeZone getTimeZone() {
}
/**
* Returns true if the time zone of the calendar overrides the time zone
* of the formatter
* <p>Returns <code>true</code> if the time zone of the
* calendar overrides the time zone of the formatter.</p>
*
* @return true if time zone of formatter overridden for calendars
* @return <code>true</code> if time zone of formatter
* overridden for calendars
*/
public boolean getTimeZoneOverridesCalendar() {
return mTimeZoneForced;
}
/**
* Gets the locale used by this formatter.
* <p>Gets the locale used by this formatter.</p>
*
* @return the locale
*/
@ -752,8 +808,11 @@ public Locale getLocale() {
}
/**
* Gets an estimate for the maximum string length that the formatter will produce.
* The actual formatted length will almost always be less than or equal to this amount.
* <p>Gets an estimate for the maximum string length that the
* formatter will produce.</p>
*
* <p>The actual formatted length will almost always be less than or
* equal to this amount.</p>
*
* @return the maximum formatted length
*/
@ -764,10 +823,10 @@ public int getMaxLengthEstimate() {
// Basics
//-----------------------------------------------------------------------
/**
* Compare two objects for equality.
* <p>Compare two objects for equality.</p>
*
* @param obj the object to compare to
* @return true if equal
* @return <code>true</code> if equal
*/
public boolean equals(Object obj) {
if (obj instanceof FastDateFormat == false) {
@ -787,7 +846,7 @@ public boolean equals(Object obj) {
}
/**
* A suitable hashcode.
* <p>A suitable hashcode.</p>
*
* @return a hashcode compatable with equals
*/
@ -802,7 +861,7 @@ public int hashCode() {
}
/**
* Gets a debugging string version of this formatter.
* <p>Gets a debugging string version of this formatter.</p>
*
* @return a debugging string
*/
@ -813,7 +872,7 @@ public String toString() {
// Rules
//-----------------------------------------------------------------------
/**
* Inner class defining a rule.
* <p>Inner class defining a rule.</p>
*/
private interface Rule {
int estimateLength();
@ -821,14 +880,14 @@ private interface Rule {
}
/**
* Inner class defining a numeric rule.
* <p>Inner class defining a numeric rule.</p>
*/
private interface NumberRule extends Rule {
void appendTo(StringBuffer buffer, int value);
}
/**
* Inner class to output a constant single character.
* <p>Inner class to output a constant single character.</p>
*/
private static class CharacterLiteral implements Rule {
private final char mValue;
@ -847,7 +906,7 @@ public void appendTo(StringBuffer buffer, Calendar calendar) {
}
/**
* Inner class to output a constant string.
* <p>Inner class to output a constant string.</p>
*/
private static class StringLiteral implements Rule {
private final String mValue;
@ -866,7 +925,7 @@ public void appendTo(StringBuffer buffer, Calendar calendar) {
}
/**
* Inner class to output one of a set of values.
* <p>Inner class to output one of a set of values.</p>
*/
private static class TextField implements Rule {
private final int mField;
@ -894,7 +953,7 @@ public void appendTo(StringBuffer buffer, Calendar calendar) {
}
/**
* Inner class to output an unpadded number.
* <p>Inner class to output an unpadded number.</p>
*/
private static class UnpaddedNumberField implements NumberRule {
static final UnpaddedNumberField INSTANCE_YEAR = new UnpaddedNumberField(Calendar.YEAR);
@ -926,7 +985,7 @@ public final void appendTo(StringBuffer buffer, int value) {
}
/**
* Inner class to output an unpadded month.
* <p>Inner class to output an unpadded month.</p>
*/
private static class UnpaddedMonthField implements NumberRule {
static final UnpaddedMonthField INSTANCE = new UnpaddedMonthField();
@ -953,7 +1012,7 @@ public final void appendTo(StringBuffer buffer, int value) {
}
/**
* Inner class to output a padded number.
* <p>Inner class to output a padded number.</p>
*/
private static class PaddedNumberField implements NumberRule {
private final int mField;
@ -999,7 +1058,7 @@ public final void appendTo(StringBuffer buffer, int value) {
}
/**
* Inner class to output a two digit number.
* <p>Inner class to output a two digit number.</p>
*/
private static class TwoDigitNumberField implements NumberRule {
private final int mField;
@ -1027,7 +1086,7 @@ public final void appendTo(StringBuffer buffer, int value) {
}
/**
* Inner class to output a two digit year.
* <p>Inner class to output a two digit year.</p>
*/
private static class TwoDigitYearField implements NumberRule {
static final TwoDigitYearField INSTANCE = new TwoDigitYearField();
@ -1050,7 +1109,7 @@ public final void appendTo(StringBuffer buffer, int value) {
}
/**
* Inner class to output a two digit month.
* <p>Inner class to output a two digit month.</p>
*/
private static class TwoDigitMonthField implements NumberRule {
static final TwoDigitMonthField INSTANCE = new TwoDigitMonthField();
@ -1073,7 +1132,7 @@ public final void appendTo(StringBuffer buffer, int value) {
}
/**
* Inner class to output the twelve hour field.
* <p>Inner class to output the twelve hour field.</p>
*/
private static class TwelveHourField implements NumberRule {
private final NumberRule mRule;
@ -1100,7 +1159,7 @@ public void appendTo(StringBuffer buffer, int value) {
}
/**
* Inner class to output the twenty four hour field.
* <p>Inner class to output the twenty four hour field.</p>
*/
private static class TwentyFourHourField implements NumberRule {
private final NumberRule mRule;
@ -1127,7 +1186,7 @@ public void appendTo(StringBuffer buffer, int value) {
}
/**
* Inner class to output a time zone name.
* <p>Inner class to output a time zone name.</p>
*/
private static class TimeZoneNameRule implements Rule {
private final TimeZone mTimeZone;
@ -1181,7 +1240,8 @@ public void appendTo(StringBuffer buffer, Calendar calendar) {
}
/**
* Inner class to output a time zone as a number +/-HHMM or +/-HH:MM.
* <p>Inner class to output a time zone as a number <code>+/-HHMM</code>
* or <code>+/-HH:MM</code>.</p>
*/
private static class TimeZoneNumberRule implements Rule {
static final TimeZoneNumberRule INSTANCE_COLON = new TimeZoneNumberRule(true);
@ -1223,7 +1283,7 @@ public void appendTo(StringBuffer buffer, Calendar calendar) {
// ----------------------------------------------------------------------
/**
* Inner class that acts as a compound key for time zone names.
* <p>Inner class that acts as a compound key for time zone names.</p>
*/
private static class TimeZoneDisplayKey {
private final TimeZone mTimeZone;
@ -1261,8 +1321,10 @@ public boolean equals(Object obj) {
// ----------------------------------------------------------------------
/**
* Helper class for creating compound objects. One use for this class is to create a
* hashtable key out of multiple objects.
* <p>Helper class for creating compound objects.</p>
*
* <p>One use for this class is to create a hashtable key
* out of multiple objects.</p>
*/
private static class Pair {
private final Object mObj1;

25
src/java/org/apache/commons/lang/time/StopWatch.java
View File

@ -62,14 +62,15 @@
*
* <p>To start the watch, call {@link #start()}. At this point you can:</p>
* <ul>
* <li>{@link #split()} the watch to get the time whilst the watch continues in the
* background. {@link #unsplit()} will remove the effect of the split. At this point,
* these three options are available again.
* <li>{@link #suspend()} the watch to pause it. {@link #resume()} allows the watch
* to continue. Any time between the suspend and resume will not be counted in
* the total. At this point, these three options are available again.
* <li>{@link #stop()} the watch to complete the timing session.
* <li>{@link #split()} the watch to get the time whilst the watch continues in the
* background. {@link #unsplit()} will remove the effect of the split. At this point,
* these three options are available again.</li>
* <li>{@link #suspend()} the watch to pause it. {@link #resume()} allows the watch
* to continue. Any time between the suspend and resume will not be counted in
* the total. At this point, these three options are available again.</li>
* <li>{@link #stop()} the watch to complete the timing session.</li>
* </ul>
*
* <p>It is intended that the output methods {@link #toString()} and {@link #getTime()}
* should only be called after stop, split or suspend, however a suitable result will
* be returned at other points.</p>
@ -77,13 +78,17 @@
* @author Henri Yandell
* @author Stephen Colebourne
* @since 2.0
* @version $Id: StopWatch.java,v 1.4 2003/06/08 23:14:23 scolebourne Exp $
* @version $Id: StopWatch.java,v 1.5 2003/07/14 22:25:05 bayard Exp $
*/
public class StopWatch {
/** The start time */
/**
* The start time.
*/
private long startTime = -1;
/** The stop time */
/**
* The stop time.
*/
private long stopTime = -1;
/**

170
src/java/org/apache/commons/lang/util/BitField.java
View File

@ -54,16 +54,16 @@
package org.apache.commons.lang.util;
/**
* Manage operations dealing with bit-mapped fields.
* <p>
* Code originated from the POI project.
* <p>Manage operations dealing with bit-mapped fields.</p>
*
* <p>Code originated from the POI project.</p>
*
* @author Scott Sanders (sanders at apache dot org)
* @author Marc Johnson (mjohnson at apache dot org)
* @author Andrew C. Oliver (acoliver at apache dot org)
* @author Stephen Colebourne
* @since 2.0
* @version $Id: BitField.java,v 1.5 2003/04/09 00:07:49 ggregory Exp $
* @version $Id: BitField.java,v 1.6 2003/07/14 22:25:06 bayard Exp $
*/
public class BitField {
@ -71,11 +71,11 @@ public class BitField {
private final int _shift_count;
/**
* Create a BitField instance
* <p>Create a BitField instance.</p>
*
* @param mask the mask specifying which bits apply to this
* BitField. Bits that are set in this mask are the
* bits that this BitField operates on
* BitField. Bits that are set in this mask are the bits
* that this BitField operates on
*/
public BitField(final int mask) {
_mask = mask;
@ -92,15 +92,16 @@ public BitField(final int mask) {
}
/**
* Obtain the value for the specified BitField, appropriately
* shifted right. Many users of a BitField will want to treat the
* specified bits as an int value, and will not want to be aware
* that the value is stored as a BitField (and so shifted left so
* many bits)
* <p>Obtain the value for the specified BitField, appropriately
* shifted right.</p>
*
* <p>Many users of a BitField will want to treat the specified
* bits as an int value, and will not want to be aware that the
* value is stored as a BitField (and so shifted left so many
* bits).</p>
*
* @param holder the int data containing the bits we're interested
* in
*
* in
* @return the selected bits, shifted right appropriately
*/
public int getValue(final int holder) {
@ -108,15 +109,16 @@ public int getValue(final int holder) {
}
/**
* Obtain the value for the specified BitField, appropriately
* shifted right, as a short. Many users of a BitField will want
* to treat the specified bits as an int value, and will not want
* to be aware that the value is stored as a BitField (and so
* shifted left so many bits)
* <p>Obtain the value for the specified BitField, appropriately
* shifted right, as a short.</p>
*
* <p>Many users of a BitField will want to treat the specified
* bits as an int value, and will not want to be aware that the
* value is stored as a BitField (and so shifted left so many
* bits).</p>
*
* @param holder the short data containing the bits we're
* interested in
*
* interested in
* @return the selected bits, shifted right appropriately
*/
public short getShortValue(final short holder) {
@ -124,11 +126,10 @@ public short getShortValue(final short holder) {
}
/**
* Obtain the value for the specified BitField, unshifted
*
* @param holder the int data containing the bits we're interested
* in
* <p>Obtain the value for the specified BitField, unshifted.</p>
*
* @param holder the int data containing the bits we're
* interested in
* @return the selected bits
*/
public int getRawValue(final int holder) {
@ -136,11 +137,10 @@ public int getRawValue(final int holder) {
}
/**
* Obtain the value for the specified BitField, unshifted
* <p>Obtain the value for the specified BitField, unshifted.</p>
*
* @param holder the short data containing the bits we're
* interested in
*
* interested in
* @return the selected bits
*/
public short getShortRawValue(final short holder) {
@ -148,144 +148,144 @@ public short getShortRawValue(final short holder) {
}
/**
* Returns whether the field is set or not. This is most commonly used for a
* single-bit field, which is often used to represent a boolean
* value; the results of using it for a multi-bit field is to
* determine whether *any* of its bits are set
* <p>Returns whether the field is set or not.</p>
*
* <p>This is most commonly used for a single-bit field, which is
* often used to represent a boolean value; the results of using
* it for a multi-bit field is to determine whether *any* of its
* bits are set.</p>
*
* @param holder the int data containing the bits we're interested
* in
*
* @return true if any of the bits are set, else false
* in
* @return <code>true</code> if any of the bits are set,
* else <code>false</code>
*/
public boolean isSet(final int holder) {
return (holder & _mask) != 0;
}
/**
* Returns whether all of the bits are set or not. This is a stricter test than
* isSet, in that all of the bits in a multi-bit set must be set
* for this method to return true
* <p>Returns whether all of the bits are set or not.</p>
*
* @param holder the int data containing the bits we're interested
* in
* <p>This is a stricter test than {@link #isSet(int)},
* in that all of the bits in a multi-bit set must be set
* for this method to return <code>true</code>.</p>
*
* @return true if all of the bits are set, else false
* @param holder the int data containing the bits we're
* interested in
* @return <code>true</code> if all of the bits are set,
* else <code>false</code>
*/
public boolean isAllSet(final int holder) {
return (holder & _mask) == _mask;
}
/**
* Replace the bits with new values.
* <p>Replace the bits with new values.</p>
*
* @param holder the int data containint the bits we're interested
* in
* @param holder the int data containint the bits we're
* interested in
* @param value the new value for the specified bits
*
* @return the value of holder with the bits from the value
* parameter replacing the old bits
* parameter replacing the old bits
*/
public int setValue(final int holder, final int value) {
return (holder & ~_mask) | ((value << _shift_count) & _mask);
}
/**
* Replace the bits with new values.
* <p>Replace the bits with new values.</p>
*
* @param holder the short data containing the bits we're
* interested in
* interested in
* @param value the new value for the specified bits
*
* @return the value of holder with the bits from the value
* parameter replacing the old bits
* parameter replacing the old bits
*/
public short setShortValue(final short holder, final short value) {
return (short) setValue(holder, value);
}
/**
* Clear the bits.
*
* @param holder the int data containing the bits we're interested
* in
* <p>Clear the bits.</p>
*
* @param holder the int data containing the bits we're
* interested in
* @return the value of holder with the specified bits cleared
* (set to 0)
* (set to <code>0</code>)
*/
public int clear(final int holder) {
return holder & ~_mask;
}
/**
* Clear the bits.
* <p>Clear the bits.</p>
*
* @param holder the short data containing the bits we're
* interested in
*
* interested in
* @return the value of holder with the specified bits cleared
* (set to 0)
* (set to <code>0</code>)
*/
public short clearShort(final short holder) {
return (short) clear(holder);
}
/**
* Clear the bits.
* <p>Clear the bits.</p>
*
* @param holder the byte data containing the bits we're
* interested in
* interested in
*
* @return the value of holder with the specified bits cleared
* (set to 0)
* (set to <code>0</code>)
*/
public byte clearByte(final byte holder) {
return (byte) clear(holder);
}
/**
* Set the bits.
* <p>Set the bits.</p>
*
* @param holder the int data containing the bits we're interested
* in
*
* @return the value of holder with the specified bits set to 1
* @param holder the int data containing the bits we're
* interested in
* @return the value of holder with the specified bits set
* to <code>1</code>
*/
public int set(final int holder) {
return holder | _mask;
}
/**
* Set the bits.
* <p>Set the bits.</p>
*
* @param holder the short data containing the bits we're
* interested in
*
* @return the value of holder with the specified bits set to 1
* interested in
* @return the value of holder with the specified bits set
* to <code>1</code>
*/
public short setShort(final short holder) {
return (short) set(holder);
}
/**
* Set the bits.
* <p>Set the bits.</p>
*
* @param holder the byte data containing the bits we're
* interested in
* interested in
*
* @return the value of holder with the specified bits set to 1
* @return the value of holder with the specified bits set
* to <code>1</code>
*/
public byte setByte(final byte holder) {
return (byte) set(holder);
}
/**
* Set a boolean BitField
* <p>Set a boolean BitField.</p>
*
* @param holder the int data containing the bits we're interested
* in
* @param holder the int data containing the bits we're
* interested in
* @param flag indicating whether to set or clear the bits
*
* @return the value of holder with the specified bits set or
* cleared
*/
@ -294,28 +294,26 @@ public int setBoolean(final int holder, final boolean flag) {
}
/**
* Set a boolean BitField
* <p>Set a boolean BitField.</p>
*
* @param holder the short data containing the bits we're
* interested in
* interested in
* @param flag indicating whether to set or clear the bits
*
* @return the value of holder with the specified bits set or
* cleared
* cleared
*/
public short setShortBoolean(final short holder, final boolean flag) {
return flag ? setShort(holder) : clearShort(holder);
}
/**
* Set a boolean BitField
* <p>Set a boolean BitField.</p>
*
* @param holder the byte data containing the bits we're
* interested in
* interested in
* @param flag indicating whether to set or clear the bits
*
* @return the value of holder with the specified bits set or
* cleared
* cleared
*/
public byte setByteBoolean(final byte holder, final boolean flag) {
return flag ? setByte(holder) : clearByte(holder);

107
src/java/org/apache/commons/lang/util/IdentifierUtils.java
View File

@ -67,7 +67,7 @@
*
* @author Stephen Colebourne
* @since 2.0
* @version $Id: IdentifierUtils.java,v 1.5 2003/05/16 22:06:43 scolebourne Exp $
* @version $Id: IdentifierUtils.java,v 1.6 2003/07/14 22:25:06 bayard Exp $
*/
public class IdentifierUtils {
@ -80,10 +80,10 @@ public class IdentifierUtils {
*
* <p>The objects returned are:</p>
* <ul>
* <li>new Long(0L)
* <li>new Long(1L)
* <li>new Long(2L)
* <li>...
* <li>new Long(0L)</li>
* <li>new Long(1L)</li>
* <li>new Long(2L)</li>
* <li>...</li>
* </ul>
*/
public static final LongIdentifierFactory LONG_IDENTIFIER_FACTORY = new LongNumericIdentifierFactory(true, 0L);
@ -96,10 +96,10 @@ public class IdentifierUtils {
*
* <p>The objects returned are:</p>
* <ul>
* <li>"0"
* <li>"1"
* <li>"2"
* <li>...
* <li>&quot;0&quot;</li>
* <li>&quot;1&quot;</li>
* <li>&quot;2&quot;</li>
* <li>...</li>
* </ul>
*/
public static final StringIdentifierFactory STRING_NUMERIC_IDENTIFIER_FACTORY = new StringNumericIdentifierFactory(true, 0L);
@ -113,18 +113,18 @@ public class IdentifierUtils {
*
* <p>The objects returned are:</p>
* <ul>
* <li>"000000000000001"
* <li>"000000000000002"
* <li>"000000000000003"
* <li>&quot;000000000000001&quot;</li>
* <li>&quot;000000000000002&quot;</li>
* <li>&quot;000000000000003&quot;</li>
* <li>...
* <li>"00000000000000y"
* <li>"00000000000000z"
* <li>"000000000000010"
* <li>"000000000000011"
* <li>...
* <li>"00000000000001z"
* <li>"000000000000020"
* <li>&quot;00000000000000y&quot;</li>
* <li>&quot;00000000000000z&quot;</li>
* <li>&quot;000000000000010&quot;</li>
* <li>&quot;000000000000011&quot;</li>
* <li>...
* <li>&quot;00000000000001z&quot;</li>
* <li>&quot;000000000000020&quot;</li>
* <li>...</li>
* </ul>
*/
public static final StringIdentifierFactory STRING_ALPHANUMERIC_IDENTIFIER_FACTORY = new StringAlphanumericIdentifierFactory(true, 15);
@ -156,8 +156,7 @@ public IdentifierUtils() {
/**
* <p>Gets the next identifier using the singleton instance of the
* Long factory.
* </p>
* Long factory.</p>
*
* <p>The singleton instance will wrap, so in a long-lived server, the id
* may be duplicated.</p>
@ -185,7 +184,7 @@ public static LongIdentifierFactory longIdentifierFactory() {
* <p>Gets a new identifier factory that returns a series of Long objects
* increasing in size.</p>
*
* @param wrap should the factory wrap when it reaches the maximum
* @param wrap should the factory wrap when it reaches the maximum
* long value (or throw an IllegalStateException)
* @param initialValue the initial long value to start at
* @return a new identifier factory
@ -198,8 +197,7 @@ public static LongIdentifierFactory longIdentifierFactory(boolean wrap, long ini
/**
* <p>Gets the next identifier using the singleton instance of the
* String Numeric factory.
* </p>
* String Numeric factory.</p>
*
* <p>The singleton instance will wrap, so in a long-lived server, the id
* may be duplicated.</p>
@ -227,7 +225,7 @@ public static StringIdentifierFactory stringNumericIdentifierFactory() {
* <p>Gets a new identifier factory that returns a series of String objects
* representing numbers increasing in size.</p>
*
* @param wrap should the factory wrap when it reaches the maximum
* @param wrap should the factory wrap when it reaches the maximum
* long value (or throw an IllegalStateException)
* @param initialValue the initial long value to start at
* @return a new identifier factory
@ -240,8 +238,7 @@ public static StringIdentifierFactory stringNumericIdentifierFactory(boolean wra
/**
* <p>Gets the next identifier using the singleton instance of the
* String Alphanumeric factory.
* </p>
* String Alphanumeric factory.</p>
*
* <p>The singleton instance will wrap, so in a long-lived server, the id
* may be duplicated.</p>
@ -268,7 +265,7 @@ public static StringIdentifierFactory stringAlphanumericIdentifierFactory() {
* <p>Gets a new identifier factory that returns a series of String objects
* representing numbers increasing in size in base-36.</p>
*
* @param wrap should the factory wrap when it reaches the maximum
* @param wrap should the factory wrap when it reaches the maximum
* size (or throw an IllegalStateException)
* @param size the number of characters the id should fill
* @return a new identifier factory
@ -281,8 +278,7 @@ public static StringIdentifierFactory stringAlphanumericIdentifierFactory(boolea
/**
* <p>Gets the next identifier using the singleton instance of the
* String Session factory.
* </p>
* String Session factory.</p>
*
* <p>The generation routine is based on a random number and a counter
* within a 2 second time interval.</p>
@ -295,8 +291,7 @@ public static String nextStringSessionIdentifier() {
/**
* <p>Gets a new identifier factory that returns a series of String objects
* that appear to be random and are suitable for use as session identifiers.
* </p>
* that appear to be random and are suitable for use as session identifiers.</p>
*
* <p>The generation routine is based on a random number and a counter
* within a 2 second time interval.</p>
@ -310,8 +305,8 @@ public static StringIdentifierFactory stringSessionIdentifierFactory() {
//---------------------------------------------------------------------------------
/**
* <code>LongIdentifierFactory</code> is an Identifier Factory
* that generates an incrementing number as a Long object.
* <p><code>LongIdentifierFactory</code> is an Identifier Factory
* that generates an incrementing number as a Long object.</p>
*
* @author Stephen Colebourne
*/
@ -323,9 +318,9 @@ private static class LongNumericIdentifierFactory implements LongIdentifierFacto
private long count = 0;
/**
* Constructor.
* <p>Constructor.</p>
*
* @param wrap should the factory wrap when it reaches the maximum
* @param wrap should the factory wrap when it reaches the maximum
* long value (or throw an exception)
* @param initialValue the initial long value to start at
*/
@ -336,7 +331,7 @@ private LongNumericIdentifierFactory(boolean wrap, long initialValue) {
}
/**
* Gets the next new identifier.
* <p>Gets the next new identifier.</p>
*
* @return a new identifier as a Long
*/
@ -345,7 +340,7 @@ public Object nextIdentifier() {
}
/**
* Gets the next new identifier.
* <p>Gets the next new identifier.</p>
*
* @return a new identifier as a Long
*/
@ -370,8 +365,8 @@ public Long nextLongIdentifier() {
//---------------------------------------------------------------------------------
/**
* <code>StringNumericIdentifierFactory</code> is an Identifier Factory
* that generates an incrementing number as a String object.
* <p><code>StringNumericIdentifierFactory</code> is an Identifier Factory
* that generates an incrementing number as a String object.</p>
*
* @author Stephen Colebourne
*/
@ -383,9 +378,9 @@ private static class StringNumericIdentifierFactory implements StringIdentifierF
private long count = 0;
/**
* Constructor.
* <p>Constructor.</p>
*
* @param wrap should the factory wrap when it reaches the maximum
* @param wrap should the factory wrap when it reaches the maximum
* long value (or throw an exception)
* @param initialValue the initial long value to start at
*/
@ -396,7 +391,7 @@ private StringNumericIdentifierFactory(boolean wrap, long initialValue) {
}
/**
* Gets the next new identifier.
* <p>Gets the next new identifier.</p>
*
* @return a new identifier as a String
*/
@ -405,7 +400,7 @@ public Object nextIdentifier() {
}
/**
* Gets the next new identifier.
* <p>Gets the next new identifier.</p>
*
* @return a new identifier as a String
*/
@ -431,9 +426,9 @@ public String nextStringIdentifier() {
//---------------------------------------------------------------------------------
/**
* <code>StringAlphanumericIdentifierFactory</code> is an Identifier Factory
* <p><code>StringAlphanumericIdentifierFactory</code> is an Identifier Factory
* that generates an incrementing incrementing number in base 36 as a String
* object.
* object.</p>
*
* @author Stephen Colebourne
*/
@ -445,9 +440,9 @@ private static class StringAlphanumericIdentifierFactory implements StringIdenti
private char[] count = null;
/**
* Constructor.
* <p>Constructor.</p>
*
* @param wrap should the factory wrap when it reaches the maximum
* @param wrap should the factory wrap when it reaches the maximum
* long value (or throw an exception)
* @param size the size of the identifier
*/
@ -464,7 +459,7 @@ private StringAlphanumericIdentifierFactory(boolean wrap, int size) {
}
/**
* Gets the next new identifier.
* <p>Gets the next new identifier.</p>
*
* @return a new identifier as a String
*/
@ -473,7 +468,7 @@ public Object nextIdentifier() {
}
/**
* Gets the next new identifier.
* <p>Gets the next new identifier.</p>
*
* @return a new identifier as a String
*/
@ -547,14 +542,14 @@ private static class StringSessionIdentifierFactory implements StringIdentifierF
private Random randomizer = new Random();
/**
* Constructor.
* <p>Constructor.</p>
*/
private StringSessionIdentifierFactory() {
super();
}
/**
* Gets the next identifier.
* <p>Gets the next identifier.</p>
*
* @return the next 10 char String identifier
*/
@ -563,11 +558,13 @@ public Object nextIdentifier() {
}
/**
* Gets the next new identifier. Only guaranteed unique within
* this JVM, but fairly safe for cross JVM usage as well.
* <p>Gets the next new identifier.</p>
*
* <p>Only guaranteed unique within this JVM, but fairly safe
* for cross JVM usage as well.</p>
*
* <p>Format of identifier is
* [6 chars random][3 chars time][1+ chars count]</p>
* <code>[6 chars random][3 chars time][1+ chars count]</code></p>
*
* @return the next 10 char String identifier
*/

195
src/java/org/apache/commons/lang/util/Validate.java
View File

@ -70,7 +70,7 @@
* @author <a href="mailto:ola.berg@arkitema.se">Ola Berg</a>
* @author Stephen Colebourne
* @since 2.0
* @version $Id: Validate.java,v 1.2 2003/03/23 17:52:25 scolebourne Exp $
* @version $Id: Validate.java,v 1.3 2003/07/14 22:25:06 bayard Exp $
*/
public class Validate {
@ -84,22 +84,25 @@ public Validate() {
//---------------------------------------------------------------------------------
/**
* <p>Validate an argument, throwing IllegalArgumentException if the test
* result is false.
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the test result is <code>false</code>.</p>
*
* <p>This is used when validating according to an arbitrary boolean expression,
* such as validating a primitive number or using your own custom validation
* expression.
* expression.</p>
*
* <pre>
* Validate.isTrue( myObject.isOk(), "The object is not OK: ", myObject);
* </pre>
*
* <p>For performance reasons, the object is passed as a separate parameter and
* appended to the message string only in the case of an error.
* appended to the message string only in the case of an error.</p>
*
* @param expression a boolean expression
* @param message the exception message you would like to see if the expression is false
* @param message the exception message you would like to see if the
* expression is <code>false</code>
* @param value the value to append to the message in case of error
* @throws IllegalArgumentException if expression is false
* @throws IllegalArgumentException if expression is <code>false</code>
*/
public static void isTrue(boolean expression, String message, Object value) {
if (expression == false) {
@ -108,22 +111,24 @@ public static void isTrue(boolean expression, String message, Object value) {
}
/**
* <p>Validate an argument, throwing IllegalArgumentException if the test
* result is false.
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the test result is <code>false</code>.</p>
*
* <p>This is used when validating according to an arbitrary boolean expression,
* such as validating a primitive number or using your own custom validation
* expression.
* expression.</p>
*
* <pre>
* Validate.isTrue( i > 0, "The value must be greater than zero: ", i);
* </pre>
*
* <p>For performance reasons, the object is passed as a separate parameter and
* appended to the message string only in the case of an error.
* appended to the message string only in the case of an error.</p>
*
* @param expression a boolean expression
* @param message the exception message you would like to see if the expression is false
* @param message the exception message you would like to see if the expression is <code>false</code>
* @param value the value to append to the message in case of error
* @throws IllegalArgumentException if expression is false
* @throws IllegalArgumentException if expression is <code>false</code>
*/
public static void isTrue(boolean expression, String message, long value) {
if (expression == false) {
@ -132,22 +137,25 @@ public static void isTrue(boolean expression, String message, long value) {
}
/**
* <p>Validate an argument, throwing IllegalArgumentException if the test
* result is false.
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the test result is <code>false</code>.</p>
*
* <p>This is used when validating according to an arbitrary boolean expression,
* such as validating a primitive number or using your own custom validation
* expression.
* expression.</p>
*
* <pre>
* Validate.isTrue( d > 0.0, "The value must be greater than zero: ", d);
* </pre>
*
* <p>For performance reasons, the object is passed as a separate parameter and
* appended to the message string only in the case of an error.
* appended to the message string only in the case of an error.</p>
*
* @param expression a boolean expression
* @param message the exception message you would like to see if the expression is false
* @param message the exception message you would like to see if the expression
* is <code>false</code>
* @param value the value to append to the message in case of error
* @throws IllegalArgumentException if expression is false
* @throws IllegalArgumentException if expression is <code>false</code>
*/
public static void isTrue(boolean expression, String message, double value) {
if (expression == false) {
@ -156,22 +164,25 @@ public static void isTrue(boolean expression, String message, double value) {
}
/**
* <p>Validate an argument, throwing IllegalArgumentException if the test
* result is false.
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the test result is <code>false</code>.</p>
*
* <p>This is used when validating according to an arbitrary boolean expression,
* such as validating a primitive number or using your own custom validation
* expression.
* expression.</p>
*
* <pre>
* Validate.isTrue( (i > 0), "The value must be greater than zero");
* Validate.isTrue( myObject.isOk(), "The object is not OK");
* </pre>
*
* <p>For performance reasons, the message string should not involve a string append,
* instead use the {@link #isTrue(boolean, String, Object)} method.
* instead use the {@link #isTrue(boolean, String, Object)} method.</p>
*
* @param expression a boolean expression
* @param message the exception message you would like to see if the expression is false
* @throws IllegalArgumentException if expression is false
* @param message the exception message you would like to see if the expression
* is <code>false</code>
* @throws IllegalArgumentException if expression is <code>false</code>
*/
public static void isTrue(boolean expression, String message) {
if (expression == false) {
@ -180,20 +191,22 @@ public static void isTrue(boolean expression, String message) {
}
/**
* <p>Validate an argument, throwing IllegalArgumentException if the test
* result is false.
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the test result is <code>false</code>.</p>
*
* <p>This is used when validating according to an arbitrary boolean expression,
* such as validating a primitive number or using your own custom validation
* expression.
* expression.</p>
*
* <pre>
* Validate.isTrue( i > 0 );
* Validate.isTrue( myObject.isOk() );
* </pre>
* <p>The message in the exception is 'The validated expression is false'.
*
* <p>The message in the exception is 'The validated expression is false'.</p>
*
* @param expression a boolean expression
* @throws IllegalArgumentException if expression is false
* @throws IllegalArgumentException if expression is <code>false</code>
*/
public static void isTrue(boolean expression) {
if (expression == false) {
@ -205,15 +218,17 @@ public static void isTrue(boolean expression) {
//---------------------------------------------------------------------------------
/**
* <p>Validate an argument, throwing IllegalArgumentException if the
* argument is null.
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the argument is <code>null</code>.</p>
*
* <pre>
* Validate.notNull(myObject, "The object must not be null");
* </pre>
*
* @param object the object to check is not null
* @param message the exception message you would like to see if the object is null
* @throws IllegalArgumentException if the object is null
* @param object the object to check is not <code>null</code>
* @param message the exception message you would like to see
* if the object is <code>null</code>
* @throws IllegalArgumentException if the object is <code>null</code>
*/
public static void notNull(Object object, String message) {
if (object == null) {
@ -222,15 +237,17 @@ public static void notNull(Object object, String message) {
}
/**
* <p>Validate an argument, throwing IllegalArgumentException if the
* argument is null.
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the argument is <code>null</code>.</p>
*
* <pre>
* Validate.notNull(myObject);
* </pre>
* <p>The message in the exception is 'The validated object is null'.
*
* <p>The message in the exception is 'The validated object is null'.</p>
*
* @param object the object to check is not null
* @throws IllegalArgumentException if the object is null
* @param object the object to check is not <code>null</code>
* @throws IllegalArgumentException if the object is <code>null</code>
*/
public static void notNull(Object object) {
if (object == null) {
@ -242,8 +259,9 @@ public static void notNull(Object object) {
//---------------------------------------------------------------------------------
/**
* <p>Validate an argument, throwing IllegalArgumentException if the
* argument array is empty (null or no elements).
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the argument array is empty (<code>null</code> or no elements).</p>
*
* <pre>
* Validate.notEmpty(myArray, "The array must not be empty");
* </pre>
@ -259,11 +277,13 @@ public static void notEmpty(Object[] array, String message) {
}
/**
* <p>Validate an argument, throwing IllegalArgumentException if the
* argument array is empty (null or no elements).
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the argument array is empty (<code>null</code> or no elements).</p>
*
* <pre>
* Validate.notEmpty(myArray);
* </pre>
*
* <p>The message in the exception is 'The validated array is empty'.
*
* @param array the array to check is not empty
@ -279,8 +299,9 @@ public static void notEmpty(Object[] array) {
//---------------------------------------------------------------------------------
/**
* <p>Validate an argument, throwing IllegalArgumentException if the
* argument Collection is empty (null or no elements).
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the argument Collection is empty (<code>null</code> or no elements).</p>
*
* <pre>
* Validate.notEmpty(myCollection, "The collection must not be empty");
* </pre>
@ -296,12 +317,14 @@ public static void notEmpty(Collection collection, String message) {
}
/**
* <p>Validate an argument, throwing IllegalArgumentException if the
* argument Collection is empty (null or no elements).
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the argument Collection is empty (<code>null</code> or no elements).</p>
*
* <pre>
* Validate.notEmpty(myCollection);
* </pre>
* <p>The message in the exception is 'The validated collection is empty'.
*
* <p>The message in the exception is 'The validated collection is empty'.</p>
*
* @param collection the collection to check is not empty
* @throws IllegalArgumentException if the collection is empty
@ -316,8 +339,9 @@ public static void notEmpty(Collection collection) {
//---------------------------------------------------------------------------------
/**
* <p>Validate an argument, throwing IllegalArgumentException if the
* argument Map is empty (null or no elements).
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the argument Map is empty (<code>null</code> or no elements).</p>
*
* <pre>
* Validate.notEmpty(myMap, "The collection must not be empty");
* </pre>
@ -333,12 +357,14 @@ public static void notEmpty(Map map, String message) {
}
/**
* <p>Validate an argument, throwing IllegalArgumentException if the
* argument Map is empty (null or no elements).
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the argument Map is empty (<code>null</code> or no elements).</p>
*
* <pre>
* Validate.notEmpty(myMap);
* </pre>
* <p>The message in the exception is 'The validated map is empty'.
*
* <p>The message in the exception is 'The validated map is empty'.</p>
*
* @param map the map to check is not empty
* @throws IllegalArgumentException if the map is empty
@ -353,8 +379,9 @@ public static void notEmpty(Map map) {
//---------------------------------------------------------------------------------
/**
* <p>Validate an argument, throwing IllegalArgumentException if the
* argument String is empty (null or zero length).
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the argument String is empty (<code>null</code> or zero length).</p>
*
* <pre>
* Validate.notEmpty(myString, "The string must not be empty");
* </pre>
@ -370,12 +397,14 @@ public static void notEmpty(String string, String message) {
}
/**
* <p>Validate an argument, throwing IllegalArgumentException if the
* argument String is empty (null or zero length).
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the argument String is empty (<code>null</code> or zero length).</p>
*
* <pre>
* Validate.notEmpty(myString);
* </pre>
* <p>The message in the exception is 'The validated string is empty'.
*
* <p>The message in the exception is 'The validated string is empty'.</p>
*
* @param string the string to check is not empty
* @throws IllegalArgumentException if the string is empty
@ -390,15 +419,19 @@ public static void notEmpty(String string) {
//---------------------------------------------------------------------------------
/**
* <p>Validate an argument, throwing IllegalArgumentException if the
* argument array has null elements or is null.
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the argument array has <code>null</code> elements or is
* <code>null</code>.</p>
*
* <pre>
* Validate.notEmpty(myArray, "The array must not contain null elements");
* </pre>
*
* @param array the array to check
* @param message the exception message if the array has null elements
* @throws IllegalArgumentException if the array has null elements or is null
* @param message the exception message if the array has
* <code>null</code> elements
* @throws IllegalArgumentException if the array has <code>null</code>
* elements or is <code>null</code>
*/
public static void noNullElements(Object[] array, String message) {
Validate.notNull(array);
@ -410,15 +443,19 @@ public static void noNullElements(Object[] array, String message) {
}
/**
* <p>Validate an argument, throwing IllegalArgumentException if the
* argument array has null elements or is null.
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the argument array has <code>null</code> elements or is
* <code>null</code>.</p>
*
* <pre>
* Validate.notEmpty(myArray);
* </pre>
* <p>The message in the exception is 'The validated array contains null element at index: '.
*
* <p>The message in the exception is 'The validated array contains null element at index: '.</p>
*
* @param array the array to check
* @throws IllegalArgumentException if the array has null elements or is null
* @throws IllegalArgumentException if the array has <code>null</code>
* elements or is <code>null</code>
*/
public static void noNullElements(Object[] array) {
Validate.notNull(array);
@ -433,15 +470,19 @@ public static void noNullElements(Object[] array) {
//---------------------------------------------------------------------------------
/**
* <p>Validate an argument, throwing IllegalArgumentException if the
* argument collection has null elements or is null.
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the argument collection has <code>null</code> elements or is
* <code>null</code>.</p>
*
* <pre>
* Validate.notEmpty(myCollection, "The collection must not contain null elements");
* </pre>
*
* @param collection the collection to check
* @param message the exception message if the array has null elements
* @throws IllegalArgumentException if the collection has null elements or is null
* @param message the exception message if the array has
* <code>null</code> elements
* @throws IllegalArgumentException if the collection has
* <code>null</code> elements or is <code>null</code>
*/
public static void noNullElements(Collection collection, String message) {
Validate.notNull(collection);
@ -454,15 +495,19 @@ public static void noNullElements(Collection collection, String message) {
}
/**
* <p>Validate an argument, throwing IllegalArgumentException if the
* argument collection has null elements or is null.
* <p>Validate an argument, throwing <code>IllegalArgumentException</code>
* if the argument collection has <code>null</code> elements or is
* <code>null</code>.</p>
*
* <pre>
* Validate.notEmpty(myCollection);
* </pre>
* <p>The message in the exception is 'The validated collection contains null element at index: '.
*
* <p>The message in the exception is 'The validated collection contains null element at index: '.</p>
*
* @param collection the collection to check
* @throws IllegalArgumentException if the collection has null elements or is null
* @throws IllegalArgumentException if the collection has
* <code>null</code> elements or is <code>null</code>
*/
public static void noNullElements(Collection collection) {
Validate.notNull(collection);