You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by sc...@apache.org on 2003/08/16 14:40:31 UTC
cvs commit: jakarta-commons/lang/src/java/org/apache/commons/lang/builder CompareToBuilder.java
scolebourne 2003/08/16 05:40:31
Modified: lang/src/java/org/apache/commons/lang/builder
CompareToBuilder.java
Log:
Javadoc changes
bug 22480, from Pete Gieser
Revision Changes Path
1.20 +295 -254 jakarta-commons/lang/src/java/org/apache/commons/lang/builder/CompareToBuilder.java
Index: CompareToBuilder.java
===================================================================
RCS file: /home/cvs/jakarta-commons/lang/src/java/org/apache/commons/lang/builder/CompareToBuilder.java,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- CompareToBuilder.java 21 Jul 2003 23:32:41 -0000 1.19
+++ CompareToBuilder.java 16 Aug 2003 12:40:31 -0000 1.20
@@ -63,44 +63,54 @@
/**
* <p><code>CompareTo</code> generation routines.</p>
*
- * <p>This class provides methods to build a good <code>compareTo</code>
- * method for any class. It is consistent with the <code>equals()</code> and
+ * <p>This class provides methods to assist in building a quality
+ * <code>compareTo(Object)</code>. It is consistent with <code>equals(Object)</code> and
* <code>hashcode()</code> built with {@link EqualsBuilder} and
* {@link HashCodeBuilder}.</p>
*
- * <p>Two Objects that compare equal using <code>equals()</code> should normally
- * also compare equal using <code>compareTo()</code></p>.
+ * <p>Two Objects that compare equal using <code>equals(Object)</code> should normally
+ * also compare equal using <code>compareTo(Object)</code>.</p>
*
* <p>All relevant fields should be included in the calculation of the
* comparison. Derived fields may be ignored. The same fields, in the same
- * order, should be used in both <code>compareTo()</code> and
- * <code>equals()</code>.</p>
+ * order, should be used in both <code>compareTo(Object)</code> and
+ * <code>equals(Object)</code>.</p>
*
- * <p>Typical use for the code is as follows:</p>
+ * <p>To use this class write code as follows:</p>
*
* <pre>
- * 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();
+ * }
+ * }
* </pre>
*
- * <p>Alternatively, there is a method that uses reflection to determine
- * the fields to test. Because these fields are usually private, the method,
- * <code>reflectionCompare</code>, uses <code>AccessibleObject.setAccessible</code> 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.</p>
+ * <p>Alternatively, there is a method {@link #reflectionCompare reflectionCompare} that uses
+ * reflection to determine the fields to append. Because fields can be private,
+ * <code>reflectionCompare</code> uses <code>AccessibleObject.setAccessible</code> 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.</p>
*
- * <p>A typical invocation for this method would look like:</p>
+ * <p>A typical implementation of <code>compareTo(Object)</code> using
+ * <code>reflectionCompare</code> looks like:</p>
+
* <pre>
* public int compareTo(Object o) {
- * return CompareToBuilder.reflectionCompare(this, obj);
+ * return CompareToBuilder.reflectionCompare(this, o);
* }
* </pre>
*
@@ -114,7 +124,7 @@
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 @@
comparison = 0;
}
- //-------------------------------------------------------------------------
-
+ //-----------------------------------------------------------------------
/**
- * <p>This method uses reflection to determine the ordering between two
- * Objects.</p>
+ * <p>Compares two <code>Object</code>s via reflection.</p>
*
- * <p>It uses <code>AccessibleObject.setAccessible</code> 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.</p>
- *
- * <p>Transient members will be not be tested, as they are likely derived
- * fields, and not part of the value of the object.</p>
- *
- * <p>Static fields will not be tested. Superclass fields will be included.</p>
- *
- * @param lhs <code>this</code> 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
+ * <p>Fields can be private, thus <code>AccessibleObject.setAccessible</code>
+ * is used to bypass normal access control checks. This will fail under a
+ * security manager unless the appropriate permissions are set.</p>
+ *
+ * <ul>
+ * <li>Static fields will not be compared</li>
+ * <li>Transient members will be not be compared, as they are likely derived
+ * fields</li>
+ * <li>Superclass fields will be compared</li>
+ * </ul>
+ *
+ * <p>If both <code>lhs</code> and <code>rhs</code> are <code>null</code>,
+ * they are considered equal.</p>
+ *
+ * @param lhs left-hand object
+ * @param rhs right-hand object
+ * @return a negative integer, zero, or a positive integer as <code>lhs</code>
+ * is less than, equal to, or greater than <code>rhs</code>
+ * @throws NullPointerException if either (but not both) parameters are
* <code>null</code>
- * @throws ClassCastException if the specified Object's type prevents it
- * from being compared to this Object.
+ * @throws ClassCastException if <code>rhs</code> is not assignment-compatible
+ * with <code>lhs</code>
*/
public static int reflectionCompare(Object lhs, Object rhs) {
return reflectionCompare(lhs, rhs, false, null);
}
/**
- * <p>This method uses reflection to determine if the two Objects are
- * equal.</p>
- *
- * <p>It uses <code>AccessibleObject.setAccessible</code> 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.</p>
- *
- * <p>If the <code>testTransients</code> is set to <code>true</code>,
- * transient members will be tested, otherwise they are ignored, as they
- * are likely derived fields, and not part of the value of the object.</p>
+ * <p>Compares two <code>Object</code>s via reflection.</p>
*
- * <p>Static fields will not be tested. Superclass fields will be included.</p>
- *
- * @param lhs <code>this</code> 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
- * <code>null</code>
- * @throws ClassCastException if the specified Object's type prevents it
- * from being compared to this Object.
- */
- public static int reflectionCompare(Object lhs, Object rhs, boolean testTransients) {
- return reflectionCompare(lhs, rhs, testTransients, null);
+ * <p>Fields can be private, thus <code>AccessibleObject.setAccessible</code>
+ * is used to bypass normal access control checks. This will fail under a
+ * security manager unless the appropriate permissions are set.</p>
+ *
+ * <ul>
+ * <li>Static fields will not be compared</li>
+ * <li>If <code>compareTransients</code> is <code>true</code>,
+ * compares transient members. Otherwise ignores them, as they
+ * are likely derived fields.</li>
+ * <li>Superclass fields will be compared</li>
+ * </ul>
+ *
+ * <p>If both <code>lhs</code> and <code>rhs</code> are <code>null</code>,
+ * they are considered equal.</p>
+ *
+ * @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 <code>lhs</code>
+ * is less than, equal to, or greater than <code>rhs</code>
+ * @throws NullPointerException if either <code>lhs</code> or <code>rhs</code>
+ * (but not both) is <code>null</code>
+ * @throws ClassCastException if <code>rhs</code> is not assignment-compatible
+ * with <code>lhs</code>
+ */
+ public static int reflectionCompare(Object lhs, Object rhs, boolean compareTransients) {
+ return reflectionCompare(lhs, rhs, compareTransients, null);
}
/**
- * <p>This method uses reflection to determine if the two Objects are
- * equal.</p>
- *
- * <p>It uses <code>AccessibleObject.setAccessible</code> 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.</p>
- *
- * <p>If the <code>testTransients</code> is set to <code>true</code>,
- * transient members will be tested, otherwise they are ignored, as they
- * are likely derived fields, and not part of the value of the object.</p>
- *
- * <p>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.</p>
- *
- * @param lhs <code>this</code> object
- * @param rhs the other object
- * @param testTransients whether to include transient fields
- * @param reflectUpToClass the superclass to reflect up to (inclusive), may be null
- * @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
- * <code>null</code>
- * @throws ClassCastException if the specified Object's type prevents it
- * from being compared to this Object.
+ * <p>Compares two <code>Object</code>s via reflection.</p>
+ *
+ * <p>Fields can be private, thus <code>AccessibleObject.setAccessible</code>
+ * is used to bypass normal access control checks. This will fail under a
+ * security manager unless the appropriate permissions are set.</p>
+ *
+ * <ul>
+ * <li>Static fields will not be compared</li>
+ * <li>If the <code>compareTransients</code> is <code>true</code>,
+ * compares transient members. Otherwise ignores them, as they
+ * are likely derived fields.</li>
+ * <li>Compares superclass fields up to and including <code>reflectUpToClass</code>.
+ * If <code>reflectUpToClass</code> is <code>null</code>, compares all superclass fields.</li>
+ * </ul>
+ *
+ * <p>If both <code>lhs</code> and <code>rhs</code> are <code>null</code>,
+ * they are considered equal.</p>
+ *
+ * @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 <code>lhs</code>
+ * is less than, equal to, or greater than <code>rhs</code>
+ * @throws NullPointerException if either <code>lhs</code> or <code>rhs</code>
+ * (but not both) is <code>null</code>
+ * @throws ClassCastException if <code>rhs</code> is not assignment-compatible
+ * with <code>lhs</code>
*/
- 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();
}
/**
- * <p>Appends the fields and values defined by the given object of the
- * given Class.</p>
+ * <p>Appends to <code>builder</code> the comparison of <code>lhs</code>
+ * to <code>rhs</code> using the fields defined in <code>clazz</code>.</p>
*
- * @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 <code>Class</code> that defines fields to be compared
+ * @param builder <code>CompareToBuilder</code> to append to
+ * @param useTransients whether to compare transient fields
*/
private static void reflectionAppend(
Object lhs,
@@ -252,6 +269,7 @@
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 @@
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");
}
}
}
}
- //-------------------------------------------------------------------------
-
+ //-----------------------------------------------------------------------
/**
- * <p>Adds the result of super.hashCode() to this builder.</p>
+ * <p>Appends to the <code>builder</code> the <code>compareTo(Object)</code>
+ * result of the superclass.</p>
*
- * @param superCompareTo the result of calling <code>super.compareTo()</code>
- * @return CompareToBuilder - used to chain calls.
+ * @param superCompareTo result of calling <code>super.compareTo(Object)</code>
+ * @return this - used to chain append calls
*/
public CompareToBuilder appendSuper(int superCompareTo) {
if (comparison != 0) {
@@ -286,49 +304,53 @@
return this;
}
- //-------------------------------------------------------------------------
-
+ //-----------------------------------------------------------------------
/**
- * <p>Comparison of two Object references.</p>
+ * <p>Appends to the <code>builder</code> the comparison of
+ * two <code>Object</code>s.</p>
*
* <ol>
- * <li>Check if Objects are same using <code>==</code></li>
- * <li>Check if either is null, a null object is less than a non-null</li>
- * <li>Check the object contents</li>
+ * <li>Check if <code>lhs == rhs</code></li>
+ * <li>Check if either <code>lhs</code> or <code>rhs</code> is <code>null</code>,
+ * a <code>null</code> object is less than a non-<code>null</code> object</li>
+ * <li>Check the object contents</li>
* </ol>
*
- * <p>The first parameter to be compared must either be an array or implement
- * <code>Comparable</code>.</p>
+ * <p><code>lhs</code> must either be an array or implement {@link Comparable}.</p>
*
- * @param lhs the Object from <code>this</code> 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 <code>rhs</code> is not assignment-compatible
+ * with <code>lhs</code>
*/
public CompareToBuilder append(Object lhs, Object rhs) {
return append(lhs, rhs, null);
}
/**
- * <p>Comparison of two Object references.</p>
+ * <p>Appends to the <code>builder</code> the comparison of
+ * two <code>Object</code>s.</p>
+ *
* <ol>
- * <li>Check if Objects are same using <code>==</code></li>
- * <li>Check if either is null, a null object is less than a non-null</li>
- * <li>Check the object contents</li>
- * </ol>
- *
- * <p>If the first parameter to be compared is an array, the array methods will
- * be used. Otherwise the comparator will be used. If the comparator is null,
- * the <code>lhs</code> will be cast to <code>Comparable</code>.</p>
- *
- * @param lhs the Object from <code>this</code> object
- * @param rhs the Object from the other object
- * @param comparator the comparator to use to compare the objects,
- * <code>null</code> means to treat the <code>lhs</code> as <code>Comparable</code>.
- * @return CompareToBuilder - used to chain calls.
- * @throws ClassCastException if the specified Object's type prevents it
- * from being compared to this Object.
+ * <li>Check if <code>lhs == rhs</code></li>
+ * <li>Check if either <code>lhs</code> or <code>rhs</code> is <code>null</code>,
+ * a <code>null</code> object is less than a non-<code>null</code> object</li>
+ * <li>Check the object contents</li>
+ * </ol>
+ *
+ * <p>If <code>lhs</code> is an array, array comparison methods will be used.
+ * Otherwise <code>comparator</code> will be used to compare the objects.
+ * If <code>comparator</code> is <code>null</code>, <code>lhs</code> must
+ * implement {@link Comparable} instead.</p>
+ *
+ * @param lhs left-hand object
+ * @param rhs right-hand object
+ * @param comparator <code>Comparator</code> used to compare the objects,
+ * <code>null</code> means treat lhs as <code>Comparable</code>
+ * @return this - used to chain append calls
+ * @throws ClassCastException if <code>rhs</code> is not assignment-compatible
+ * with <code>lhs</code>
*/
public CompareToBuilder append(Object lhs, Object rhs, Comparator comparator) {
if (comparison != 0) {
@@ -345,11 +367,10 @@
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 @@
} 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 @@
return this;
}
+ //-------------------------------------------------------------------------
/**
- * <p>Test if two <code>long</code>s are <, > or ==.</p>
+ * Appends to the <code>builder</code> the comparison of
+ * two <code>long</code>s.
*
- * @param lhs the <code>long</code> from <code>this</code> object
- * @param rhs the <code>long</code> 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 @@
}
/**
- * <p>Test if two <code>int</code>s are <, > or ==.</p>
+ * Appends to the <code>builder</code> the comparison of
+ * two <code>int</code>s.
*
- * @param lhs the <code>int</code> from <code>this</code> object
- * @param rhs the <code>int</code> 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 @@
}
/**
- * <p>Test if two <code>short</code>s are <, > or ==.</p>
+ * Appends to the <code>builder</code> the comparison of
+ * two <code>short</code>s.
*
- * @param lhs the <code>short</code> from <code>this</code> object
- * @param rhs the <code>short</code> 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 @@
}
/**
- * <p>Test if two <code>char</code>s are <, > or ==.</p>
+ * Appends to the <code>builder</code> the comparison of
+ * two <code>char</code>s.
*
- * @param lhs the <code>char</code> from <code>this</code> object
- * @param rhs the <code>char</code> 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 @@
}
/**
- * <p>Test if two <code>byte</code>s are <, > or ==.</p>
+ * Appends to the <code>builder</code> the comparison of
+ * two <code>byte</code>s.
*
- * @param lhs the <code>byte</code> from <code>this</code> object
- * @param rhs the <code>byte</code> 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 @@
}
/**
- * <p>Test if two <code>double</code>s are <, > or ==.</p>
+ * <p>Appends to the <code>builder</code> the comparison of
+ * two <code>double</code>s.</p>
*
* <p>This handles NaNs, Infinties, and <code>-0.0</code>.</p>
*
* <p>It is compatible with the hash code generated by
* <code>HashCodeBuilder</code>.</p>
*
- * @param lhs the <code>double</code> from <code>this</code> object
- * @param rhs the <code>double</code> 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 @@
}
/**
- * <p>Test if two <code>float</code>s are <, > or ==.</p>
+ * <p>Appends to the <code>builder</code> the comparison of
+ * two <code>float</code>s.</p>
*
* <p>This handles NaNs, Infinties, and <code>-0.0</code>.</p>
*
* <p>It is compatible with the hash code generated by
* <code>HashCodeBuilder</code>.</p>
*
- * @param lhs the <code>float</code> from <code>this</code> object
- * @param rhs the <code>float</code> 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 @@
}
/**
- * <p>Test if two <code>booleans</code>s are <, > or ==.</p>
+ * Appends to the <code>builder</code> the comparison of
+ * two <code>booleans</code>s.
*
- * @param lhs the <code>boolean</code> from <code>this</code> object
- * @param rhs the <code>boolean</code> 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 @@
return this;
}
+ //-----------------------------------------------------------------------
/**
- * <p>Deep comparison of an <code>Object</code> array.</p>
+ * <p>Appends to the <code>builder</code> the deep comparison of
+ * two <code>Object</code> arrays.</p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
- * <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
+ * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a short length array is less than a long length array</li>
- * <li>Check array contents element by element using {@link #append(long, long)}</li>
+ * <li>Check array contents element by element using {@link #append(Object, Object, Comparator)}</li>
* </ol>
*
* <p>This method will also will be called for the top level of multi-dimensional,
* ragged, and multi-typed arrays.</p>
*
- * @param lhs array from <code>this</code> 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.
+ * @param lhs left-hand array
+ * @param rhs right-hand array
+ * @return this - used to chain append calls
+ * @throws ClassCastException if <code>rhs</code> is not assignment-compatible
+ * with <code>lhs</code>
*/
public CompareToBuilder append(Object[] lhs, Object[] rhs) {
return append(lhs, rhs, null);
}
/**
- * <p>Deep comparison of an <code>Object</code> array.</p>
+ * <p>Appends to the <code>builder</code> the deep comparison of
+ * two <code>Object</code> arrays.</p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
- * <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
- * <li>Check array length, a shorter length array is less than a longer length array</li>
+ * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
+ * <li>Check array length, a short length array is less than a long length array</li>
* <li>Check array contents element by element using {@link #append(Object, Object, Comparator)}</li>
* </ol>
*
* <p>This method will also will be called for the top level of multi-dimensional,
* ragged, and multi-typed arrays.</p>
*
- * @param lhs array from <code>this</code> object
- * @param rhs array from the other object
- * @param comparator the comparator to use to compare the objects,
- * <code>null</code> means to treat the <code>lhs</code> as <code>Comparable</code>.
- * @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
+ * @param comparator <code>Comparator</code> to use to compare the array elements,
+ * <code>null</code> means to treat <code>lhs</code> elements as <code>Comparable</code>.
+ * @return this - used to chain append calls
+ * @throws ClassCastException if <code>rhs</code> is not assignment-compatible
+ * with <code>lhs</code>
+ */
public CompareToBuilder append(Object[] lhs, Object[] rhs, Comparator comparator) {
if (comparison != 0) {
return this;
@@ -589,18 +622,19 @@
}
/**
- * <p>Deep comparison of a <code>long</code> array.</p>
+ * <p>Appends to the <code>builder</code> the deep comparison of
+ * two <code>long</code> arrays.</p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
- * <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
+ * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(long, long)}</li>
* </ol>
*
- * @param lhs array from <code>this</code> object
- * @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 @@
}
/**
- * <p>Deep comparison of an <code>int</code> array.</p>
+ * <p>Appends to the <code>builder</code> the deep comparison of
+ * two <code>int</code> arrays.</p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
- * <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
+ * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(int, int)}</li>
* </ol>
*
- * @param lhs array from <code>this</code> object
- * @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 @@
}
/**
- * <p>Deep comparison of a <code>short</code> array.</p>
+ * <p>Appends to the <code>builder</code> the deep comparison of
+ * two <code>short</code> arrays.</p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
- * <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
+ * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(short, short)}</li>
* </ol>
*
- * @param lhs array from <code>this</code> object
- * @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 @@
}
/**
- * <p>Deep comparison of a <code>char</code> array.</p>
+ * <p>Appends to the <code>builder</code> the deep comparison of
+ * two <code>char</code> arrays.</p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
- * <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
+ * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(char, char)}</li>
* </ol>
*
- * @param lhs array from <code>this</code> object
- * @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 @@
}
/**
- * <p>Deep comparison of a <code>byte</code> array.</p>
+ * <p>Appends to the <code>builder</code> the deep comparison of
+ * two <code>byte</code> arrays.</p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
- * <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
+ * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(byte, byte)}</li>
* </ol>
*
- * @param lhs array from <code>this</code> object
- * @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 @@
}
/**
- * <p>Deep comparison of a <code>double</code> array.</p>
+ * <p>Appends to the <code>builder</code> the deep comparison of
+ * two <code>double</code> arrays.</p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
- * <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
+ * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(double, double)}</li>
* </ol>
*
- * @param lhs array from <code>this</code> object
- * @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 @@
}
/**
- * <p>Deep comparison of a <code>float</code> array.</p>
+ * <p>Appends to the <code>builder</code> the deep comparison of
+ * two <code>float</code> arrays.</p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
- * <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
+ * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
- * <li>Check array contents element by element using {@link #append(float, float)}
+ * <li>Check array contents element by element using {@link #append(float, float)}</li>
* </ol>
*
- * @param lhs array from <code>this</code> 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 @@
}
/**
- * <p>Deep comparison of a <code>boolean/code> array.</p>
+ * <p>Appends to the <code>builder</code> the deep comparison of
+ * two <code>boolean</code> arrays.</p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
- * <li>Check if either is <code>null</code>, a null array is less than a non-null</li>
+ * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(boolean, boolean)}</li>
* </ol>
*
- * @param lhs array from <code>this</code> object
- * @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 @@
return this;
}
+ //-----------------------------------------------------------------------
/**
- * <p>Return a negative integer if this <code>Object</code> is less
- * than, a positive integer if this <code>Object</code> is greater than,
- * or <code>0</code> if this <code>Object</code> is equal to the specified
- * Object.</p>
+ * Returns a negative integer, a positive integer, or zero as
+ * the <code>builder</code> 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;