org.apache.commons.lang.builder
public class CompareToBuilder extends Object
equals(Object) and
hashcode() built with EqualsBuilder and
HashCodeBuilder.
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(Object) and
equals(Object).
To use this class write code as follows:
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 are reflectionCompare methods that use
reflection to determine the fields to append. Because fields can be private,
reflectionCompare uses java.lang.reflect.AccessibleObject#setAccessible(boolean) 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 implementation of compareTo(Object) using
reflectionCompare looks like:
public int compareTo(Object o) {
return CompareToBuilder.reflectionCompare(this, o);
}
Since: 1.0
Version: $Id: CompareToBuilder.java 583666 2007-10-11 01:38:13Z ggregory $
See Also: java.lang.Comparable java.lang.Object#equals(Object) java.lang.Object#hashCode() EqualsBuilder HashCodeBuilder
| Constructor Summary | |
|---|---|
| CompareToBuilder() Constructor for CompareToBuilder. Starts off assuming that the objects are equal. | |
| Method Summary | |
|---|---|
| CompareToBuilder | append(Object lhs, Object rhs) Appends to the
|
| CompareToBuilder | append(Object lhs, Object rhs, Comparator comparator) Appends to the
If |
| CompareToBuilder | append(long lhs, long rhs)
Appends to the builder the comparison of
two longs.
|
| CompareToBuilder | append(int lhs, int rhs)
Appends to the builder the comparison of
two ints.
|
| CompareToBuilder | append(short lhs, short rhs)
Appends to the builder the comparison of
two shorts.
|
| CompareToBuilder | append(char lhs, char rhs)
Appends to the builder the comparison of
two chars.
|
| CompareToBuilder | append(byte lhs, byte rhs)
Appends to the builder the comparison of
two bytes.
|
| CompareToBuilder | append(double lhs, double rhs) Appends to the This handles NaNs, Infinities, and It is compatible with the hash code generated by
|
| CompareToBuilder | append(float lhs, float rhs) Appends to the This handles NaNs, Infinities, and It is compatible with the hash code generated by
|
| CompareToBuilder | append(boolean lhs, boolean rhs)
Appends to the builder the comparison of
two booleanss.
|
| CompareToBuilder | append(Object[] lhs, Object[] rhs) Appends to the
This method will also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays. |
| CompareToBuilder | append(Object[] lhs, Object[] rhs, Comparator comparator) Appends to the
This method will also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays. |
| CompareToBuilder | append(long[] lhs, long[] rhs) Appends to the
|
| CompareToBuilder | append(int[] lhs, int[] rhs) Appends to the
|
| CompareToBuilder | append(short[] lhs, short[] rhs) Appends to the
|
| CompareToBuilder | append(char[] lhs, char[] rhs) Appends to the
|
| CompareToBuilder | append(byte[] lhs, byte[] rhs) Appends to the
|
| CompareToBuilder | append(double[] lhs, double[] rhs) Appends to the
|
| CompareToBuilder | append(float[] lhs, float[] rhs) Appends to the
|
| CompareToBuilder | append(boolean[] lhs, boolean[] rhs) Appends to the
|
| CompareToBuilder | appendSuper(int superCompareTo) Appends to the |
| static int | reflectionCompare(Object lhs, Object rhs) Compares two Fields can be private, thus |
| static int | reflectionCompare(Object lhs, Object rhs, boolean compareTransients) Compares two Fields can be private, thus |
| static int | reflectionCompare(Object lhs, Object rhs, Collection excludeFields) Compares two Fields can be private, thus |
| static int | reflectionCompare(Object lhs, Object rhs, String[] excludeFields) Compares two Fields can be private, thus |
| static int | reflectionCompare(Object lhs, Object rhs, boolean compareTransients, Class reflectUpToClass) Compares two Fields can be private, thus |
| static int | reflectionCompare(Object lhs, Object rhs, boolean compareTransients, Class reflectUpToClass, String[] excludeFields) Compares two Fields can be private, thus |
| int | toComparison()
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.
|
Constructor for CompareToBuilder.
Starts off assuming that the objects are equal. Multiple calls are then made to the various append methods, followed by a call to CompareToBuilder to get the result.
Appends to the builder the comparison of
two Objects.
lhs == rhslhs or rhs is null,
a null object is less than a non-null objectlhs must either be an array or implement Comparable.
Parameters: lhs left-hand object rhs right-hand object
Returns: this - used to chain append calls
Throws: ClassCastException if rhs is not assignment-compatible
with lhs
Appends to the builder the comparison of
two Objects.
lhs == rhslhs or rhs is null,
a null object is less than a non-null objectIf 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 Comparable instead.
Parameters: lhs left-hand object rhs right-hand object comparator Comparator used to compare the objects,
null means treat lhs as Comparable
Returns: this - used to chain append calls
Throws: ClassCastException if rhs is not assignment-compatible
with lhs
Since: 2.0
builder the comparison of
two longs.
Parameters: lhs left-hand value rhs right-hand value
Returns: this - used to chain append calls
builder the comparison of
two ints.
Parameters: lhs left-hand value rhs right-hand value
Returns: this - used to chain append calls
builder the comparison of
two shorts.
Parameters: lhs left-hand value rhs right-hand value
Returns: this - used to chain append calls
builder the comparison of
two chars.
Parameters: lhs left-hand value rhs right-hand value
Returns: this - used to chain append calls
builder the comparison of
two bytes.
Parameters: lhs left-hand value rhs right-hand value
Returns: this - used to chain append calls
Appends to the builder the comparison of
two doubles.
This handles NaNs, Infinities, and -0.0.
It is compatible with the hash code generated by
HashCodeBuilder.
Parameters: lhs left-hand value rhs right-hand value
Returns: this - used to chain append calls
Appends to the builder the comparison of
two floats.
This handles NaNs, Infinities, and -0.0.
It is compatible with the hash code generated by
HashCodeBuilder.
Parameters: lhs left-hand value rhs right-hand value
Returns: this - used to chain append calls
builder the comparison of
two booleanss.
Parameters: lhs left-hand value rhs right-hand value
Returns: this - used to chain append calls
Appends to the builder the deep comparison of
two Object arrays.
==null, null is less than non-nullThis method will also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays.
Parameters: lhs left-hand array rhs right-hand array
Returns: this - used to chain append calls
Throws: ClassCastException if rhs is not assignment-compatible
with lhs
Appends to the builder the deep comparison of
two Object arrays.
==null, null is less than non-nullThis method will also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays.
Parameters: lhs left-hand array rhs right-hand array comparator Comparator to use to compare the array elements,
null means to treat lhs elements as Comparable.
Returns: this - used to chain append calls
Throws: ClassCastException if rhs is not assignment-compatible
with lhs
Since: 2.0
Appends to the builder the deep comparison of
two long arrays.
==null, null is less than non-nullParameters: lhs left-hand array rhs right-hand array
Returns: this - used to chain append calls
Appends to the builder the deep comparison of
two int arrays.
==null, null is less than non-nullParameters: lhs left-hand array rhs right-hand array
Returns: this - used to chain append calls
Appends to the builder the deep comparison of
two short arrays.
==null, null is less than non-nullParameters: lhs left-hand array rhs right-hand array
Returns: this - used to chain append calls
Appends to the builder the deep comparison of
two char arrays.
==null, null is less than non-nullParameters: lhs left-hand array rhs right-hand array
Returns: this - used to chain append calls
Appends to the builder the deep comparison of
two byte arrays.
==null, null is less than non-nullParameters: lhs left-hand array rhs right-hand array
Returns: this - used to chain append calls
Appends to the builder the deep comparison of
two double arrays.
==null, null is less than non-nullParameters: lhs left-hand array rhs right-hand array
Returns: this - used to chain append calls
Appends to the builder the deep comparison of
two float arrays.
==null, null is less than non-nullParameters: lhs left-hand array rhs right-hand array
Returns: this - used to chain append calls
Appends to the builder the deep comparison of
two boolean arrays.
==null, null is less than non-nullParameters: lhs left-hand array rhs right-hand array
Returns: this - used to chain append calls
Appends to the builder the compareTo(Object)
result of the superclass.
Parameters: superCompareTo result of calling super.compareTo(Object)
Returns: this - used to chain append calls
Since: 2.0
Compares two Objects via reflection.
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 both lhs and rhs are null,
they are considered equal.
Parameters: lhs left-hand object rhs right-hand object
Returns: 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 ClassCastException if rhs is not assignment-compatible
with lhs
Compares two Objects via reflection.
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.
compareTransients is true,
compares transient members. Otherwise ignores them, as they
are likely derived fields.If both lhs and rhs are null,
they are considered equal.
Parameters: lhs left-hand object rhs right-hand object compareTransients whether to compare transient fields
Returns: 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 ClassCastException if rhs is not assignment-compatible
with lhs
Compares two Objects via reflection.
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.
compareTransients is true,
compares transient members. Otherwise ignores them, as they
are likely derived fields.If both lhs and rhs are null,
they are considered equal.
Parameters: lhs left-hand object rhs right-hand object excludeFields Collection of String fields to exclude
Returns: 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 ClassCastException if rhs is not assignment-compatible
with lhs
Since: 2.2
Compares two Objects via reflection.
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.
compareTransients is true,
compares transient members. Otherwise ignores them, as they
are likely derived fields.If both lhs and rhs are null,
they are considered equal.
Parameters: lhs left-hand object rhs right-hand object excludeFields array of fields to exclude
Returns: 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 ClassCastException if rhs is not assignment-compatible
with lhs
Since: 2.2
Compares two Objects via reflection.
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.
compareTransients is true,
compares transient members. Otherwise ignores them, as they
are likely derived fields.reflectUpToClass.
If reflectUpToClass is null, compares all superclass fields.If both lhs and rhs are null,
they are considered equal.
Parameters: lhs left-hand object rhs right-hand object compareTransients whether to compare transient fields reflectUpToClass last superclass for which fields are compared
Returns: 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 ClassCastException if rhs is not assignment-compatible
with lhs
Since: 2.0
Compares two Objects via reflection.
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.
compareTransients is true,
compares transient members. Otherwise ignores them, as they
are likely derived fields.reflectUpToClass.
If reflectUpToClass is null, compares all superclass fields.If both lhs and rhs are null,
they are considered equal.
Parameters: lhs left-hand object rhs right-hand object compareTransients whether to compare transient fields reflectUpToClass last superclass for which fields are compared excludeFields fields to exclude
Returns: 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 ClassCastException if rhs is not assignment-compatible
with lhs
Since: 2.2
builder has judged the "left-hand" side
as less than, greater than, or equal to the "right-hand"
side.
Returns: final comparison result