Apache
/
commons-lang
mirror of https://github.com/apache/commons-lang.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Checkstyle and trailing spaces. 

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/lang/trunk@1083217 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Oliver Heger 2011-03-19 16:41:05 +00:00
parent 33c75a4ac8
commit 57706fae97
1 changed files with 98 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
src/main/java/org/apache/commons/lang3/builder/HashCodeBuilder.java
View File

@ -5,9 +5,9 @@
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -30,20 +30,20 @@
* <p>
* Assists in implementing {@link Object#hashCode()} methods.
* </p>
*
*
* <p>
* This class enables a good <code>hashCode</code> method to be built for any class. It follows the rules laid out in
* the book <a href="http://java.sun.com/docs/books/effective/index.html">Effective Java</a> by Joshua Bloch. Writing a
* good <code>hashCode</code> method is actually quite difficult. This class aims to simplify the process.
* </p>
*
*
* <p>
* 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.
* 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.
* </p>
*
*
* <p>
* All relevant fields from the object should be included in the <code>hashCode</code> method. Derived fields may be
* excluded. In general, any field used in the <code>equals</code> method must be used in the <code>hashCode</code>
@ -53,7 +53,7 @@
* <p>
* To use this class write code as follows:
* </p>
*
*
* <pre>
* public class Person {
* String name;
@ -72,28 +72,28 @@
* }
* }
* </pre>
*
*
* <p>
* If required, the superclass <code>hashCode()</code> can be added using {@link #appendSuper}.
* </p>
*
*
* <p>
* Alternatively, there is a method that uses reflection to determine the fields to test. Because these fields are
* usually private, the method, <code>reflectionHashCode</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 up correctly. It is also slower than testing explicitly.
* </p>
*
*
* <p>
* A typical invocation for this method would look like:
* </p>
*
*
* <pre>
* public int hashCode() {
* return HashCodeBuilder.reflectionHashCode(this);
* }
* </pre>
*
*
* @author Apache Software Foundation
* @author Gary Gregory
* @author Pete Gieser
@ -105,7 +105,7 @@ public class HashCodeBuilder implements Builder<Integer> {
* <p>
* A registry of objects used by reflection methods to detect cyclical object references and avoid infinite loops.
* </p>
*
*
* @since 2.3
*/
private static final ThreadLocal<Set<IDKey>> REGISTRY = new ThreadLocal<Set<IDKey>>();
@ -113,25 +113,25 @@ public class HashCodeBuilder implements Builder<Integer> {
/*
* N.B. we cannot store the actual objects in a HashSet, as that would use the very hashCode()
* we are in the process of calculating.
*
*
* So we generate a one-to-one mapping from the original object to a new object.
*
*
* Now HashSet uses equals() to determine if two elements with the same hashcode really
* are equal, so we also need to ensure that the replacement objects are only equal
* if the original objects are identical.
*
*
* The original implementation (2.4 and before) used the System.indentityHashCode()
* method - however this is not guaranteed to generate unique ids (e.g. LANG-459)
*
*
* We now use the IDKey helper class (adapted from org.apache.axis.utils.IDKey)
* to disambiguate the duplicate ids.
*/
/**
* <p>
* Returns the registry of objects being traversed by the reflection methods in the current thread.
* </p>
*
*
* @return Set the registry of objects being traversed
* @since 2.3
*/
@ -144,7 +144,7 @@ static Set<IDKey> getRegistry() {
* Returns <code>true</code> if the registry contains the given object. Used by the reflection methods to avoid
* infinite loops.
* </p>
*
*
* @param value
* The object to lookup in the registry.
* @return boolean <code>true</code> if the registry contains the given object.
@ -159,7 +159,7 @@ static boolean isRegistered(Object value) {
* <p>
* Appends the fields and values defined by the given object of the given <code>Class</code>.
* </p>
*
*
* @param object
* the object to append details of
* @param clazz
@ -204,27 +204,27 @@ private static void reflectionAppend(Object object, Class<?> clazz, HashCodeBuil
* <p>
* This method uses reflection to build a valid hash code.
* </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 used, as they are likely derived fields, and not part of the value of the
* <code>Object</code>.
* </p>
*
*
* <p>
* Static fields will not be tested. Superclass fields will be included.
* </p>
*
*
* <p>
* 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.
* </p>
*
*
* @param initialNonZeroOddNumber
* a non-zero, odd number used as the initial value
* @param multiplierNonZeroOddNumber
@ -245,27 +245,27 @@ public static int reflectionHashCode(int initialNonZeroOddNumber, int multiplier
* <p>
* This method uses reflection to build a valid hash code.
* </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 TestTransients parameter 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 <code>Object</code>.
* </p>
*
*
* <p>
* Static fields will not be tested. Superclass fields will be included.
* </p>
*
*
* <p>
* 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.
* </p>
*
*
* @param initialNonZeroOddNumber
* a non-zero, odd number used as the initial value
* @param multiplierNonZeroOddNumber
@ -289,7 +289,9 @@ public static int reflectionHashCode(int initialNonZeroOddNumber, int multiplier
/**
* Calls {@link #reflectionHashCode(int, int, Object, boolean, Class, String[])} with excludeFields set to
* <code>null</code>.
*
*
* @param <T>
* the type of the object involved
* @param initialNonZeroOddNumber
* a non-zero, odd number used as the initial value
* @param multiplierNonZeroOddNumber
@ -312,28 +314,30 @@ public static <T> int reflectionHashCode(int initialNonZeroOddNumber, int multip
* <p>
* This method uses reflection to build a valid hash code.
* </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 TestTransients parameter 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 <code>Object</code>.
* </p>
*
*
* <p>
* 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.
* </p>
*
*
* <p>
* 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.
* </p>
*
*
* @param <T>
* the type of the object involved
* @param initialNonZeroOddNumber
* a non-zero, odd number used as the initial value
* @param multiplierNonZeroOddNumber
@ -373,26 +377,26 @@ public static <T> int reflectionHashCode(int initialNonZeroOddNumber, int multip
* <p>
* This method uses reflection to build a valid hash code.
* </p>
*
*
* <p>
* This constructor uses two hard coded choices for the constants needed to build a hash code.
* </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 used, as they are likely derived fields, and not part of the value of the
* <code>Object</code>.
* </p>
*
*
* <p>
* Static fields will not be tested. Superclass fields will be included.
* </p>
*
*
* @param object
* the Object to create a <code>hashCode</code> for
* @return int hash code
@ -407,26 +411,26 @@ public static int reflectionHashCode(Object object) {
* <p>
* This method uses reflection to build a valid hash code.
* </p>
*
*
* <p>
* This constructor uses two hard coded choices for the constants needed to build a hash code.
* </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 TestTransients parameter 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 <code>Object</code>.
* </p>
*
*
* <p>
* Static fields will not be tested. Superclass fields will be included.
* </p>
*
*
* @param object
* the Object to create a <code>hashCode</code> for
* @param testTransients
@ -443,26 +447,26 @@ public static int reflectionHashCode(Object object, boolean testTransients) {
* <p>
* This method uses reflection to build a valid hash code.
* </p>
*
*
* <p>
* This constructor uses two hard coded choices for the constants needed to build a hash code.
* </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 used, as they are likely derived fields, and not part of the value of the
* <code>Object</code>.
* </p>
*
*
* <p>
* Static fields will not be tested. Superclass fields will be included.
* </p>
*
*
* @param object
* the Object to create a <code>hashCode</code> for
* @param excludeFields
@ -481,26 +485,26 @@ public static int reflectionHashCode(Object object, Collection<String> excludeFi
* <p>
* This method uses reflection to build a valid hash code.
* </p>
*
*
* <p>
* This constructor uses two hard coded choices for the constants needed to build a hash code.
* </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 used, as they are likely derived fields, and not part of the value of the
* <code>Object</code>.
* </p>
*
*
* <p>
* Static fields will not be tested. Superclass fields will be included.
* </p>
*
*
* @param object
* the Object to create a <code>hashCode</code> for
* @param excludeFields
@ -517,7 +521,7 @@ public static int reflectionHashCode(Object object, String[] excludeFields) {
* <p>
* Registers the given object. Used by the reflection methods to avoid infinite loops.
* </p>
*
*
* @param value
* The object to register.
*/
@ -534,10 +538,10 @@ static void register(Object value) {
* <p>
* Unregisters the given object.
* </p>
*
*
* <p>
* Used by the reflection methods to avoid infinite loops.
*
*
* @param value
* The object to unregister.
* @since 2.3
@ -581,11 +585,11 @@ public HashCodeBuilder() {
* Two randomly chosen, non-zero, odd numbers must be passed in. Ideally these should be different for each class,
* however this is not vital.
* </p>
*
*
* <p>
* Prime numbers are preferred, especially for the multiplier.
* </p>
*
*
* @param initialNonZeroOddNumber
* a non-zero, odd number used as the initial value
* @param multiplierNonZeroOddNumber
@ -626,7 +630,7 @@ public HashCodeBuilder(int initialNonZeroOddNumber, int multiplierNonZeroOddNumb
* <p>
* This is in accordance with the <quote>Effective Java</quote> design.
* </p>
*
*
* @param value
* the boolean to add to the <code>hashCode</code>
* @return this
@ -640,7 +644,7 @@ public HashCodeBuilder append(boolean value) {
* <p>
* Append a <code>hashCode</code> for a <code>boolean</code> array.
* </p>
*
*
* @param array
* the array to add to the <code>hashCode</code>
* @return this
@ -662,7 +666,7 @@ public HashCodeBuilder append(boolean[] array) {
* <p>
* Append a <code>hashCode</code> for a <code>byte</code>.
* </p>
*
*
* @param value
* the byte to add to the <code>hashCode</code>
* @return this
@ -678,7 +682,7 @@ public HashCodeBuilder append(byte value) {
* <p>
* Append a <code>hashCode</code> for a <code>byte</code> array.
* </p>
*
*
* @param array
* the array to add to the <code>hashCode</code>
* @return this
@ -698,7 +702,7 @@ public HashCodeBuilder append(byte[] array) {
* <p>
* Append a <code>hashCode</code> for a <code>char</code>.
* </p>
*
*
* @param value
* the char to add to the <code>hashCode</code>
* @return this
@ -712,7 +716,7 @@ public HashCodeBuilder append(char value) {
* <p>
* Append a <code>hashCode</code> for a <code>char</code> array.
* </p>
*
*
* @param array
* the array to add to the <code>hashCode</code>
* @return this
@ -732,7 +736,7 @@ public HashCodeBuilder append(char[] array) {
* <p>
* Append a <code>hashCode</code> for a <code>double</code>.
* </p>
*
*
* @param value
* the double to add to the <code>hashCode</code>
* @return this
@ -745,7 +749,7 @@ public HashCodeBuilder append(double value) {
* <p>
* Append a <code>hashCode</code> for a <code>double</code> array.
* </p>
*
*
* @param array
* the array to add to the <code>hashCode</code>
* @return this
@ -765,7 +769,7 @@ public HashCodeBuilder append(double[] array) {
* <p>
* Append a <code>hashCode</code> for a <code>float</code>.
* </p>
*
*
* @param value
* the float to add to the <code>hashCode</code>
* @return this
@ -779,7 +783,7 @@ public HashCodeBuilder append(float value) {
* <p>
* Append a <code>hashCode</code> for a <code>float</code> array.
* </p>
*
*
* @param array
* the array to add to the <code>hashCode</code>
* @return this
@ -799,7 +803,7 @@ public HashCodeBuilder append(float[] array) {
* <p>
* Append a <code>hashCode</code> for an <code>int</code>.
* </p>
*
*
* @param value
* the int to add to the <code>hashCode</code>
* @return this
@ -813,7 +817,7 @@ public HashCodeBuilder append(int value) {
* <p>
* Append a <code>hashCode</code> for an <code>int</code> array.
* </p>
*
*
* @param array
* the array to add to the <code>hashCode</code>
* @return this
@ -833,14 +837,14 @@ public HashCodeBuilder append(int[] array) {
* <p>
* Append a <code>hashCode</code> for a <code>long</code>.
* </p>
*
*
* @param value
* the long to add to the <code>hashCode</code>
* @return this
*/
// NOTE: This method uses >> and not >>> as Effective Java and
// Long.hashCode do. Ideally we should switch to >>> at
// some stage. There are backwards compat issues, so
// NOTE: This method uses >> and not >>> as Effective Java and
// Long.hashCode do. Ideally we should switch to >>> at
// some stage. There are backwards compat issues, so
// that will have to wait for the time being. cf LANG-342.
public HashCodeBuilder append(long value) {
iTotal = iTotal * iConstant + ((int) (value ^ (value >> 32)));
@ -851,7 +855,7 @@ public HashCodeBuilder append(long value) {
* <p>
* Append a <code>hashCode</code> for a <code>long</code> array.
* </p>
*
*
* @param array
* the array to add to the <code>hashCode</code>
* @return this
@ -871,7 +875,7 @@ public HashCodeBuilder append(long[] array) {
* <p>
* Append a <code>hashCode</code> for an <code>Object</code>.
* </p>
*
*
* @param object
* the Object to add to the <code>hashCode</code>
* @return this
@ -915,7 +919,7 @@ public HashCodeBuilder append(Object object) {
* <p>
* Append a <code>hashCode</code> for an <code>Object</code> array.
* </p>
*
*
* @param array
* the array to add to the <code>hashCode</code>
* @return this
@ -935,7 +939,7 @@ public HashCodeBuilder append(Object[] array) {
* <p>
* Append a <code>hashCode</code> for a <code>short</code>.
* </p>
*
*
* @param value
* the short to add to the <code>hashCode</code>
* @return this
@ -949,7 +953,7 @@ public HashCodeBuilder append(short value) {
* <p>
* Append a <code>hashCode</code> for a <code>short</code> array.
* </p>
*
*
* @param array
* the array to add to the <code>hashCode</code>
* @return this
@ -969,7 +973,7 @@ public HashCodeBuilder append(short[] array) {
* <p>
* Adds the result of super.hashCode() to this builder.
* </p>
*
*
* @param superHashCode
* the result of calling <code>super.hashCode()</code>
* @return this HashCodeBuilder, used to chain calls.
@ -984,18 +988,18 @@ public HashCodeBuilder appendSuper(int superHashCode) {
* <p>
* Return the computed <code>hashCode</code>.
* </p>
*
*
* @return <code>hashCode</code> based on the fields appended
*/
public int toHashCode() {
return iTotal;
}
/**
* Returns the computed <code>hashCode</code>.
*
*
* @return <code>hashCode</code> based on the fields appended
*
*
* @since 3.0
*/
public Integer build() {
@ -1004,10 +1008,10 @@ public Integer build() {
/**
* <p>
* The computed <code>hashCode</code> from toHashCode() is returned due to the likelyhood
* of bugs in mis-calling toHashCode() and the unlikelyness of it mattering what the hashCode for
* The computed <code>hashCode</code> 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.
*
*
* @return <code>hashCode</code> based on the fields appended
* @since 2.5
*/