Return-Path: Delivered-To: apmail-commons-commits-archive@minotaur.apache.org Received: (qmail 24279 invoked from network); 19 Mar 2011 16:41:35 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 19 Mar 2011 16:41:35 -0000 Received: (qmail 59502 invoked by uid 500); 19 Mar 2011 16:41:35 -0000 Delivered-To: apmail-commons-commits-archive@commons.apache.org Received: (qmail 59452 invoked by uid 500); 19 Mar 2011 16:41:35 -0000 Mailing-List: contact commits-help@commons.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@commons.apache.org Delivered-To: mailing list commits@commons.apache.org Received: (qmail 59445 invoked by uid 99); 19 Mar 2011 16:41:35 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 19 Mar 2011 16:41:35 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 19 Mar 2011 16:41:30 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 06F60238897A; Sat, 19 Mar 2011 16:41:06 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1083217 - /commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/HashCodeBuilder.java Date: Sat, 19 Mar 2011 16:41:05 -0000 To: commits@commons.apache.org From: oheger@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20110319164106.06F60238897A@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: oheger Date: Sat Mar 19 16:41:05 2011 New Revision: 1083217 URL: http://svn.apache.org/viewvc?rev=1083217&view=rev Log: Checkstyle and trailing spaces. Modified: commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/HashCodeBuilder.java Modified: commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/HashCodeBuilder.java URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/HashCodeBuilder.java?rev=1083217&r1=1083216&r2=1083217&view=diff ============================================================================== --- commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/HashCodeBuilder.java (original) +++ commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/HashCodeBuilder.java Sat Mar 19 16:41:05 2011 @@ -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 @@ import org.apache.commons.lang3.ArrayUti *

* Assists in implementing {@link 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 * good hashCode 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. + * 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 the equals method must be used in the hashCode @@ -53,7 +53,7 @@ import org.apache.commons.lang3.ArrayUti *

* To use this class write code as follows: *

- * + * * 
  * public class Person {
  *   String name;
@@ -72,28 +72,28 @@ import org.apache.commons.lang3.ArrayUti
  *   }
  * }
  *
- * + * *

* If required, the superclass hashCode() can be added using {@link #appendSuper}. *

- * + * *

* Alternatively, there is a method that uses reflection to determine the fields to test. Because these fields are * usually private, the method, reflectionHashCode, uses AccessibleObject.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);
  * }
  *
- * + * * @author Apache Software Foundation * @author Gary Gregory * @author Pete Gieser @@ -105,7 +105,7 @@ public class HashCodeBuilder implements *

* A registry of objects used by reflection methods to detect cyclical object references and avoid infinite loops. *

- * + * * @since 2.3 */ private static final ThreadLocal> REGISTRY = new ThreadLocal>(); @@ -113,25 +113,25 @@ public class HashCodeBuilder implements /* * 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. */ - + /** *

* Returns the registry of objects being traversed by the reflection methods in the current thread. *

- * + * * @return Set the registry of objects being traversed * @since 2.3 */ @@ -144,7 +144,7 @@ public class HashCodeBuilder implements * Returns true if the registry contains the given object. Used by the reflection methods to avoid * infinite loops. *

- * + * * @param value * The object to lookup in the registry. * @return boolean true if the registry contains the given object. @@ -159,7 +159,7 @@ public class HashCodeBuilder implements *

* Appends the fields and values defined by the given object of the given Class. *

- * + * * @param object * the object to append details of * @param clazz @@ -204,27 +204,27 @@ public class HashCodeBuilder implements *

* 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. *

- * + * * @param initialNonZeroOddNumber * a non-zero, odd number used as the initial value * @param multiplierNonZeroOddNumber @@ -245,27 +245,27 @@ public class HashCodeBuilder implements *

* 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 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. *

- * + * * @param initialNonZeroOddNumber * a non-zero, odd number used as the initial value * @param multiplierNonZeroOddNumber @@ -289,7 +289,9 @@ public class HashCodeBuilder implements /** * Calls {@link #reflectionHashCode(int, int, Object, boolean, Class, String[])} with excludeFields set to * null. - * + * + * @param + * 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 class HashCodeBuilder implements *

* 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 the Object. *

- * + * *

* 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. *

- * + * + * @param + * 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 class HashCodeBuilder implements *

* 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. *

- * + * * @param object * the Object to create a hashCode for * @return int hash code @@ -407,26 +411,26 @@ public class HashCodeBuilder implements *

* 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 the Object. *

- * + * *

* Static fields will not be tested. Superclass fields will be included. *

- * + * * @param object * the Object to create a hashCode for * @param testTransients @@ -443,26 +447,26 @@ public class HashCodeBuilder implements *

* 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. *

- * + * * @param object * the Object to create a hashCode for * @param excludeFields @@ -481,26 +485,26 @@ public class HashCodeBuilder implements *

* 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. *

- * + * * @param object * the Object to create a hashCode for * @param excludeFields @@ -517,7 +521,7 @@ public class HashCodeBuilder implements *

* Registers the given object. Used by the reflection methods to avoid infinite loops. *

- * + * * @param value * The object to register. */ @@ -534,10 +538,10 @@ public class HashCodeBuilder implements *

* Unregisters the given object. *

- * + * *

* Used by the reflection methods to avoid infinite loops. - * + * * @param value * The object to unregister. * @since 2.3 @@ -581,11 +585,11 @@ public class HashCodeBuilder implements * 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. *

- * + * * @param initialNonZeroOddNumber * a non-zero, odd number used as the initial value * @param multiplierNonZeroOddNumber @@ -626,7 +630,7 @@ public class HashCodeBuilder implements *

* This is in accordance with the Effective Java design. *

- * + * * @param value * the boolean to add to the hashCode * @return this @@ -640,7 +644,7 @@ public class HashCodeBuilder implements *

* Append a hashCode for a boolean array. *

- * + * * @param array * the array to add to the hashCode * @return this @@ -662,7 +666,7 @@ public class HashCodeBuilder implements *

* Append a hashCode for a byte. *

- * + * * @param value * the byte to add to the hashCode * @return this @@ -678,7 +682,7 @@ public class HashCodeBuilder implements *

* Append a hashCode for a byte array. *

- * + * * @param array * the array to add to the hashCode * @return this @@ -698,7 +702,7 @@ public class HashCodeBuilder implements *

* Append a hashCode for a char. *

- * + * * @param value * the char to add to the hashCode * @return this @@ -712,7 +716,7 @@ public class HashCodeBuilder implements *

* Append a hashCode for a char array. *

- * + * * @param array * the array to add to the hashCode * @return this @@ -732,7 +736,7 @@ public class HashCodeBuilder implements *

* Append a hashCode for a double. *

- * + * * @param value * the double to add to the hashCode * @return this @@ -745,7 +749,7 @@ public class HashCodeBuilder implements *

* Append a hashCode for a double array. *

- * + * * @param array * the array to add to the hashCode * @return this @@ -765,7 +769,7 @@ public class HashCodeBuilder implements *

* Append a hashCode for a float. *

- * + * * @param value * the float to add to the hashCode * @return this @@ -779,7 +783,7 @@ public class HashCodeBuilder implements *

* Append a hashCode for a float array. *

- * + * * @param array * the array to add to the hashCode * @return this @@ -799,7 +803,7 @@ public class HashCodeBuilder implements *

* Append a hashCode for an int. *

- * + * * @param value * the int to add to the hashCode * @return this @@ -813,7 +817,7 @@ public class HashCodeBuilder implements *

* Append a hashCode for an int array. *

- * + * * @param array * the array to add to the hashCode * @return this @@ -833,14 +837,14 @@ public class HashCodeBuilder implements *

* Append a hashCode for a long. *

- * + * * @param value * the long to add to the hashCode * @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 class HashCodeBuilder implements *

* Append a hashCode for a long array. *

- * + * * @param array * the array to add to the hashCode * @return this @@ -871,7 +875,7 @@ public class HashCodeBuilder implements *

* Append a hashCode for an Object. *

- * + * * @param object * the Object to add to the hashCode * @return this @@ -915,7 +919,7 @@ public class HashCodeBuilder implements *

* Append a hashCode for an Object array. *

- * + * * @param array * the array to add to the hashCode * @return this @@ -935,7 +939,7 @@ public class HashCodeBuilder implements *

* Append a hashCode for a short. *

- * + * * @param value * the short to add to the hashCode * @return this @@ -949,7 +953,7 @@ public class HashCodeBuilder implements *

* Append a hashCode for a short array. *

- * + * * @param array * the array to add to the hashCode * @return this @@ -969,7 +973,7 @@ public class HashCodeBuilder implements *

* Adds the result of super.hashCode() to this builder. *

- * + * * @param superHashCode * the result of calling super.hashCode() * @return this HashCodeBuilder, used to chain calls. @@ -984,18 +988,18 @@ public class HashCodeBuilder implements *

* Return the computed hashCode. *

- * + * * @return hashCode based on the fields appended */ public int toHashCode() { return iTotal; } - + /** * Returns the computed hashCode. - * + * * @return hashCode based on the fields appended - * + * * @since 3.0 */ public Integer build() { @@ -1004,10 +1008,10 @@ public class HashCodeBuilder implements /** *

- * 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 + * 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. - * + * * @return hashCode based on the fields appended * @since 2.5 */