Java > Open Source Codes > org > apache > commons > lang > builder > HashCodeBuilder


1 /*
2  * Copyright 2002-2005 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.lang.builder;
17
18 import java.lang.reflect.AccessibleObject ;
19 import java.lang.reflect.Field ;
20 import java.lang.reflect.Modifier ;
21
22 /**
23  * <p>Assists in implementing {@link Object#hashCode()} methods.</p>
24  *
25  * <p> This class enables a good <code>hashCode</code> method to be built for any class. It
26  * follows the rules laid out in the book
27  * <a HREF="http://java.sun.com/docs/books/effective/index.html">Effective Java</a>
28  * by Joshua Bloch. Writing a good <code>hashCode</code> method is actually quite
29  * difficult. This class aims to simplify the process.</p>
30  *
31  * <p>All relevant fields from the object should be included in the
32  * <code>hashCode</code> method. Derived fields may be excluded. In general, any
33  * field used in the <code>equals</code> method must be used in the <code>hashCode</code>
34  * method.</p>
35  *
36  * <p>To use this class write code as follows:</p>
37  * <pre>
38  * public class Person {
39  * String name;
40  * int age;
41  * boolean isSmoker;
42  * ...
43  *
44  * public int hashCode() {
45  * // you pick a hard-coded, randomly chosen, non-zero, odd number
46  * // ideally different for each class
47  * return new HashCodeBuilder(17, 37).
48  * append(name).
49  * append(age).
50  * append(smoker).
51  * toHashCode();
52  * }
53  * }
54  * </pre>
55  *
56  * <p>If required, the superclass <code>hashCode()</code> can be added
57  * using {@link #appendSuper}.</p>
58  *
59  * <p>Alternatively, there is a method that uses reflection to determine
60  * the fields to test. Because these fields are usually private, the method,
61  * <code>reflectionHashCode</code>, uses <code>AccessibleObject.setAccessible</code> to
62  * change the visibility of the fields. This will fail under a security manager,
63  * unless the appropriate permissions are set up correctly. It is also slower
64  * than testing explicitly.</p>
65  *
66  * <p>A typical invocation for this method would look like:</p>
67  * <pre>
68  * public int hashCode() {
69  * return HashCodeBuilder.reflectionHashCode(this);
70  * }
71  * </pre>
72  *
73  * @author Stephen Colebourne
74  * @author Gary Gregory
75  * @author Pete Gieser
76  * @since 1.0
77  * @version $Id: HashCodeBuilder.java 161243 2005-04-14 04:30:28Z ggregory $
78  */
79 public class HashCodeBuilder {
80
81     /**
82      * Constant to use in building the hashCode.
83      */
84     private final int iConstant;
85     /**
86      * Running total of the hashCode.
87      */
88     private int iTotal = 0;
89
90     /**
91      * <p>Uses two hard coded choices for the constants
92      * needed to build a <code>hashCode</code>.</p>
93      */
94     public HashCodeBuilder() {
95         iConstant = 37;
96         iTotal = 17;
97     }
98
99     /**
100      * <p>Two randomly chosen, non-zero, odd numbers must be passed in.
101      * Ideally these should be different for each class, however this is
102      * not vital.</p>
103      *
104      * <p>Prime numbers are preferred, especially for the multiplier.</p>
105      *
106      * @param initialNonZeroOddNumber a non-zero, odd number used as the initial value
107      * @param multiplierNonZeroOddNumber a non-zero, odd number used as the multiplier
108      * @throws IllegalArgumentException if the number is zero or even
109      */
110     public HashCodeBuilder(int initialNonZeroOddNumber, int multiplierNonZeroOddNumber) {
111         if (initialNonZeroOddNumber == 0) {
112             throw new IllegalArgumentException ("HashCodeBuilder requires a non zero initial value");
113         }
114         if (initialNonZeroOddNumber % 2 == 0) {
115             throw new IllegalArgumentException ("HashCodeBuilder requires an odd initial value");
116         }
117         if (multiplierNonZeroOddNumber == 0) {
118             throw new IllegalArgumentException ("HashCodeBuilder requires a non zero multiplier");
119         }
120         if (multiplierNonZeroOddNumber % 2 == 0) {
121             throw new IllegalArgumentException ("HashCodeBuilder requires an odd multiplier");
122         }
123         iConstant = multiplierNonZeroOddNumber;
124         iTotal = initialNonZeroOddNumber;
125     }
126
127     //-------------------------------------------------------------------------
128
129     /**
130      * <p>This method uses reflection to build a valid hash code.</p>
131      *
132      * <p>This constructor uses two hard coded choices for the constants
133      * needed to build a hash code.</p>
134      *
135      * <p>It uses <code>AccessibleObject.setAccessible</code> to gain access to private
136      * fields. This means that it will throw a security exception if run under
137      * a security manager, if the permissions are not set up correctly. It is
138      * also not as efficient as testing explicitly.</p>
139      *
140      * <p>Transient members will be not be used, as they are likely derived
141      * fields, and not part of the value of the <code>Object</code>.</p>
142      *
143      * <p>Static fields will not be tested. Superclass fields will be included.</p>
144      *
145      * @param object the Object to create a <code>hashCode</code> for
146      * @return int hash code
147      * @throws IllegalArgumentException if the object is <code>null</code>
148      */
149     public static int reflectionHashCode(Object object) {
150         return reflectionHashCode(17, 37, object, false, null);
151     }
152
153     /**
154      * <p>This method uses reflection to build a valid hash code.</p>
155      *
156      * <p>This constructor uses two hard coded choices for the constants needed
157      * to build a hash code.</p>
158      *
159      * <p> It uses <code>AccessibleObject.setAccessible</code> to gain access to private
160      * fields. This means that it will throw a security exception if run under
161      * a security manager, if the permissions are not set up correctly. It is
162      * also not as efficient as testing explicitly.</p>
163      *
164      * <P>If the TestTransients parameter is set to <code>true</code>, transient
165      * members will be tested, otherwise they are ignored, as they are likely
166      * derived fields, and not part of the value of the <code>Object</code>.</p>
167      *
168      * <p>Static fields will not be tested. Superclass fields will be included.</p>
169      *
170      * @param object the Object to create a <code>hashCode</code> for
171      * @param testTransients whether to include transient fields
172      * @return int hash code
173      * @throws IllegalArgumentException if the object is <code>null</code>
174      */
175     public static int reflectionHashCode(Object object, boolean testTransients) {
176         return reflectionHashCode(17, 37, object, testTransients, null);
177     }
178
179     /**
180      * <p>This method uses reflection to build a valid hash code.</p>
181      *
182      * <p>It uses <code>AccessibleObject.setAccessible</code> to gain access to private
183      * fields. This means that it will throw a security exception if run under
184      * a security manager, if the permissions are not set up correctly. It is
185      * also not as efficient as testing explicitly.</p>
186      *
187      * <p>Transient members will be not be used, as they are likely derived
188      * fields, and not part of the value of the <code>Object</code>.</p>
189      *
190      * <p>Static fields will not be tested. Superclass fields will be included.</p>
191      *
192      * <p>Two randomly chosen, non-zero, odd numbers must be passed in. Ideally
193      * these should be different for each class, however this is not vital.
194      * Prime numbers are preferred, especially for the multiplier.</p>
195      *
196      * @param initialNonZeroOddNumber a non-zero, odd number used as the initial value
197      * @param multiplierNonZeroOddNumber a non-zero, odd number used as the multiplier
198      * @param object the Object to create a <code>hashCode</code> for
199      * @return int hash code
200      * @throws IllegalArgumentException if the Object is <code>null</code>
201      * @throws IllegalArgumentException if the number is zero or even
202      */
203     public static int reflectionHashCode(
204             int initialNonZeroOddNumber, int multiplierNonZeroOddNumber, Object object) {
205         return reflectionHashCode(initialNonZeroOddNumber, multiplierNonZeroOddNumber, object, false, null);
206     }
207
208     /**
209      * <p>This method uses reflection to build a valid hash code.</p>
210      *
211      * <p>It uses <code>AccessibleObject.setAccessible</code> to gain access to private
212      * fields. This means that it will throw a security exception if run under
213      * a security manager, if the permissions are not set up correctly. It is also
214      * not as efficient as testing explicitly.</p>
215      *
216      * <p>If the TestTransients parameter is set to <code>true</code>, transient
217      * members will be tested, otherwise they are ignored, as they are likely
218      * derived fields, and not part of the value of the <code>Object</code>.</p>
219      *
220      * <p>Static fields will not be tested. Superclass fields will be included.</p>
221      *
222      * <p>Two randomly chosen, non-zero, odd numbers must be passed in. Ideally
223      * these should be different for each class, however this is not vital.
224      * Prime numbers are preferred, especially for the multiplier.</p>
225      *
226      * @param initialNonZeroOddNumber a non-zero, odd number used as the initial value
227      * @param multiplierNonZeroOddNumber a non-zero, odd number used as the multiplier
228      * @param object the Object to create a <code>hashCode</code> for
229      * @param testTransients whether to include transient fields
230      * @return int hash code
231      * @throws IllegalArgumentException if the Object is <code>null</code>
232      * @throws IllegalArgumentException if the number is zero or even
233      */
234     public static int reflectionHashCode(
235             int initialNonZeroOddNumber, int multiplierNonZeroOddNumber,
236             Object object, boolean testTransients) {
237         return reflectionHashCode(initialNonZeroOddNumber, multiplierNonZeroOddNumber, object, testTransients, null);
238     }
239             
240     /**
241      * <p>This method uses reflection to build a valid hash code.</p>
242      *
243      * <p>It uses <code>AccessibleObject.setAccessible</code> to gain access to private
244      * fields. This means that it will throw a security exception if run under
245      * a security manager, if the permissions are not set up correctly. It is also
246      * not as efficient as testing explicitly.</p>
247      *
248      * <p>If the TestTransients parameter is set to <code>true</code>, transient
249      * members will be tested, otherwise they are ignored, as they are likely
250      * derived fields, and not part of the value of the <code>Object</code>.</p>
251      *
252      * <p>Static fields will not be included. Superclass fields will be included
253      * up to and including the specified superclass. A null superclass is treated
254      * as java.lang.Object.</p>
255      *
256      * <p>Two randomly chosen, non-zero, odd numbers must be passed in. Ideally
257      * these should be different for each class, however this is not vital.
258      * Prime numbers are preferred, especially for the multiplier.</p>
259      *
260      * @param initialNonZeroOddNumber a non-zero, odd number used as the initial value
261      * @param multiplierNonZeroOddNumber a non-zero, odd number used as the multiplier
262      * @param object the Object to create a <code>hashCode</code> for
263      * @param testTransients whether to include transient fields
264      * @param reflectUpToClass the superclass to reflect up to (inclusive),
265      * may be <code>null</code>
266      * @return int hash code
267      * @throws IllegalArgumentException if the Object is <code>null</code>
268      * @throws IllegalArgumentException if the number is zero or even
269      * @since 2.0
270      */
271     public static int reflectionHashCode(
272         int initialNonZeroOddNumber,
273         int multiplierNonZeroOddNumber,
274         Object object,
275         boolean testTransients,
276         Class reflectUpToClass) {
277
278         if (object == null) {
279             throw new IllegalArgumentException ("The object to build a hash code for must not be null");
280         }
281         HashCodeBuilder builder = new HashCodeBuilder(initialNonZeroOddNumber, multiplierNonZeroOddNumber);
282         Class clazz = object.getClass();
283         reflectionAppend(object, clazz, builder, testTransients);
284         while (clazz.getSuperclass() != null && clazz != reflectUpToClass) {
285             clazz = clazz.getSuperclass();
286             reflectionAppend(object, clazz, builder, testTransients);
287         }
288         return builder.toHashCode();
289     }
290
291     /**
292      * <p>Appends the fields and values defined by the given object of the
293      * given <code>Class</code>.</p>
294      *
295      * @param object the object to append details of
296      * @param clazz the class to append details of
297      * @param builder the builder to append to
298      * @param useTransients whether to use transient fields
299      */
300     private static void reflectionAppend(Object object, Class clazz, HashCodeBuilder builder, boolean useTransients) {
301         Field [] fields = clazz.getDeclaredFields();
302         AccessibleObject.setAccessible(fields, true);
303         for (int i = 0; i < fields.length; i++) {
304             Field f = fields[i];
305             if ((f.getName().indexOf('$') == -1)
306                 && (useTransients || !Modifier.isTransient(f.getModifiers()))
307                 && (!Modifier.isStatic(f.getModifiers()))) {
308                 try {
309                     builder.append(f.get(object));
310                 } catch (IllegalAccessException e) {
311                     //this can't happen. Would get a Security exception instead
312 //throw a runtime exception in case the impossible happens.
313 throw new InternalError ("Unexpected IllegalAccessException");
314                 }
315             }
316         }
317     }
318
319     //-------------------------------------------------------------------------
320
321     /**
322      * <p>Adds the result of super.hashCode() to this builder.</p>
323      *
324      * @param superHashCode the result of calling <code>super.hashCode()</code>
325      * @return this HashCodeBuilder, used to chain calls.
326      * @since 2.0
327      */
328     public HashCodeBuilder appendSuper(int superHashCode) {
329         iTotal = iTotal * iConstant + superHashCode;
330         return this;
331     }
332
333     //-------------------------------------------------------------------------
334
335     /**
336      * <p>Append a <code>hashCode</code> for an <code>Object</code>.</p>
337      *
338      * @param object the Object to add to the <code>hashCode</code>
339      * @return this
340      */
341     public HashCodeBuilder append(Object object) {
342         if (object == null) {
343             iTotal = iTotal * iConstant;
344
345         } else {
346             if (object.getClass().isArray() == false) {
347                 //the simple case, not an array, just the element
348 iTotal = iTotal * iConstant + object.hashCode();
349
350             } else {
351                 //'Switch' on type of array, to dispatch to the correct handler
352 // This handles multi dimensional arrays
353 if (object instanceof long[]) {
354                     append((long[]) object);
355                 } else if (object instanceof int[]) {
356                     append((int[]) object);
357                 } else if (object instanceof short[]) {
358                     append((short[]) object);
359                 } else if (object instanceof char[]) {
360                     append((char[]) object);
361                 } else if (object instanceof byte[]) {
362                     append((byte[]) object);
363                 } else if (object instanceof double[]) {
364                     append((double[]) object);
365                 } else if (object instanceof float[]) {
366                     append((float[]) object);
367                 } else if (object instanceof boolean[]) {
368                     append((boolean[]) object);
369                 } else {
370                     // Not an array of primitives
371 append((Object []) object);
372                 }
373             }
374         }
375         return this;
376     }
377
378     /**
379      * <p>Append a <code>hashCode</code> for a <code>long</code>.</p>
380      *
381      * @param value the long to add to the <code>hashCode</code>
382      * @return this
383      */
384     public HashCodeBuilder append(long value) {
385         iTotal = iTotal * iConstant + ((int) (value ^ (value >> 32)));
386         return this;
387     }
388
389     /**
390      * <p>Append a <code>hashCode</code> for an <code>int</code>.</p>
391      *
392      * @param value the int to add to the <code>hashCode</code>
393      * @return this
394      */
395     public HashCodeBuilder append(int value) {
396         iTotal = iTotal * iConstant + value;
397         return this;
398     }
399
400     /**
401      * <p>Append a <code>hashCode</code> for a <code>short</code>.</p>
402      *
403      * @param value the short to add to the <code>hashCode</code>
404      * @return this
405      */
406     public HashCodeBuilder append(short value) {
407         iTotal = iTotal * iConstant + value;
408         return this;
409     }
410
411     /**
412      * <p>Append a <code>hashCode</code> for a <code>char</code>.</p>
413      *
414      * @param value the char to add to the <code>hashCode</code>
415      * @return this
416      */
417     public HashCodeBuilder append(char value) {
418         iTotal = iTotal * iConstant + value;
419         return this;
420     }
421
422     /**
423      * <p>Append a <code>hashCode</code> for a <code>byte</code>.</p>
424      *
425      * @param value the byte to add to the <code>hashCode</code>
426      * @return this
427      */
428     public HashCodeBuilder append(byte value) {
429         iTotal = iTotal * iConstant + value;
430         return this;
431     }
432
433     /**
434      * <p>Append a <code>hashCode</code> for a <code>double</code>.</p>
435      *
436      * @param value the double to add to the <code>hashCode</code>
437      * @return this
438      */
439     public HashCodeBuilder append(double value) {
440         return append(Double.doubleToLongBits(value));
441     }
442
443     /**
444      * <p>Append a <code>hashCode</code> for a <code>float</code>.</p>
445      *
446      * @param value the float to add to the <code>hashCode</code>
447      * @return this
448      */
449     public HashCodeBuilder append(float value) {
450         iTotal = iTotal * iConstant + Float.floatToIntBits(value);
451         return this;
452     }
453
454     /**
455      * <p>Append a <code>hashCode</code> for a <code>boolean</code>.</p>
456      * <p>This adds <code>iConstant * 1</code> to the <code>hashCode</code>
457      * and not a <code>1231</code> or <code>1237</code> as done in java.lang.Boolean.
458      * This is in accordance with the <quote>Effective Java</quote> design. </p>
459      *
460      * @param value the boolean to add to the <code>hashCode</code>
461      * @return this
462      */
463     public HashCodeBuilder append(boolean value) {
464         iTotal = iTotal * iConstant + (value ? 0 : 1);
465         return this;
466     }
467
468     /**
469      * <p>Append a <code>hashCode</code> for an <code>Object</code> array.</p>
470      *
471      * @param array the array to add to the <code>hashCode</code>
472      * @return this
473      */
474     public HashCodeBuilder append(Object [] array) {
475         if (array == null) {
476             iTotal = iTotal * iConstant;
477         } else {
478             for (int i = 0; i < array.length; i++) {
479                 append(array[i]);
480             }
481         }
482         return this;
483     }
484
485     /**
486      * <p>Append a <code>hashCode</code> for a <code>long</code> array.</p>
487      *
488      * @param array the array to add to the <code>hashCode</code>
489      * @return this
490      */
491     public HashCodeBuilder append(long[] array) {
492         if (array == null) {
493             iTotal = iTotal * iConstant;
494         } else {
495             for (int i = 0; i < array.length; i++) {
496                 append(array[i]);
497             }
498         }
499         return this;
500     }
501
502     /**
503      * <p>Append a <code>hashCode</code> for an <code>int</code> array.</p>
504      *
505      * @param array the array to add to the <code>hashCode</code>
506      * @return this
507      */
508     public HashCodeBuilder append(int[] array) {
509         if (array == null) {
510             iTotal = iTotal * iConstant;
511         } else {
512             for (int i = 0; i < array.length; i++) {
513                 append(array[i]);
514             }
515         }
516         return this;
517     }
518
519     /**
520      * <p>Append a <code>hashCode</code> for a <code>short</code> array.</p>
521      *
522      * @param array the array to add to the <code>hashCode</code>
523      * @return this
524      */
525     public HashCodeBuilder append(short[] array) {
526         if (array == null) {
527             iTotal = iTotal * iConstant;
528         } else {
529             for (int i = 0; i < array.length; i++) {
530                 append(array[i]);
531             }
532         }
533         return this;
534     }
535
536     /**
537      * <p>Append a <code>hashCode</code> for a <code>char</code> array.</p>
538      *
539      * @param array the array to add to the <code>hashCode</code>
540      * @return this
541      */
542     public HashCodeBuilder append(char[] array) {
543         if (array == null) {
544             iTotal = iTotal * iConstant;
545         } else {
546             for (int i = 0; i < array.length; i++) {
547                 append(array[i]);
548             }
549         }
550         return this;
551     }
552
553     /**
554      * <p>Append a <code>hashCode</code> for a <code>byte</code> array.</p>
555      *
556      * @param array the array to add to the <code>hashCode</code>
557      * @return this
558      */
559     public HashCodeBuilder append(byte[] array) {
560         if (array == null) {
561             iTotal = iTotal * iConstant;
562         } else {
563             for (int i = 0; i < array.length; i++) {
564                 append(array[i]);
565             }
566         }
567         return this;
568     }
569
570     /**
571      * <p>Append a <code>hashCode</code> for a <code>double</code> array.</p>
572      *
573      * @param array the array to add to the <code>hashCode</code>
574      * @return this
575      */
576     public HashCodeBuilder append(double[] array) {
577         if (array == null) {
578             iTotal = iTotal * iConstant;
579         } else {
580             for (int i = 0; i < array.length; i++) {
581                 append(array[i]);
582             }
583         }
584         return this;
585     }
586
587     /**
588      * <p>Append a <code>hashCode</code> for a <code>float</code> array.</p>
589      *
590      * @param array the array to add to the <code>hashCode</code>
591      * @return this
592      */
593     public HashCodeBuilder append(float[] array) {
594         if (array == null) {
595             iTotal = iTotal * iConstant;
596         } else {
597             for (int i = 0; i < array.length; i++) {
598                 append(array[i]);
599             }
600         }
601         return this;
602     }
603
604     /**
605      * <p>Append a <code>hashCode</code> for a <code>boolean</code> array.</p>
606      *
607      * @param array the array to add to the <code>hashCode</code>
608      * @return this
609      */
610     public HashCodeBuilder append(boolean[] array) {
611         if (array == null) {
612             iTotal = iTotal * iConstant;
613         } else {
614             for (int i = 0; i < array.length; i++) {
615                 append(array[i]);
616             }
617         }
618         return this;
619     }
620
621     /**
622      * <p>Return the computed <code>hashCode</code>.</p>
623      *
624      * @return <code>hashCode</code> based on the fields appended
625      */
626     public int toHashCode() {
627         return iTotal;
628     }
629
630 }
631

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags