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

Javadoc formatting patch, by Fredrik Westermarck 

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/lang/trunk@137133 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Stephen Colebourne 2002-11-16 10:41:03 +00:00
parent c248c060c6
commit 7477a1e08f
15 changed files with 1024 additions and 763 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -59,13 +59,13 @@ import java.util.Map;
import org.apache.commons.lang.builder.ToStringBuilder; import org.apache.commons.lang.builder.ToStringBuilder;
import org.apache.commons.lang.builder.ToStringStyle; import org.apache.commons.lang.builder.ToStringStyle;
/** /**
* <code>ArrayUtils</code> contains utility methods for working for * <p><code>ArrayUtils</code> contains utility methods for working for
* arrays. * arrays.</p>
* *
* @author <a href="mailto:scolebourne@apache.org">Stephen Colebourne</a> * @author <a href="mailto:scolebourne@apache.org">Stephen Colebourne</a>
* @author Moritz Petersen * @author Moritz Petersen
* @author <a href="mailto:fredrik@westermarck.com">Fredrik Westermarck</a> * @author <a href="mailto:fredrik@westermarck.com">Fredrik Westermarck</a>
* @version $Id: ArrayUtils.java,v 1.3 2002/11/15 00:25:45 scolebourne Exp $ * @version $Id: ArrayUtils.java,v 1.4 2002/11/16 10:41:03 scolebourne Exp $
*/ */
public class ArrayUtils { public class ArrayUtils {
@ -91,10 +91,11 @@ public class ArrayUtils {
public static final boolean[] EMPTY_BOOLEAN_ARRAY = new boolean[0]; public static final boolean[] EMPTY_BOOLEAN_ARRAY = new boolean[0];
/** /**
* ArrayUtils instances should NOT be constructed in standard programming. * <p>ArrayUtils instances should NOT be constructed in standard programming.
* Instead, the class should be used as <code>ArrayUtils.clone(new int[] {2})</code>. * Instead, the class should be used as <code>ArrayUtils.clone(new int[] {2})</code>.</p>
* This constructor is public to permit tools that require a JavaBean instance *
* to operate. * <p>This constructor is public to permit tools that require a JavaBean instance
* to operate.</p>
*/ */
public ArrayUtils() { public ArrayUtils() {
} }
@ -102,11 +103,12 @@ public class ArrayUtils {
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* Outputs an array as a String, treating <code>null</code> as an empty array. * <p>Outputs an array as a String, treating <code>null</code> as an empty array.</p>
* <p> *
* Multi-dimensional arrays are handled correctly, including * <p>Multi-dimensional arrays are handled correctly, including
* multi-dimensional primitive arrays. * multi-dimensional primitive arrays.</p>
* The format is that of Java source code, for example {a,b}. *
* <p>The format is that of Java source code, for example {a,b}.</p>
* *
* @param array the array to get a toString for, may not be <code>null</code> * @param array the array to get a toString for, may not be <code>null</code>
* @return a String representation of the array, '{}' if <code>null</code> passed in * @return a String representation of the array, '{}' if <code>null</code> passed in
@ -116,11 +118,12 @@ public class ArrayUtils {
} }
/** /**
* Outputs an array as a String handling <code>null</code>s. * <p>Outputs an array as a String handling <code>null</code>s.</p>
* <p> *
* Multi-dimensional arrays are handled correctly, including * <p>Multi-dimensional arrays are handled correctly, including
* multi-dimensional primitive arrays. * multi-dimensional primitive arrays.</p>
* The format is that of Java source code, for example {a,b}. *
* <p>The format is that of Java source code, for example {a,b}.</p>
* *
* @param array the array to get a toString for, may be <code>null</code> * @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> * @param stringIfNull the String to return if the array is <code>null</code>
@ -134,11 +137,12 @@ public class ArrayUtils {
} }
/** /**
* Converts the given array into a {@link Map}. Each element of the array * <p>Converts the given array into a {@link Map}. Each element of the array
* must be either a {@link Map.Entry} or an Array, containing at least two * must be either a {@link Map.Entry} or an Array, containing at least two
* elements, where the first element is used as key and the second as * elements, where the first element is used as key and the second as
* value. This method can be used to initialize: * value.</p>
* *
* <p>This method can be used to initialize:</p>
* <pre> * <pre>
* // Create a Map mapping colors. * // Create a Map mapping colors.
* Map colorMap = MapUtils.toMap(new String[][] {{ * Map colorMap = MapUtils.toMap(new String[][] {{
@ -149,7 +153,7 @@ public class ArrayUtils {
* *
* @param array an array whose elements are either a {@link Map.Entry} or * @param array an array whose elements are either a {@link Map.Entry} or
* an Array containing at least two elements * an Array containing at least two elements
* @return a Map that was created from the array * @return a <code>Map</code> that was created from the array
* @throws IllegalArgumentException if the array is <code>null</code> * @throws IllegalArgumentException if the array is <code>null</code>
* @throws IllegalArgumentException if one element of this Array is * @throws IllegalArgumentException if one element of this Array is
* itself an Array containing less then two elements * itself an Array containing less then two elements
@ -184,10 +188,11 @@ public class ArrayUtils {
} }
// /** // /**
// * Output the array as a String. // * <p>Output the array as a String.</p>
// * <p> // *
// * Multi-dimensional arrays are handled by the Object[] method. // * <p>Multi-dimensional arrays are handled by the Object[] method.</p>
// * The format is that of Java source code, for example {1,2}. // *
// * <p>The format is that of Java source code, for example {1,2}.</p>
// * // *
// * @param array the array to get a toString for, must not be <code>null</code> // * @param array the array to get a toString for, must not be <code>null</code>
// * @return a String representation of the array // * @return a String representation of the array
@ -198,10 +203,11 @@ public class ArrayUtils {
// } // }
// //
// /** // /**
// * Output the array as a String. // * <p>Output the array as a String.</p>
// * <p> // *
// * Multi-dimensional arrays are handled by the Object[] method. // * <p>Multi-dimensional arrays are handled by the Object[] method.</p>
// * The format is that of Java source code, for example {1,2}. // *
// * <p>The format is that of Java source code, for example {1,2}.</p>
// * // *
// * @param array the array to get a toString for, must not be <code>null</code> // * @param array the array to get a toString for, must not be <code>null</code>
// * @return a String representation of the array // * @return a String representation of the array
@ -212,10 +218,11 @@ public class ArrayUtils {
// } // }
// //
// /** // /**
// * Output the array as a String. // * <p>Output the array as a String.</p>
// * <p> // *
// * Multi-dimensional arrays are handled by the Object[] method. // * <p>Multi-dimensional arrays are handled by the Object[] method.</p>
// * The format is that of Java source code, for example {1,2}. // *
// * <p>The format is that of Java source code, for example {1,2}.</p>
// * // *
// * @param array the array to get a toString for, must not be <code>null</code> // * @param array the array to get a toString for, must not be <code>null</code>
// * @return a String representation of the array // * @return a String representation of the array
@ -226,10 +233,11 @@ public class ArrayUtils {
// } // }
// //
// /** // /**
// * Output the array as a String. // * <p>Output the array as a String.</p>
// * <p> // *
// * Multi-dimensional arrays are handled by the Object[] method. // * <p>Multi-dimensional arrays are handled by the Object[] method.</p>
// * The format is that of Java source code, for example {1,2}. // *
// * <p>The format is that of Java source code, for example {1,2}.</p>
// * // *
// * @param array the array to get a toString for, must not be <code>null</code> // * @param array the array to get a toString for, must not be <code>null</code>
// * @return a String representation of the array // * @return a String representation of the array
@ -240,10 +248,11 @@ public class ArrayUtils {
// } // }
// //
// /** // /**
// * Output the array as a String. // * <p>Output the array as a String.</p>
// * <p> // *
// * Multi-dimensional arrays are handled by the Object[] method. // * <p>Multi-dimensional arrays are handled by the Object[] method.</p>
// * The format is that of Java source code, for example {1.0,2.0}. // *
// * <p>The format is that of Java source code, for example {1.0,2.0}.</p>
// * // *
// * @param array the array to get a toString for, must not be <code>null</code> // * @param array the array to get a toString for, must not be <code>null</code>
// * @return a String representation of the array // * @return a String representation of the array
@ -254,10 +263,11 @@ public class ArrayUtils {
// } // }
// //
// /** // /**
// * Output the array as a String. // * <p>Output the array as a String.</p>
// * <p> // *
// * Multi-dimensional arrays are handled by the Object[] method. // * <p>Multi-dimensional arrays are handled by the Object[] method.</p>
// * The format is that of Java source code, for example {1.0,2.0}. // *
// * <p>The format is that of Java source code, for example {1.0,2.0}.</p>
// * // *
// * @param array the array to get a toString for, must not be <code>null</code> // * @param array the array to get a toString for, must not be <code>null</code>
// * @return a String representation of the array // * @return a String representation of the array
@ -268,10 +278,11 @@ public class ArrayUtils {
// } // }
// //
// /** // /**
// * Output the array as a String. // * <p>Output the array as a String.</p>
// * <p> // *
// * Multi-dimensional arrays are handled by the Object[] method. // * <p>Multi-dimensional arrays are handled by the Object[] method.</p>
// * The format is that of Java source code, for example {true,false}. // *
// * <p>The format is that of Java source code, for example {true,false}.</p>
// * // *
// * @param array the array to get a toString for, must not be <code>null</code> // * @param array the array to get a toString for, must not be <code>null</code>
// * @return a String representation of the array // * @return a String representation of the array
@ -284,12 +295,14 @@ public class ArrayUtils {
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* Shallow clones an array returning a typecast result and handling <code>null</code>. * <p>Shallow clones an array returning a typecast result and handling
* <p> * <code>null</code>.</p>
* The objecs in the array are not cloned. *
* <p>The objecs in the array are not cloned.</p>
* *
* @param array the array to shallow clone, may not be <code>null</code> * @param array the array to shallow clone, may not be <code>null</code>
* @return the cloned array, or <code>null</code> if <code>null</code> passed in * @return the cloned array, or <code>null</code> if <code>null</code>
* passed in
*/ */
public static Object[] clone(Object[] array) { public static Object[] clone(Object[] array) {
if (array == null) { if (array == null) {
@ -299,10 +312,12 @@ public class ArrayUtils {
} }
/** /**
* Clones an array returning a typecast result and handling <code>null</code>. * <p>Clones an array returning a typecast result and handling
* <code>null</code>.</p>
* *
* @param array the array to clone, may not be <code>null</code> * @param array the array to clone, may not be <code>null</code>
* @return the cloned array, or <code>null</code> if <code>null</code> passed in * @return the cloned array, or <code>null</code> if <code>null</code>
* passed in
*/ */
public static long[] clone(long[] array) { public static long[] clone(long[] array) {
if (array == null) { if (array == null) {
@ -312,10 +327,12 @@ public class ArrayUtils {
} }
/** /**
* Clones an array returning a typecast result and handling <code>null</code>. * <p>Clones an array returning a typecast result and handling
* <code>null</code>.</p>
* *
* @param array the array to clone, may not be <code>null</code> * @param array the array to clone, may not be <code>null</code>
* @return the cloned array, or <code>null</code> if <code>null</code> passed in * @return the cloned array, or <code>null</code> if <code>null</code>
* passed in
*/ */
public static int[] clone(int[] array) { public static int[] clone(int[] array) {
if (array == null) { if (array == null) {
@ -325,10 +342,12 @@ public class ArrayUtils {
} }
/** /**
* Clones an array returning a typecast result and handling <code>null</code>. * <p>Clones an array returning a typecast result and handling
* <code>null</code>.</p>
* *
* @param array the array to clone, may not be <code>null</code> * @param array the array to clone, may not be <code>null</code>
* @return the cloned array, or <code>null</code> if <code>null</code> passed in * @return the cloned array, or <code>null</code> if <code>null</code>
* passed in
*/ */
public static short[] clone(short[] array) { public static short[] clone(short[] array) {
if (array == null) { if (array == null) {
@ -338,10 +357,12 @@ public class ArrayUtils {
} }
/** /**
* Clones an array returning a typecast result and handling <code>null</code>. * <p>Clones an array returning a typecast result and handling
* <code>null</code>.</p>
* *
* @param array the array to clone, may not be <code>null</code> * @param array the array to clone, may not be <code>null</code>
* @return the cloned array, or <code>null</code> if <code>null</code> passed in * @return the cloned array, or <code>null</code> if <code>null</code>
* passed in
*/ */
public static byte[] clone(byte[] array) { public static byte[] clone(byte[] array) {
if (array == null) { if (array == null) {
@ -351,10 +372,12 @@ public class ArrayUtils {
} }
/** /**
* Clones an array returning a typecast result and handling <code>null</code>. * <p>Clones an array returning a typecast result and handling
* <code>null</code>.</p>
* *
* @param array the array to clone, may not be <code>null</code> * @param array the array to clone, may not be <code>null</code>
* @return the cloned array, or <code>null</code> if <code>null</code> passed in * @return the cloned array, or <code>null</code> if <code>null</code>
* passed in
*/ */
public static double[] clone(double[] array) { public static double[] clone(double[] array) {
if (array == null) { if (array == null) {
@ -364,10 +387,12 @@ public class ArrayUtils {
} }
/** /**
* Clones an array returning a typecast result and handling <code>null</code>. * <p>Clones an array returning a typecast result and handling
* <code>null</code>.</p>
* *
* @param array the array to clone, may not be <code>null</code> * @param array the array to clone, may not be <code>null</code>
* @return the cloned array, or <code>null</code> if <code>null</code> passed in * @return the cloned array, or <code>null</code> if <code>null</code>
* passed in
*/ */
public static float[] clone(float[] array) { public static float[] clone(float[] array) {
if (array == null) { if (array == null) {
@ -377,10 +402,12 @@ public class ArrayUtils {
} }
/** /**
* Clones an array returning a typecast result and handling <code>null</code>. * <p>Clones an array returning a typecast result and handling
* <code>null</code>.</p>
* *
* @param array the array to clone, may not be <code>null</code> * @param array the array to clone, may not be <code>null</code>
* @return the cloned array, or <code>null</code> if <code>null</code> passed in * @return the cloned array, or <code>null</code> if <code>null</code>
* passed in
*/ */
public static boolean[] clone(boolean[] array) { public static boolean[] clone(boolean[] array) {
if (array == null) { if (array == null) {
@ -392,9 +419,10 @@ public class ArrayUtils {
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* Checks whether two arrays are the same length, treating <code>null</code> * <p>Checks whether two arrays are the same length, treating
* arrays as length 0. * <code>null</code> arrays as length <code>0</code>.
* Any multi-dimensional aspects of the arrays are ignored. *
* <p>Any multi-dimensional aspects of the arrays are ignored.</p>
* *
* @param array1 the first array, may be <code>null</code> * @param array1 the first array, may be <code>null</code>
* @param array2 the second array, may be <code>null</code> * @param array2 the second array, may be <code>null</code>
@ -411,9 +439,10 @@ public class ArrayUtils {
} }
/** /**
* Checks whether two arrays are the same length, treating <code>null</code> * <p>Checks whether two arrays are the same length, treating
* arrays as length 0. * <code>null</code> arrays as length <code>0</code>.</p>
* Any multi-dimensional aspects of the arrays are ignored. *
* <p>Any multi-dimensional aspects of the arrays are ignored.</p>
* *
* @param array1 the first array, may be <code>null</code> * @param array1 the first array, may be <code>null</code>
* @param array2 the second array, may be <code>null</code> * @param array2 the second array, may be <code>null</code>
@ -430,9 +459,10 @@ public class ArrayUtils {
} }
/** /**
* Checks whether two arrays are the same length, treating <code>null</code> * <p>Checks whether two arrays are the same length, treating
* arrays as length 0. * <code>null</code> arrays as length <code>0</code>.</p>
* Any multi-dimensional aspects of the arrays are ignored. *
* <p>Any multi-dimensional aspects of the arrays are ignored.</p>
* *
* @param array1 the first array, may be <code>null</code> * @param array1 the first array, may be <code>null</code>
* @param array2 the second array, may be <code>null</code> * @param array2 the second array, may be <code>null</code>
@ -449,9 +479,10 @@ public class ArrayUtils {
} }
/** /**
* Checks whether two arrays are the same length, treating <code>null</code> * <p>Checks whether two arrays are the same length, treating
* arrays as length 0. * <code>null</code> arrays as length <code>0</code>.</p>
* Any multi-dimensional aspects of the arrays are ignored. *
* <p>Any multi-dimensional aspects of the arrays are ignored.</p>
* *
* @param array1 the first array, may be <code>null</code> * @param array1 the first array, may be <code>null</code>
* @param array2 the second array, may be <code>null</code> * @param array2 the second array, may be <code>null</code>
@ -468,9 +499,10 @@ public class ArrayUtils {
} }
/** /**
* Checks whether two arrays are the same length, treating <code>null</code> * <p>Checks whether two arrays are the same length, treating
* arrays as length 0. * <code>null</code> arrays as length <code>0</code>.</p>
* Any multi-dimensional aspects of the arrays are ignored. *
* <p>Any multi-dimensional aspects of the arrays are ignored.</p>
* *
* @param array1 the first array, may be <code>null</code> * @param array1 the first array, may be <code>null</code>
* @param array2 the second array, may be <code>null</code> * @param array2 the second array, may be <code>null</code>
@ -487,9 +519,10 @@ public class ArrayUtils {
} }
/** /**
* Checks whether two arrays are the same length, treating <code>null</code> * <p>Checks whether two arrays are the same length, treating
* arrays as length 0. * <code>null</code> arrays as length <code>0</code>.</p>
* Any multi-dimensional aspects of the arrays are ignored. *
* <p>Any multi-dimensional aspects of the arrays are ignored.</p>
* *
* @param array1 the first array, may be <code>null</code> * @param array1 the first array, may be <code>null</code>
* @param array2 the second array, may be <code>null</code> * @param array2 the second array, may be <code>null</code>
@ -506,9 +539,10 @@ public class ArrayUtils {
} }
/** /**
* Checks whether two arrays are the same length, treating <code>null</code> * <p>Checks whether two arrays are the same length, treating
* arrays as length 0. * <code>null</code> arrays as length <code>0</code>.</p>
* Any multi-dimensional aspects of the arrays are ignored. *
* <p>Any multi-dimensional aspects of the arrays are ignored</p>.
* *
* @param array1 the first array, may be <code>null</code> * @param array1 the first array, may be <code>null</code>
* @param array2 the second array, may be <code>null</code> * @param array2 the second array, may be <code>null</code>
@ -525,9 +559,10 @@ public class ArrayUtils {
} }
/** /**
* Checks whether two arrays are the same length, treating <code>null</code> * <p>Checks whether two arrays are the same length, treating
* arrays as length 0. * <code>null</code> arrays as length <code>0</code>.</p>
* Any multi-dimensional aspects of the arrays are ignored. *
* <p>Any multi-dimensional aspects of the arrays are ignored.</p>
* *
* @param array1 the first array, may be <code>null</code> * @param array1 the first array, may be <code>null</code>
* @param array2 the second array, may be <code>null</code> * @param array2 the second array, may be <code>null</code>
@ -544,8 +579,8 @@ public class ArrayUtils {
} }
/** /**
* Checks whether two arrays are the same type taking into account * <p>Checks whether two arrays are the same type taking into account
* multi-dimensional arrays. * multi-dimensional arrays.</p>
* *
* @param array1 the first array, must not be <code>null</code> * @param array1 the first array, must not be <code>null</code>
* @param array2 the second array, must not be <code>null</code> * @param array2 the second array, must not be <code>null</code>

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

@ -55,13 +55,14 @@ package org.apache.commons.lang;
*/ */
/** /**
* A range of characters. Able to understand the idea of a contiguous * <p>A range of characters. Able to understand the idea of a contiguous
* sublist of an alphabet, a negated concept, and a set of characters. * sublist of an alphabet, a negated concept, and a set of characters.</p>
* Used by CharSet to handle sets of characters. *
* <p>Used by <code>CharSet</code> to handle sets of characters.</p>
* *
* @author <a href="bayard@generationjava.com">Henri Yandell</a> * @author <a href="bayard@generationjava.com">Henri Yandell</a>
* @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a> * @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a>
* @version $Id: CharRange.java,v 1.1 2002/07/19 03:35:54 bayard Exp $ * @version $Id: CharRange.java,v 1.2 2002/11/16 10:41:03 scolebourne Exp $
*/ */
class CharRange { class CharRange {
@ -75,7 +76,7 @@ class CharRange {
private boolean negated; private boolean negated;
/** /**
* Construct a CharRange over a single character. * <p>Construct a <code>CharRange</code> over a single character.</p>
* *
* @param start char over which this range is placed * @param start char over which this range is placed
*/ */
@ -84,7 +85,7 @@ class CharRange {
} }
/** /**
* Construct a CharRange over a set of characters. * <p>Construct a <code>CharRange</code> over a set of characters.</p>
* *
* @param start char start character in this range. inclusive * @param start char start character in this range. inclusive
* @param close char close character in this range. inclusive * @param close char close character in this range. inclusive
@ -95,7 +96,7 @@ class CharRange {
} }
/** /**
* Construct a CharRange over a set of characters. * <p>Construct a <code>CharRange</code> over a set of characters.</p>
* *
* @param start String start first character is in this range (inclusive). * @param start String start first character is in this range (inclusive).
* @param close String first character is close character in this * @param close String first character is close character in this
@ -107,7 +108,7 @@ class CharRange {
} }
/** /**
* Get the start character for this character range * <p>Get the start character for this character range.</p>
* *
* @return start char (inclusive) * @return start char (inclusive)
*/ */
@ -116,7 +117,7 @@ class CharRange {
} }
/** /**
* Get the end character for this character range * <p>Get the end character for this character range.</p>
* *
* @return end char (inclusive) * @return end char (inclusive)
*/ */
@ -125,7 +126,7 @@ class CharRange {
} }
/** /**
* Set the start character for this character range * <p>Set the start character for this character range.</p>
* *
* @param ch start char (inclusive) * @param ch start char (inclusive)
*/ */
@ -134,7 +135,7 @@ class CharRange {
} }
/** /**
* Set the end character for this character range * <p>Set the end character for this character range.</p>
* *
* @param ch start char (inclusive) * @param ch start char (inclusive)
*/ */
@ -143,18 +144,19 @@ class CharRange {
} }
/** /**
* Is this CharRange over many characters * <p>Is this <code>CharRange</code> over many characters.</p>
* *
* @return boolean true is many characters * @return boolean <code>true</code> is many characters
*/ */
public boolean isRange() { public boolean isRange() {
return this.close != UNSET; return this.close != UNSET;
} }
/** /**
* Is the passed in character inside this range * <p>Is the passed in character <code>ch</code> inside
* this range.</p>
* *
* @return boolean true is in range * @return boolean <code>true</code> is in range
*/ */
public boolean inRange(char ch) { public boolean inRange(char ch) {
if(isRange()) { if(isRange()) {
@ -165,27 +167,28 @@ class CharRange {
} }
/** /**
* Checks if this CharRange is negated. * <p>Checks if this <code>CharRange</code> is negated.</p>
* *
* @return boolean true is negated * @return boolean <code>true</code> is negated
*/ */
public boolean isNegated() { public boolean isNegated() {
return negated; return negated;
} }
/** /**
* Sets this character range to be negated or not. * <p>Sets this character range to be negated or not.</p>
* This implies that this CharRange is over all characters except
* the ones in this range.
* *
* @param negated true to negate the range * <p>This implies that this <code>CharRange</code> is over
* all characters except the ones in this range.</p>
*
* @param negated <code>true</code> to negate the range
*/ */
public void setNegated(boolean negated) { public void setNegated(boolean negated) {
this.negated = negated; this.negated = negated;
} }
/** /**
* Output a string representation of the character range * <p>Output a string representation of the character range.</p>
* *
* @return string representation * @return string representation
*/ */

26
src/java/org/apache/commons/lang/CharSet.java
View File

@ -59,21 +59,25 @@ import java.util.LinkedList;
import java.util.List; import java.util.List;
/** /**
* A set of characters. You can iterate over the characters in the * <p>A set of characters. You can iterate over the characters in the
* set. * set.</p>
* *
* @author <a href="bayard@generationjava.com">Henri Yandell</a> * @author <a href="bayard@generationjava.com">Henri Yandell</a>
* @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a> * @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a>
* @version $Id: CharSet.java,v 1.5 2002/10/09 04:35:03 sullis Exp $ * @version $Id: CharSet.java,v 1.6 2002/11/16 10:41:03 scolebourne Exp $
*/ */
public class CharSet { public class CharSet {
private List set = new LinkedList(); private List set = new LinkedList();
/** /**
* Restricted constructor. Use the factory method evaluateSet(). * <p>Restricted constructor.</p>
* *
* @throws NullPointerException if any of set[i] is null or if set is null * <p>Use the factory method
* {@link CharSetUtils#evaluateSet(java.lang.String[])}.</p>
*
* @throws NullPointerException if any of set[i] is <code>null</code>
* or if set is <code>null</code>
*/ */
protected CharSet(String[] set) { protected CharSet(String[] set) {
int sz = set.length; int sz = set.length;
@ -83,10 +87,12 @@ public class CharSet {
} }
/** /**
* Does the set contain the character specified * <p>Does the <code>CharSet</code> contain the specified
* character <code>ch</code>.</p>
* *
* @param ch the character to check for * @param ch the character to check for
* @return true if it does contain it * @return <code>true</code> if it does contain the character
* <code>ch</code>
*/ */
public boolean contains(char ch) { public boolean contains(char ch) {
Iterator iterator = set.iterator(); Iterator iterator = set.iterator();
@ -107,10 +113,10 @@ public class CharSet {
} }
/** /**
* Add a set definition string to the set * <p>Add a set definition string to the <code>CharSet</code>.</p>
* *
* @param str set definition string * @param str set definition string
* @throws NullPointerException if str is null * @throws NullPointerException if <code>str</code> is <code>null</code>
*/ */
protected void add(String str) { protected void add(String str) {
int sz = str.length(); int sz = str.length();
@ -145,7 +151,7 @@ public class CharSet {
} }
/** /**
* Returns a string representation of the set * <p>Returns a string representation of the set.</p>
* *
* @return string representation * @return string representation
*/ */

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

@ -55,46 +55,52 @@ package org.apache.commons.lang;
*/ */
/** /**
* Numerous routines to manipulate a character set. * <p>Numerous routines to manipulate a <code>CharSet</code>.</p>
* *
* @author <a href="bayard@generationjava.com">Henri Yandell</a> * @author <a href="bayard@generationjava.com">Henri Yandell</a>
* @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a> * @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a>
* @version $Id: CharSetUtils.java,v 1.6 2002/09/29 08:20:52 bayard Exp $ * @version $Id: CharSetUtils.java,v 1.7 2002/11/16 10:41:03 scolebourne Exp $
*/ */
public class CharSetUtils { public class CharSetUtils {
/** /**
* CharSetUtils instances should NOT be constructed in standard programming. * <p>CharSetUtils instances should NOT be constructed in standard programming.
* Instead, the class should be used as <code>CharSetUtils.evaluateSet(null);</code>. * Instead, the class should be used as <code>CharSetUtils.evaluateSet(null);</code>.</p>
* This constructor is public to permit tools that require a JavaBean instance *
* to operate. * <p>This constructor is public to permit tools that require a JavaBean instance
* to operate.</p>
*/ */
public CharSetUtils() { public CharSetUtils() {
} }
/** /**
* Creates a CharSetUtils object which allows a certain amount of * <p>Creates a CharSetUtils object which allows a certain amount of
* set logic to be performed upon the following syntax: * set logic to be performed upon the following syntax:</p>
* *
* "aeio" which implies 'a','e',.. * <ul>
* "^e" implies not e. However it only negates, it's not * <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. * a set in itself due to the size of that set in unicode.
* "ej-m" implies e,j->m. e,j,k,l,m. * <li>"ej-m" implies e,j->m. e,j,k,l,m.
* </ul>
*
* @param set * @param set
* @return CharSet * @return CharSet
* @throws NullPointerException if any of set[i] is null or if set is null * @throws NullPointerException if any of set[i] is null or if set is null
* @param set
* @return CharSet
*/ */
public static CharSet evaluateSet(String[] set) { public static CharSet evaluateSet(String[] set) {
return new CharSet(set); return new CharSet(set);
} }
/** /**
* Squeezes any repititions of a character that is mentioned in the * <p>Squeezes any repititions of a character that is mentioned in the
* supplied set. An example is: * supplied set.</p>
* squeeze("hello", "el") => "helo" *
* See evaluateSet for set-syntax. * <p>An example is:</p>
* <ul>
* <li>squeeze("hello", "el") => "helo"
* </ul>
* @see #evaluateSet(java.lang.String[]) for set-syntax.
* *
* @param str the string to work from * @param str the string to work from
* @param set the character set to use for manipulation * @param set the character set to use for manipulation
@ -106,14 +112,19 @@ public class CharSetUtils {
} }
/** /**
* Squeezes any repititions of a character that is mentioned in the * <p>Squeezes any repititions of a character that is mentioned in the
* supplied set. An example is: * supplied set.</p>
* squeeze("hello", {"el"}) => "helo" *
* See evaluateSet for set-syntax. * <p>An example is:</p>
* <ul>
* <li>squeeze("hello", {"el"}) => "helo"
* </ul>
* @see #evaluateSet(java.lang.String[]) for set-syntax.
* *
* @param str the string to work from * @param str the string to work from
* @param set the character set to use for manipulation * @param set the character set to use for manipulation
* @throws NullPointerException if str is null * @throws NullPointerException if <code>str</code> is
* <code>null</code>
*/ */
public static String squeeze(String str, String[] set) { public static String squeeze(String str, String[] set) {
CharSet chars = evaluateSet(set); CharSet chars = evaluateSet(set);
@ -136,9 +147,13 @@ public class CharSetUtils {
} }
/** /**
* Takes an argument in set-syntax, see evaluateSet, * <p>Takes an argument in set-syntax, see evaluateSet,
* and returns the number of characters present in the specified string. * and returns the number of characters present in the specified string.</p>
* An example would be: count("hello", {"c-f","o"}) returns 2. *
* <p>An example would be:</p>
* <ul>
* <li>count("hello", {"c-f","o"}) returns 2.
* </ul>
* *
* @param str String target to count characters in * @param str String target to count characters in
* @param set String set of characters to count * @param set String set of characters to count
@ -150,9 +165,13 @@ public class CharSetUtils {
} }
/** /**
* Takes an argument in set-syntax, see evaluateSet, * <p>Takes an argument in set-syntax, see evaluateSet,
* and returns the number of characters present in the specified string. * and returns the number of characters present in the specified string.</p>
* An example would be: count("hello", {"c-f","o"}) returns 2. *
* An example would be:</p>
* <ul>
* <li>count("hello", {"c-f","o"}) returns 2.
* </ul>
* *
* @param str String target to count characters in * @param str String target to count characters in
* @param set String[] set of characters to count * @param set String[] set of characters to count
@ -171,9 +190,13 @@ public class CharSetUtils {
} }
/** /**
* Takes an argument in set-syntax, see evaluateSet, * <p>Takes an argument in set-syntax, see evaluateSet,
* and deletes any of characters present in the specified string. * and deletes any of characters present in the specified string.</p>
* An example would be: delete("hello", {"c-f","o"}) returns "hll" *
* <p>An example would be:</p>
* <ul>
* <li>delete("hello", {"c-f","o"}) returns "hll"
* </ul>
* *
* @param str String target to delete characters from * @param str String target to delete characters from
* @param set String set of characters to delete * @param set String set of characters to delete
@ -185,13 +208,18 @@ public class CharSetUtils {
} }
/** /**
* Takes an argument in set-syntax, see evaluateSet, * <p>Takes an argument in set-syntax, see evaluateSet,
* and deletes any of characters present in the specified string. * and deletes any of characters present in the specified string.</p>
* An example would be: delete("hello", {"c-f","o"}) returns "hll" *
* <p>An example would be:</p>
* <ul>
* <li>delete("hello", {"c-f","o"}) returns "hll"
* </ul>
* *
* @param str String target to delete characters from * @param str String target to delete characters from
* @param set String[] set of characters to delete * @param set String[] set of characters to delete
* @throws NullPointerException of str is null * @throws NullPointerException of <code>str</code> is
* <code>null</code>
*/ */
public static String delete(String str, String[] set) { public static String delete(String str, String[] set) {
CharSet chars = evaluateSet(set); CharSet chars = evaluateSet(set);
@ -207,16 +235,22 @@ public class CharSetUtils {
} }
/** /**
* Translate characters in a String. * <p>Translate characters in a String.</p>
* An example is: translate("hello", "ho", "jy") => jelly *
* If the length of characters to search for is greater than the * <p>An example is:</p>
* <ul>
* <li>translate("hello", "ho", "jy") => jelly
* </ul>
*
* <p>If the length of characters to search for is greater than the
* length of characters to replace, then the last character is * length of characters to replace, then the last character is
* used. * used.</p>
* *
* @param target String to replace characters in * @param target String to replace characters in
* @param repl String to find that will be replaced * @param repl String to find that will be replaced
* @param with String to put into the target String * @param with String to put into the target String
* @throws NullPointerException if target, with or repl is null * @throws NullPointerException if <code>target</code>, with
* or <code>repl</code> is <code>null</code>
*/ */
public static String translate(String target, String repl, String with) { public static String translate(String target, String repl, String with) {
StringBuffer buffer = new StringBuffer(target.length()); StringBuffer buffer = new StringBuffer(target.length());

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

@ -57,19 +57,21 @@ import java.util.ArrayList;
import java.util.Iterator; import java.util.Iterator;
import java.util.List; import java.util.List;
/** /**
* <code>ClassUtils</code> contains utility methods for working for * <p><code>ClassUtils</code> contains utility methods for working for
* classes without using reflection. * classes without using reflection.</p>
* *
* @author <a href="mailto:scolebourne@apache.org">Stephen Colebourne</a> * @author <a href="mailto:scolebourne@apache.org">Stephen Colebourne</a>
* @version $Id: ClassUtils.java,v 1.4 2002/11/14 22:29:25 scolebourne Exp $ * @version $Id: ClassUtils.java,v 1.5 2002/11/16 10:41:03 scolebourne Exp $
*/ */
public class ClassUtils { public class ClassUtils {
/** /**
* ClassUtils instances should NOT be constructed in standard programming. * <p>ClassUtils instances should NOT be constructed in standard programming.
* Instead, the class should be used as <code>ClassUtils.getShortClassName(cls)</code>. * Instead, the class should be used as
* This constructor is public to permit tools that require a JavaBean instance * <code>ClassUtils.getShortClassName(cls)</code>.</p>
* to operate. *
* <p>This constructor is public to permit tools that require a JavaBean
* instance to operate.</p>
*/ */
public ClassUtils() { public ClassUtils() {
} }
@ -77,9 +79,11 @@ public class ClassUtils {
// ------------------------------------------------------------------------- // -------------------------------------------------------------------------
/** /**
* Gets the class name minus the package name from a Class. * <p>Gets the class name minus the package name from a
* <code>Class</code>.</p>
* *
* @param cls the class to get the short name for, must not be <code>null</code> * @param cls the class to get the short name for, must not be
* <code>null</code>
* @return the class name without the package name * @return the class name without the package name
* @throws IllegalArgumentException if the class is <code>null</code> * @throws IllegalArgumentException if the class is <code>null</code>
*/ */
@ -91,9 +95,11 @@ public class ClassUtils {
} }
/** /**
* Gets the class name minus the package name for an Object. * <p>Gets the class name minus the package name for an
* <code>Object</code>.</p>
* *
* @param object the class to get the short name for, must not be <code>null</code> * @param object the class to get the short name for, must not be
* <code>null</code>
* @return the class name of the object without the package name * @return the class name of the object without the package name
* @throws IllegalArgumentException if the object is <code>null</code> * @throws IllegalArgumentException if the object is <code>null</code>
*/ */
@ -105,9 +111,9 @@ public class ClassUtils {
} }
/** /**
* Gets the class name minus the package name from a String. * <p>Gets the class name minus the package name from a String.</p>
* <p> *
* The string passed in is assumed to be a class name - it is not checked. * <p>The string passed in is assumed to be a class name - it is not checked.</p>
* *
* @param className the className to get the short name for, must not be empty * @param className the className to get the short name for, must not be empty
* @return the class name of the class without the package name * @return the class name of the class without the package name
@ -132,9 +138,10 @@ public class ClassUtils {
// ------------------------------------------------------------------------- // -------------------------------------------------------------------------
/** /**
* Gets the package name of a Class. * <p>Gets the package name of a <code>Class</code>.</p>
* *
* @param cls the class to get the package name for, must not be <code>null</code> * @param cls the class to get the package name for, must not be
* <code>null</code>
* @return the package name * @return the package name
* @throws IllegalArgumentException if the class is <code>null</code> * @throws IllegalArgumentException if the class is <code>null</code>
*/ */
@ -146,9 +153,10 @@ public class ClassUtils {
} }
/** /**
* Gets the package name of an Object. * <p>Gets the package name of an <code>Object</code>.</p>
* *
* @param object the class to get the package name for, must not be <code>null</code> * @param object the class to get the package name for, must not be
* <code>null</code>
* @return the package name * @return the package name
* @throws IllegalArgumentException if the object is <code>null</code> * @throws IllegalArgumentException if the object is <code>null</code>
*/ */
@ -160,9 +168,9 @@ public class ClassUtils {
} }
/** /**
* Gets the package name from a String. * <p>Gets the package name from a <code>String</code>.</p>
* <p> *
* The string passed in is assumed to be a class name - it is not checked. * <p>The string passed in is assumed to be a class name - it is not checked.</p>
* *
* @param className the className to get the package name for, must not be empty * @param className the className to get the package name for, must not be empty
* @return the package name * @return the package name
@ -182,10 +190,10 @@ public class ClassUtils {
// ------------------------------------------------------------------------- // -------------------------------------------------------------------------
/** /**
* Gets a list of superclasses for the given class. * <p>Gets a <code>List</code> of superclasses for the given class.</p>
* *
* @param cls the class to look up, must not be <code>null</code> * @param cls the class to look up, must not be <code>null</code>
* @return the list of superclasses in order going up from this one * @return the <code>List</code> of superclasses in order going up from this one
* @throws IllegalArgumentException if the class is <code>null</code> * @throws IllegalArgumentException if the class is <code>null</code>
*/ */
public static List getAllSuperclasses(Class cls) { public static List getAllSuperclasses(Class cls) {
@ -202,14 +210,15 @@ public class ClassUtils {
} }
/** /**
* Gets a list of all interfaces implemented by the given class. * <p>Gets a <code>List</code> of all interfaces implemented by the given
* <p> * class.</p>
* The order is determined by looking through each interface in turn as *
* <p>The order is determined by looking through each interface in turn as
* declared in the source file and following its hieracrchy up. Later * declared in the source file and following its hieracrchy up. Later
* duplicates are ignored, so the order is maintained. * duplicates are ignored, so the order is maintained.</p>
* *
* @param cls the class to look up, must not be <code>null</code> * @param cls the class to look up, must not be <code>null</code>
* @return the list of interfaces in order * @return the <code>List</code> of interfaces in order
* @throws IllegalArgumentException if the class is <code>null</code> * @throws IllegalArgumentException if the class is <code>null</code>
*/ */
public static List getAllInterfaces(Class cls) { public static List getAllInterfaces(Class cls) {
@ -234,14 +243,14 @@ public class ClassUtils {
} }
// /** // /**
// * Gets a list of subclasses of the specified class. // * <p>Gets a <code>List</code> of subclasses of the specified class.</p>
// * <p> // *
// * This method searches the classpath to find all the subclasses // * <p>This method searches the classpath to find all the subclasses
// * of a particular class available. No classes are loaded, the // * of a particular class available. No classes are loaded, the
// * returned list contains class names, not classes. // * returned list contains class names, not classes.</p>
// * // *
// * @param cls the class to find subclasses for // * @param cls the class to find subclasses for
// * @return the list of subclass String class names // * @return the <code>List</code> of subclass String class names
// * @throws IllegalArgumentException if the class is <code>null</code> // * @throws IllegalArgumentException if the class is <code>null</code>
// */ // */
// public static List getAllSubclassNames(Class cls) { // public static List getAllSubclassNames(Class cls) {
@ -253,13 +262,13 @@ public class ClassUtils {
// } // }
// /** // /**
// * Gets a list of subclasses of the specified class. // * <p>Gets a <code>List</code> of subclasses of the specified class.</p>
// * <p> // *
// * This method searches the classpath to find all the subclasses // * <p>This method searches the classpath to find all the subclasses
// * of a particular class available. // * of a particular class available.</p>
// * // *
// * @param cls the class to find subclasses for // * @param cls the class to find subclasses for
// * @return the list of subclasses // * @return the <code>List</code> of subclasses
// * @throws IllegalArgumentException if the class is <code>null</code> // * @throws IllegalArgumentException if the class is <code>null</code>
// */ // */
// public static List getAllSubclasses(Class cls) { // public static List getAllSubclasses(Class cls) {
@ -268,14 +277,14 @@ public class ClassUtils {
// } // }
// /** // /**
// * Gets a list of implementations of the specified interface. // * <p>Gets a <code>List</code> of implementations of the specified interface.</p>
// * <p> // *
// * This method searches the classpath to find all the implementations // * <p>This method searches the classpath to find all the implementations
// * of a particular interface available. No classes are loaded, the // * of a particular interface available. No classes are loaded, the
// * returned list contains class names, not classes. // * returned list contains class names, not classes.</p>
// * // *
// * @param cls the class to find sub classes for // * @param cls the class to find sub classes for
// * @return the list of implementation String class names // * @return the <code>List</code> of implementation String class names
// * @throws IllegalArgumentException if the class is <code>null</code> // * @throws IllegalArgumentException if the class is <code>null</code>
// */ // */
// public static List getAllImplementationClassNames(Class cls) { // public static List getAllImplementationClassNames(Class cls) {
@ -287,14 +296,15 @@ public class ClassUtils {
// } // }
/** /**
* Given a list of class names, this method converts them into classes. * <p>Given a <code>List</code> of class names, this method converts them into classes. *
* A new list is returned. If the class name cannot be found, <code>null</code> * A new <code>List</code> is returned. If the class name cannot be found, <code>null</code>
* is stored in the list. If the class name in the list is <code>null</code>, * is stored in the <code>List</code>. If the class name in the <code>List</code> is
* <code>null</code> is stored in the output list. * <code>null</code>, <code>null</code> is stored in the output <code>List</code>.</p>
* *
* @param classNames the classNames to change, the class is stored back * @param classNames the classNames to change, the class is stored back
* into the list. <code>null</code> will be stored in the list if no class is found. * into the <code>List</code>. <code>null</code> will be stored in the <code>List</code>
* @return the list of Class objects corresponding to the class names * if no class is found.
* @return the <code>List</code> of Class objects corresponding to the class names
* @throws IllegalArgumentException if the classNames is <code>null</code> * @throws IllegalArgumentException if the classNames is <code>null</code>
*/ */
public static List convertClassNamesToClasses(List classNames) { public static List convertClassNamesToClasses(List classNames) {
@ -314,8 +324,8 @@ public class ClassUtils {
} }
/** /**
* Given a list of classes, this method finds all those which are * <p>Given a <code>List</code> of classes, this method finds all those which
* subclasses or implementations of a specified superclass. * are subclasses or implementations of a specified superclass.</p>
* *
* @param classes the classes to check * @param classes the classes to check
* @param superclass the superclass to check for * @param superclass the superclass to check for
@ -344,30 +354,33 @@ public class ClassUtils {
} }
/** /**
* Checks if an array of Classes can be assigned to another array of Classes. * <p>Checks if an array of Classes can be assigned to another array of Classes.</p>
* <p> *
* This can be used to check if parameter types are suitably compatable for * <p>This can be used to check if parameter types are suitably compatable for
* reflection invocation. * reflection invocation.</p>
* <p> *
* Unlike the Class.isAssignableFrom method, this method takes into * <p>Unlike the {@link Class#isAssignableFrom(java.lang.Class)} method, this
* account widenings of primitive classes and <code>null</code>s. * method takes into account widenings of primitive classes and
* <p> * <code>null</code>s.</p>
* Primitive widenings allow an int to be assigned to a long, float or *
* double. This method returns the correct result for these cases. * <p>Primitive widenings allow an int to be assigned to a <code>long</code>,
* <p> * <code>float</code> or <code>double</code>. This method returns the correct
* <code>Null</code> may be assigned to any reference type. This method will return * result for these cases.</p>
* true if <code>null</code> is passed in and the toClass is non-primitive. *
* <p> * <p><code>Null</code> may be assigned to any reference type. This method will
* Specifically, this method tests whether the type represented by the * return <code>true</code> if <code>null</code> is passed in and the toClass is
* non-primitive.</p>
*
* <p>Specifically, this method tests whether the type represented by the
* specified <code>Class</code> parameter can be converted to the type * specified <code>Class</code> parameter can be converted to the type
* represented by this <code>Class</code> object via an identity conversion * represented by this <code>Class</code> object via an identity conversion
* widening primitive or widening reference conversion. See * widening primitive or widening reference conversion. See
* <em>The Java Language Specification</em>, sections 5.1.1, 5.1.2 and * <em><a href="http://java.sun.com/docs/books/jls/">The Java Language Specification</a></em>,
* 5.1.4 for details. * sections 5.1.1, 5.1.2 and 5.1.4 for details.</p>
* *
* @param classArray the array of Classes to check, may be <code>null</code> * @param classArray the array of Classes to check, may be <code>null</code>
* @param toClassArray the array of Classes to try to assign into, may be <code>null</code> * @param toClassArray the array of Classes to try to assign into, may be <code>null</code>
* @return true if assignment possible * @return <code>true</code> if assignment possible
*/ */
public static boolean isAssignable(Class[] classArray, Class[] toClassArray) { public static boolean isAssignable(Class[] classArray, Class[] toClassArray) {
if (ArrayUtils.isSameLength(classArray, toClassArray) == false) { if (ArrayUtils.isSameLength(classArray, toClassArray) == false) {
@ -388,27 +401,30 @@ public class ClassUtils {
} }
/** /**
* Checks if one Class can be assigned to a variable of another Class. * <p>Checks if one <code>Class</code> can be assigned to a variable of
* <p> * another <code>Class</code>.</p>
* Unlike the Class.isAssignableFrom method, this method takes into *
* account widenings of primitive classes and <code>null</code>s. * <p>Unlike the {@link Class#isAssignableFrom(java.lang.Class)} method,
* <p> * this method takes into account widenings of primitive classes and
* Primitive widenings allow an int to be assigned to a long, float or * <code>null</code>s.</p>
* double. This method returns the correct result for these cases. *
* <p> * <p>Primitive widenings allow an int to be assigned to a long, float or
* Null may be assigned to any reference type. This method will return * double. This method returns the correct result for these cases.</p>
* true if <code>null</code> is passed in and the toClass is non-primitive. *
* <p> * <p><code>Null</code> may be assigned to any reference type. This method
* Specifically, this method tests whether the type represented by the * will return <code>true</code> if <code>null</code> is passed in and the
* toClass is non-primitive.</p>
*
* <p>Specifically, this method tests whether the type represented by the
* specified <code>Class</code> parameter can be converted to the type * specified <code>Class</code> parameter can be converted to the type
* represented by this <code>Class</code> object via an identity conversion * represented by this <code>Class</code> object via an identity conversion
* widening primitive or widening reference conversion. See * widening primitive or widening reference conversion. See
* <em>The Java Language Specification</em>, sections 5.1.1, 5.1.2 and * <em><a href="http://java.sun.com/docs/books/jls/">The Java Language Specification</a></em>,
* 5.1.4 for details. * sections 5.1.1, 5.1.2 and 5.1.4 for details.</p>
* *
* @param cls the Class to check, may be <code>null</code> * @param cls the Class to check, may be <code>null</code>
* @param toClass the Class to try to assign into, must not be <code>null</code> * @param toClass the Class to try to assign into, must not be <code>null</code>
* @return true if assignment possible * @return <code>true</code> if assignment possible
* @throws IllegalArgumentException if the toClass is <code>null</code> * @throws IllegalArgumentException if the toClass is <code>null</code>
*/ */
public static boolean isAssignable(Class cls, Class toClass) { public static boolean isAssignable(Class cls, Class toClass) {
@ -470,10 +486,10 @@ public class ClassUtils {
} }
/** /**
* Is the specified class an inner class or static nested class. * <p>Is the specified class an inner class or static nested class.</p>
* *
* @param cls the class to check * @param cls the class to check
* @return true if the class is an inner or static nested class * @return <code>true</code> if the class is an inner or static nested class
* @throws IllegalArgumentException if the class is <code>null</code> * @throws IllegalArgumentException if the class is <code>null</code>
*/ */
public static boolean isInnerClass(Class cls) { public static boolean isInnerClass(Class cls) {

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

@ -63,13 +63,13 @@ import java.lang.reflect.Method;
import java.lang.reflect.InvocationTargetException; import java.lang.reflect.InvocationTargetException;
/** /**
* A utility which takes much of the pain out of the Event/Listener * <p>A utility which takes much of the pain out of the Event/Listener
* system. It handles the collection, and the loop-notification. * system. It handles the collection, and the loop-notification.
* Reflection is used for the actual notification call. * Reflection is used for the actual notification call.</p>
* *
* Alternate strategies are usable. For example this class currently * <p>Alternate strategies are usable. For example this class currently
* does not enforce a particular interface, which means it cannot * does not enforce a particular interface, which means it cannot
* cache that method. Doing this probably makes a lot of sense. * cache that method. Doing this probably makes a lot of sense.</p>
*/ */
public class Notifier { public class Notifier {
@ -93,8 +93,8 @@ public class Notifier {
} }
/** /**
* Construct with the class and the name of the method to * <p>Construct with the class and the name of the method to
* call upon the listeners. * call upon the listeners.</p>
*/ */
public Notifier(Class clss, String name) { public Notifier(Class clss, String name) {
if(clss == null) { if(clss == null) {
@ -128,10 +128,11 @@ public class Notifier {
} }
/** /**
* Convenience method for when a listener has a single method. * <p>Convenience method for when a listener has a single method.</p>
* Currently this method needs to be called, but it's possible *
* <p>Currently this method needs to be called, but it's possible
* that by providing the interface class, it can be assumed as * that by providing the interface class, it can be assumed as
* to what the listening method is. * to what the listening method is.</p>
*/ */
public void notify(EventObject event) throws NotifierException { public void notify(EventObject event) throws NotifierException {
if(this.clss == null) { if(this.clss == null) {
@ -142,9 +143,10 @@ public class Notifier {
} }
/** /**
* Notify the listeners of a certain event, to a certain method. * <p>Notify the listeners of a certain event, to a certain method.</p>
* This is usable when a Listener has more than one method and *
* a single Notifier wants to be shared. * <p>This is usable when a Listener has more than one method and
* a single <code>Notifier</code> wants to be shared.</p>
*/ */
private void notify(Method listenerMethod, EventObject event) throws NotifierException { private void notify(Method listenerMethod, EventObject event) throws NotifierException {
Iterator itr = getListeners().iterator(); Iterator itr = getListeners().iterator();
@ -165,9 +167,10 @@ public class Notifier {
} }
/** /**
* Notify the listeners of a certain event, to a certain method. * <p>Notify the listeners of a certain event, to a certain method.</p>
* This is usable when a Listener has more than one method and *
* a single Notifier wants to be shared. * <p>This is usable when a Listener has more than one method and
* a single Notifier wants to be shared.</p>
*/ */
public void notify(String methodName, EventObject event) throws NotifierException { public void notify(String methodName, EventObject event) throws NotifierException {
Iterator itr = getListeners().iterator(); Iterator itr = getListeners().iterator();

28
src/java/org/apache/commons/lang/NotifierException.java
View File

@ -56,24 +56,24 @@ package org.apache.commons.lang;
import org.apache.commons.lang.exception.NestableException; import org.apache.commons.lang.exception.NestableException;
/** /**
* Exception thrown when something goes wrong in notifying. * <p>Exception thrown when something goes wrong in notifying.</p>
* *
* @author <a href="mailto:bayard@apache.org">Henri Yandell</a> * @author <a href="mailto:bayard@apache.org">Henri Yandell</a>
* @version $Id: NotifierException.java,v 1.1 2002/11/12 03:01:05 bayard Exp $ * @version $Id: NotifierException.java,v 1.2 2002/11/16 10:41:03 scolebourne Exp $
*/ */
public class NotifierException extends NestableException { public class NotifierException extends NestableException {
/** /**
* Constructs a new <code>NotifierException</code> without specified * <p>Constructs a new <code>NotifierException</code> without specified
* detail message. * detail message.</p>
*/ */
public NotifierException() { public NotifierException() {
super(); super();
} }
/** /**
* Constructs a new <code>NotifierException</code> with specified * <p>Constructs a new <code>NotifierException</code> with specified
* detail message. * detail message.</p>
* *
* @param msg the error message. * @param msg the error message.
*/ */
@ -82,23 +82,23 @@ public class NotifierException extends NestableException {
} }
/** /**
* Constructs a new <code>NotifierException</code> with specified * <p>Constructs a new <code>NotifierException</code> with specified
* nested <code>Throwable</code> root cause. * nested <code>Throwable</code> root cause.</p>
* *
* @param rootCause the exception or error that caused this exception * @param rootCause the <code>Exception</code> or <code>Error</code> that
* to be thrown. * caused this exception to be thrown.
*/ */
public NotifierException(Throwable rootCause) { public NotifierException(Throwable rootCause) {
super(rootCause); super(rootCause);
} }
/** /**
* Constructs a new <code>NotifierException</code> with specified * <p>Constructs a new <code>NotifierException</code> with specified
* detail message and nested <code>Throwable</code> root cause. * detail message and nested <code>Throwable</code> root cause.</p>
* *
* @param msg the error message. * @param msg the error message.
* @param rootCause the exception or error that caused this exception * @param rootCause the <code>Exception</code> or <code>Error</code> that
* to be thrown. * caused this exception to be thrown.
*/ */
public NotifierException(String msg, Throwable rootCause) { public NotifierException(String msg, Throwable rootCause) {
super(msg, rootCause); super(msg, rootCause);

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

@ -55,11 +55,11 @@ package org.apache.commons.lang;
*/ */
/** /**
* Represents a range of {@link Number} objects. * <p>Represents a range of {@link Number} objects.</p>
* *
* @author <a href="mailto:chrise@esha.com">Christopher Elkins</a> * @author <a href="mailto:chrise@esha.com">Christopher Elkins</a>
* @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a> * @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a>
* @version $Revision: 1.2 $ $Date: 2002/11/07 16:59:44 $ * @version $Revision: 1.3 $ $Date: 2002/11/16 10:41:03 $
*/ */
public final class NumberRange { public final class NumberRange {
@ -72,8 +72,8 @@ public final class NumberRange {
/** /**
* Constructs a new instance using the specified number as both the * <p>Constructs a new <code>NumberRange</code> using the specified
* minimum and maximum in theis range. * number as both the minimum and maximum in this range.</p>
* *
* @param num the number to use for this range * @param num the number to use for this range
* @throws NullPointerException if the number is <code>null</code> * @throws NullPointerException if the number is <code>null</code>
@ -88,8 +88,8 @@ public final class NumberRange {
} }
/** /**
* Constructs a new instance with the specified minimum and maximum * <p>Constructs a new <code>NumberRange</code> with the specified
* numbers. * minimum and maximum numbers.</p>
* *
* @param min the minimum number in this range * @param min the minimum number in this range
* @param max the maximum number in this range * @param max the maximum number in this range
@ -112,7 +112,7 @@ public final class NumberRange {
} }
/** /**
* Returns the minimum number in this range. * <p>Returns the minimum number in this range.</p>
* *
* @return the minimum number in this range * @return the minimum number in this range
*/ */
@ -121,7 +121,7 @@ public final class NumberRange {
} }
/** /**
* Returns the maximum number in this range. * <p>Returns the maximum number in this range.</p>
* *
* @return the maximum number in this range * @return the maximum number in this range
*/ */
@ -130,7 +130,8 @@ public final class NumberRange {
} }
/** /**
* Tests whether the specified number occurs within this range. * <p>Tests whether the specified <code>number</code> occurs within
* this range.</p>
* *
* @param number the number to test * @param number the number to test
* @return <code>true</code> if the specified number occurs within this * @return <code>true</code> if the specified number occurs within this
@ -146,7 +147,8 @@ public final class NumberRange {
} }
/** /**
* Tests whether the specified range occurs entirely within this range. * <p>Tests whether the specified range occurs entirely within this
* range.</p>
* *
* @param range the range to test * @param range the range to test
* @return <code>true</code> if the specified range occurs entirely within * @return <code>true</code> if the specified range occurs entirely within
@ -161,7 +163,7 @@ public final class NumberRange {
} }
/** /**
* Tests whether the specified range overlaps with this range. * <p>Tests whether the specified range overlaps with this range.</p>
* *
* @param range the range to test * @param range the range to test
* @return <code>true</code> if the specified range overlaps with this * @return <code>true</code> if the specified range overlaps with this
@ -177,7 +179,8 @@ public final class NumberRange {
} }
/** /**
* Indicates whether some other object is "equal" to this one. * <p>Indicates whether some other <code>Object</code> is "equal" to
* this one</p>.
* *
* @param obj the reference object with which to compare * @param obj the reference object with which to compare
* @return <code>true</code> if this object is the same as the obj * @return <code>true</code> if this object is the same as the obj
@ -195,7 +198,7 @@ public final class NumberRange {
} }
/** /**
* Returns a hash code value for this object. * <p>Returns a hash code value for this object.</p>
* *
* @return a hash code value for this object * @return a hash code value for this object
*/ */
@ -207,10 +210,11 @@ public final class NumberRange {
} }
/** /**
* Returns the string representation of this range. This string is the * <p>Returns the string representation of this range.</p>
* string representation of the minimum and maximum numbers in the range, *
* separated by a hyphen. If a number is negative, then it is enclosed * <p>This string is the string representation of the minimum and
* in parentheses. * maximum numbers in the range, separated by a hyphen. If a number
* is negative, then it is enclosed in parentheses.</p>
* *
* @return the string representation of this range * @return the string representation of this range
*/ */

194
src/java/org/apache/commons/lang/NumberUtils.java
View File

@ -57,21 +57,22 @@ package org.apache.commons.lang;
import java.math.BigInteger; import java.math.BigInteger;
import java.math.BigDecimal; import java.math.BigDecimal;
/** /**
* Provides extra functionality for Java Number classes. * <p>Provides extra functionality for Java Number classes</p>.
* *
* @author <a href="mailto:bayard@generationjava.com">Henri Yandell</a> * @author <a href="mailto:bayard@generationjava.com">Henri Yandell</a>
* @author <a href="mailto:rand_mcneely@yahoo.com">Rand McNeely</a> * @author <a href="mailto:rand_mcneely@yahoo.com">Rand McNeely</a>
* @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a> * @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a>
* @author <a href="mailto:steve.downey@netfolio.com">Steve Downey</a> * @author <a href="mailto:steve.downey@netfolio.com">Steve Downey</a>
* @version $Id: NumberUtils.java,v 1.3 2002/09/28 10:34:54 scolebourne Exp $ * @version $Id: NumberUtils.java,v 1.4 2002/11/16 10:41:03 scolebourne Exp $
*/ */
public final class NumberUtils { public final class NumberUtils {
/** /**
* NumberUtils instances should NOT be constructed in standard programming. * <p>NumberUtils instances should NOT be constructed in standard programming.
* Instead, the class should be used as <code>NumberUtils.stringToInt("6");</code>. * Instead, the class should be used as <code>NumberUtils.stringToInt("6");</code>.</p>
* This constructor is public to permit tools that require a JavaBean instance *
* to operate. * <p>This constructor is public to permit tools that require a JavaBean instance
* to operate.</p>
*/ */
public NumberUtils() { public NumberUtils() {
} }
@ -79,18 +80,20 @@ public final class NumberUtils {
//-------------------------------------------------------------------- //--------------------------------------------------------------------
/** /**
* Convert a String to an int, returning zero if the conversion fails * <p>Convert a <code>String</code> to an <code>int</code>, returning
* <code>zero</code> if the conversion fails.</p>
* *
* @param str the string to convert * @param str the string to convert
* @return the int represented by the string, or zero if conversion fails * @return the int represented by the string, or <code>zero</code> if
* conversion fails
*/ */
public static int stringToInt(String str) { public static int stringToInt(String str) {
return stringToInt(str, 0); return stringToInt(str, 0);
} }
/** /**
* Convert a String to an int, returning a default value if the * <p>Convert a <code>String</code> to an <code>int</code>, returning a
* conversion fails. * default value if the conversion fails.</p>
* *
* @param str the string to convert * @param str the string to convert
* @param defaultValue the default value * @param defaultValue the default value
@ -142,23 +145,21 @@ public final class NumberUtils {
// plus minus everything. Prolly more. A lot are not separable. // plus minus everything. Prolly more. A lot are not separable.
/** /**
* <p> * <p>Turns a string value into a java.lang.Number.</p>
* Turns a string value into a java.lang.Number. *
* First, the value is examined for a type qualifier on the end * <p>First, the value is examined for a type qualifier on the end
* (<code>'f','F','d','D','l','L'</code>). If it is found, it starts * (<code>'f','F','d','D','l','L'</code>). If it is found, it starts
* trying to create succissively larger types from the type specified * trying to create succissively larger types from the type specified
* until one is found that can hold the value. * until one is found that can hold the value.</p>
* </p> *
* <p> * <p>If a type specifier is not found, it will check for a decimal point
* If a type specifier is not found, it will check for a decimal point * and then try successively larger types from <code>Integer</code> to
* and then try successively larger types from Integer to BigInteger * <code>BigInteger</code> and from <code>Float</code> to
* and from Float to BigDecimal. * <code>BigDecimal</code>.</p>
* </p> *
* <p> * <p>If the string starts with <code>0x</code> or <code>-0x</code>, it
* If the string starts with "0x" or "-0x", it will be interpreted as a * will be interpreted as a hexadecimal integer. Values with leading
* hexadecimal integer. Values with leading 0's will not be interpreted * <code>0</code>'s will not be interpreted as octal.</p>
* as octal.
* </p>
* *
* @param val String containing a number * @param val String containing a number
* @return Number created from the string * @return Number created from the string
@ -309,10 +310,12 @@ public final class NumberUtils {
} }
/** /**
* Utility method for createNumber. Returns true if s is null * <p>Utility method for {@link #createNumber(java.lang.String)}.</p>
*
* <p>Returns <code>true</code> if s is <code>null</code>.</p>
* *
* @param s the String to check * @param s the String to check
* @return if it is all zeros or null * @return if it is all zeros or <code>null</code>
*/ */
private static boolean isAllZeros(String s) { private static boolean isAllZeros(String s) {
if (s == null) { if (s == null) {
@ -329,10 +332,10 @@ public final class NumberUtils {
//-------------------------------------------------------------------- //--------------------------------------------------------------------
/** /**
* Convert a String to a Float * <p>Convert a <code>String</code> to a <code>Float</code>.</p>
* *
* @param val a String to convert * @param val a <code>String</code> to convert
* @return converted Float * @return converted <code>Float</code>
* @throws NumberFormatException if the value cannot be converted * @throws NumberFormatException if the value cannot be converted
*/ */
public static Float createFloat(String val) { public static Float createFloat(String val) {
@ -340,10 +343,10 @@ public final class NumberUtils {
} }
/** /**
* Convert a String to a Double * <p>Convert a <code>String</code> to a <code>Double</code>.</p>
* *
* @param val a String to convert * @param val a <code>String</code> to convert
* @return converted Double * @return converted <code>Double</code>
* @throws NumberFormatException if the value cannot be converted * @throws NumberFormatException if the value cannot be converted
*/ */
public static Double createDouble(String val) { public static Double createDouble(String val) {
@ -351,11 +354,11 @@ public final class NumberUtils {
} }
/** /**
* Convert a String to a Integer, handling hex and * <p>Convert a <code>String</code> to a <code>Integer</code>, handling
* octal notations. * hex and octal notations.</p>
* *
* @param val a String to convert * @param val a <code>String</code> to convert
* @return converted Integer * @return converted <code>Integer</code>
* @throws NumberFormatException if the value cannot be converted * @throws NumberFormatException if the value cannot be converted
*/ */
public static Integer createInteger(String val) { public static Integer createInteger(String val) {
@ -364,10 +367,10 @@ public final class NumberUtils {
} }
/** /**
* Convert a String to a Long * <p>Convert a <code>String</code> to a <code>Long</code>.</p>
* *
* @param val a String to convert * @param val a <code>String</code> to convert
* @return converted Long * @return converted <code>Long</code>
* @throws NumberFormatException if the value cannot be converted * @throws NumberFormatException if the value cannot be converted
*/ */
public static Long createLong(String val) { public static Long createLong(String val) {
@ -375,10 +378,10 @@ public final class NumberUtils {
} }
/** /**
* Convert a String to a BigInteger * <p>Convert a <code>String</code> to a <code>BigInteger</code>.</p>
* *
* @param val a String to convert * @param val a <code>String</code> to convert
* @return converted BigInteger * @return converted <code>BigInteger</code>
* @throws NumberFormatException if the value cannot be converted * @throws NumberFormatException if the value cannot be converted
*/ */
public static BigInteger createBigInteger(String val) { public static BigInteger createBigInteger(String val) {
@ -387,10 +390,10 @@ public final class NumberUtils {
} }
/** /**
* Convert a String to a BigDecimal * <p>Convert a <code>String</code> to a <code>BigDecimal</code>.</p>
* *
* @param val a String to convert * @param val a <code>String</code> to convert
* @return converted BigDecimal * @return converted <code>BigDecimal</code>
* @throws NumberFormatException if the value cannot be converted * @throws NumberFormatException if the value cannot be converted
*/ */
public static BigDecimal createBigDecimal(String val) { public static BigDecimal createBigDecimal(String val) {
@ -401,7 +404,7 @@ public final class NumberUtils {
//-------------------------------------------------------------------- //--------------------------------------------------------------------
/** /**
* Gets the minimum of three long values. * <p>Gets the minimum of three <code>long</code> values.</p>
* *
* @param a value 1 * @param a value 1
* @param b value 2 * @param b value 2
@ -419,7 +422,7 @@ public final class NumberUtils {
} }
/** /**
* Gets the minimum of three int values. * <p>Gets the minimum of three <code>int</code> values.</p>
* *
* @param a value 1 * @param a value 1
* @param b value 2 * @param b value 2
@ -437,7 +440,7 @@ public final class NumberUtils {
} }
/** /**
* Gets the maximum of three long values. * <p>Gets the maximum of three <code>long</code> values.</p>
* *
* @param a value 1 * @param a value 1
* @param b value 2 * @param b value 2
@ -455,7 +458,7 @@ public final class NumberUtils {
} }
/** /**
* Gets the maximum of three int values. * <p>Gets the maximum of three <code>int</code> values.</p>
* *
* @param a value 1 * @param a value 1
* @param b value 2 * @param b value 2
@ -475,13 +478,16 @@ public final class NumberUtils {
//-------------------------------------------------------------------- //--------------------------------------------------------------------
/** /**
* Compares two doubles for order. * <p>Compares two <code>doubles</code> for order.</p>
* <p> *
* This method is more comprhensive than the standard Java greater than, * <p>This method is more comprehensive than the standard Java greater
* less than and equals operators. * than, less than and equals operators.</p>
* It returns -1 if the first value is less than the second. * <ul>
* It returns +1 if the first value is greater than the second. * <li>It returns <code>-1</code> if the first value is less than the second.
* It returns 0 if the values are equal. * <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.
* </ul>
*
* <p> * <p>
* The ordering is as follows, largest to smallest: * The ordering is as follows, largest to smallest:
* <ul> * <ul>
@ -495,11 +501,15 @@ public final class NumberUtils {
* <li>Minimum double (-Double.MAX_VALUE) * <li>Minimum double (-Double.MAX_VALUE)
* <li>Negative infinity * <li>Negative infinity
* </ul> * </ul>
* Comparing NaN with NaN will return 0. * </p>
* *
* @param lhs the first double * <p>Comparing <code>NaN</code> with <code>NaN</code> will
* @param rhs the second double * return <code>0</code>.</p>
* @return -1 if lhs is less, +1 if greater, 0 if equal to rhs *
* @param lhs the first <code>double</code>
* @param rhs the second <code>double</code>
* @return <code>-1</code> if lhs is less, <code>+1</code> if greater,
* <code>0</code> if equal to rhs
*/ */
public static int compare(double lhs, double rhs) { public static int compare(double lhs, double rhs) {
if (lhs < rhs) { if (lhs < rhs) {
@ -531,15 +541,17 @@ public final class NumberUtils {
} }
/** /**
* Compares two floats for order. * <p>Compares two floats for order.</p>
* <p> *
* This method is more comprhensive than the standard Java greater than, * <p>This method is more comprhensive than the standard Java greater than,
* less than and equals operators. * less than and equals operators.</p>
* It returns -1 if the first value is less than the second. * <ul>
* It returns +1 if the first value is greater than the second. * <li>It returns <code>-1</code> if the first value is less than the second.
* It returns 0 if the values are equal. * <li>It returns <code>+1</code> if the first value is greater than the second.
* <p> * <li>It returns <code>0</code> if the values are equal.
* The ordering is as follows, largest to smallest: * </ul>
*
* <p> The ordering is as follows, largest to smallest:
* <ul> * <ul>
* <li>NaN * <li>NaN
* <li>Positive infinity * <li>Positive infinity
@ -551,11 +563,14 @@ public final class NumberUtils {
* <li>Minimum float (-Float.MAX_VALUE) * <li>Minimum float (-Float.MAX_VALUE)
* <li>Negative infinity * <li>Negative infinity
* </ul> * </ul>
* Comparing NaN with NaN will return 0.
* *
* @param lhs the first float * <p>Comparing <code>NaN</code> with <code>NaN</code> will return
* @param rhs the second float * <code>0</code>.</p>
* @return -1 if lhs is less, +1 if greater, 0 if equal to rhs *
* @param lhs the first <code>float</code>
* @param rhs the second <code>float</code>
* @return <code>-1</code> if lhs is less, <code>+1</code> if greater,
* <code>0</code> if equal to rhs
*/ */
public static int compare(float lhs, float rhs) { public static int compare(float lhs, float rhs) {
if (lhs < rhs) { if (lhs < rhs) {
@ -589,11 +604,14 @@ public final class NumberUtils {
//-------------------------------------------------------------------- //--------------------------------------------------------------------
/** /**
* Checks whether the String contains only digit characters. * <p>Checks whether the <code>String</code> contains only
* Null and blank string will return false. * digit characters.</p>
* *
* @param str the string to check * <p><code>Null</code> and empty String will return
* @return boolean contains only unicode numeric * <code>false</code>.</p>
*
* @param str the <code>String</code> to check
* @return <code>true</code> if str contains only unicode numeric
*/ */
public static boolean isDigits(String str) { public static boolean isDigits(String str) {
if ((str == null) || (str.length() == 0)) { if ((str == null) || (str.length() == 0)) {
@ -608,17 +626,17 @@ public final class NumberUtils {
} }
/** /**
* <p> * <p>Checks whether the String a valid Java number.</p>
* Checks whether the String a valid Java number.
* Valid numbers include hexadecimal marked with the "0x" qualifier,
* scientific notation and numbers marked with a type qualifier (e.g. 123L).
* </p>
* <p>
* Null and blank string will return false.
* </p>
* *
* @param str the string to check * <p>Valid numbers include hexadecimal marked with the <code>0x</code>
* @return true if the string is a correctly formatted number * qualifier, scientific notation and numbers marked with a type
* qualifier (e.g. 123L).</p>
*
* <p><code>Null</code> and empty String will return
* <code>false</code>.</p>
*
* @param str the <code>String</code> to check
* @return <code>true</code> if the string is a correctly formatted number
*/ */
public static boolean isNumber(String str) { public static boolean isNumber(String str) {
if ((str == null) || (str.length() == 0)) { if ((str == null) || (str.length() == 0)) {

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

@ -55,35 +55,41 @@ package org.apache.commons.lang;
import java.io.Serializable; import java.io.Serializable;
/** /**
* Common <code>Object</code> manipulation routines. * <p>Common <code>Object</code> manipulation routines.</p>
* *
* @author <a href="mailto:nissim@nksystems.com">Nissim Karpenstein</a> * @author <a href="mailto:nissim@nksystems.com">Nissim Karpenstein</a>
* @author <a href="mailto:janekdb@yahoo.co.uk">Janek Bogucki</a> * @author <a href="mailto:janekdb@yahoo.co.uk">Janek Bogucki</a>
* @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a> * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
* @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a> * @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a>
* @version $Id: ObjectUtils.java,v 1.4 2002/09/22 09:18:33 scolebourne Exp $ * @version $Id: ObjectUtils.java,v 1.5 2002/11/16 10:41:03 scolebourne Exp $
*/ */
public class ObjectUtils { public class ObjectUtils {
/** /**
* Singleton used as a null placeholder where null has another meaning. * <p>Singleton used as a <code>null</code> placeholder where
* <p> * <code>null</code> has another meaning.</p>
* For example, in a <code>HashMap</code> the get(key) method returns null *
* if the Map contains null or if there is no matching key. The Null * <p>For example, in a <code>HashMap</code> the
* placeholder can be used to distinguish between these two cases. * {@link java.util.HashMap#get(java.lang.Object)} method returns
* <p> * <code>null</code> if the <code>Map</code> contains
* Another example is <code>HashTable</code>, where <code>null</code> * <code>null</code> or if there is no matching key. The
* cannot be stored. * <code>Null</code> placeholder can be used to distinguish between
* <p> * these two cases.</p>
* This instance is Serializable. *
* <p>Another example is <code>HashTable</code>, where <code>null</code>
* cannot be stored.</p>
*
* <p>This instance is Serializable.</p>
*/ */
public static final Null NULL = new Null(); public static final Null NULL = new Null();
/** /**
* ObjectUtils instances should NOT be constructed in standard programming. * <p><code>ObjectUtils</code> instances should NOT be constructed in
* Instead, the class should be used as <code>ObjectUtils.defaultIfNull("a","b");</code>. * standard programming. Instead, the class should be used as
* This constructor is public to permit tools that require a JavaBean instance * <code>ObjectUtils.defaultIfNull("a","b");</code>.</p>
* to operate. *
* <p>This constructor is public to permit tools that require a JavaBean instance
* to operate.</p>
*/ */
public ObjectUtils() { public ObjectUtils() {
} }
@ -91,19 +97,20 @@ public class ObjectUtils {
//-------------------------------------------------------------------- //--------------------------------------------------------------------
/** /**
* Returns a default value if the object passed is null. * <p>Returns a default value if the object passed is
* <code>null</code>.</p>
* *
* @param object the object to test * @param object the <code>Object</code> to test
* @param defaultValue the default value to return * @param defaultValue the default value to return
* @return object if it is not null, defaultValue otherwise * @return <code>object</code> if it is not <code>null</code>, defaultValue otherwise
*/ */
public static Object defaultIfNull(Object object, Object defaultValue) { public static Object defaultIfNull(Object object, Object defaultValue) {
return (object != null ? object : defaultValue); return (object != null ? object : defaultValue);
} }
/** /**
* Compares two objects for equality, where either one or both * <p>Compares two objects for equality, where either one or both
* objects may be <code>null</code>. * objects may be <code>null</code>.</p>
* *
* @param object1 the first object * @param object1 the first object
* @param object2 the second object * @param object2 the second object
@ -120,11 +127,14 @@ public class ObjectUtils {
} }
/** /**
* Gets the toString that would be produced by Object if a class did not * <p>Gets the toString that would be produced by <code>Object</code>
* override toString itself. Null will return null. * if a class did not override toString itself. <code>Null</code>
* will return <code>null</code>.</p>
* *
* @param object the object to create a toString for, may be null * @param object the object to create a toString for, may be
* @return the default toString text, or null if null passed in * <code>null</code>
* @return the default toString text, or <code>null</code> if
* <code>null</code> passed in
*/ */
public static String identityToString(Object object) { public static String identityToString(Object object) {
if (object == null) { if (object == null) {
@ -138,14 +148,17 @@ public class ObjectUtils {
} }
/** /**
* Class used as a null placeholder where null has another meaning. * <p>Class used as a null placeholder where null has another meaning.</p>
* <p> *
* For example, in a <code>HashMap</code> the get(key) method returns null * <p>For example, in a <code>HashMap</code> the
* if the Map contains null or if there is no matching key. The Null * {@link java.util.HashMap#get(java.lang.Object)} method returns
* placeholder can be used to distinguish between these two cases. * <code>null</code> if the <code>Map</code> contains
* <p> * <code>null</code> or if there is no matching key. The
* Another example is <code>HashTable</code>, where <code>null</code> * <code>Null</code> placeholder can be used to distinguish between
* cannot be stored. * these two cases.</p>
*
* <p>Another example is <code>HashTable</code>, where <code>null</code>
* cannot be stored.</p>
*/ */
public static class Null implements Serializable { public static class Null implements Serializable {
/** /**
@ -155,7 +168,8 @@ public class ObjectUtils {
} }
/** /**
* Ensure singleton. * <p>Ensure singleton.</p>
*
* @return the singleton value * @return the singleton value
*/ */
private Object readResolve() { private Object readResolve() {

130
src/java/org/apache/commons/lang/RandomStringUtils.java
View File

@ -63,29 +63,33 @@ import java.util.Random;
* @author <a href="mailto:bayard@generationjava.com">Henri Yandell</a> * @author <a href="mailto:bayard@generationjava.com">Henri Yandell</a>
* @author <a href="mailto:steven@caswell.name">Steven Caswell</a> * @author <a href="mailto:steven@caswell.name">Steven Caswell</a>
* @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a> * @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a>
* @version $Id: RandomStringUtils.java,v 1.5 2002/09/28 10:34:54 scolebourne Exp $ * @version $Id: RandomStringUtils.java,v 1.6 2002/11/16 10:41:03 scolebourne Exp $
*/ */
public class RandomStringUtils { public class RandomStringUtils {
/** /**
* Random object used by random method. This has to be not local * <p>Random object used by random method. This has to be not local
* to the random method so as to not return the same value in the * to the random method so as to not return the same value in the
* same millisecond. * same millisecond.</p>
*/ */
private static final Random RANDOM = new Random(); private static final Random RANDOM = new Random();
/** /**
* RandomStringUtils instances should NOT be constructed in standard programming. * <p><code>RandomStringUtils</code> instances should NOT be constructed in
* Instead, the class should be used as <code>RandomStringUtils.random(5);</code>. * standard programming. Instead, the class should be used as
* This constructor is public to permit tools that require a JavaBean instance * <code>RandomStringUtils.random(5);</code>.</p>
* to operate. *
* <p>This constructor is public to permit tools that require a JavaBean instance
* to operate.</p>
*/ */
public RandomStringUtils() { public RandomStringUtils() {
} }
/** /**
* Creates a random string whose length is the number of characters * <p>Creates a random string whose length is the number of characters
* specified. Characters will be chosen from the set of all characters. * specified.</p>
*
* <p>Characters will be chosen from the set of all characters.</p>
* *
* @param count length of random string to create * @param count length of random string to create
* @return the random string * @return the random string
@ -95,9 +99,11 @@ public class RandomStringUtils {
} }
/** /**
* Creates a random string whose length is the number of characters * <p>Creates a random string whose length is the number of characters
* specified. Characters will be chosen from the set of characters whose * specified.</p>
* ASCII value is between 32 and 127 . *
* <p>Characters will be chosen from the set of characters whose
* ASCII value is between <code>32</code> and <code>127</code>.</p>
* *
* @param count length of random string to create * @param count length of random string to create
* @return the random string * @return the random string
@ -107,9 +113,11 @@ public class RandomStringUtils {
} }
/** /**
* Creates a random string whose length is the number of characters * <p>Creates a random string whose length is the number of characters
* specified. Characters will be chosen from the set of alphabetic * specified.</p>
* characters. *
* <p>Characters will be chosen from the set of alphabetic
* characters.</p>
* *
* @param count length of random string to create * @param count length of random string to create
* @return the random string * @return the random string
@ -119,9 +127,11 @@ public class RandomStringUtils {
} }
/** /**
* Creates a random string whose length is the number of characters * <p>Creates a random string whose length is the number of characters
* specified. Characters will be chosen from the set of alpha-numeric * specified.</p>
* characters. *
* <u>Characters will be chosen from the set of alpha-numeric
* characters.</p>
* *
* @param count length of random string to create * @param count length of random string to create
* @return the random string * @return the random string
@ -131,9 +141,11 @@ public class RandomStringUtils {
} }
/** /**
* Creates a random string whose length is the number of characters * <p>Creates a random string whose length is the number of characters
* specified. Characters will be chosen from the set of numeric * specified.</p>
* characters. *
* <p>Characters will be chosen from the set of numeric
* characters.</p>
* *
* @param count length of random string to create * @param count length of random string to create
* @return the random string * @return the random string
@ -143,9 +155,11 @@ public class RandomStringUtils {
} }
/** /**
* Creates a random string whose length is the number of characters * <p>Creates a random string whose length is the number of characters
* specified. Characters will be chosen from the set of alpha-numeric * specified.</p>
* characters as indicated by the arguments. *
* <p>Characters will be chosen from the set of alpha-numeric
* characters as indicated by the arguments.</p>
* *
* @param count length of random string to create * @param count length of random string to create
* @param letters if <code>true</code>, generated string will include * @param letters if <code>true</code>, generated string will include
@ -159,16 +173,18 @@ public class RandomStringUtils {
} }
/** /**
* Creates a random string whose length is the number of characters * <p>Creates a random string whose length is the number of characters
* specified. Characters will be chosen from the set of alpha-numeric * specified.</p>
* characters as indicated by the arguments. *
* <p>Characters will be chosen from the set of alpha-numeric
* characters as indicated by the arguments.</p>
* *
* @param count length of random string to create * @param count length of random string to create
* @param start int position in set of chars to start at * @param start position in set of chars to start at
* @param end int position in set of chars to end before * @param end position in set of chars to end before
* @param letters if <code>true</code>, generated string will include * @param letters if <code>true</code>, generated string will include
* alphabetic characters * alphabetic characters
* @param numbers if <code>true</code>, generatd string will include * @param numbers if <code>true</code>, generated string will include
* numeric characters * numeric characters
* @return the random string * @return the random string
*/ */
@ -177,24 +193,27 @@ public class RandomStringUtils {
} }
/** /**
* Creates a random string based on a variety of options. * <p>Creates a random string based on a variety of options.</p>
* If start and end are both 0, start and end are set to ' ' and 'z', the ASCII
* printable characters, will be used, unless letters and numbers are both
* false, in which case, start and end are set to 0 and Integer.MAX_VALUE.
* <p>
* If set is not null, characters between start and end are chosen.
* <p>
* *
* @param count int length of random string to create * <p>If start and end are both <code>0</code>, start and end are set
* @param start int position in set of chars to start at * to <code>' '</code> and <code>'z'</code>, the ASCII printable
* @param end int position in set of chars to end before * characters, will be used, unless letters and numbers are both
* @param letters boolean only allow letters? * <code>false</code>, in which case, start and end are set to
* @param numbers boolean only allow numbers? * <code>0</code> and <code>Integer.MAX_VALUE</code>.
* @param set char[] set of chars to choose randoms from. *
* If null, then it will use the set of all chars. * <p>If set is not <code>null</code>, characters between start and
* end are chosen.</p>
*
* @param count length of random string to create
* @param start position in set of chars to start at
* @param end position in set of chars to end before
* @param letters only allow letters?
* @param numbers only allow numbers?
* @param set set of chars to choose randoms from. If <code>null</code>,
* then it will use the set of all chars.
* @return the random string * @return the random string
* @throws ArrayIndexOutOfBoundsException if there are not (end - start) + 1 * @throws ArrayIndexOutOfBoundsException if there are not
* characters in the set array. * <code>(end - start) + 1</code> characters in the set array.
*/ */
public static String random(int count, int start, int end, boolean letters, boolean numbers, char[] set) { public static String random(int count, int start, int end, boolean letters, boolean numbers, char[] set) {
if( (start == 0) && (end == 0) ) { if( (start == 0) && (end == 0) ) {
@ -231,11 +250,13 @@ public class RandomStringUtils {
} }
/** /**
* Creates a random string whose length is the number of characters * <p>Creates a random string whose length is the number of characters
* specified. Characters will be chosen from the set of characters * specified.</p>
* specified.
* *
* @param count int length of random string to create * <p>Characters will be chosen from the set of characters
* specified.</p>
*
* @param count length of random string to create
* @param set String containing the set of characters to use * @param set String containing the set of characters to use
* @return the random string * @return the random string
*/ */
@ -244,11 +265,12 @@ public class RandomStringUtils {
} }
/** /**
* Creates a random string whose length is the number of characters * <p>Creates a random string whose length is the number of characters
* specified. Characters will be chosen from the set of characters * specified.</p>
* specified.
* *
* @param count int length of random string to create * <p>Characters will be chosen from the set of characters specified.</p>
*
* @param count length of random string to create
* @param set character array containing the set of characters to use * @param set character array containing the set of characters to use
* @return the random string * @return the random string
*/ */

31
src/java/org/apache/commons/lang/SerializationException.java
View File

@ -57,25 +57,26 @@ package org.apache.commons.lang;
import org.apache.commons.lang.exception.NestableRuntimeException; import org.apache.commons.lang.exception.NestableRuntimeException;
/** /**
* Exception thrown when the Serialization process fails. The original * <p>Exception thrown when the Serialization process fails.</p>
* error is wrapped within this one. *
* <p>The original error is wrapped within this one.</p>
* *
* @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a> * @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a>
* @version $Id: SerializationException.java,v 1.2 2002/08/31 11:11:03 scolebourne Exp $ * @version $Id: SerializationException.java,v 1.3 2002/11/16 10:41:03 scolebourne Exp $
*/ */
public class SerializationException extends NestableRuntimeException { public class SerializationException extends NestableRuntimeException {
/** /**
* Constructs a new <code>SerializationException</code> without specified * <p>Constructs a new <code>SerializationException</code> without specified
* detail message. * detail message.</p>
*/ */
public SerializationException() { public SerializationException() {
super(); super();
} }
/** /**
* Constructs a new <code>SerializationException</code> with specified * <p>Constructs a new <code>SerializationException</code> with specified
* detail message. * detail message.</p>
* *
* @param msg The error message. * @param msg The error message.
*/ */
@ -84,23 +85,23 @@ public class SerializationException extends NestableRuntimeException {
} }
/** /**
* Constructs a new <code>SerializationException</code> with specified * <p>Constructs a new <code>SerializationException</code> with specified
* nested <code>Throwable</code>. * nested <code>Throwable</code>.</p>
* *
* @param cause The exception or error that caused this exception * @param cause The <code>Exception</code> or <code>Error</code>
* to be thrown. * that caused this exception to be thrown.
*/ */
public SerializationException(Throwable cause) { public SerializationException(Throwable cause) {
super(cause); super(cause);
} }
/** /**
* Constructs a new <code>SerializationException</code> with specified * <p>Constructs a new <code>SerializationException</code> with specified
* detail message and nested <code>Throwable</code>. * detail message and nested <code>Throwable</code>.</p>
* *
* @param msg The error message. * @param msg The error message.
* @param cause The exception or error that caused this exception * @param cause The <code>Exception</code> or <code>Error</code>
* to be thrown. * that caused this exception to be thrown.
*/ */
public SerializationException(String msg, Throwable cause) { public SerializationException(String msg, Throwable cause) {
super(msg, cause); super(msg, cause);

39
src/java/org/apache/commons/lang/SerializationUtils.java
View File

@ -64,8 +64,8 @@ import java.io.OutputStream;
import java.io.Serializable; import java.io.Serializable;
/** /**
* Methods that assist with the serialization process, or perform * <p>Methods that assist with the serialization process, or perform
* additional functionality based on serialization. * additional functionality based on serialization.</p>
* <ul> * <ul>
* <li>Deep clone using serialization * <li>Deep clone using serialization
* <li>Serialize managing finally and IOException * <li>Serialize managing finally and IOException
@ -76,25 +76,25 @@ import java.io.Serializable;
* @author <a href="mailto:janekdb@yahoo.co.uk">Janek Bogucki</a> * @author <a href="mailto:janekdb@yahoo.co.uk">Janek Bogucki</a>
* @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a> * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
* @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a> * @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a>
* @version $Id: SerializationUtils.java,v 1.2 2002/08/31 11:09:45 scolebourne Exp $ * @version $Id: SerializationUtils.java,v 1.3 2002/11/16 10:41:03 scolebourne Exp $
*/ */
public class SerializationUtils { public class SerializationUtils {
/** /**
* Constructor for SerializationUtils is private * <p>Constructor for SerializationUtils is private.</p>
*/ */
private SerializationUtils() { private SerializationUtils() {
super(); super();
} }
/** /**
* Deep clone an object using serialization. * <p>Deep clone an <code>Object</code> using serialization.</p>
* <p> *
* This is many times slower than writing clone methods by hand * <p>This is many times slower than writing clone methods by hand
* on all objects in your object graph. However, for complex object * on all objects in your object graph. However, for complex object
* graphs, or for those that don't support deep cloning this can * graphs, or for those that don't support deep cloning this can
* be a simple alternative implementation. Of course all the objects * be a simple alternative implementation. Of course all the objects
* must be <code>Serializable</code>. * must be <code>Serializable</code>.</p>
* *
* @param object the <code>Serializable</code> object to clone * @param object the <code>Serializable</code> object to clone
* @return the cloned object * @return the cloned object
@ -105,10 +105,11 @@ public class SerializationUtils {
} }
/** /**
* Serializes an object to the specified stream. The stream will * <p>Serializes an <code>Object</code> to the specified stream.</p>
* be closed once the object is written. This avoids the need for *
* a finally clause, and maybe also exception handling, in the * <p>The stream will be closed once the object is written.
* application code. * This avoids the need for a finally clause, and maybe also exception
* handling, in the application code.</p>
* *
* @param obj the object to serialize to bytes * @param obj the object to serialize to bytes
* @param outputStream the stream to write to * @param outputStream the stream to write to
@ -135,7 +136,8 @@ public class SerializationUtils {
} }
/** /**
* Serializes an object to a byte array for storage/serialization. * <p>Serializes an <code>Object</code> to a byte array for
* storage/serialization.</p>
* *
* @param obj the object to serialize to bytes * @param obj the object to serialize to bytes
* @return a byte[] with the converted Serializable * @return a byte[] with the converted Serializable
@ -148,10 +150,11 @@ public class SerializationUtils {
} }
/** /**
* Deserializes an object from the specified stream. The stream will * <p>Deserializes an <code>Object</code> from the specified stream.</p>
* be closed once the object is written. This avoids the need for *
* a finally clause, and maybe also exception handling, in the * <p>The stream will be closed once the object is written. This
* application code. * avoids the need for a finally clause, and maybe also exception
* handling, in the application code.</p>
* *
* @param inputStream the serialized object input stream * @param inputStream the serialized object input stream
* @return the deserialized object * @return the deserialized object
@ -180,7 +183,7 @@ public class SerializationUtils {
} }
/** /**
* Deserializes a single object from an array of bytes. * <p>Deserializes a single <code>Object</code> from an array of bytes.</p>
* *
* @param objectData the serialized object * @param objectData the serialized object
* @return the deserialized object * @return the deserialized object

513
src/java/org/apache/commons/lang/StringUtils.java
View File

File diff suppressed because it is too large Load Diff

39
src/java/org/apache/commons/lang/SystemUtils.java
View File

@ -55,21 +55,23 @@ package org.apache.commons.lang;
*/ */
/** /**
* Common <code>System</code> class helpers. * <p>Common <code>System</code> class helpers.</p>
* *
* @author Based on code from Avalon Excalibur * @author Based on code from Avalon Excalibur
* @author Based on code from Lucene * @author Based on code from Lucene
* @author <a href="mailto:scolebourne@apache.org">Stephen Colebourne</a> * @author <a href="mailto:scolebourne@apache.org">Stephen Colebourne</a>
* @author <a href="mailto:sdowney@panix.com">Steve Downey</a> * @author <a href="mailto:sdowney@panix.com">Steve Downey</a>
* @version $Id: SystemUtils.java,v 1.3 2002/10/29 19:47:02 bayard Exp $ * @version $Id: SystemUtils.java,v 1.4 2002/11/16 10:41:03 scolebourne Exp $
*/ */
public class SystemUtils { public class SystemUtils {
/** /**
* SystemUtils instances should NOT be constructed in standard programming. * <P>SystemUtils instances should NOT be constructed in standard
* Instead, the class should be used as <code>SystemUtils.FILE_SEPARATOR</code>. * programming. Instead, the class should be used as
* This constructor is public to permit tools that require a JavaBean instance * <code>SystemUtils.FILE_SEPARATOR</code>.</p>
* to operate. *
* <p>This constructor is public to permit tools that require a JavaBean
* instance to operate.</p>
*/ */
public SystemUtils() { public SystemUtils() {
} }
@ -409,10 +411,13 @@ public class SystemUtils {
// } // }
/** /**
* Get the Java version number as a float. * <p>Get the Java version number as a <code>float</code>.</p>
* Example output:<br> *
* 1.2f for JDK 1.2<br> * <P>Example output:</p>
* 1.31f for JDK 1.3.1<br> * <ul>
* <li><code>1.2f</code> for JDK 1.2
* <li><code>1.31f</code> for JDK 1.3.1
* </ul>
* *
* @return the version, for example 1.31f for JDK 1.3.1 * @return the version, for example 1.31f for JDK 1.3.1
*/ */
@ -425,13 +430,17 @@ public class SystemUtils {
} }
/** /**
* Is the Java version at the the requested version. * <p>Is the Java version at the the requested version.</p>
* Example input:<br> *
* 1.2f for JDK 1.2<br> * <p>Example input:</p>
* 1.31f for JDK 1.3.1<br> * <ul>
* <li><code>1.2f</code> for JDK 1.2
* <li><code>1.31f</code> for JDK 1.3.1
* </ul>
* *
* @param requiredVersion the required version, for example 1.31f * @param requiredVersion the required version, for example 1.31f
* @return true if the actual version is equal or greater than the required version * @return <code>true</code> if the actual version is equal or greater
* than the required version
*/ */
public boolean isJavaVersionAtLeast(float requiredVersion) { public boolean isJavaVersionAtLeast(float requiredVersion) {
return (getJavaVersion() >= requiredVersion); return (getJavaVersion() >= requiredVersion);