org.apache.commons.lang.builder.CompareToBuilder
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
public class CompareToBuilder
Assists in implementing Comparable.compareTo(Object) methods.
It is consistent with 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 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);
}
Comparable,
Object.equals(Object),
Object.hashCode(),
EqualsBuilder,
HashCodeBuilder| Constructor Summary | |
|---|---|
CompareToBuilder()
Constructor for CompareToBuilder. |
|
| Method Summary | |
|---|---|
CompareToBuilder |
append(boolean[] lhs,
boolean[] rhs)
Appends to the builder the deep comparison of
two boolean arrays. |
CompareToBuilder |
append(boolean lhs,
boolean rhs)
Appends to the builder the comparison of
two booleanss. |
CompareToBuilder |
append(byte[] lhs,
byte[] rhs)
Appends to the builder the deep comparison of
two byte arrays. |
CompareToBuilder |
append(byte lhs,
byte rhs)
Appends to the builder the comparison of
two bytes. |
CompareToBuilder |
append(char[] lhs,
char[] rhs)
Appends to the builder the deep comparison of
two char arrays. |
CompareToBuilder |
append(char lhs,
char rhs)
Appends to the builder the comparison of
two chars. |
CompareToBuilder |
append(double[] lhs,
double[] rhs)
Appends to the builder the deep comparison of
two double arrays. |
CompareToBuilder |
append(double lhs,
double rhs)
Appends to the builder the comparison of
two doubles. |
CompareToBuilder |
append(float[] lhs,
float[] rhs)
Appends to the builder the deep comparison of
two float arrays. |
CompareToBuilder |
append(float lhs,
float rhs)
Appends to the builder the comparison of
two floats. |
CompareToBuilder |
append(int[] lhs,
int[] rhs)
Appends to the builder the deep comparison of
two int arrays. |
CompareToBuilder |
append(int lhs,
int rhs)
Appends to the builder the comparison of
two ints. |
CompareToBuilder |
append(long[] lhs,
long[] rhs)
Appends to the builder the deep comparison of
two long arrays. |
CompareToBuilder |
append(long lhs,
long rhs)
Appends to the builder the comparison of
two longs. |
CompareToBuilder |
append(Object[] lhs,
Object[] rhs)
Appends to the builder the deep comparison of
two Object arrays. |
CompareToBuilder |
append(Object[] lhs,
Object[] rhs,
Comparator comparator)
Appends to the builder the deep comparison of
two Object arrays. |
CompareToBuilder |
append(Object lhs,
Object rhs)
Appends to the builder the comparison of
two Objects. |
CompareToBuilder |
append(Object lhs,
Object rhs,
Comparator comparator)
Appends to the builder the comparison of
two Objects. |
CompareToBuilder |
append(short[] lhs,
short[] rhs)
Appends to the builder the deep comparison of
two short arrays. |
CompareToBuilder |
append(short lhs,
short rhs)
Appends to the builder the comparison of
two shorts. |
CompareToBuilder |
appendSuper(int superCompareTo)
Appends to the builder the compareTo(Object)
result of the superclass. |
static int |
reflectionCompare(Object lhs,
Object rhs)
Compares two Objects via reflection. |
static int |
reflectionCompare(Object lhs,
Object rhs,
boolean compareTransients)
Compares two Objects via reflection. |
static int |
reflectionCompare(Object lhs,
Object rhs,
boolean compareTransients,
Class reflectUpToClass)
Compares two Objects via reflection. |
static int |
reflectionCompare(Object lhs,
Object rhs,
boolean compareTransients,
Class reflectUpToClass,
String[] excludeFields)
Compares two Objects via reflection. |
static int |
reflectionCompare(Object lhs,
Object rhs,
Collection excludeFields)
Compares two Objects via reflection. |
static int |
reflectionCompare(Object lhs,
Object rhs,
String[] excludeFields)
Compares two Objects via reflection. |
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. |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
|---|
public CompareToBuilder()
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
toComparison() to get the result.
| Method Detail |
|---|
public static int reflectionCompare(Object lhs,
Object rhs)
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.
lhs - left-hand objectrhs - right-hand object
lhs
is less than, equal to, or greater than rhs
NullPointerException - if either (but not both) parameters are
null
ClassCastException - if rhs is not assignment-compatible
with lhs
public static int reflectionCompare(Object lhs,
Object rhs,
boolean compareTransients)
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.
lhs - left-hand objectrhs - right-hand objectcompareTransients - whether to compare transient fields
lhs
is less than, equal to, or greater than rhs
NullPointerException - if either lhs or rhs
(but not both) is null
ClassCastException - if rhs is not assignment-compatible
with lhs
public static int reflectionCompare(Object lhs,
Object rhs,
Collection excludeFields)
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.
lhs - left-hand objectrhs - right-hand objectexcludeFields - Collection of String fields to exclude
lhs
is less than, equal to, or greater than rhs
NullPointerException - if either lhs or rhs
(but not both) is null
ClassCastException - if rhs is not assignment-compatible
with lhs
public static int reflectionCompare(Object lhs,
Object rhs,
String[] excludeFields)
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.
lhs - left-hand objectrhs - right-hand objectexcludeFields - array of fields to exclude
lhs
is less than, equal to, or greater than rhs
NullPointerException - if either lhs or rhs
(but not both) is null
ClassCastException - if rhs is not assignment-compatible
with lhs
public static int reflectionCompare(Object lhs,
Object rhs,
boolean compareTransients,
Class reflectUpToClass)
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.
lhs - left-hand objectrhs - right-hand objectcompareTransients - whether to compare transient fieldsreflectUpToClass - last superclass for which fields are compared
lhs
is less than, equal to, or greater than rhs
NullPointerException - if either lhs or rhs
(but not both) is null
ClassCastException - if rhs is not assignment-compatible
with lhs
public static int reflectionCompare(Object lhs,
Object rhs,
boolean compareTransients,
Class reflectUpToClass,
String[] excludeFields)
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.
lhs - left-hand objectrhs - right-hand objectcompareTransients - whether to compare transient fieldsreflectUpToClass - last superclass for which fields are comparedexcludeFields - fields to exclude
lhs
is less than, equal to, or greater than rhs
NullPointerException - if either lhs or rhs
(but not both) is null
ClassCastException - if rhs is not assignment-compatible
with lhspublic CompareToBuilder appendSuper(int superCompareTo)
Appends to the builder the compareTo(Object)
result of the superclass.
superCompareTo - result of calling super.compareTo(Object)
public CompareToBuilder append(Object lhs,
Object rhs)
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.
lhs - left-hand objectrhs - right-hand object
ClassCastException - if rhs is not assignment-compatible
with lhs
public CompareToBuilder append(Object lhs,
Object rhs,
Comparator comparator)
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.
lhs - left-hand objectrhs - right-hand objectcomparator - Comparator used to compare the objects,
null means treat lhs as Comparable
ClassCastException - if rhs is not assignment-compatible
with lhs
public CompareToBuilder append(long lhs,
long rhs)
builder the comparison of
two longs.
lhs - left-hand valuerhs - right-hand value
public CompareToBuilder append(int lhs,
int rhs)
builder the comparison of
two ints.
lhs - left-hand valuerhs - right-hand value
public CompareToBuilder append(short lhs,
short rhs)
builder the comparison of
two shorts.
lhs - left-hand valuerhs - right-hand value
public CompareToBuilder append(char lhs,
char rhs)
builder the comparison of
two chars.
lhs - left-hand valuerhs - right-hand value
public CompareToBuilder append(byte lhs,
byte rhs)
builder the comparison of
two bytes.
lhs - left-hand valuerhs - right-hand value
public CompareToBuilder append(double lhs,
double rhs)
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.
lhs - left-hand valuerhs - right-hand value
public CompareToBuilder append(float lhs,
float rhs)
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.
lhs - left-hand valuerhs - right-hand value
public CompareToBuilder append(boolean lhs,
boolean rhs)
builder the comparison of
two booleanss.
lhs - left-hand valuerhs - right-hand value
public CompareToBuilder append(Object[] lhs,
Object[] rhs)
Appends to the builder the deep comparison of
two Object arrays.
==null, null is less than non-nullappend(Object, Object, Comparator)This method will also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays.
lhs - left-hand arrayrhs - right-hand array
ClassCastException - if rhs is not assignment-compatible
with lhs
public CompareToBuilder append(Object[] lhs,
Object[] rhs,
Comparator comparator)
Appends to the builder the deep comparison of
two Object arrays.
==null, null is less than non-nullappend(Object, Object, Comparator)This method will also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays.
lhs - left-hand arrayrhs - right-hand arraycomparator - Comparator to use to compare the array elements,
null means to treat lhs elements as Comparable.
ClassCastException - if rhs is not assignment-compatible
with lhs
public CompareToBuilder append(long[] lhs,
long[] rhs)
Appends to the builder the deep comparison of
two long arrays.
==null, null is less than non-nullappend(long, long)
lhs - left-hand arrayrhs - right-hand array
public CompareToBuilder append(int[] lhs,
int[] rhs)
Appends to the builder the deep comparison of
two int arrays.
==null, null is less than non-nullappend(int, int)
lhs - left-hand arrayrhs - right-hand array
public CompareToBuilder append(short[] lhs,
short[] rhs)
Appends to the builder the deep comparison of
two short arrays.
==null, null is less than non-nullappend(short, short)
lhs - left-hand arrayrhs - right-hand array
public CompareToBuilder append(char[] lhs,
char[] rhs)
Appends to the builder the deep comparison of
two char arrays.
==null, null is less than non-nullappend(char, char)
lhs - left-hand arrayrhs - right-hand array
public CompareToBuilder append(byte[] lhs,
byte[] rhs)
Appends to the builder the deep comparison of
two byte arrays.
==null, null is less than non-nullappend(byte, byte)
lhs - left-hand arrayrhs - right-hand array
public CompareToBuilder append(double[] lhs,
double[] rhs)
Appends to the builder the deep comparison of
two double arrays.
==null, null is less than non-nullappend(double, double)
lhs - left-hand arrayrhs - right-hand array
public CompareToBuilder append(float[] lhs,
float[] rhs)
Appends to the builder the deep comparison of
two float arrays.
==null, null is less than non-nullappend(float, float)
lhs - left-hand arrayrhs - right-hand array
public CompareToBuilder append(boolean[] lhs,
boolean[] rhs)
Appends to the builder the deep comparison of
two boolean arrays.
==null, null is less than non-nullappend(boolean, boolean)
lhs - left-hand arrayrhs - right-hand array
public int toComparison()
builder has judged the "left-hand" side
as less than, greater than, or equal to the "right-hand"
side.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||