public class CompareToBuilder extends Object implements Builder<Integer>
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(); } }
Values are compared in the order they are appended to the builder. If any comparison returns
a non-zero result, then that value will be the result returned by toComparison()
and all
subsequent comparisons are skipped.
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); }
The reflective methods compare object fields in the order returned by
Class.getDeclaredFields()
. The fields of the class are compared first, followed by those
of its parent classes (in order from the bottom to the top of the class hierarchy).
Comparable
,
Object.equals(Object)
,
Object.hashCode()
,
EqualsBuilder
,
HashCodeBuilder
Constructor and Description |
---|
CompareToBuilder()
Constructor for CompareToBuilder.
|
Modifier and Type | Method and Description |
---|---|
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 booleans s. |
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 byte s. |
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 char s. |
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 double s. |
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 float s. |
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 int s. |
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 long s. |
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 Object s. |
CompareToBuilder |
append(Object lhs,
Object rhs,
Comparator<?> comparator)
Appends to the
builder the comparison of
two Object s. |
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 short s. |
CompareToBuilder |
appendSuper(int superCompareTo)
Appends to the
builder the compareTo(Object)
result of the superclass. |
Integer |
build()
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. |
static int |
reflectionCompare(Object lhs,
Object rhs)
Compares two
Object s via reflection. |
static int |
reflectionCompare(Object lhs,
Object rhs,
boolean compareTransients)
Compares two
Object s via reflection. |
static int |
reflectionCompare(Object lhs,
Object rhs,
boolean compareTransients,
Class<?> reflectUpToClass,
String... excludeFields)
Compares two
Object s via reflection. |
static int |
reflectionCompare(Object lhs,
Object rhs,
Collection<String> excludeFields)
Compares two
Object s via reflection. |
static int |
reflectionCompare(Object lhs,
Object rhs,
String... excludeFields)
Compares two
Object s 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. |
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.
public static int reflectionCompare(Object lhs, Object rhs)
Compares two Object
s 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 objectlhs
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 Object
s 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 fieldslhs
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<String> excludeFields)
Compares two Object
s 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 excludelhs
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 Object
s 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 excludelhs
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 Object
s 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 excludelhs
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
reflectionCompare(Object, Object, boolean, Class)
)public 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 Object
s.
lhs == rhs
lhs
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 objectClassCastException
- 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 Object
s.
lhs == rhs
lhs
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 long
s.lhs
- left-hand valuerhs
- right-hand valuepublic CompareToBuilder append(int lhs, int rhs)
builder
the comparison of
two int
s.lhs
- left-hand valuerhs
- right-hand valuepublic CompareToBuilder append(short lhs, short rhs)
builder
the comparison of
two short
s.lhs
- left-hand valuerhs
- right-hand valuepublic CompareToBuilder append(char lhs, char rhs)
builder
the comparison of
two char
s.lhs
- left-hand valuerhs
- right-hand valuepublic CompareToBuilder append(byte lhs, byte rhs)
builder
the comparison of
two byte
s.lhs
- left-hand valuerhs
- right-hand valuepublic CompareToBuilder append(double lhs, double rhs)
Appends to the builder
the comparison of
two double
s.
This handles NaNs, Infinities, and -0.0
.
It is compatible with the hash code generated by
HashCodeBuilder
.
lhs
- left-hand valuerhs
- right-hand valuepublic CompareToBuilder append(float lhs, float rhs)
Appends to the builder
the comparison of
two float
s.
This handles NaNs, Infinities, and -0.0
.
It is compatible with the hash code generated by
HashCodeBuilder
.
lhs
- left-hand valuerhs
- right-hand valuepublic CompareToBuilder append(boolean lhs, boolean rhs)
builder
the comparison of
two booleans
s.lhs
- left-hand valuerhs
- right-hand valuepublic CompareToBuilder append(Object[] lhs, Object[] rhs)
Appends to the builder
the deep comparison of
two Object
arrays.
==
null
, null
is less than non-null
append(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 arrayClassCastException
- 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-null
append(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-null
append(long, long)
lhs
- left-hand arrayrhs
- right-hand arraypublic CompareToBuilder append(int[] lhs, int[] rhs)
Appends to the builder
the deep comparison of
two int
arrays.
==
null
, null
is less than non-null
append(int, int)
lhs
- left-hand arrayrhs
- right-hand arraypublic CompareToBuilder append(short[] lhs, short[] rhs)
Appends to the builder
the deep comparison of
two short
arrays.
==
null
, null
is less than non-null
append(short, short)
lhs
- left-hand arrayrhs
- right-hand arraypublic CompareToBuilder append(char[] lhs, char[] rhs)
Appends to the builder
the deep comparison of
two char
arrays.
==
null
, null
is less than non-null
append(char, char)
lhs
- left-hand arrayrhs
- right-hand arraypublic CompareToBuilder append(byte[] lhs, byte[] rhs)
Appends to the builder
the deep comparison of
two byte
arrays.
==
null
, null
is less than non-null
append(byte, byte)
lhs
- left-hand arrayrhs
- right-hand arraypublic CompareToBuilder append(double[] lhs, double[] rhs)
Appends to the builder
the deep comparison of
two double
arrays.
==
null
, null
is less than non-null
append(double, double)
lhs
- left-hand arrayrhs
- right-hand arraypublic CompareToBuilder append(float[] lhs, float[] rhs)
Appends to the builder
the deep comparison of
two float
arrays.
==
null
, null
is less than non-null
append(float, float)
lhs
- left-hand arrayrhs
- right-hand arraypublic CompareToBuilder append(boolean[] lhs, boolean[] rhs)
Appends to the builder
the deep comparison of
two boolean
arrays.
==
null
, null
is less than non-null
append(boolean, boolean)
lhs
- left-hand arrayrhs
- right-hand arraypublic int toComparison()
builder
has judged the "left-hand" side
as less than, greater than, or equal to the "right-hand"
side.build()
public Integer build()
builder
has judged the "left-hand" side
as less than, greater than, or equal to the "right-hand"
side.build
in interface Builder<Integer>
toComparison()
Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.