From 443e9b36965228f281b3fa3212baca04a486b35f Mon Sep 17 00:00:00 2001 From: Stephen Colebourne Date: Sat, 16 Aug 2003 12:41:23 +0000 Subject: [PATCH] Javadoc changes bug 22480, from Pete Gieser git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/lang/trunk@137608 13f79535-47bb-0310-9956-ffa450edef68 --- .../lang/builder/CompareToBuilder.java | 557 ++++++++++-------- .../lang/builder/StandardToStringStyle.java | 8 +- .../apache/commons/lang/builder/package.html | 5 +- 3 files changed, 306 insertions(+), 264 deletions(-) diff --git a/src/java/org/apache/commons/lang/builder/CompareToBuilder.java b/src/java/org/apache/commons/lang/builder/CompareToBuilder.java index f986c6444..cb6331b0d 100644 --- a/src/java/org/apache/commons/lang/builder/CompareToBuilder.java +++ b/src/java/org/apache/commons/lang/builder/CompareToBuilder.java @@ -63,44 +63,54 @@ import org.apache.commons.lang.math.NumberUtils; /** *

CompareTo generation routines.

* - *

This class provides methods to build a good compareTo - * method for any class. It is consistent with the equals() and + *

This class provides methods to assist in building a quality + * compareTo(Object). It is consistent with equals(Object) and * hashcode() built with {@link EqualsBuilder} and * {@link HashCodeBuilder}.

* - *

Two Objects that compare equal using equals() should normally - * also compare equal using compareTo()

. + *

Two Objects that compare equal using equals(Object) should normally + * also compare equal using compareTo(Object).

* *

All relevant fields should be included in the calculation of the * comparison. Derived fields may be ignored. The same fields, in the same - * order, should be used in both compareTo() and - * equals().

+ * order, should be used in both compareTo(Object) and + * equals(Object).

* - *

Typical use for the code is as follows:

+ *

To use this class write code as follows:

* * 
- *  public int compareTo(Object o) {
- *    MyClass rhs = (MyClass) o;
- *    return new CompareToBuilder()
- *                 .appendSuper(super.compareTo(o)
- *                 .append(field1, rhs.field1)
- *                 .append(field2, rhs.field2)
- *                 .append(field3, rhs.field3)
- *                 .toComparison();
- *  }
+ * public class MyClass {
+ *   String field1;
+ *   int field2;
+ *   boolean field3;
+ *
+ *   ...
+ *
+ *   public int compareTo(Object o) {
+ *     MyClass myClass = (MyClass) o;
+ *     return new CompareToBuilder()
+ *       .appendSuper(super.compareTo(o)
+ *       .append(this.field1, myClass.field1)
+ *       .append(this.field2, myClass.field2)
+ *       .append(this.field3, myClass.field3)
+ *       .toComparison();
+ *   }
+ * }
  *
* - *

Alternatively, there is a method that uses reflection to determine - * the fields to test. Because these fields are usually private, the method, - * reflectionCompare, uses AccessibleObject.setAccessible to change - * the visibility of the fields. This will fail under a security manager, - * unless the appropriate permissions are set. It is also slower than testing - * explicitly.

+ *

Alternatively, there is a method {@link #reflectionCompare reflectionCompare} that uses + * reflection to determine the fields to append. Because fields can be private, + * reflectionCompare uses AccessibleObject.setAccessible to + * bypass normal access control checks. This will fail under a security manager, + * unless the appropriate permissions are set up correctly. It is also + * slower than appending explicitly.

* - *

A typical invocation for this method would look like:

+ *

A typical implementation of compareTo(Object) using + * reflectionCompare looks like:

+ * 
  * public int compareTo(Object o) {
- *   return CompareToBuilder.reflectionCompare(this, obj);
+ *   return CompareToBuilder.reflectionCompare(this, o);
  * }
  *
* @@ -109,12 +119,12 @@ import org.apache.commons.lang.math.NumberUtils; * @author Gary Gregory * @author Pete Gieser * @since 1.0 - * @version $Id: CompareToBuilder.java,v 1.19 2003/07/21 23:32:41 scolebourne Exp $ + * @version $Id: CompareToBuilder.java,v 1.20 2003/08/16 12:40:31 scolebourne Exp $ */ public class CompareToBuilder { /** - * If the fields tested are equals. + * Current state of the comparison as appended fields are checked. */ private int comparison; @@ -130,121 +140,128 @@ public class CompareToBuilder { comparison = 0; } - //------------------------------------------------------------------------- - + //----------------------------------------------------------------------- /** - *

This method uses reflection to determine the ordering between two - * Objects.

+ *

Compares two Objects via reflection.

* - *

It uses AccessibleObject.setAccessible to gain access to private - * fields. This means that it will throw a security exception if run under - * a security manager, if the permissions are not set up correctly. It is - * also not as efficient as testing explicitly.

+ *

Fields can be private, thus AccessibleObject.setAccessible + * is used to bypass normal access control checks. This will fail under a + * security manager unless the appropriate permissions are set.

* - *

Transient members will be not be tested, as they are likely derived - * fields, and not part of the value of the object.

+ * * - *

Static fields will not be tested. Superclass fields will be included.

+ *

If both lhs and rhs are null, + * they are considered equal.

* - * @param lhs this object - * @param rhs the other object - * @return a negative integer, zero, or a positive integer as this - * Object is less than, equal to, or greater than the specified Object. - * @throws NullPointerException if either (but not both) parameter is + * @param lhs left-hand object + * @param rhs right-hand object + * @return a negative integer, zero, or a positive integer as lhs + * is less than, equal to, or greater than rhs + * @throws NullPointerException if either (but not both) parameters are * null - * @throws ClassCastException if the specified Object's type prevents it - * from being compared to this Object. + * @throws ClassCastException if rhs is not assignment-compatible + * with lhs */ public static int reflectionCompare(Object lhs, Object rhs) { return reflectionCompare(lhs, rhs, false, null); } /** - *

This method uses reflection to determine if the two Objects are - * equal.

+ *

Compares two Objects via reflection.

* - *

It uses AccessibleObject.setAccessible to gain access to private - * fields. This means that it will throw a security exception if run under - * a security manager, if the permissions are not set up correctly. It is - * also not as efficient as testing explicitly.

+ *

Fields can be private, thus AccessibleObject.setAccessible + * is used to bypass normal access control checks. This will fail under a + * security manager unless the appropriate permissions are set.

* - *

If the testTransients is set to true, - * transient members will be tested, otherwise they are ignored, as they - * are likely derived fields, and not part of the value of the object.

+ * * - *

Static fields will not be tested. Superclass fields will be included.

- * - * @param lhs this object - * @param rhs the other object - * @param testTransients whether to include transient fields - * @return a negative integer, zero, or a positive integer as this - * Object is less than, equal to, or greater than the specified Object. - * @throws NullPointerException if either (but not both) parameter is - * null - * @throws ClassCastException if the specified Object's type prevents it - * from being compared to this Object. + *

If both lhs and rhs are null, + * they are considered equal.

+ * + * @param lhs left-hand object + * @param rhs right-hand object + * @param compareTransients whether to compare transient fields + * @return a negative integer, zero, or a positive integer as lhs + * is less than, equal to, or greater than rhs + * @throws NullPointerException if either lhs or rhs + * (but not both) is null + * @throws ClassCastException if rhs is not assignment-compatible + * with lhs */ - public static int reflectionCompare(Object lhs, Object rhs, boolean testTransients) { - return reflectionCompare(lhs, rhs, testTransients, null); + public static int reflectionCompare(Object lhs, Object rhs, boolean compareTransients) { + return reflectionCompare(lhs, rhs, compareTransients, null); } /** - *

This method uses reflection to determine if the two Objects are - * equal.

+ *

Compares two Objects via reflection.

* - *

It uses AccessibleObject.setAccessible to gain access to private - * fields. This means that it will throw a security exception if run under - * a security manager, if the permissions are not set up correctly. It is - * also not as efficient as testing explicitly.

+ *

Fields can be private, thus AccessibleObject.setAccessible + * is used to bypass normal access control checks. This will fail under a + * security manager unless the appropriate permissions are set.

* - *

If the testTransients is set to true, - * transient members will be tested, otherwise they are ignored, as they - * are likely derived fields, and not part of the value of the object.

+ * * - *

Static fields will not be included. Superclass fields will be appended - * up to and including the specified superclass. A null superclass is treated - * as java.lang.Object.

- * - * @param lhs this object - * @param rhs the other object - * @param testTransients whether to include transient fields - * @param reflectUpToClass the superclass to reflect up to (inclusive), may be null - * @return a negative integer, zero, or a positive integer as this - * Object is less than, equal to, or greater than the specified Object. - * @throws NullPointerException if either (but not both) parameter is - * null - * @throws ClassCastException if the specified Object's type prevents it - * from being compared to this Object. + *

If both lhs and rhs are null, + * they are considered equal.

+ * + * @param lhs left-hand object + * @param rhs right-hand object + * @param compareTransients whether to compare transient fields + * @param reflectUpToClass last superclass for which fields are compared + * @return a negative integer, zero, or a positive integer as lhs + * is less than, equal to, or greater than rhs + * @throws NullPointerException if either lhs or rhs + * (but not both) is null + * @throws ClassCastException if rhs is not assignment-compatible + * with lhs */ - public static int reflectionCompare(Object lhs, Object rhs, boolean testTransients, Class reflectUpToClass) { + public static int reflectionCompare(Object lhs, Object rhs, boolean compareTransients, Class reflectUpToClass) { if (lhs == rhs) { return 0; } if (lhs == null || rhs == null) { throw new NullPointerException(); } - Class c1 = lhs.getClass(); - if (!c1.isInstance(rhs)) { + Class lhsClazz = lhs.getClass(); + if (!lhsClazz.isInstance(rhs)) { throw new ClassCastException(); } CompareToBuilder compareToBuilder = new CompareToBuilder(); - reflectionAppend(lhs, rhs, c1, compareToBuilder, testTransients); - while (c1.getSuperclass() != null && c1 != reflectUpToClass) { - c1 = c1.getSuperclass(); - reflectionAppend(lhs, rhs, c1, compareToBuilder, testTransients); + reflectionAppend(lhs, rhs, lhsClazz, compareToBuilder, compareTransients); + while (lhsClazz.getSuperclass() != null && lhsClazz != reflectUpToClass) { + lhsClazz = lhsClazz.getSuperclass(); + reflectionAppend(lhs, rhs, lhsClazz, compareToBuilder, compareTransients); } return compareToBuilder.toComparison(); } /** - *

Appends the fields and values defined by the given object of the - * given Class.

+ *

Appends to builder the comparison of lhs + * to rhs using the fields defined in clazz.

* - * @param lhs the left hand object - * @param rhs the right hand object - * @param clazz the class to append details of - * @param builder the builder to append to - * @param useTransients whether to test transient fields + * @param lhs left-hand object + * @param rhs right-hand object + * @param clazz Class that defines fields to be compared + * @param builder CompareToBuilder to append to + * @param useTransients whether to compare transient fields */ private static void reflectionAppend( Object lhs, @@ -252,6 +269,7 @@ public class CompareToBuilder { Class clazz, CompareToBuilder builder, boolean useTransients) { + Field[] fields = clazz.getDeclaredFields(); AccessibleObject.setAccessible(fields, true); for (int i = 0; i < fields.length && builder.comparison == 0; i++) { @@ -262,21 +280,21 @@ public class CompareToBuilder { try { builder.append(f.get(lhs), f.get(rhs)); } catch (IllegalAccessException e) { - //this can't happen. Would get a Security exception instead - //throw a runtime exception in case the impossible happens. + // This can't happen. Would get a Security exception instead. + // Throw a runtime exception in case the impossible happens. throw new InternalError("Unexpected IllegalAccessException"); } } } } - //------------------------------------------------------------------------- - + //----------------------------------------------------------------------- /** - *

Adds the result of super.hashCode() to this builder.

+ *

Appends to the builder the compareTo(Object) + * result of the superclass.

* - * @param superCompareTo the result of calling super.compareTo() - * @return CompareToBuilder - used to chain calls. + * @param superCompareTo result of calling super.compareTo(Object) + * @return this - used to chain append calls */ public CompareToBuilder appendSuper(int superCompareTo) { if (comparison != 0) { @@ -286,49 +304,53 @@ public class CompareToBuilder { return this; } - //------------------------------------------------------------------------- - + //----------------------------------------------------------------------- /** - *

Comparison of two Object references.

+ *

Appends to the builder the comparison of + * two Objects.

* *
    - *
  1. Check if Objects are same using ==
    2. - *
  2. Check if either is null, a null object is less than a non-null
    3. - *
  3. Check the object contents
    4. + *
  4. Check if lhs == rhs
    5. + *
  5. Check if either lhs or rhs is null, + * a null object is less than a non-null object
    6. + *
  6. Check the object contents
    7. *
* - *

The first parameter to be compared must either be an array or implement - * Comparable.

+ *

lhs must either be an array or implement {@link Comparable}.

* - * @param lhs the Object from this object - * @param rhs the Object from the other object - * @return CompareToBuilder - used to chain calls. - * @throws ClassCastException if the specified Object's type prevents it - * from being compared to this Object. + * @param lhs left-hand object + * @param rhs right-hand object + * @return this - used to chain append calls + * @throws ClassCastException if rhs is not assignment-compatible + * with lhs */ public CompareToBuilder append(Object lhs, Object rhs) { return append(lhs, rhs, null); } /** - *

Comparison of two Object references.

- *
    - *
  1. Check if Objects are same using ==
    2. - *
  2. Check if either is null, a null object is less than a non-null
    3. - *
  3. Check the object contents
    4. - *
- * - *

If the first parameter to be compared is an array, the array methods will - * be used. Otherwise the comparator will be used. If the comparator is null, - * the lhs will be cast to Comparable.

+ *

Appends to the builder the comparison of + * two Objects.

* - * @param lhs the Object from this object - * @param rhs the Object from the other object - * @param comparator the comparator to use to compare the objects, - * null means to treat the lhs as Comparable. - * @return CompareToBuilder - used to chain calls. - * @throws ClassCastException if the specified Object's type prevents it - * from being compared to this Object. + *
    + *
  1. Check if lhs == rhs
    2. + *
  2. Check if either lhs or rhs is null, + * a null object is less than a non-null object
    3. + *
  3. Check the object contents
    4. + *
+ * + *

If lhs is an array, array comparison methods will be used. + * Otherwise comparator will be used to compare the objects. + * If comparator is null, lhs must + * implement {@link Comparable} instead.

+ * + * @param lhs left-hand object + * @param rhs right-hand object + * @param comparator Comparator used to compare the objects, + * null means treat lhs as Comparable + * @return this - used to chain append calls + * @throws ClassCastException if rhs is not assignment-compatible + * with lhs */ public CompareToBuilder append(Object lhs, Object rhs, Comparator comparator) { if (comparison != 0) { @@ -345,11 +367,10 @@ public class CompareToBuilder { comparison = +1; return this; } - Class lhsClass = lhs.getClass(); - if (lhsClass.isArray()) { - // 'Switch' on type of array, to dispatch to the correct handler - // This handles multi dimensional arrays - // this could throw a ClassCastException is rhs is not the correct array type + if (lhs.getClass().isArray()) { + // switch on type of array, to dispatch to the correct handler + // handles multi dimensional arrays + // throws a ClassCastException if rhs is not the correct array type if (lhs instanceof long[]) { append((long[]) lhs, (long[]) rhs); } else if (lhs instanceof int[]) { @@ -367,8 +388,8 @@ public class CompareToBuilder { } else if (lhs instanceof boolean[]) { append((boolean[]) lhs, (boolean[]) rhs); } else { - // Not an array of primitives - // this could throw a ClassCastException is rhs is not an array + // not an array of primitives + // throws a ClassCastException if rhs is not an array append((Object[]) lhs, (Object[]) rhs, comparator); } } else { @@ -382,12 +403,14 @@ public class CompareToBuilder { return this; } + //------------------------------------------------------------------------- /** - *

Test if two longs are <, > or ==.

+ * Appends to the builder the comparison of + * two longs. * - * @param lhs the long from this object - * @param rhs the long from the other object - * @return CompareToBuilder - used to chain calls. + * @param lhs left-hand value + * @param rhs right-hand value + * @return this - used to chain append calls */ public CompareToBuilder append(long lhs, long rhs) { if (comparison != 0) { @@ -398,11 +421,12 @@ public class CompareToBuilder { } /** - *

Test if two ints are <, > or ==.

+ * Appends to the builder the comparison of + * two ints. * - * @param lhs the int from this object - * @param rhs the int from the other object - * @return CompareToBuilder - used to chain calls. + * @param lhs left-hand value + * @param rhs right-hand value + * @return this - used to chain append calls */ public CompareToBuilder append(int lhs, int rhs) { if (comparison != 0) { @@ -413,11 +437,12 @@ public class CompareToBuilder { } /** - *

Test if two shorts are <, > or ==.

+ * Appends to the builder the comparison of + * two shorts. * - * @param lhs the short from this object - * @param rhs the short from the other object - * @return CompareToBuilder - used to chain calls. + * @param lhs left-hand value + * @param rhs right-hand value + * @return this - used to chain append calls */ public CompareToBuilder append(short lhs, short rhs) { if (comparison != 0) { @@ -428,11 +453,12 @@ public class CompareToBuilder { } /** - *

Test if two chars are <, > or ==.

+ * Appends to the builder the comparison of + * two chars. * - * @param lhs the char from this object - * @param rhs the char from the other object - * @return CompareToBuilder - used to chain calls. + * @param lhs left-hand value + * @param rhs right-hand value + * @return this - used to chain append calls */ public CompareToBuilder append(char lhs, char rhs) { if (comparison != 0) { @@ -443,11 +469,12 @@ public class CompareToBuilder { } /** - *

Test if two bytes are <, > or ==.

+ * Appends to the builder the comparison of + * two bytes. * - * @param lhs the byte from this object - * @param rhs the byte from the other object - * @return CompareToBuilder - used to chain calls. + * @param lhs left-hand value + * @param rhs right-hand value + * @return this - used to chain append calls */ public CompareToBuilder append(byte lhs, byte rhs) { if (comparison != 0) { @@ -458,16 +485,17 @@ public class CompareToBuilder { } /** - *

Test if two doubles are <, > or ==.

+ *

Appends to the builder the comparison of + * two doubles.

* *

This handles NaNs, Infinties, and -0.0.

* *

It is compatible with the hash code generated by * HashCodeBuilder.

* - * @param lhs the double from this object - * @param rhs the double from the other object - * @return CompareToBuilder - used to chain calls. + * @param lhs left-hand value + * @param rhs right-hand value + * @return this - used to chain append calls */ public CompareToBuilder append(double lhs, double rhs) { if (comparison != 0) { @@ -478,16 +506,17 @@ public class CompareToBuilder { } /** - *

Test if two floats are <, > or ==.

+ *

Appends to the builder the comparison of + * two floats.

* *

This handles NaNs, Infinties, and -0.0.

* *

It is compatible with the hash code generated by * HashCodeBuilder.

* - * @param lhs the float from this object - * @param rhs the float from the other object - * @return CompareToBuilder - used to chain calls. + * @param lhs left-hand value + * @param rhs right-hand value + * @return this - used to chain append calls */ public CompareToBuilder append(float lhs, float rhs) { if (comparison != 0) { @@ -498,11 +527,12 @@ public class CompareToBuilder { } /** - *

Test if two booleanss are <, > or ==.

+ * Appends to the builder the comparison of + * two booleanss. * - * @param lhs the boolean from this object - * @param rhs the boolean from the other object - * @return CompareToBuilder - used to chain calls. + * @param lhs left-hand value + * @param rhs right-hand value + * @return this - used to chain append calls */ public CompareToBuilder append(boolean lhs, boolean rhs) { if (comparison != 0) { @@ -519,50 +549,53 @@ public class CompareToBuilder { return this; } + //----------------------------------------------------------------------- /** - *

Deep comparison of an Object array.

+ *

Appends to the builder the deep comparison of + * two Object arrays.

* *
    *
  1. Check if arrays are the same using ==
    2. - *
  2. Check if either is null, a null array is less than a non-null
    3. + *
  3. Check if for null, null is less than non-null
    4. *
  4. Check array length, a short length array is less than a long length array
    5. - *
  5. Check array contents element by element using {@link #append(long, long)}
    6. - *
- * - *

This method will also will be called for the top level of multi-dimensional, - * ragged, and multi-typed arrays.

- * - * @param lhs array from this object - * @param rhs array from the other object - * @return CompareToBuilder - used to chain calls. - * @throws ClassCastException if the specified Object's type prevents it - * from being compared to this Object. - */ - public CompareToBuilder append(Object[] lhs, Object[] rhs) { - return append(lhs, rhs, null); - } - - /** - *

Deep comparison of an Object array.

- * - *
    - *
  1. Check if arrays are the same using ==
    2. - *
  2. Check if either is null, a null array is less than a non-null
    3. - *
  3. Check array length, a shorter length array is less than a longer length array
    4. *
  4. Check array contents element by element using {@link #append(Object, Object, Comparator)}
    5. *
* *

This method will also will be called for the top level of multi-dimensional, * ragged, and multi-typed arrays.

* - * @param lhs array from this object - * @param rhs array from the other object - * @param comparator the comparator to use to compare the objects, - * null means to treat the lhs as Comparable. - * @return CompareToBuilder - used to chain calls. - * @throws ClassCastException if the specified Object's type prevents it - * from being compared to this Object. + * @param lhs left-hand array + * @param rhs right-hand array + * @return this - used to chain append calls + * @throws ClassCastException if rhs is not assignment-compatible + * with lhs */ + public CompareToBuilder append(Object[] lhs, Object[] rhs) { + return append(lhs, rhs, null); + } + + /** + *

Appends to the builder the deep comparison of + * two Object arrays.

+ * + *
    + *
  1. Check if arrays are the same using ==
    2. + *
  2. Check if for null, null is less than non-null
    3. + *
  3. Check array length, a short length array is less than a long length array
    4. + *
  4. Check array contents element by element using {@link #append(Object, Object, Comparator)}
    5. + *
+ * + *

This method will also will be called for the top level of multi-dimensional, + * ragged, and multi-typed arrays.

+ * + * @param lhs left-hand array + * @param rhs right-hand array + * @param comparator Comparator to use to compare the array elements, + * null means to treat lhs elements as Comparable. + * @return this - used to chain append calls + * @throws ClassCastException if rhs is not assignment-compatible + * with lhs + */ public CompareToBuilder append(Object[] lhs, Object[] rhs, Comparator comparator) { if (comparison != 0) { return this; @@ -589,18 +622,19 @@ public class CompareToBuilder { } /** - *

Deep comparison of a long array.

+ *

Appends to the builder the deep comparison of + * two long arrays.

* *
    *
  1. Check if arrays are the same using ==
    2. - *
  2. Check if either is null, a null array is less than a non-null
    3. + *
  3. Check if for null, null is less than non-null
    4. *
  4. Check array length, a shorter length array is less than a longer length array
    5. *
  5. Check array contents element by element using {@link #append(long, long)}
    6. *
* - * @param lhs array from this object - * @param rhs array from the other object - * @return CompareToBuilder - used to chain calls. + * @param lhs left-hand array + * @param rhs right-hand array + * @return this - used to chain append calls */ public CompareToBuilder append(long[] lhs, long[] rhs) { if (comparison != 0) { @@ -628,18 +662,19 @@ public class CompareToBuilder { } /** - *

Deep comparison of an int array.

+ *

Appends to the builder the deep comparison of + * two int arrays.

* *
    *
  1. Check if arrays are the same using ==
    2. - *
  2. Check if either is null, a null array is less than a non-null
    3. + *
  3. Check if for null, null is less than non-null
    4. *
  4. Check array length, a shorter length array is less than a longer length array
    5. *
  5. Check array contents element by element using {@link #append(int, int)}
    6. *
* - * @param lhs array from this object - * @param rhs array from the other object - * @return CompareToBuilder - used to chain calls. + * @param lhs left-hand array + * @param rhs right-hand array + * @return this - used to chain append calls */ public CompareToBuilder append(int[] lhs, int[] rhs) { if (comparison != 0) { @@ -667,18 +702,19 @@ public class CompareToBuilder { } /** - *

Deep comparison of a short array.

+ *

Appends to the builder the deep comparison of + * two short arrays.

* *
    *
  1. Check if arrays are the same using ==
    2. - *
  2. Check if either is null, a null array is less than a non-null
    3. + *
  3. Check if for null, null is less than non-null
    4. *
  4. Check array length, a shorter length array is less than a longer length array
    5. *
  5. Check array contents element by element using {@link #append(short, short)}
    6. *
* - * @param lhs array from this object - * @param rhs array from the other object - * @return CompareToBuilder - used to chain calls. + * @param lhs left-hand array + * @param rhs right-hand array + * @return this - used to chain append calls */ public CompareToBuilder append(short[] lhs, short[] rhs) { if (comparison != 0) { @@ -706,18 +742,19 @@ public class CompareToBuilder { } /** - *

Deep comparison of a char array.

+ *

Appends to the builder the deep comparison of + * two char arrays.

* *
    *
  1. Check if arrays are the same using ==
    2. - *
  2. Check if either is null, a null array is less than a non-null
    3. + *
  3. Check if for null, null is less than non-null
    4. *
  4. Check array length, a shorter length array is less than a longer length array
    5. *
  5. Check array contents element by element using {@link #append(char, char)}
    6. *
* - * @param lhs array from this object - * @param rhs array from the other object - * @return CompareToBuilder - used to chain calls. + * @param lhs left-hand array + * @param rhs right-hand array + * @return this - used to chain append calls */ public CompareToBuilder append(char[] lhs, char[] rhs) { if (comparison != 0) { @@ -745,18 +782,19 @@ public class CompareToBuilder { } /** - *

Deep comparison of a byte array.

+ *

Appends to the builder the deep comparison of + * two byte arrays.

* *
    *
  1. Check if arrays are the same using ==
    2. - *
  2. Check if either is null, a null array is less than a non-null
    3. + *
  3. Check if for null, null is less than non-null
    4. *
  4. Check array length, a shorter length array is less than a longer length array
    5. *
  5. Check array contents element by element using {@link #append(byte, byte)}
    6. *
* - * @param lhs array from this object - * @param rhs array from the other object - * @return CompareToBuilder - used to chain calls. + * @param lhs left-hand array + * @param rhs right-hand array + * @return this - used to chain append calls */ public CompareToBuilder append(byte[] lhs, byte[] rhs) { if (comparison != 0) { @@ -784,18 +822,19 @@ public class CompareToBuilder { } /** - *

Deep comparison of a double array.

+ *

Appends to the builder the deep comparison of + * two double arrays.

* *
    *
  1. Check if arrays are the same using ==
    2. - *
  2. Check if either is null, a null array is less than a non-null
    3. + *
  3. Check if for null, null is less than non-null
    4. *
  4. Check array length, a shorter length array is less than a longer length array
    5. *
  5. Check array contents element by element using {@link #append(double, double)}
    6. *
* - * @param lhs array from this object - * @param rhs array from the other object - * @return CompareToBuilder - used to chain calls. + * @param lhs left-hand array + * @param rhs right-hand array + * @return this - used to chain append calls */ public CompareToBuilder append(double[] lhs, double[] rhs) { if (comparison != 0) { @@ -823,18 +862,19 @@ public class CompareToBuilder { } /** - *

Deep comparison of a float array.

+ *

Appends to the builder the deep comparison of + * two float arrays.

* *
    *
  1. Check if arrays are the same using ==
    2. - *
  2. Check if either is null, a null array is less than a non-null
    3. + *
  3. Check if for null, null is less than non-null
    4. *
  4. Check array length, a shorter length array is less than a longer length array
    5. - *
  5. Check array contents element by element using {@link #append(float, float)} + *
  6. Check array contents element by element using {@link #append(float, float)}
    7. *
* - * @param lhs array from this object - * @param rhs array from the other object - * @return CompareToBuilder - used to chain calls. + * @param lhs left-hand array + * @param rhs right-hand array + * @return this - used to chain append calls */ public CompareToBuilder append(float[] lhs, float[] rhs) { if (comparison != 0) { @@ -862,18 +902,19 @@ public class CompareToBuilder { } /** - *

Deep comparison of a boolean/code> array.

+ *

Appends to the builder the deep comparison of + * two boolean arrays.

* *
    *
  1. Check if arrays are the same using ==
    2. - *
  2. Check if either is null, a null array is less than a non-null
    3. + *
  3. Check if for null, null is less than non-null
    4. *
  4. Check array length, a shorter length array is less than a longer length array
    5. *
  5. Check array contents element by element using {@link #append(boolean, boolean)}
    6. *
* - * @param lhs array from this object - * @param rhs array from the other object - * @return CompareToBuilder - used to chain calls. + * @param lhs left-hand array + * @param rhs right-hand array + * @return this - used to chain append calls */ public CompareToBuilder append(boolean[] lhs, boolean[] rhs) { if (comparison != 0) { @@ -900,14 +941,14 @@ public class CompareToBuilder { return this; } + //----------------------------------------------------------------------- /** - *

Return a negative integer if this Object is less - * than, a positive integer if this Object is greater than, - * or 0 if this Object is equal to the specified - * Object.

+ * Returns a negative integer, a positive integer, or zero as + * the builder has judged the "left-hand" side + * as less than, greater than, or equal to the "right-hand" + * side. * - * @return int - a negative integer, zero, or a positive integer as this - * Object is less than, equal to, or greater than the specified Object. + * @return final comparison result */ public int toComparison() { return comparison; diff --git a/src/java/org/apache/commons/lang/builder/StandardToStringStyle.java b/src/java/org/apache/commons/lang/builder/StandardToStringStyle.java index 7a682b967..5b9239ba3 100644 --- a/src/java/org/apache/commons/lang/builder/StandardToStringStyle.java +++ b/src/java/org/apache/commons/lang/builder/StandardToStringStyle.java @@ -57,16 +57,16 @@ package org.apache.commons.lang.builder; *

StandardToStringStyle works with {@link ToStringBuilder} * to create a toString.

* - *

This class is intended to be used as a Singleton. There - * is no need to instantiate a new style each time. Your code should - * instantiate the class once, customize the values as required, and then + *

This class is intended to be used as a singleton. + * There is no need to instantiate a new style each time. + * Simply instantiate the class once, customize the values as required, and * store the result in a public static final variable for the rest of the * program to access.

* * @author Stephen Colebourne * @author Pete Gieser * @since 1.0 - * @version $Id: StandardToStringStyle.java,v 1.10 2003/07/21 23:30:42 scolebourne Exp $ + * @version $Id: StandardToStringStyle.java,v 1.11 2003/08/16 12:41:23 scolebourne Exp $ */ public class StandardToStringStyle extends ToStringStyle { diff --git a/src/java/org/apache/commons/lang/builder/package.html b/src/java/org/apache/commons/lang/builder/package.html index 7d68184b6..a89bf2856 100644 --- a/src/java/org/apache/commons/lang/builder/package.html +++ b/src/java/org/apache/commons/lang/builder/package.html @@ -1,6 +1,7 @@ -Assists in creating good and consistent equals(), toString(), -hashCode(), and compareTo() methods. +Assists in creating consistent equals(Object), toString(), +hashCode(), and compareTo(Object) methods. +@since 1.0