View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      https://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.lang3.builder;
19  
20  import java.lang.reflect.Field;
21  import java.lang.reflect.Modifier;
22  import java.util.Collection;
23  import java.util.Comparator;
24  import java.util.HashSet;
25  import java.util.Objects;
26  import java.util.Set;
27  
28  import org.apache.commons.lang3.ArraySorter;
29  import org.apache.commons.lang3.ArrayUtils;
30  import org.apache.commons.lang3.ObjectUtils;
31  import org.apache.commons.lang3.Validate;
32  
33  /**
34   * Assists in implementing {@link Object#hashCode()} methods.
35   *
36   * <p>
37   * This class enables a good {@code hashCode} method to be built for any class. It follows the rules laid out in
38   * the book <a href="https://www.oracle.com/technetwork/java/effectivejava-136174.html">Effective Java</a> by Joshua Bloch. Writing a
39   * good {@code hashCode} method is actually quite difficult. This class aims to simplify the process.
40   * </p>
41   *
42   * <p>
43   * The following is the approach taken. When appending a data field, the current total is multiplied by the
44   * multiplier then a relevant value
45   * for that data type is added. For example, if the current hashCode is 17, and the multiplier is 37, then
46   * appending the integer 45 will create a hash code of 674, namely 17 * 37 + 45.
47   * </p>
48   *
49   * <p>
50   * All relevant fields from the object should be included in the {@code hashCode} method. Derived fields may be
51   * excluded. In general, any field used in the {@code equals} method must be used in the {@code hashCode}
52   * method.
53   * </p>
54   *
55   * <p>
56   * To use this class write code as follows:
57   * </p>
58   *
59   * <pre>
60   * public class Person {
61   *   String name;
62   *   int age;
63   *   boolean smoker;
64   *   ...
65   *
66   *   public int hashCode() {
67   *     // you pick a hard-coded, randomly chosen, non-zero, odd number
68   *     // ideally different for each class
69   *     return new HashCodeBuilder(17, 37).
70   *       append(name).
71   *       append(age).
72   *       append(smoker).
73   *       toHashCode();
74   *   }
75   * }
76   * </pre>
77   *
78   * <p>
79   * If required, the superclass {@code hashCode()} can be added using {@link #appendSuper}.
80   * </p>
81   *
82   * <p>
83   * Alternatively, there is a method that uses reflection to determine the fields to test. Because these fields are
84   * usually private, the method, {@code reflectionHashCode}, uses {@code AccessibleObject.setAccessible}
85   * to change the visibility of the fields. This will fail under a security manager, unless the appropriate permissions
86   * are set up correctly. It is also slower than testing explicitly.
87   * </p>
88   * <p>
89   * See also {@link AbstractBuilder#setForceAccessible(boolean)}
90   * </p>
91   *
92   * <p>
93   * A typical invocation for this method would look like:
94   * </p>
95   *
96   * <pre>
97   * public int hashCode() {
98   *   return HashCodeBuilder.reflectionHashCode(this);
99   * }
100  * </pre>
101  *
102  * <p>
103  * The {@link HashCodeExclude} annotation can be used to exclude fields from being
104  * used by the {@code reflectionHashCode} methods.
105  * </p>
106  *
107  * @see AbstractBuilder#setForceAccessible(boolean)
108  * @since 1.0
109  */
110 public class HashCodeBuilder extends AbstractReflection implements Builder<Integer> {
111 
112     /**
113      * Builds instances of CompareToBuilder.
114      */
115     public static class Builder extends AbstractBuilder<Builder> {
116 
117         private int initialOddNumber;
118 
119         private int multiplierOddNumber;
120 
121         /**
122          * Constructs a new Builder instance.
123          */
124         private Builder() {
125             // empty
126         }
127 
128         @Override
129         public HashCodeBuilder get() {
130             return new HashCodeBuilder(this);
131         }
132 
133 
134         /**
135          * Sets an odd number used as the initial value.
136          *
137          * @param initialOddNumber An odd number used as the initial value.
138          * @return {@code this} instance.
139          */
140         public Builder setInitialOddNumber(final int initialOddNumber) {
141             this.initialOddNumber = initialOddNumber;
142             return asThis();
143         }
144 
145         /**
146          * Sets an odd number used as the multiplier.
147          *
148          * @param multiplierOddNumber An odd number used as the multiplier.
149          * @return {@code this} instance.
150          */
151         public Builder setMultiplierOddNumber(final int multiplierOddNumber) {
152             this.multiplierOddNumber = multiplierOddNumber;
153             return asThis();
154         }
155 
156     }
157 
158     /**
159      * The default initial value to use in reflection hash code building.
160      */
161     private static final int DEFAULT_INITIAL_VALUE = 17;
162 
163     /**
164      * The default multiplier value to use in reflection hash code building.
165      */
166     private static final int DEFAULT_MULTIPLIER_VALUE = 37;
167 
168     /**
169      * A registry of objects to detect cyclical object references, avoid infinite loops, and stack overflows.
170      */
171     private static final ThreadLocal<Set<IDKey>> REGISTRY = ThreadLocal.withInitial(HashSet::new);
172 
173     /**
174      * A registry of objects being appended by {@link #append(Object)}, kept separate from {@link #REGISTRY} so that
175      * guarding {@code append} against its own re-entrant cycles does not trip the reflection cycle guard checked by
176      * {@link #reflectionAppend(Object, Class, HashCodeBuilder, boolean, String[], boolean)}.
177      */
178     private static final ThreadLocal<Set<IDKey>> APPEND_REGISTRY = ThreadLocal.withInitial(HashSet::new);
179 
180     /**
181      * Registers the given object in the append registry.
182      *
183      * @param value The object to register.
184      */
185     private static void appendRegister(final Object value) {
186         APPEND_REGISTRY.get().add(new IDKey(value));
187     }
188 
189     /*
190      * NOTE: we cannot store the actual objects in a HashSet, as that would use the very hashCode()
191      * we are in the process of calculating.
192      *
193      * So we generate a one-to-one mapping from the original object to a new object.
194      *
195      * Now HashSet uses equals() to determine if two elements with the same hash code really
196      * are equal, so we also need to ensure that the replacement objects are only equal
197      * if the original objects are identical.
198      *
199      * The original implementation (2.4 and before) used the System.identityHashCode()
200      * method - however this is not guaranteed to generate unique ids (e.g. LANG-459)
201      *
202      * We now use the IDKey helper class (adapted from org.apache.axis.utils.IDKey)
203      * to disambiguate the duplicate ids.
204      */
205 
206     /**
207      * Unregisters the given object from the append registry.
208      *
209      * @param value The object to unregister.
210      */
211     private static void appendUnregister(final Object value) {
212         final Set<IDKey> registry = APPEND_REGISTRY.get();
213         registry.remove(new IDKey(value));
214         if (registry.isEmpty()) {
215             APPEND_REGISTRY.remove();
216         }
217     }
218 
219     /**
220      * Constructs a new Builder.
221      *
222      * @return A new Builder.
223      */
224     public static Builder builder() {
225         return new Builder();
226     }
227 
228     /**
229      * Gets the registry of objects being traversed by the reflection methods in the current thread.
230      *
231      * @return Set the registry of objects being traversed
232      */
233     static Set<IDKey> getRegistry() {
234         return REGISTRY.get();
235     }
236 
237     /**
238      * Tests whether the append registry contains the given object. Used by {@link #append(Object)} to break its own re-entrant cycles.
239      *
240      * @param value The object to look up in the append registry.
241      * @return {@code true} if the append registry contains the given object.
242      */
243     private static boolean isAppendRegistered(final Object value) {
244         return APPEND_REGISTRY.get().contains(new IDKey(value));
245     }
246 
247     /**
248      * Tests whether the registry contains the given object. Used by the reflection methods to avoid
249      * infinite loops.
250      *
251      * @param value
252      *            The object to lookup in the registry.
253      * @return boolean {@code true} if the registry contains the given object.
254      */
255     static boolean isRegistered(final Object value) {
256         final Set<IDKey> registry = getRegistry();
257         return registry != null && registry.contains(new IDKey(value));
258     }
259 
260     /**
261      * Appends the fields and values defined by the given object of the given {@link Class}.
262      *
263      * @param object
264      *            the object to append details of
265      * @param clazz
266      *            the class to append details of
267      * @param builder
268      *            the builder to append to
269      * @param useTransients
270      *            whether to use transient fields
271      * @param excludeFields
272      *            Collection of String field names to exclude from use in calculation of hash code
273      * @param forceAccessible Whether to set fields' accessible flags
274      */
275     private static void reflectionAppend(final Object object, final Class<?> clazz, final HashCodeBuilder builder, final boolean useTransients,
276             final String[] excludeFields, final boolean forceAccessible) {
277         if (isRegistered(object)) {
278             return;
279         }
280         try {
281             register(object);
282             // The elements in the returned array are not sorted and are not in any particular order.
283             final Field[] fields = ArraySorter.sort(clazz.getDeclaredFields(), Comparator.comparing(Field::getName));
284             for (final Field field : fields) {
285                 if (!ArrayUtils.contains(excludeFields, field.getName())
286                     && !field.getName().contains("$")
287                     && (useTransients || !Modifier.isTransient(field.getModifiers()))
288                     && !Modifier.isStatic(field.getModifiers())
289                     && !field.isAnnotationPresent(HashCodeExclude.class)) {
290                     if (setAccessible(forceAccessible, field)) {
291                         builder.append(Reflection.getUnchecked(field, object));
292                     }
293                 }
294             }
295         } finally {
296             unregister(object);
297         }
298     }
299 
300     /**
301      * Uses reflection to build a valid hash code from the fields of {@code object}.
302      *
303      * <p>
304      * It uses {@code AccessibleObject.setAccessible} to gain access to private fields. This means that it will
305      * throw a security exception if run under a security manager, if the permissions are not set up correctly. It is
306      * also not as efficient as testing explicitly.
307      * </p>
308      *
309      * <p>
310      * Transient members will be not be used, as they are likely derived fields, and not part of the value of the
311      * {@link Object}.
312      * </p>
313      *
314      * <p>
315      * Static fields will not be tested. Superclass fields will be included.
316      * </p>
317      *
318      * <p>
319      * Two randomly chosen, non-zero, odd numbers must be passed in. Ideally these should be different for each class,
320      * however this is not vital. Prime numbers are preferred, especially for the multiplier.
321      * </p>
322      *
323      * @param initialNonZeroOddNumber
324      *            a non-zero, odd number used as the initial value. This will be the returned
325      *            value if no fields are found to include in the hash code
326      * @param multiplierNonZeroOddNumber
327      *            a non-zero, odd number used as the multiplier
328      * @param object
329      *            the Object to create a {@code hashCode} for
330      * @return int hash code
331      * @throws NullPointerException Thrown if the Object is {@code null}.
332      * @throws IllegalArgumentException Thrown if the number is zero or even.
333      * @see HashCodeExclude
334      */
335     public static int reflectionHashCode(final int initialNonZeroOddNumber, final int multiplierNonZeroOddNumber, final Object object) {
336         return reflectionHashCode(initialNonZeroOddNumber, multiplierNonZeroOddNumber, object, false, null);
337     }
338 
339     /**
340      * Uses reflection to build a valid hash code from the fields of {@code object}.
341      *
342      * <p>
343      * It uses {@code AccessibleObject.setAccessible} to gain access to private fields. This means that it will
344      * throw a security exception if run under a security manager, if the permissions are not set up correctly. It is
345      * also not as efficient as testing explicitly.
346      * </p>
347      *
348      * <p>
349      * If the TestTransients parameter is set to {@code true}, transient members will be tested, otherwise they
350      * are ignored, as they are likely derived fields, and not part of the value of the {@link Object}.
351      * </p>
352      *
353      * <p>
354      * Static fields will not be tested. Superclass fields will be included.
355      * </p>
356      *
357      * <p>
358      * Two randomly chosen, non-zero, odd numbers must be passed in. Ideally these should be different for each class,
359      * however this is not vital. Prime numbers are preferred, especially for the multiplier.
360      * </p>
361      *
362      * @param initialNonZeroOddNumber
363      *            a non-zero, odd number used as the initial value. This will be the returned
364      *            value if no fields are found to include in the hash code
365      * @param multiplierNonZeroOddNumber
366      *            a non-zero, odd number used as the multiplier
367      * @param object
368      *            the Object to create a {@code hashCode} for
369      * @param testTransients
370      *            whether to include transient fields
371      * @return int hash code
372      * @throws NullPointerException Thrown if the Object is {@code null}.
373      * @throws IllegalArgumentException Thrown if the number is zero or even.
374      * @see HashCodeExclude
375      */
376     public static int reflectionHashCode(final int initialNonZeroOddNumber, final int multiplierNonZeroOddNumber, final Object object,
377             final boolean testTransients) {
378         return reflectionHashCode(initialNonZeroOddNumber, multiplierNonZeroOddNumber, object, testTransients, null);
379     }
380 
381     /**
382      * Uses reflection to build a valid hash code from the fields of {@code object}.
383      *
384      * <p>
385      * It uses {@code AccessibleObject.setAccessible} to gain access to private fields. This means that it will
386      * throw a security exception if run under a security manager, if the permissions are not set up correctly. It is
387      * also not as efficient as testing explicitly.
388      * </p>
389      *
390      * <p>
391      * If the TestTransients parameter is set to {@code true}, transient members will be tested, otherwise they
392      * are ignored, as they are likely derived fields, and not part of the value of the {@link Object}.
393      * </p>
394      *
395      * <p>
396      * Static fields will not be included. Superclass fields will be included up to and including the specified
397      * superclass. A null superclass is treated as java.lang.Object.
398      * </p>
399      *
400      * <p>
401      * Two randomly chosen, non-zero, odd numbers must be passed in. Ideally these should be different for each class,
402      * however this is not vital. Prime numbers are preferred, especially for the multiplier.
403      * </p>
404      *
405      * @param <T>
406      *            the type of the object involved
407      * @param initialNonZeroOddNumber
408      *            a non-zero, odd number used as the initial value. This will be the returned
409      *            value if no fields are found to include in the hash code
410      * @param multiplierNonZeroOddNumber
411      *            a non-zero, odd number used as the multiplier
412      * @param object
413      *            the Object to create a {@code hashCode} for
414      * @param testTransients
415      *            whether to include transient fields
416      * @param reflectUpToClass
417      *            the superclass to reflect up to (inclusive), may be {@code null}
418      * @param excludeFields
419      *            array of field names to exclude from use in calculation of hash code
420      * @return int hash code
421      * @throws NullPointerException Thrown if the Object is {@code null}.
422      * @throws IllegalArgumentException Thrown if the number is zero or even.
423      * @see HashCodeExclude
424      * @since 2.0
425      */
426     public static <T> int reflectionHashCode(final int initialNonZeroOddNumber, final int multiplierNonZeroOddNumber, final T object,
427             final boolean testTransients, final Class<? super T> reflectUpToClass, final String... excludeFields) {
428         Objects.requireNonNull(object, "object");
429         final HashCodeBuilder builder = new HashCodeBuilder(initialNonZeroOddNumber, multiplierNonZeroOddNumber);
430         Class<?> clazz = object.getClass();
431         reflectionAppend(object, clazz, builder, testTransients, excludeFields, true);
432         while (clazz.getSuperclass() != null && clazz != reflectUpToClass) {
433             clazz = clazz.getSuperclass();
434             reflectionAppend(object, clazz, builder, testTransients, excludeFields, true);
435         }
436         return builder.toHashCode();
437     }
438 
439     /**
440      * Uses reflection to build a valid hash code from the fields of {@code object}.
441      *
442      * <p>
443      * This constructor uses two hard coded choices for the constants needed to build a hash code.
444      * </p>
445      *
446      * <p>
447      * It uses {@code AccessibleObject.setAccessible} to gain access to private fields. This means that it will
448      * throw a security exception if run under a security manager, if the permissions are not set up correctly. It is
449      * also not as efficient as testing explicitly.
450      * </p>
451      *
452      * <p>
453      * If the TestTransients parameter is set to {@code true}, transient members will be tested, otherwise they
454      * are ignored, as they are likely derived fields, and not part of the value of the {@link Object}.
455      * </p>
456      *
457      * <p>
458      * Static fields will not be tested. Superclass fields will be included. If no fields are found to include
459      * in the hash code, the result of this method will be constant.
460      * </p>
461      *
462      * @param object
463      *            the Object to create a {@code hashCode} for
464      * @param testTransients
465      *            whether to include transient fields
466      * @return int hash code
467      * @throws NullPointerException Thrown if the object is {@code null}.
468      * @see HashCodeExclude
469      */
470     public static int reflectionHashCode(final Object object, final boolean testTransients) {
471         return reflectionHashCode(DEFAULT_INITIAL_VALUE, DEFAULT_MULTIPLIER_VALUE, object,
472                 testTransients, null);
473     }
474 
475     /**
476      * Uses reflection to build a valid hash code from the fields of {@code object}.
477      *
478      * <p>
479      * This constructor uses two hard coded choices for the constants needed to build a hash code.
480      * </p>
481      *
482      * <p>
483      * It uses {@code AccessibleObject.setAccessible} to gain access to private fields. This means that it will
484      * throw a security exception if run under a security manager, if the permissions are not set up correctly. It is
485      * also not as efficient as testing explicitly.
486      * </p>
487      *
488      * <p>
489      * Transient members will be not be used, as they are likely derived fields, and not part of the value of the
490      * {@link Object}.
491      * </p>
492      *
493      * <p>
494      * Static fields will not be tested. Superclass fields will be included. If no fields are found to include
495      * in the hash code, the result of this method will be constant.
496      * </p>
497      *
498      * @param object
499      *            the Object to create a {@code hashCode} for
500      * @param excludeFields
501      *            Collection of String field names to exclude from use in calculation of hash code
502      * @return int hash code
503      * @throws NullPointerException Thrown if the object is {@code null}.
504      * @see HashCodeExclude
505      */
506     public static int reflectionHashCode(final Object object, final Collection<String> excludeFields) {
507         return reflectionHashCode(object, ReflectionToStringBuilder.toNoNullStringArray(excludeFields));
508     }
509 
510     /**
511      * Uses reflection to build a valid hash code from the fields of {@code object}.
512      *
513      * <p>
514      * This constructor uses two hard coded choices for the constants needed to build a hash code.
515      * </p>
516      *
517      * <p>
518      * It uses {@code AccessibleObject.setAccessible} to gain access to private fields. This means that it will
519      * throw a security exception if run under a security manager, if the permissions are not set up correctly. It is
520      * also not as efficient as testing explicitly.
521      * </p>
522      *
523      * <p>
524      * Transient members will be not be used, as they are likely derived fields, and not part of the value of the
525      * {@link Object}.
526      * </p>
527      *
528      * <p>
529      * Static fields will not be tested. Superclass fields will be included. If no fields are found to include
530      * in the hash code, the result of this method will be constant.
531      * </p>
532      *
533      * @param object
534      *            the Object to create a {@code hashCode} for
535      * @param excludeFields
536      *            array of field names to exclude from use in calculation of hash code
537      * @return int hash code
538      * @throws NullPointerException Thrown if the object is {@code null}.
539      * @see HashCodeExclude
540      */
541     public static int reflectionHashCode(final Object object, final String... excludeFields) {
542         return reflectionHashCode(DEFAULT_INITIAL_VALUE, DEFAULT_MULTIPLIER_VALUE, object, false,
543                 null, excludeFields);
544     }
545 
546     /**
547      * Registers the given object. Used by the reflection methods to avoid infinite loops.
548      *
549      * @param value
550      *            The object to register.
551      */
552     private static void register(final Object value) {
553         getRegistry().add(new IDKey(value));
554     }
555 
556     /**
557      * Unregisters the given object.
558      *
559      * <p>
560      * Used by the reflection methods to avoid infinite loops.
561      * </p>
562      *
563      * @param value
564      *            The object to unregister.
565      * @since 2.3
566      */
567     private static void unregister(final Object value) {
568         final Set<IDKey> registry = getRegistry();
569         registry.remove(new IDKey(value));
570         if (registry.isEmpty()) {
571             REGISTRY.remove();
572         }
573     }
574 
575     /**
576      * Constant to use in building the hashCode.
577      */
578     private final int constant;
579 
580     /**
581      * Running total of the hashCode.
582      */
583     private int total;
584 
585     /**
586      * Uses two hard coded choices for the constants needed to build a {@code hashCode}.
587      */
588     public HashCodeBuilder() {
589         this(builder().setInitialOddNumber(17).setMultiplierOddNumber(37));
590     }
591 
592     private HashCodeBuilder(final Builder builder) {
593         super(builder);
594         Validate.isTrue(builder.initialOddNumber % 2 != 0, "HashCodeBuilder requires an odd initial value");
595         Validate.isTrue(builder.multiplierOddNumber % 2 != 0, "HashCodeBuilder requires an odd multiplier");
596         constant = builder.multiplierOddNumber;
597         total = builder.initialOddNumber;    }
598 
599     /**
600      * Two randomly chosen, odd numbers must be passed in. Ideally these should be different for each class,
601      * however this is not vital.
602      *
603      * <p>
604      * Prime numbers are preferred, especially for the multiplier.
605      * </p>
606      *
607      * @param initialOddNumber
608      *            an odd number used as the initial value
609      * @param multiplierOddNumber
610      *            an odd number used as the multiplier
611      * @throws IllegalArgumentException Thrown if the number is even.
612      */
613     public HashCodeBuilder(final int initialOddNumber, final int multiplierOddNumber) {
614         this(builder().setInitialOddNumber(initialOddNumber).setMultiplierOddNumber(multiplierOddNumber));
615     }
616 
617     /**
618      * Appends a {@code hashCode} for a {@code boolean}.
619      *
620      * <p>
621      * This adds {@code 1} when true, and {@code 0} when false to the {@code hashCode}.
622      * </p>
623      * <p>
624      * This is in contrast to the standard {@link Boolean#hashCode()} handling, which computes
625      * a {@code hashCode} value of {@code 1231} for {@link Boolean} instances
626      * that represent {@code true} or {@code 1237} for {@link Boolean} instances
627      * that represent {@code false}.
628      * </p>
629      * <p>
630      * This is in accordance with the <em>Effective Java</em> design.
631      * </p>
632      *
633      * @param value
634      *            the boolean to add to the {@code hashCode}
635      * @return {@code this} instance.
636      */
637     public HashCodeBuilder append(final boolean value) {
638         total = total * constant + (value ? 0 : 1);
639         return this;
640     }
641 
642     /**
643      * Appends a {@code hashCode} for a {@code boolean} array.
644      *
645      * @param array
646      *            the array to add to the {@code hashCode}
647      * @return {@code this} instance.
648      */
649     public HashCodeBuilder append(final boolean[] array) {
650         if (array == null) {
651             total = total * constant;
652         } else {
653             for (final boolean element : array) {
654                 append(element);
655             }
656         }
657         return this;
658     }
659 
660     /**
661      * Appends a {@code hashCode} for a {@code byte}.
662      *
663      * @param value
664      *            the byte to add to the {@code hashCode}
665      * @return {@code this} instance.
666      */
667     public HashCodeBuilder append(final byte value) {
668         total = total * constant + value;
669         return this;
670     }
671 
672     /**
673      * Appends a {@code hashCode} for a {@code byte} array.
674      *
675      * @param array
676      *            the array to add to the {@code hashCode}
677      * @return {@code this} instance.
678      */
679     public HashCodeBuilder append(final byte[] array) {
680         if (array == null) {
681             total = total * constant;
682         } else {
683             for (final byte element : array) {
684                 append(element);
685             }
686         }
687         return this;
688     }
689 
690     /**
691      * Appends a {@code hashCode} for a {@code char}.
692      *
693      * @param value
694      *            the char to add to the {@code hashCode}
695      * @return {@code this} instance.
696      */
697     public HashCodeBuilder append(final char value) {
698         total = total * constant + value;
699         return this;
700     }
701 
702     /**
703      * Appends a {@code hashCode} for a {@code char} array.
704      *
705      * @param array
706      *            the array to add to the {@code hashCode}
707      * @return {@code this} instance.
708      */
709     public HashCodeBuilder append(final char[] array) {
710         if (array == null) {
711             total = total * constant;
712         } else {
713             for (final char element : array) {
714                 append(element);
715             }
716         }
717         return this;
718     }
719 
720     /**
721      * Appends a {@code hashCode} for a {@code double}.
722      *
723      * @param value
724      *            the double to add to the {@code hashCode}
725      * @return {@code this} instance.
726      */
727     public HashCodeBuilder append(final double value) {
728         return append(Double.doubleToLongBits(value));
729     }
730 
731     /**
732      * Appends a {@code hashCode} for a {@code double} array.
733      *
734      * @param array
735      *            the array to add to the {@code hashCode}
736      * @return {@code this} instance.
737      */
738     public HashCodeBuilder append(final double[] array) {
739         if (array == null) {
740             total = total * constant;
741         } else {
742             for (final double element : array) {
743                 append(element);
744             }
745         }
746         return this;
747     }
748 
749     /**
750      * Appends a {@code hashCode} for a {@code float}.
751      *
752      * @param value
753      *            the float to add to the {@code hashCode}
754      * @return {@code this} instance.
755      */
756     public HashCodeBuilder append(final float value) {
757         total = total * constant + Float.floatToIntBits(value);
758         return this;
759     }
760 
761     /**
762      * Appends a {@code hashCode} for a {@code float} array.
763      *
764      * @param array
765      *            the array to add to the {@code hashCode}
766      * @return {@code this} instance.
767      */
768     public HashCodeBuilder append(final float[] array) {
769         if (array == null) {
770             total = total * constant;
771         } else {
772             for (final float element : array) {
773                 append(element);
774             }
775         }
776         return this;
777     }
778 
779     /**
780      * Appends a {@code hashCode} for an {@code int}.
781      *
782      * @param value
783      *            the int to add to the {@code hashCode}
784      * @return {@code this} instance.
785      */
786     public HashCodeBuilder append(final int value) {
787         total = total * constant + value;
788         return this;
789     }
790 
791     /**
792      * Appends a {@code hashCode} for an {@code int} array.
793      *
794      * @param array
795      *            the array to add to the {@code hashCode}
796      * @return {@code this} instance.
797      */
798     public HashCodeBuilder append(final int[] array) {
799         if (array == null) {
800             total = total * constant;
801         } else {
802             for (final int element : array) {
803                 append(element);
804             }
805         }
806         return this;
807     }
808 
809     /**
810      * Appends a {@code hashCode} for a {@code long}.
811      *
812      * @param value
813      *            the long to add to the {@code hashCode}
814      * @return {@code this} instance.
815      */
816     // NOTE: This method uses >> and not >>> as Effective Java and
817     //       Long.hashCode do. Ideally we should switch to >>> at
818     //       some stage. There are backwards compat issues, so
819     //       that will have to wait for the time being. See LANG-342.
820     public HashCodeBuilder append(final long value) {
821         total = total * constant + (int) (value ^ value >> 32);
822         return this;
823     }
824 
825     /**
826      * Appends a {@code hashCode} for a {@code long} array.
827      *
828      * @param array
829      *            the array to add to the {@code hashCode}
830      * @return {@code this} instance.
831      */
832     public HashCodeBuilder append(final long[] array) {
833         if (array == null) {
834             total = total * constant;
835         } else {
836             for (final long element : array) {
837                 append(element);
838             }
839         }
840         return this;
841     }
842 
843     /**
844      * Appends a {@code hashCode} for an {@link Object}.
845      *
846      * @param object
847      *            the Object to add to the {@code hashCode}
848      * @return {@code this} instance.
849      */
850     public HashCodeBuilder append(final Object object) {
851         if (object == null || isRegistered(object) || isAppendRegistered(object)) {
852             total = total * constant;
853         } else if (ObjectUtils.isArray(object)) {
854             try {
855                 appendRegister(object);
856                 appendArray(object);
857             } finally {
858                 appendUnregister(object);
859             }
860         } else {
861             try {
862                 appendRegister(object);
863                 total = total * constant + object.hashCode();
864             } finally {
865                 appendUnregister(object);
866             }
867         }
868         return this;
869     }
870 
871     /**
872      * Appends a {@code hashCode} for an {@link Object} array.
873      *
874      * @param array
875      *            the array to add to the {@code hashCode}
876      * @return {@code this} instance.
877      */
878     public HashCodeBuilder append(final Object[] array) {
879         if (array == null) {
880             total = total * constant;
881         } else {
882             for (final Object element : array) {
883                 append(element);
884             }
885         }
886         return this;
887     }
888 
889     /**
890      * Appends a {@code hashCode} for a {@code short}.
891      *
892      * @param value
893      *            the short to add to the {@code hashCode}
894      * @return {@code this} instance.
895      */
896     public HashCodeBuilder append(final short value) {
897         total = total * constant + value;
898         return this;
899     }
900 
901     /**
902      * Appends a {@code hashCode} for a {@code short} array.
903      *
904      * @param array
905      *            the array to add to the {@code hashCode}
906      * @return {@code this} instance.
907      */
908     public HashCodeBuilder append(final short[] array) {
909         if (array == null) {
910             total = total * constant;
911         } else {
912             for (final short element : array) {
913                 append(element);
914             }
915         }
916         return this;
917     }
918 
919     /**
920      * Appends a {@code hashCode} for an array.
921      *
922      * @param object
923      *            the array to add to the {@code hashCode}
924      */
925     private void appendArray(final Object object) {
926         // 'Switch' on type of array, to dispatch to the correct handler
927         // This handles multidimensional arrays
928         if (object instanceof long[]) {
929             append((long[]) object);
930         } else if (object instanceof int[]) {
931             append((int[]) object);
932         } else if (object instanceof short[]) {
933             append((short[]) object);
934         } else if (object instanceof char[]) {
935             append((char[]) object);
936         } else if (object instanceof byte[]) {
937             append((byte[]) object);
938         } else if (object instanceof double[]) {
939             append((double[]) object);
940         } else if (object instanceof float[]) {
941             append((float[]) object);
942         } else if (object instanceof boolean[]) {
943             append((boolean[]) object);
944         } else {
945             // Not an array of primitives
946             append((Object[]) object);
947         }
948     }
949 
950     /**
951      * Adds the result of super.hashCode() to this builder.
952      *
953      * @param superHashCode
954      *            the result of calling {@code super.hashCode()}
955      * @return {@code this} instance.
956      * @since 2.0
957      */
958     public HashCodeBuilder appendSuper(final int superHashCode) {
959         total = total * constant + superHashCode;
960         return this;
961     }
962 
963     /**
964      * Returns the computed {@code hashCode}.
965      *
966      * @return {@code hashCode} based on the fields appended
967      * @since 3.0
968      */
969     @Override
970     public Integer build() {
971         return Integer.valueOf(toHashCode());
972     }
973 
974     /**
975      * Implements equals using the hash code.
976      *
977      * @since 3.13.0
978      */
979     @Override
980     public boolean equals(final Object obj) {
981         if (this == obj) {
982             return true;
983         }
984         if (!(obj instanceof HashCodeBuilder)) {
985             return false;
986         }
987         final HashCodeBuilder other = (HashCodeBuilder) obj;
988         return total == other.total;
989     }
990 
991     /**
992      * Returns the computed {@code hashCode} from {@link #toHashCode()} due to the likelihood of bugs in mis-calling {@link #toHashCode()} and the unlikeliness
993      * of it mattering what the hashCode for {@link HashCodeBuilder} itself is.
994      *
995      * @return {@code hashCode} based on the fields appended
996      * @since 2.5
997      */
998     @Override
999     public int hashCode() {
1000         return toHashCode();
1001     }
1002 
1003     /**
1004      * Returns the computed {@code hashCode}.
1005      *
1006      * @return {@code hashCode} based on the fields appended
1007      */
1008     public int toHashCode() {
1009         return total;
1010     }
1011 
1012 }