Class HashCodeBuilder
- java.lang.Object
-
- org.apache.commons.lang.builder.HashCodeBuilder
-
public class HashCodeBuilder extends java.lang.Object
Assists in implementing
Object.hashCode()
methods.This class enables a good
hashCode
method to be built for any class. It follows the rules laid out in the book Effective Java by Joshua Bloch. Writing a goodhashCode
method is actually quite difficult. This class aims to simplify the process.The following is the approach taken. When appending a data field, the current total is multiplied by the multiplier then a relevant value for that data type is added. For example, if the current hashCode is 17, and the multiplier is 37, then appending the integer 45 will create a hashcode of 674, namely 17 * 37 + 45.
All relevant fields from the object should be included in the
hashCode
method. Derived fields may be excluded. In general, any field used in theequals
method must be used in thehashCode
method.To use this class write code as follows:
public class Person { String name; int age; boolean smoker; ... public int hashCode() { // you pick a hard-coded, randomly chosen, non-zero, odd number // ideally different for each class return new HashCodeBuilder(17, 37). append(name). append(age). append(smoker). toHashCode(); } }
If required, the superclass
hashCode()
can be added usingappendSuper(int)
.Alternatively, there is a method that uses reflection to determine the fields to test. Because these fields are usually private, the method,
reflectionHashCode
, usesAccessibleObject.setAccessible
to change the visibility of the fields. This will fail under a security manager, unless the appropriate permissions are set up correctly. It is also slower than testing explicitly.A typical invocation for this method would look like:
public int hashCode() { return HashCodeBuilder.reflectionHashCode(this); }
- Since:
- 1.0
- Version:
- $Id: HashCodeBuilder.java 1057009 2011-01-09 19:48:06Z niallp $
-
-
Field Summary
Fields Modifier and Type Field Description private int
iConstant
Constant to use in building the hashCode.private int
iTotal
Running total of the hashCode.private static java.lang.ThreadLocal
REGISTRY
A registry of objects used by reflection methods to detect cyclical object references and avoid infinite loops.
-
Constructor Summary
Constructors Constructor Description HashCodeBuilder()
Uses two hard coded choices for the constants needed to build ahashCode
.HashCodeBuilder(int initialNonZeroOddNumber, int multiplierNonZeroOddNumber)
Two randomly chosen, non-zero, odd numbers must be passed in.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description HashCodeBuilder
append(boolean value)
Append ahashCode
for aboolean
.HashCodeBuilder
append(boolean[] array)
Append ahashCode
for aboolean
array.HashCodeBuilder
append(byte value)
Append ahashCode
for abyte
.HashCodeBuilder
append(byte[] array)
Append ahashCode
for abyte
array.HashCodeBuilder
append(char value)
Append ahashCode
for achar
.HashCodeBuilder
append(char[] array)
Append ahashCode
for achar
array.HashCodeBuilder
append(double value)
Append ahashCode
for adouble
.HashCodeBuilder
append(double[] array)
Append ahashCode
for adouble
array.HashCodeBuilder
append(float value)
Append ahashCode
for afloat
.HashCodeBuilder
append(float[] array)
Append ahashCode
for afloat
array.HashCodeBuilder
append(int value)
Append ahashCode
for anint
.HashCodeBuilder
append(int[] array)
Append ahashCode
for anint
array.HashCodeBuilder
append(long value)
Append ahashCode
for along
.HashCodeBuilder
append(long[] array)
Append ahashCode
for along
array.HashCodeBuilder
append(short value)
Append ahashCode
for ashort
.HashCodeBuilder
append(short[] array)
Append ahashCode
for ashort
array.HashCodeBuilder
append(java.lang.Object object)
Append ahashCode
for anObject
.HashCodeBuilder
append(java.lang.Object[] array)
Append ahashCode
for anObject
array.HashCodeBuilder
appendSuper(int superHashCode)
Adds the result of super.hashCode() to this builder.(package private) static java.util.Set
getRegistry()
Returns the registry of objects being traversed by the reflection methods in the current thread.int
hashCode()
The computedhashCode
from toHashCode() is returned due to the likelyhood of bugs in mis-calling toHashCode() and the unlikelyness of it mattering what the hashCode for HashCodeBuilder itself is.(package private) static boolean
isRegistered(java.lang.Object value)
Returnstrue
if the registry contains the given object.private static void
reflectionAppend(java.lang.Object object, java.lang.Class clazz, HashCodeBuilder builder, boolean useTransients, java.lang.String[] excludeFields)
Appends the fields and values defined by the given object of the givenClass
.static int
reflectionHashCode(int initialNonZeroOddNumber, int multiplierNonZeroOddNumber, java.lang.Object object)
This method uses reflection to build a valid hash code.static int
reflectionHashCode(int initialNonZeroOddNumber, int multiplierNonZeroOddNumber, java.lang.Object object, boolean testTransients)
This method uses reflection to build a valid hash code.static int
reflectionHashCode(int initialNonZeroOddNumber, int multiplierNonZeroOddNumber, java.lang.Object object, boolean testTransients, java.lang.Class reflectUpToClass)
CallsreflectionHashCode(int, int, Object, boolean, Class, String[])
with excludeFields set tonull
.static int
reflectionHashCode(int initialNonZeroOddNumber, int multiplierNonZeroOddNumber, java.lang.Object object, boolean testTransients, java.lang.Class reflectUpToClass, java.lang.String[] excludeFields)
This method uses reflection to build a valid hash code.static int
reflectionHashCode(java.lang.Object object)
This method uses reflection to build a valid hash code.static int
reflectionHashCode(java.lang.Object object, boolean testTransients)
This method uses reflection to build a valid hash code.static int
reflectionHashCode(java.lang.Object object, java.lang.String[] excludeFields)
This method uses reflection to build a valid hash code.static int
reflectionHashCode(java.lang.Object object, java.util.Collection excludeFields)
This method uses reflection to build a valid hash code.(package private) static void
register(java.lang.Object value)
Registers the given object.int
toHashCode()
Return the computedhashCode
.(package private) static void
unregister(java.lang.Object value)
Unregisters the given object.
-
-
-
Field Detail
-
REGISTRY
private static final java.lang.ThreadLocal REGISTRY
A registry of objects used by reflection methods to detect cyclical object references and avoid infinite loops.
- Since:
- 2.3
-
iConstant
private final int iConstant
Constant to use in building the hashCode.
-
iTotal
private int iTotal
Running total of the hashCode.
-
-
Constructor Detail
-
HashCodeBuilder
public HashCodeBuilder()
Uses two hard coded choices for the constants needed to build a
hashCode
.
-
HashCodeBuilder
public HashCodeBuilder(int initialNonZeroOddNumber, int multiplierNonZeroOddNumber)
Two randomly chosen, non-zero, odd numbers must be passed in. Ideally these should be different for each class, however this is not vital.
Prime numbers are preferred, especially for the multiplier.
- Parameters:
initialNonZeroOddNumber
- a non-zero, odd number used as the initial valuemultiplierNonZeroOddNumber
- a non-zero, odd number used as the multiplier- Throws:
java.lang.IllegalArgumentException
- if the number is zero or even
-
-
Method Detail
-
getRegistry
static java.util.Set getRegistry()
Returns the registry of objects being traversed by the reflection methods in the current thread.
- Returns:
- Set the registry of objects being traversed
- Since:
- 2.3
-
isRegistered
static boolean isRegistered(java.lang.Object value)
Returns
true
if the registry contains the given object. Used by the reflection methods to avoid infinite loops.- Parameters:
value
- The object to lookup in the registry.- Returns:
- boolean
true
if the registry contains the given object. - Since:
- 2.3
-
reflectionAppend
private static void reflectionAppend(java.lang.Object object, java.lang.Class clazz, HashCodeBuilder builder, boolean useTransients, java.lang.String[] excludeFields)
Appends the fields and values defined by the given object of the given
Class
.- Parameters:
object
- the object to append details ofclazz
- the class to append details ofbuilder
- the builder to append touseTransients
- whether to use transient fieldsexcludeFields
- Collection of String field names to exclude from use in calculation of hash code
-
reflectionHashCode
public static int reflectionHashCode(int initialNonZeroOddNumber, int multiplierNonZeroOddNumber, java.lang.Object object)
This method uses reflection to build a valid hash code.
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.Transient members will be not be used, 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.
Two randomly chosen, non-zero, odd numbers must be passed in. Ideally these should be different for each class, however this is not vital. Prime numbers are preferred, especially for the multiplier.
- Parameters:
initialNonZeroOddNumber
- a non-zero, odd number used as the initial valuemultiplierNonZeroOddNumber
- a non-zero, odd number used as the multiplierobject
- the Object to create ahashCode
for- Returns:
- int hash code
- Throws:
java.lang.IllegalArgumentException
- if the Object isnull
java.lang.IllegalArgumentException
- if the number is zero or even
-
reflectionHashCode
public static int reflectionHashCode(int initialNonZeroOddNumber, int multiplierNonZeroOddNumber, java.lang.Object object, boolean testTransients)
This method uses reflection to build a valid hash code.
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.If the TestTransients parameter 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 theObject
.Static fields will not be tested. Superclass fields will be included.
Two randomly chosen, non-zero, odd numbers must be passed in. Ideally these should be different for each class, however this is not vital. Prime numbers are preferred, especially for the multiplier.
- Parameters:
initialNonZeroOddNumber
- a non-zero, odd number used as the initial valuemultiplierNonZeroOddNumber
- a non-zero, odd number used as the multiplierobject
- the Object to create ahashCode
fortestTransients
- whether to include transient fields- Returns:
- int hash code
- Throws:
java.lang.IllegalArgumentException
- if the Object isnull
java.lang.IllegalArgumentException
- if the number is zero or even
-
reflectionHashCode
public static int reflectionHashCode(int initialNonZeroOddNumber, int multiplierNonZeroOddNumber, java.lang.Object object, boolean testTransients, java.lang.Class reflectUpToClass)
CallsreflectionHashCode(int, int, Object, boolean, Class, String[])
with excludeFields set tonull
.- Parameters:
initialNonZeroOddNumber
- a non-zero, odd number used as the initial valuemultiplierNonZeroOddNumber
- a non-zero, odd number used as the multiplierobject
- the Object to create ahashCode
fortestTransients
- whether to include transient fieldsreflectUpToClass
- the superclass to reflect up to (inclusive), may benull
- Returns:
- int hash code
-
reflectionHashCode
public static int reflectionHashCode(int initialNonZeroOddNumber, int multiplierNonZeroOddNumber, java.lang.Object object, boolean testTransients, java.lang.Class reflectUpToClass, java.lang.String[] excludeFields)
This method uses reflection to build a valid hash code.
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.If the TestTransients parameter 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 theObject
.Static fields will not be included. Superclass fields will be included up to and including the specified superclass. A null superclass is treated as java.lang.Object.
Two randomly chosen, non-zero, odd numbers must be passed in. Ideally these should be different for each class, however this is not vital. Prime numbers are preferred, especially for the multiplier.
- Parameters:
initialNonZeroOddNumber
- a non-zero, odd number used as the initial valuemultiplierNonZeroOddNumber
- a non-zero, odd number used as the multiplierobject
- the Object to create ahashCode
fortestTransients
- whether to include transient fieldsreflectUpToClass
- the superclass to reflect up to (inclusive), may benull
excludeFields
- array of field names to exclude from use in calculation of hash code- Returns:
- int hash code
- Throws:
java.lang.IllegalArgumentException
- if the Object isnull
java.lang.IllegalArgumentException
- if the number is zero or even- Since:
- 2.0
-
reflectionHashCode
public static int reflectionHashCode(java.lang.Object object)
This method uses reflection to build a valid hash code.
This constructor uses two hard coded choices for the constants needed to build a hash code.
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.Transient members will be not be used, 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.
- Parameters:
object
- the Object to create ahashCode
for- Returns:
- int hash code
- Throws:
java.lang.IllegalArgumentException
- if the object isnull
-
reflectionHashCode
public static int reflectionHashCode(java.lang.Object object, boolean testTransients)
This method uses reflection to build a valid hash code.
This constructor uses two hard coded choices for the constants needed to build a hash code.
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.If the TestTransients parameter 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 theObject
.Static fields will not be tested. Superclass fields will be included.
- Parameters:
object
- the Object to create ahashCode
fortestTransients
- whether to include transient fields- Returns:
- int hash code
- Throws:
java.lang.IllegalArgumentException
- if the object isnull
-
reflectionHashCode
public static int reflectionHashCode(java.lang.Object object, java.util.Collection excludeFields)
This method uses reflection to build a valid hash code.
This constructor uses two hard coded choices for the constants needed to build a hash code.
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.Transient members will be not be used, 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.
- Parameters:
object
- the Object to create ahashCode
forexcludeFields
- Collection of String field names to exclude from use in calculation of hash code- Returns:
- int hash code
- Throws:
java.lang.IllegalArgumentException
- if the object isnull
-
reflectionHashCode
public static int reflectionHashCode(java.lang.Object object, java.lang.String[] excludeFields)
This method uses reflection to build a valid hash code.
This constructor uses two hard coded choices for the constants needed to build a hash code.
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.Transient members will be not be used, 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.
- Parameters:
object
- the Object to create ahashCode
forexcludeFields
- array of field names to exclude from use in calculation of hash code- Returns:
- int hash code
- Throws:
java.lang.IllegalArgumentException
- if the object isnull
-
register
static void register(java.lang.Object value)
Registers the given object. Used by the reflection methods to avoid infinite loops.
- Parameters:
value
- The object to register.
-
unregister
static void unregister(java.lang.Object value)
Unregisters the given object.
Used by the reflection methods to avoid infinite loops.
- Parameters:
value
- The object to unregister.- Since:
- 2.3
-
append
public HashCodeBuilder append(boolean value)
Append a
hashCode
for aboolean
.This adds
1
when true, and0
when false to thehashCode
.This is in contrast to the standard
java.lang.Boolean.hashCode
handling, which computes ahashCode
value of1231
forjava.lang.Boolean
instances that representtrue
or1237
forjava.lang.Boolean
instances that representfalse
.This is in accordance with the
Effective Java
design.- Parameters:
value
- the boolean to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(boolean[] array)
Append a
hashCode
for aboolean
array.- Parameters:
array
- the array to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(byte value)
Append a
hashCode
for abyte
.- Parameters:
value
- the byte to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(byte[] array)
Append a
hashCode
for abyte
array.- Parameters:
array
- the array to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(char value)
Append a
hashCode
for achar
.- Parameters:
value
- the char to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(char[] array)
Append a
hashCode
for achar
array.- Parameters:
array
- the array to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(double value)
Append a
hashCode
for adouble
.- Parameters:
value
- the double to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(double[] array)
Append a
hashCode
for adouble
array.- Parameters:
array
- the array to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(float value)
Append a
hashCode
for afloat
.- Parameters:
value
- the float to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(float[] array)
Append a
hashCode
for afloat
array.- Parameters:
array
- the array to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(int value)
Append a
hashCode
for anint
.- Parameters:
value
- the int to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(int[] array)
Append a
hashCode
for anint
array.- Parameters:
array
- the array to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(long value)
Append a
hashCode
for along
.- Parameters:
value
- the long to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(long[] array)
Append a
hashCode
for along
array.- Parameters:
array
- the array to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(java.lang.Object object)
Append a
hashCode
for anObject
.- Parameters:
object
- the Object to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(java.lang.Object[] array)
Append a
hashCode
for anObject
array.- Parameters:
array
- the array to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(short value)
Append a
hashCode
for ashort
.- Parameters:
value
- the short to add to thehashCode
- Returns:
- this
-
append
public HashCodeBuilder append(short[] array)
Append a
hashCode
for ashort
array.- Parameters:
array
- the array to add to thehashCode
- Returns:
- this
-
appendSuper
public HashCodeBuilder appendSuper(int superHashCode)
Adds the result of super.hashCode() to this builder.
- Parameters:
superHashCode
- the result of callingsuper.hashCode()
- Returns:
- this HashCodeBuilder, used to chain calls.
- Since:
- 2.0
-
toHashCode
public int toHashCode()
Return the computed
hashCode
.- Returns:
hashCode
based on the fields appended
-
hashCode
public int hashCode()
The computed
hashCode
from toHashCode() is returned due to the likelyhood of bugs in mis-calling toHashCode() and the unlikelyness of it mattering what the hashCode for HashCodeBuilder itself is.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
hashCode
based on the fields appended- Since:
- 2.5
-
-