001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.lang3.builder;
018
019import java.lang.reflect.AccessibleObject;
020import java.lang.reflect.Field;
021import java.lang.reflect.Modifier;
022import java.util.ArrayList;
023import java.util.Collection;
024import java.util.HashSet;
025import java.util.List;
026import java.util.Set;
027
028import org.apache.commons.lang3.ArrayUtils;
029import org.apache.commons.lang3.ClassUtils;
030import org.apache.commons.lang3.tuple.Pair;
031
032/**
033 * Assists in implementing {@link Object#equals(Object)} methods.
034 *
035 * <p> This class provides methods to build a good equals method for any
036 * class. It follows rules laid out in
037 * <a href="https://www.oracle.com/java/technologies/effectivejava.html">Effective Java</a>
038 * , by Joshua Bloch. In particular the rule for comparing {@code doubles},
039 * {@code floats}, and arrays can be tricky. Also, making sure that
040 * {@code equals()} and {@code hashCode()} are consistent can be
041 * difficult.</p>
042 *
043 * <p>Two Objects that compare as equals must generate the same hash code,
044 * but two Objects with the same hash code do not have to be equal.</p>
045 *
046 * <p>All relevant fields should be included in the calculation of equals.
047 * Derived fields may be ignored. In particular, any field used in
048 * generating a hash code must be used in the equals method, and vice
049 * versa.</p>
050 *
051 * <p>Typical use for the code is as follows:</p>
052 * <pre>
053 * public boolean equals(Object obj) {
054 *   if (obj == null) { return false; }
055 *   if (obj == this) { return true; }
056 *   if (obj.getClass() != getClass()) {
057 *     return false;
058 *   }
059 *   MyClass rhs = (MyClass) obj;
060 *   return new EqualsBuilder()
061 *                 .appendSuper(super.equals(obj))
062 *                 .append(field1, rhs.field1)
063 *                 .append(field2, rhs.field2)
064 *                 .append(field3, rhs.field3)
065 *                 .isEquals();
066 *  }
067 * </pre>
068 *
069 * <p> Alternatively, there is a method that uses reflection to determine
070 * the fields to test. Because these fields are usually private, the method,
071 * {@code reflectionEquals}, uses {@code AccessibleObject.setAccessible} to
072 * change the visibility of the fields. This will fail under a security
073 * manager, unless the appropriate permissions are set up correctly. It is
074 * also slower than testing explicitly.  Non-primitive fields are compared using
075 * {@code equals()}.</p>
076 *
077 * <p> A typical invocation for this method would look like:</p>
078 * <pre>
079 * public boolean equals(Object obj) {
080 *   return EqualsBuilder.reflectionEquals(this, obj);
081 * }
082 * </pre>
083 *
084 * <p>The {@link EqualsExclude} annotation can be used to exclude fields from being
085 * used by the {@code reflectionEquals} methods.</p>
086 *
087 * @since 1.0
088 */
089public class EqualsBuilder implements Builder<Boolean> {
090
091    /**
092     * A registry of objects used by reflection methods to detect cyclical object references and avoid infinite loops.
093     *
094     * @since 3.0
095     */
096    private static final ThreadLocal<Set<Pair<IDKey, IDKey>>> REGISTRY = new ThreadLocal<>();
097
098    /*
099     * NOTE: we cannot store the actual objects in a HashSet, as that would use the very hashCode()
100     * we are in the process of calculating.
101     *
102     * So we generate a one-to-one mapping from the original object to a new object.
103     *
104     * Now HashSet uses equals() to determine if two elements with the same hash code really
105     * are equal, so we also need to ensure that the replacement objects are only equal
106     * if the original objects are identical.
107     *
108     * The original implementation (2.4 and before) used the System.identityHashCode()
109     * method - however this is not guaranteed to generate unique ids (e.g. LANG-459)
110     *
111     * We now use the IDKey helper class (adapted from org.apache.axis.utils.IDKey)
112     * to disambiguate the duplicate ids.
113     */
114
115    /**
116     * Returns the registry of object pairs being traversed by the reflection
117     * methods in the current thread.
118     *
119     * @return Set the registry of objects being traversed
120     * @since 3.0
121     */
122    static Set<Pair<IDKey, IDKey>> getRegistry() {
123        return REGISTRY.get();
124    }
125
126    /**
127     * Converters value pair into a register pair.
128     *
129     * @param lhs {@code this} object
130     * @param rhs the other object
131     *
132     * @return the pair
133     */
134    static Pair<IDKey, IDKey> getRegisterPair(final Object lhs, final Object rhs) {
135        final IDKey left = new IDKey(lhs);
136        final IDKey right = new IDKey(rhs);
137        return Pair.of(left, right);
138    }
139
140    /**
141     * Returns {@code true} if the registry contains the given object pair.
142     * Used by the reflection methods to avoid infinite loops.
143     * Objects might be swapped therefore a check is needed if the object pair
144     * is registered in given or swapped order.
145     *
146     * @param lhs {@code this} object to lookup in registry
147     * @param rhs the other object to lookup on registry
148     * @return boolean {@code true} if the registry contains the given object.
149     * @since 3.0
150     */
151    static boolean isRegistered(final Object lhs, final Object rhs) {
152        final Set<Pair<IDKey, IDKey>> registry = getRegistry();
153        final Pair<IDKey, IDKey> pair = getRegisterPair(lhs, rhs);
154        final Pair<IDKey, IDKey> swappedPair = Pair.of(pair.getRight(), pair.getLeft());
155
156        return registry != null
157                && (registry.contains(pair) || registry.contains(swappedPair));
158    }
159
160    /**
161     * Registers the given object pair.
162     * Used by the reflection methods to avoid infinite loops.
163     *
164     * @param lhs {@code this} object to register
165     * @param rhs the other object to register
166     */
167    private static void register(final Object lhs, final Object rhs) {
168        Set<Pair<IDKey, IDKey>> registry = getRegistry();
169        if (registry == null) {
170            registry = new HashSet<>();
171            REGISTRY.set(registry);
172        }
173        final Pair<IDKey, IDKey> pair = getRegisterPair(lhs, rhs);
174        registry.add(pair);
175    }
176
177    /**
178     * Unregisters the given object pair.
179     *
180     * <p>
181     * Used by the reflection methods to avoid infinite loops.
182     *
183     * @param lhs {@code this} object to unregister
184     * @param rhs the other object to unregister
185     * @since 3.0
186     */
187    private static void unregister(final Object lhs, final Object rhs) {
188        final Set<Pair<IDKey, IDKey>> registry = getRegistry();
189        if (registry != null) {
190            registry.remove(getRegisterPair(lhs, rhs));
191            if (registry.isEmpty()) {
192                REGISTRY.remove();
193            }
194        }
195    }
196
197    /**
198     * If the fields tested are equals.
199     * The default value is {@code true}.
200     */
201    private boolean isEquals = true;
202
203    private boolean testTransients;
204    private boolean testRecursive;
205    private List<Class<?>> bypassReflectionClasses;
206    private Class<?> reflectUpToClass;
207    private String[] excludeFields;
208
209    /**
210     * Constructor for EqualsBuilder.
211     *
212     * <p>Starts off assuming that equals is {@code true}.</p>
213     * @see Object#equals(Object)
214     */
215    public EqualsBuilder() {
216        // set up default classes to bypass reflection for
217        bypassReflectionClasses = new ArrayList<>(1);
218        bypassReflectionClasses.add(String.class); //hashCode field being lazy but not transient
219    }
220
221    /**
222     * Set whether to include transient fields when reflectively comparing objects.
223     * @param testTransients whether to test transient fields
224     * @return this
225     * @since 3.6
226     */
227    public EqualsBuilder setTestTransients(final boolean testTransients) {
228        this.testTransients = testTransients;
229        return this;
230    }
231
232    /**
233     * Set whether to test fields recursively, instead of using their equals method, when reflectively comparing objects.
234     * String objects, which cache a hash value, are automatically excluded from recursive testing.
235     * You may specify other exceptions by calling {@link #setBypassReflectionClasses(List)}.
236     * @param testRecursive whether to do a recursive test
237     * @return this
238     * @see #setBypassReflectionClasses(List)
239     * @since 3.6
240     */
241    public EqualsBuilder setTestRecursive(final boolean testRecursive) {
242        this.testRecursive = testRecursive;
243        return this;
244    }
245
246    /**
247     * Set {@link Class}es whose instances should be compared by calling their {@code equals}
248     * although being in recursive mode. So the fields of theses classes will not be compared recursively by reflection.
249     *
250     * <p>Here you should name classes having non-transient fields which are cache fields being set lazily.<br>
251     * Prominent example being {@link String} class with its hash code cache field. Due to the importance
252     * of the {@link String} class, it is included in the default bypasses classes. Usually, if you use
253     * your own set of classes here, remember to include {@link String} class, too.</p>
254     * @param bypassReflectionClasses  classes to bypass reflection test
255     * @return this
256     * @see #setTestRecursive(boolean)
257     * @since 3.8
258     */
259    public EqualsBuilder setBypassReflectionClasses(final List<Class<?>> bypassReflectionClasses) {
260        this.bypassReflectionClasses = bypassReflectionClasses;
261        return this;
262    }
263
264    /**
265     * Set the superclass to reflect up to at reflective tests.
266     * @param reflectUpToClass the super class to reflect up to
267     * @return this
268     * @since 3.6
269     */
270    public EqualsBuilder setReflectUpToClass(final Class<?> reflectUpToClass) {
271        this.reflectUpToClass = reflectUpToClass;
272        return this;
273    }
274
275    /**
276     * Set field names to be excluded by reflection tests.
277     * @param excludeFields the fields to exclude
278     * @return this
279     * @since 3.6
280     */
281    public EqualsBuilder setExcludeFields(final String... excludeFields) {
282        this.excludeFields = excludeFields;
283        return this;
284    }
285
286
287    /**
288     * This method uses reflection to determine if the two {@link Object}s
289     * are equal.
290     *
291     * <p>It uses {@code AccessibleObject.setAccessible} to gain access to private
292     * fields. This means that it will throw a security exception if run under
293     * a security manager, if the permissions are not set up correctly. It is also
294     * not as efficient as testing explicitly. Non-primitive fields are compared using
295     * {@code equals()}.</p>
296     *
297     * <p>Transient members will be not be tested, as they are likely derived
298     * fields, and not part of the value of the Object.</p>
299     *
300     * <p>Static fields will not be tested. Superclass fields will be included.</p>
301     *
302     * @param lhs  {@code this} object
303     * @param rhs  the other object
304     * @param excludeFields  Collection of String field names to exclude from testing
305     * @return {@code true} if the two Objects have tested equals.
306     *
307     * @see EqualsExclude
308     */
309    public static boolean reflectionEquals(final Object lhs, final Object rhs, final Collection<String> excludeFields) {
310        return reflectionEquals(lhs, rhs, ReflectionToStringBuilder.toNoNullStringArray(excludeFields));
311    }
312
313    /**
314     * This method uses reflection to determine if the two {@link Object}s
315     * are equal.
316     *
317     * <p>It uses {@code AccessibleObject.setAccessible} to gain access to private
318     * fields. This means that it will throw a security exception if run under
319     * a security manager, if the permissions are not set up correctly. It is also
320     * not as efficient as testing explicitly. Non-primitive fields are compared using
321     * {@code equals()}.</p>
322     *
323     * <p>Transient members will be not be tested, as they are likely derived
324     * fields, and not part of the value of the Object.</p>
325     *
326     * <p>Static fields will not be tested. Superclass fields will be included.</p>
327     *
328     * @param lhs  {@code this} object
329     * @param rhs  the other object
330     * @param excludeFields  array of field names to exclude from testing
331     * @return {@code true} if the two Objects have tested equals.
332     *
333     * @see EqualsExclude
334     */
335    public static boolean reflectionEquals(final Object lhs, final Object rhs, final String... excludeFields) {
336        return reflectionEquals(lhs, rhs, false, null, excludeFields);
337    }
338
339    /**
340     * This method uses reflection to determine if the two {@link Object}s
341     * are equal.
342     *
343     * <p>It uses {@code AccessibleObject.setAccessible} to gain access to private
344     * fields. This means that it will throw a security exception if run under
345     * a security manager, if the permissions are not set up correctly. It is also
346     * not as efficient as testing explicitly. Non-primitive fields are compared using
347     * {@code equals()}.</p>
348     *
349     * <p>If the TestTransients parameter is set to {@code true}, transient
350     * members will be tested, otherwise they are ignored, as they are likely
351     * derived fields, and not part of the value of the {@link Object}.</p>
352     *
353     * <p>Static fields will not be tested. Superclass fields will be included.</p>
354     *
355     * @param lhs  {@code this} object
356     * @param rhs  the other object
357     * @param testTransients  whether to include transient fields
358     * @return {@code true} if the two Objects have tested equals.
359     *
360     * @see EqualsExclude
361     */
362    public static boolean reflectionEquals(final Object lhs, final Object rhs, final boolean testTransients) {
363        return reflectionEquals(lhs, rhs, testTransients, null);
364    }
365
366    /**
367     * This method uses reflection to determine if the two {@link Object}s
368     * are equal.
369     *
370     * <p>It uses {@code AccessibleObject.setAccessible} to gain access to private
371     * fields. This means that it will throw a security exception if run under
372     * a security manager, if the permissions are not set up correctly. It is also
373     * not as efficient as testing explicitly. Non-primitive fields are compared using
374     * {@code equals()}.</p>
375     *
376     * <p>If the testTransients parameter is set to {@code true}, transient
377     * members will be tested, otherwise they are ignored, as they are likely
378     * derived fields, and not part of the value of the {@link Object}.</p>
379     *
380     * <p>Static fields will not be included. Superclass fields will be appended
381     * up to and including the specified superclass. A null superclass is treated
382     * as java.lang.Object.</p>
383     *
384     * @param lhs  {@code this} object
385     * @param rhs  the other object
386     * @param testTransients  whether to include transient fields
387     * @param reflectUpToClass  the superclass to reflect up to (inclusive),
388     *  may be {@code null}
389     * @param excludeFields  array of field names to exclude from testing
390     * @return {@code true} if the two Objects have tested equals.
391     *
392     * @see EqualsExclude
393     * @since 2.0
394     */
395    public static boolean reflectionEquals(final Object lhs, final Object rhs, final boolean testTransients, final Class<?> reflectUpToClass,
396            final String... excludeFields) {
397        return reflectionEquals(lhs, rhs, testTransients, reflectUpToClass, false, excludeFields);
398    }
399
400    /**
401     * This method uses reflection to determine if the two {@link Object}s
402     * are equal.
403     *
404     * <p>It uses {@code AccessibleObject.setAccessible} to gain access to private
405     * fields. This means that it will throw a security exception if run under
406     * a security manager, if the permissions are not set up correctly. It is also
407     * not as efficient as testing explicitly. Non-primitive fields are compared using
408     * {@code equals()}.</p>
409     *
410     * <p>If the testTransients parameter is set to {@code true}, transient
411     * members will be tested, otherwise they are ignored, as they are likely
412     * derived fields, and not part of the value of the {@link Object}.</p>
413     *
414     * <p>Static fields will not be included. Superclass fields will be appended
415     * up to and including the specified superclass. A null superclass is treated
416     * as java.lang.Object.</p>
417     *
418     * <p>If the testRecursive parameter is set to {@code true}, non primitive
419     * (and non primitive wrapper) field types will be compared by
420     * {@link EqualsBuilder} recursively instead of invoking their
421     * {@code equals()} method. Leading to a deep reflection equals test.
422     *
423     * @param lhs  {@code this} object
424     * @param rhs  the other object
425     * @param testTransients  whether to include transient fields
426     * @param reflectUpToClass  the superclass to reflect up to (inclusive),
427     *  may be {@code null}
428     * @param testRecursive  whether to call reflection equals on non-primitive
429     *  fields recursively.
430     * @param excludeFields  array of field names to exclude from testing
431     * @return {@code true} if the two Objects have tested equals.
432     *
433     * @see EqualsExclude
434     * @since 3.6
435     */
436    public static boolean reflectionEquals(final Object lhs, final Object rhs, final boolean testTransients, final Class<?> reflectUpToClass,
437            final boolean testRecursive, final String... excludeFields) {
438        if (lhs == rhs) {
439            return true;
440        }
441        if (lhs == null || rhs == null) {
442            return false;
443        }
444        return new EqualsBuilder()
445                    .setExcludeFields(excludeFields)
446                    .setReflectUpToClass(reflectUpToClass)
447                    .setTestTransients(testTransients)
448                    .setTestRecursive(testRecursive)
449                    .reflectionAppend(lhs, rhs)
450                    .isEquals();
451    }
452
453    /**
454     * Tests if two {@code objects} by using reflection.
455     *
456     * <p>It uses {@code AccessibleObject.setAccessible} to gain access to private
457     * fields. This means that it will throw a security exception if run under
458     * a security manager, if the permissions are not set up correctly. It is also
459     * not as efficient as testing explicitly. Non-primitive fields are compared using
460     * {@code equals()}.</p>
461     *
462     * <p>If the testTransients field is set to {@code true}, transient
463     * members will be tested, otherwise they are ignored, as they are likely
464     * derived fields, and not part of the value of the {@link Object}.</p>
465     *
466     * <p>Static fields will not be included. Superclass fields will be appended
467     * up to and including the specified superclass in field {@code reflectUpToClass}.
468     * A null superclass is treated as java.lang.Object.</p>
469     *
470     * <p>Field names listed in field {@code excludeFields} will be ignored.</p>
471     *
472     * <p>If either class of the compared objects is contained in
473     * {@code bypassReflectionClasses}, both objects are compared by calling
474     * the equals method of the left-hand object with the right-hand object as an argument.</p>
475     *
476     * @param lhs  the left-hand object
477     * @param rhs  the right-hand object
478     * @return this
479     */
480    public EqualsBuilder reflectionAppend(final Object lhs, final Object rhs) {
481        if (!isEquals) {
482            return this;
483        }
484        if (lhs == rhs) {
485            return this;
486        }
487        if (lhs == null || rhs == null) {
488            isEquals = false;
489            return this;
490        }
491
492        // Find the leaf class since there may be transients in the leaf
493        // class or in classes between the leaf and root.
494        // If we are not testing transients or a subclass has no ivars,
495        // then a subclass can test equals to a superclass.
496        final Class<?> lhsClass = lhs.getClass();
497        final Class<?> rhsClass = rhs.getClass();
498        Class<?> testClass;
499        if (lhsClass.isInstance(rhs)) {
500            testClass = lhsClass;
501            if (!rhsClass.isInstance(lhs)) {
502                // rhsClass is a subclass of lhsClass
503                testClass = rhsClass;
504            }
505        } else if (rhsClass.isInstance(lhs)) {
506            testClass = rhsClass;
507            if (!lhsClass.isInstance(rhs)) {
508                // lhsClass is a subclass of rhsClass
509                testClass = lhsClass;
510            }
511        } else {
512            // The two classes are not related.
513            isEquals = false;
514            return this;
515        }
516
517        try {
518            if (testClass.isArray()) {
519                append(lhs, rhs);
520            } else //If either class is being excluded, call normal object equals method on lhsClass.
521            if (bypassReflectionClasses != null
522                    && (bypassReflectionClasses.contains(lhsClass) || bypassReflectionClasses.contains(rhsClass))) {
523                isEquals = lhs.equals(rhs);
524            } else {
525                reflectionAppend(lhs, rhs, testClass);
526                while (testClass.getSuperclass() != null && testClass != reflectUpToClass) {
527                    testClass = testClass.getSuperclass();
528                    reflectionAppend(lhs, rhs, testClass);
529                }
530            }
531        } catch (final IllegalArgumentException e) {
532            // In this case, we tried to test a subclass vs. a superclass and
533            // the subclass has ivars or the ivars are transient and
534            // we are testing transients.
535            // If a subclass has ivars that we are trying to test them, we get an
536            // exception and we know that the objects are not equal.
537            isEquals = false;
538        }
539        return this;
540    }
541
542    /**
543     * Appends the fields and values defined by the given object of the
544     * given Class.
545     *
546     * @param lhs  the left-hand object
547     * @param rhs  the right-hand object
548     * @param clazz  the class to append details of
549     */
550    private void reflectionAppend(
551        final Object lhs,
552        final Object rhs,
553        final Class<?> clazz) {
554
555        if (isRegistered(lhs, rhs)) {
556            return;
557        }
558
559        try {
560            register(lhs, rhs);
561            final Field[] fields = clazz.getDeclaredFields();
562            AccessibleObject.setAccessible(fields, true);
563            for (int i = 0; i < fields.length && isEquals; i++) {
564                final Field field = fields[i];
565                if (!ArrayUtils.contains(excludeFields, field.getName())
566                    && !field.getName().contains("$")
567                    && (testTransients || !Modifier.isTransient(field.getModifiers()))
568                    && !Modifier.isStatic(field.getModifiers())
569                    && !field.isAnnotationPresent(EqualsExclude.class)) {
570                    append(Reflection.getUnchecked(field, lhs), Reflection.getUnchecked(field, rhs));
571                }
572            }
573        } finally {
574            unregister(lhs, rhs);
575        }
576    }
577
578    /**
579     * Adds the result of {@code super.equals()} to this builder.
580     *
581     * @param superEquals  the result of calling {@code super.equals()}
582     * @return this
583     * @since 2.0
584     */
585    public EqualsBuilder appendSuper(final boolean superEquals) {
586        if (!isEquals) {
587            return this;
588        }
589        isEquals = superEquals;
590        return this;
591    }
592
593    /**
594     * Test if two {@link Object}s are equal using either
595     * #{@link #reflectionAppend(Object, Object)}, if object are non
596     * primitives (or wrapper of primitives) or if field {@code testRecursive}
597     * is set to {@code false}. Otherwise, using their
598     * {@code equals} method.
599     *
600     * @param lhs  the left-hand object
601     * @param rhs  the right-hand object
602     * @return this
603     */
604    public EqualsBuilder append(final Object lhs, final Object rhs) {
605        if (!isEquals) {
606            return this;
607        }
608        if (lhs == rhs) {
609            return this;
610        }
611        if (lhs == null || rhs == null) {
612            this.setEquals(false);
613            return this;
614        }
615        final Class<?> lhsClass = lhs.getClass();
616        if (lhsClass.isArray()) {
617            // factor out array case in order to keep method small enough
618            // to be inlined
619            appendArray(lhs, rhs);
620        } else // The simple case, not an array, just test the element
621        if (testRecursive && !ClassUtils.isPrimitiveOrWrapper(lhsClass)) {
622            reflectionAppend(lhs, rhs);
623        } else {
624            isEquals = lhs.equals(rhs);
625        }
626        return this;
627    }
628
629    /**
630     * Test if an {@link Object} is equal to an array.
631     *
632     * @param lhs  the left-hand object, an array
633     * @param rhs  the right-hand object
634     */
635    private void appendArray(final Object lhs, final Object rhs) {
636        // First we compare different dimensions, for example: a boolean[][] to a boolean[]
637        // then we 'Switch' on type of array, to dispatch to the correct handler
638        // This handles multidimensional arrays of the same depth
639        if (lhs.getClass() != rhs.getClass()) {
640            this.setEquals(false);
641        } else if (lhs instanceof long[]) {
642            append((long[]) lhs, (long[]) rhs);
643        } else if (lhs instanceof int[]) {
644            append((int[]) lhs, (int[]) rhs);
645        } else if (lhs instanceof short[]) {
646            append((short[]) lhs, (short[]) rhs);
647        } else if (lhs instanceof char[]) {
648            append((char[]) lhs, (char[]) rhs);
649        } else if (lhs instanceof byte[]) {
650            append((byte[]) lhs, (byte[]) rhs);
651        } else if (lhs instanceof double[]) {
652            append((double[]) lhs, (double[]) rhs);
653        } else if (lhs instanceof float[]) {
654            append((float[]) lhs, (float[]) rhs);
655        } else if (lhs instanceof boolean[]) {
656            append((boolean[]) lhs, (boolean[]) rhs);
657        } else {
658            // Not an array of primitives
659            append((Object[]) lhs, (Object[]) rhs);
660        }
661    }
662
663    /**
664     * Test if two {@code long} s are equal.
665     *
666     * @param lhs
667     *                  the left-hand {@code long}
668     * @param rhs
669     *                  the right-hand {@code long}
670     * @return this
671     */
672    public EqualsBuilder append(final long lhs, final long rhs) {
673        if (!isEquals) {
674            return this;
675        }
676        isEquals = lhs == rhs;
677        return this;
678    }
679
680    /**
681     * Test if two {@code int}s are equal.
682     *
683     * @param lhs  the left-hand {@code int}
684     * @param rhs  the right-hand {@code int}
685     * @return this
686     */
687    public EqualsBuilder append(final int lhs, final int rhs) {
688        if (!isEquals) {
689            return this;
690        }
691        isEquals = lhs == rhs;
692        return this;
693    }
694
695    /**
696     * Test if two {@code short}s are equal.
697     *
698     * @param lhs  the left-hand {@code short}
699     * @param rhs  the right-hand {@code short}
700     * @return this
701     */
702    public EqualsBuilder append(final short lhs, final short rhs) {
703        if (!isEquals) {
704            return this;
705        }
706        isEquals = lhs == rhs;
707        return this;
708    }
709
710    /**
711     * Test if two {@code char}s are equal.
712     *
713     * @param lhs  the left-hand {@code char}
714     * @param rhs  the right-hand {@code char}
715     * @return this
716     */
717    public EqualsBuilder append(final char lhs, final char rhs) {
718        if (!isEquals) {
719            return this;
720        }
721        isEquals = lhs == rhs;
722        return this;
723    }
724
725    /**
726     * Test if two {@code byte}s are equal.
727     *
728     * @param lhs  the left-hand {@code byte}
729     * @param rhs  the right-hand {@code byte}
730     * @return this
731     */
732    public EqualsBuilder append(final byte lhs, final byte rhs) {
733        if (!isEquals) {
734            return this;
735        }
736        isEquals = lhs == rhs;
737        return this;
738    }
739
740    /**
741     * Test if two {@code double}s are equal by testing that the
742     * pattern of bits returned by {@code doubleToLong} are equal.
743     *
744     * <p>This handles NaNs, Infinities, and {@code -0.0}.</p>
745     *
746     * <p>It is compatible with the hash code generated by
747     * {@link HashCodeBuilder}.</p>
748     *
749     * @param lhs  the left-hand {@code double}
750     * @param rhs  the right-hand {@code double}
751     * @return this
752     */
753    public EqualsBuilder append(final double lhs, final double rhs) {
754        if (!isEquals) {
755            return this;
756        }
757        return append(Double.doubleToLongBits(lhs), Double.doubleToLongBits(rhs));
758    }
759
760    /**
761     * Test if two {@code float}s are equal by testing that the
762     * pattern of bits returned by doubleToLong are equal.
763     *
764     * <p>This handles NaNs, Infinities, and {@code -0.0}.</p>
765     *
766     * <p>It is compatible with the hash code generated by
767     * {@link HashCodeBuilder}.</p>
768     *
769     * @param lhs  the left-hand {@code float}
770     * @param rhs  the right-hand {@code float}
771     * @return this
772     */
773    public EqualsBuilder append(final float lhs, final float rhs) {
774        if (!isEquals) {
775            return this;
776        }
777        return append(Float.floatToIntBits(lhs), Float.floatToIntBits(rhs));
778    }
779
780    /**
781     * Test if two {@code booleans}s are equal.
782     *
783     * @param lhs  the left-hand {@code boolean}
784     * @param rhs  the right-hand {@code boolean}
785     * @return this
786      */
787    public EqualsBuilder append(final boolean lhs, final boolean rhs) {
788        if (!isEquals) {
789            return this;
790        }
791        isEquals = lhs == rhs;
792        return this;
793    }
794
795    /**
796     * Performs a deep comparison of two {@link Object} arrays.
797     *
798     * <p>This also will be called for the top level of
799     * multi-dimensional, ragged, and multi-typed arrays.</p>
800     *
801     * <p>Note that this method does not compare the type of the arrays; it only
802     * compares the contents.</p>
803     *
804     * @param lhs  the left-hand {@code Object[]}
805     * @param rhs  the right-hand {@code Object[]}
806     * @return this
807     */
808    public EqualsBuilder append(final Object[] lhs, final Object[] rhs) {
809        if (!isEquals) {
810            return this;
811        }
812        if (lhs == rhs) {
813            return this;
814        }
815        if (lhs == null || rhs == null) {
816            this.setEquals(false);
817            return this;
818        }
819        if (lhs.length != rhs.length) {
820            this.setEquals(false);
821            return this;
822        }
823        for (int i = 0; i < lhs.length && isEquals; ++i) {
824            append(lhs[i], rhs[i]);
825        }
826        return this;
827    }
828
829    /**
830     * Deep comparison of array of {@code long}. Length and all
831     * values are compared.
832     *
833     * <p>The method {@link #append(long, long)} is used.</p>
834     *
835     * @param lhs  the left-hand {@code long[]}
836     * @param rhs  the right-hand {@code long[]}
837     * @return this
838     */
839    public EqualsBuilder append(final long[] lhs, final long[] rhs) {
840        if (!isEquals) {
841            return this;
842        }
843        if (lhs == rhs) {
844            return this;
845        }
846        if (lhs == null || rhs == null) {
847            this.setEquals(false);
848            return this;
849        }
850        if (lhs.length != rhs.length) {
851            this.setEquals(false);
852            return this;
853        }
854        for (int i = 0; i < lhs.length && isEquals; ++i) {
855            append(lhs[i], rhs[i]);
856        }
857        return this;
858    }
859
860    /**
861     * Deep comparison of array of {@code int}. Length and all
862     * values are compared.
863     *
864     * <p>The method {@link #append(int, int)} is used.</p>
865     *
866     * @param lhs  the left-hand {@code int[]}
867     * @param rhs  the right-hand {@code int[]}
868     * @return this
869     */
870    public EqualsBuilder append(final int[] lhs, final int[] rhs) {
871        if (!isEquals) {
872            return this;
873        }
874        if (lhs == rhs) {
875            return this;
876        }
877        if (lhs == null || rhs == null) {
878            this.setEquals(false);
879            return this;
880        }
881        if (lhs.length != rhs.length) {
882            this.setEquals(false);
883            return this;
884        }
885        for (int i = 0; i < lhs.length && isEquals; ++i) {
886            append(lhs[i], rhs[i]);
887        }
888        return this;
889    }
890
891    /**
892     * Deep comparison of array of {@code short}. Length and all
893     * values are compared.
894     *
895     * <p>The method {@link #append(short, short)} is used.</p>
896     *
897     * @param lhs  the left-hand {@code short[]}
898     * @param rhs  the right-hand {@code short[]}
899     * @return this
900     */
901    public EqualsBuilder append(final short[] lhs, final short[] rhs) {
902        if (!isEquals) {
903            return this;
904        }
905        if (lhs == rhs) {
906            return this;
907        }
908        if (lhs == null || rhs == null) {
909            this.setEquals(false);
910            return this;
911        }
912        if (lhs.length != rhs.length) {
913            this.setEquals(false);
914            return this;
915        }
916        for (int i = 0; i < lhs.length && isEquals; ++i) {
917            append(lhs[i], rhs[i]);
918        }
919        return this;
920    }
921
922    /**
923     * Deep comparison of array of {@code char}. Length and all
924     * values are compared.
925     *
926     * <p>The method {@link #append(char, char)} is used.</p>
927     *
928     * @param lhs  the left-hand {@code char[]}
929     * @param rhs  the right-hand {@code char[]}
930     * @return this
931     */
932    public EqualsBuilder append(final char[] lhs, final char[] rhs) {
933        if (!isEquals) {
934            return this;
935        }
936        if (lhs == rhs) {
937            return this;
938        }
939        if (lhs == null || rhs == null) {
940            this.setEquals(false);
941            return this;
942        }
943        if (lhs.length != rhs.length) {
944            this.setEquals(false);
945            return this;
946        }
947        for (int i = 0; i < lhs.length && isEquals; ++i) {
948            append(lhs[i], rhs[i]);
949        }
950        return this;
951    }
952
953    /**
954     * Deep comparison of array of {@code byte}. Length and all
955     * values are compared.
956     *
957     * <p>The method {@link #append(byte, byte)} is used.</p>
958     *
959     * @param lhs  the left-hand {@code byte[]}
960     * @param rhs  the right-hand {@code byte[]}
961     * @return this
962     */
963    public EqualsBuilder append(final byte[] lhs, final byte[] rhs) {
964        if (!isEquals) {
965            return this;
966        }
967        if (lhs == rhs) {
968            return this;
969        }
970        if (lhs == null || rhs == null) {
971            this.setEquals(false);
972            return this;
973        }
974        if (lhs.length != rhs.length) {
975            this.setEquals(false);
976            return this;
977        }
978        for (int i = 0; i < lhs.length && isEquals; ++i) {
979            append(lhs[i], rhs[i]);
980        }
981        return this;
982    }
983
984    /**
985     * Deep comparison of array of {@code double}. Length and all
986     * values are compared.
987     *
988     * <p>The method {@link #append(double, double)} is used.</p>
989     *
990     * @param lhs  the left-hand {@code double[]}
991     * @param rhs  the right-hand {@code double[]}
992     * @return this
993     */
994    public EqualsBuilder append(final double[] lhs, final double[] rhs) {
995        if (!isEquals) {
996            return this;
997        }
998        if (lhs == rhs) {
999            return this;
1000        }
1001        if (lhs == null || rhs == null) {
1002            this.setEquals(false);
1003            return this;
1004        }
1005        if (lhs.length != rhs.length) {
1006            this.setEquals(false);
1007            return this;
1008        }
1009        for (int i = 0; i < lhs.length && isEquals; ++i) {
1010            append(lhs[i], rhs[i]);
1011        }
1012        return this;
1013    }
1014
1015    /**
1016     * Deep comparison of array of {@code float}. Length and all
1017     * values are compared.
1018     *
1019     * <p>The method {@link #append(float, float)} is used.</p>
1020     *
1021     * @param lhs  the left-hand {@code float[]}
1022     * @param rhs  the right-hand {@code float[]}
1023     * @return this
1024     */
1025    public EqualsBuilder append(final float[] lhs, final float[] rhs) {
1026        if (!isEquals) {
1027            return this;
1028        }
1029        if (lhs == rhs) {
1030            return this;
1031        }
1032        if (lhs == null || rhs == null) {
1033            this.setEquals(false);
1034            return this;
1035        }
1036        if (lhs.length != rhs.length) {
1037            this.setEquals(false);
1038            return this;
1039        }
1040        for (int i = 0; i < lhs.length && isEquals; ++i) {
1041            append(lhs[i], rhs[i]);
1042        }
1043        return this;
1044    }
1045
1046    /**
1047     * Deep comparison of array of {@code boolean}. Length and all
1048     * values are compared.
1049     *
1050     * <p>The method {@link #append(boolean, boolean)} is used.</p>
1051     *
1052     * @param lhs  the left-hand {@code boolean[]}
1053     * @param rhs  the right-hand {@code boolean[]}
1054     * @return this
1055     */
1056    public EqualsBuilder append(final boolean[] lhs, final boolean[] rhs) {
1057        if (!isEquals) {
1058            return this;
1059        }
1060        if (lhs == rhs) {
1061            return this;
1062        }
1063        if (lhs == null || rhs == null) {
1064            this.setEquals(false);
1065            return this;
1066        }
1067        if (lhs.length != rhs.length) {
1068            this.setEquals(false);
1069            return this;
1070        }
1071        for (int i = 0; i < lhs.length && isEquals; ++i) {
1072            append(lhs[i], rhs[i]);
1073        }
1074        return this;
1075    }
1076
1077    /**
1078     * Returns {@code true} if the fields that have been checked
1079     * are all equal.
1080     *
1081     * @return boolean
1082     */
1083    public boolean isEquals() {
1084        return this.isEquals;
1085    }
1086
1087    /**
1088     * Returns {@code true} if the fields that have been checked
1089     * are all equal.
1090     *
1091     * @return {@code true} if all of the fields that have been checked
1092     *         are equal, {@code false} otherwise.
1093     *
1094     * @since 3.0
1095     */
1096    @Override
1097    public Boolean build() {
1098        return Boolean.valueOf(isEquals());
1099    }
1100
1101    /**
1102     * Sets the {@code isEquals} value.
1103     *
1104     * @param isEquals The value to set.
1105     * @since 2.1
1106     */
1107    protected void setEquals(final boolean isEquals) {
1108        this.isEquals = isEquals;
1109    }
1110
1111    /**
1112     * Reset the EqualsBuilder so you can use the same object again
1113     * @since 2.5
1114     */
1115    public void reset() {
1116        this.isEquals = true;
1117    }
1118}