All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.mockito.internal.matchers.apachecommons.EqualsBuilder Maven / Gradle / Ivy

There is a newer version: 2.0.2-beta
Show newest version
/*
 * Copyright (c) 2007 Mockito contributors
 * This program is made available under the terms of the MIT License.
 */

//Class comes from Apache Commons Lang, added some tiny changes  

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.mockito.internal.matchers.apachecommons;

import java.lang.reflect.AccessibleObject;
import java.lang.reflect.Field;
import java.lang.reflect.Modifier;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;

/**
 * 

Assists in implementing {@link Object#equals(Object)} methods.

* *

This class provides methods to build a good equals method for any * class. It follows rules laid out in * Effective Java * , by Joshua Bloch. In particular the rule for comparing doubles, * floats, and arrays can be tricky. Also, making sure that * equals() and hashCode() are consistent can be * difficult.

* *

Two Objects that compare as equals must generate the same hash code, * but two Objects with the same hash code do not have to be equal.

* *

All relevant fields should be included in the calculation of equals. * Derived fields may be ignored. In particular, any field used in * generating a hash code must be used in the equals method, and vice * versa.

* *

Typical use for the code is as follows:

*
 * public boolean equals(Object obj) {
 *   if (obj == null) { return false; }
 *   if (obj == this) { return true; }
 *   if (obj.getClass() != getClass()) {
 *     return false;
 *   }
 *   MyClass rhs = (MyClass) obj;
 *   return new EqualsBuilder()
 *                 .appendSuper(super.equals(obj))
 *                 .append(field1, rhs.field1)
 *                 .append(field2, rhs.field2)
 *                 .append(field3, rhs.field3)
 *                 .isEquals();
 *  }
 * 
* *

Alternatively, there is a method that uses reflection to determine * the fields to test. Because these fields are usually private, the method, * reflectionEquals, uses AccessibleObject.setAccessible to * change the visibility of the fields. This will fail under a security * manager, unless the appropriate permissions are set up correctly. It is * also slower than testing explicitly.

* *

A typical invocation for this method would look like:

*
 * public boolean equals(Object obj) {
 *   return EqualsBuilder.reflectionEquals(this, obj);
 * }
 * 
* * @author Steve Downey * @author Stephen Colebourne * @author Gary Gregory * @author Pete Gieser * @author Arun Mammen Thomas * @since 1.0 * @version $Id: EqualsBuilder.java 611543 2008-01-13 07:00:22Z bayard $ */ @SuppressWarnings("unchecked") class EqualsBuilder { /** * If the fields tested are equals. * The default value is true. */ private boolean isEquals = true; /** *

Constructor for EqualsBuilder.

* *

Starts off assuming that equals is true.

* @see Object#equals(Object) */ public EqualsBuilder() { // do nothing for now. } //------------------------------------------------------------------------- /** *

This method uses reflection to determine if the two Objects * are equal.

* *

It uses AccessibleObject.setAccessible to gain access to private * fields. This means that it will throw a security exception if run under * a security manager, if the permissions are not set up correctly. It is also * not as efficient as testing explicitly.

* *

Transient members will be not be tested, as they are likely derived * fields, and not part of the value of the Object.

* *

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

* * @param lhs this object * @param rhs the other object * @return true if the two Objects have tested equals. */ public static boolean reflectionEquals(Object lhs, Object rhs) { return reflectionEquals(lhs, rhs, false, null, null); } /** *

This method uses reflection to determine if the two Objects * are equal.

* *

It uses AccessibleObject.setAccessible to gain access to private * fields. This means that it will throw a security exception if run under * a security manager, if the permissions are not set up correctly. It is also * not as efficient as testing explicitly.

* *

Transient members will be not be tested, as they are likely derived * fields, and not part of the value of the Object.

* *

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

* * @param lhs this object * @param rhs the other object * @param excludeFields array of field names to exclude from testing * @return true if the two Objects have tested equals. */ public static boolean reflectionEquals(Object lhs, Object rhs, String[] excludeFields) { return reflectionEquals(lhs, rhs, false, null, excludeFields); } /** *

This method uses reflection to determine if the two Objects * are equal.

* *

It uses AccessibleObject.setAccessible to gain access to private * fields. This means that it will throw a security exception if run under * a security manager, if the permissions are not set up correctly. It is also * not as efficient as testing explicitly.

* *

If the TestTransients parameter is set to true, transient * members will be tested, otherwise they are ignored, as they are likely * derived fields, and not part of the value of the Object.

* *

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

* * @param lhs this object * @param rhs the other object * @param testTransients whether to include transient fields * @return true if the two Objects have tested equals. */ public static boolean reflectionEquals(Object lhs, Object rhs, boolean testTransients) { return reflectionEquals(lhs, rhs, testTransients, null, null); } /** *

This method uses reflection to determine if the two Objects * are equal.

* *

It uses AccessibleObject.setAccessible to gain access to private * fields. This means that it will throw a security exception if run under * a security manager, if the permissions are not set up correctly. It is also * not as efficient as testing explicitly.

* *

If the testTransients parameter is set to true, transient * members will be tested, otherwise they are ignored, as they are likely * derived fields, and not part of the value of the Object.

* *

Static fields will not be included. Superclass fields will be appended * up to and including the specified superclass. A null superclass is treated * as java.lang.Object.

* * @param lhs this object * @param rhs the other object * @param testTransients whether to include transient fields * @param reflectUpToClass the superclass to reflect up to (inclusive), * may be null * @return true if the two Objects have tested equals. * @since 2.0 */ public static boolean reflectionEquals(Object lhs, Object rhs, boolean testTransients, Class reflectUpToClass) { return reflectionEquals(lhs, rhs, testTransients, reflectUpToClass, null); } /** *

This method uses reflection to determine if the two Objects * are equal.

* *

It uses AccessibleObject.setAccessible to gain access to private * fields. This means that it will throw a security exception if run under * a security manager, if the permissions are not set up correctly. It is also * not as efficient as testing explicitly.

* *

If the testTransients parameter is set to true, transient * members will be tested, otherwise they are ignored, as they are likely * derived fields, and not part of the value of the Object.

* *

Static fields will not be included. Superclass fields will be appended * up to and including the specified superclass. A null superclass is treated * as java.lang.Object.

* * @param lhs this object * @param rhs the other object * @param testTransients whether to include transient fields * @param reflectUpToClass the superclass to reflect up to (inclusive), * may be null * @param excludeFields array of field names to exclude from testing * @return true if the two Objects have tested equals. * @since 2.0 */ public static boolean reflectionEquals(Object lhs, Object rhs, boolean testTransients, Class reflectUpToClass, String[] excludeFields) { if (lhs == rhs) { return true; } if (lhs == null || rhs == null) { return false; } // Find the leaf class since there may be transients in the leaf // class or in classes between the leaf and root. // If we are not testing transients or a subclass has no ivars, // then a subclass can test equals to a superclass. Class lhsClass = lhs.getClass(); Class rhsClass = rhs.getClass(); Class testClass; if (lhsClass.isInstance(rhs)) { testClass = lhsClass; if (!rhsClass.isInstance(lhs)) { // rhsClass is a subclass of lhsClass testClass = rhsClass; } } else if (rhsClass.isInstance(lhs)) { testClass = rhsClass; if (!lhsClass.isInstance(rhs)) { // lhsClass is a subclass of rhsClass testClass = lhsClass; } } else { // The two classes are not related. return false; } EqualsBuilder equalsBuilder = new EqualsBuilder(); try { reflectionAppend(lhs, rhs, testClass, equalsBuilder, testTransients, excludeFields); while (testClass.getSuperclass() != null && testClass != reflectUpToClass) { testClass = testClass.getSuperclass(); reflectionAppend(lhs, rhs, testClass, equalsBuilder, testTransients, excludeFields); } } catch (IllegalArgumentException e) { // In this case, we tried to test a subclass vs. a superclass and // the subclass has ivars or the ivars are transient and // we are testing transients. // If a subclass has ivars that we are trying to test them, we get an // exception and we know that the objects are not equal. return false; } return equalsBuilder.isEquals(); } /** *

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

* * @param lhs the left hand object * @param rhs the right hand object * @param clazz the class to append details of * @param builder the builder to append to * @param useTransients whether to test transient fields * @param excludeFields array of field names to exclude from testing */ private static void reflectionAppend( Object lhs, Object rhs, Class clazz, EqualsBuilder builder, boolean useTransients, String[] excludeFields) { Field[] fields = clazz.getDeclaredFields(); List excludedFieldList = excludeFields != null ? Arrays.asList(excludeFields) : Collections.EMPTY_LIST; AccessibleObject.setAccessible(fields, true); for (int i = 0; i < fields.length && builder.isEquals; i++) { Field f = fields[i]; if (!excludedFieldList.contains(f.getName()) && (f.getName().indexOf('$') == -1) && (useTransients || !Modifier.isTransient(f.getModifiers())) && (!Modifier.isStatic(f.getModifiers()))) { try { builder.append(f.get(lhs), f.get(rhs)); } catch (IllegalAccessException e) { //this can't happen. Would get a Security exception instead //throw a runtime exception in case the impossible happens. throw new InternalError("Unexpected IllegalAccessException"); } } } } //------------------------------------------------------------------------- /** *

Adds the result of super.equals() to this builder.

* * @param superEquals the result of calling super.equals() * @return EqualsBuilder - used to chain calls. * @since 2.0 */ public EqualsBuilder appendSuper(boolean superEquals) { if (isEquals == false) { return this; } isEquals = superEquals; return this; } //------------------------------------------------------------------------- /** *

Test if two Objects are equal using their * equals method.

* * @param lhs the left hand object * @param rhs the right hand object * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(Object lhs, Object rhs) { if (isEquals == false) { return this; } if (lhs == rhs) { return this; } if (lhs == null || rhs == null) { this.setEquals(false); return this; } Class lhsClass = lhs.getClass(); if (!lhsClass.isArray()) { if (lhs instanceof java.math.BigDecimal && rhs instanceof java.math.BigDecimal) { isEquals = (((java.math.BigDecimal) lhs).compareTo((java.math.BigDecimal) rhs) == 0); } else { // The simple case, not an array, just test the element isEquals = lhs.equals(rhs); } } else if (lhs.getClass() != rhs.getClass()) { // Here when we compare different dimensions, for example: a boolean[][] to a boolean[] this.setEquals(false); // 'Switch' on type of array, to dispatch to the correct handler // This handles multi dimensional arrays of the same depth } else if (lhs instanceof long[]) { append((long[]) lhs, (long[]) rhs); } else if (lhs instanceof int[]) { append((int[]) lhs, (int[]) rhs); } else if (lhs instanceof short[]) { append((short[]) lhs, (short[]) rhs); } else if (lhs instanceof char[]) { append((char[]) lhs, (char[]) rhs); } else if (lhs instanceof byte[]) { append((byte[]) lhs, (byte[]) rhs); } else if (lhs instanceof double[]) { append((double[]) lhs, (double[]) rhs); } else if (lhs instanceof float[]) { append((float[]) lhs, (float[]) rhs); } else if (lhs instanceof boolean[]) { append((boolean[]) lhs, (boolean[]) rhs); } else { // Not an array of primitives append((Object[]) lhs, (Object[]) rhs); } return this; } /** *

* Test if two long s are equal. *

* * @param lhs * the left hand long * @param rhs * the right hand long * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(long lhs, long rhs) { if (isEquals == false) { return this; } isEquals = (lhs == rhs); return this; } /** *

Test if two ints are equal.

* * @param lhs the left hand int * @param rhs the right hand int * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(int lhs, int rhs) { if (isEquals == false) { return this; } isEquals = (lhs == rhs); return this; } /** *

Test if two shorts are equal.

* * @param lhs the left hand short * @param rhs the right hand short * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(short lhs, short rhs) { if (isEquals == false) { return this; } isEquals = (lhs == rhs); return this; } /** *

Test if two chars are equal.

* * @param lhs the left hand char * @param rhs the right hand char * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(char lhs, char rhs) { if (isEquals == false) { return this; } isEquals = (lhs == rhs); return this; } /** *

Test if two bytes are equal.

* * @param lhs the left hand byte * @param rhs the right hand byte * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(byte lhs, byte rhs) { if (isEquals == false) { return this; } isEquals = (lhs == rhs); return this; } /** *

Test if two doubles are equal by testing that the * pattern of bits returned by doubleToLong are equal.

* *

This handles NaNs, Infinities, and -0.0.

* *

It is compatible with the hash code generated by * HashCodeBuilder.

* * @param lhs the left hand double * @param rhs the right hand double * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(double lhs, double rhs) { if (isEquals == false) { return this; } return append(Double.doubleToLongBits(lhs), Double.doubleToLongBits(rhs)); } /** *

Test if two floats are equal byt testing that the * pattern of bits returned by doubleToLong are equal.

* *

This handles NaNs, Infinities, and -0.0.

* *

It is compatible with the hash code generated by * HashCodeBuilder.

* * @param lhs the left hand float * @param rhs the right hand float * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(float lhs, float rhs) { if (isEquals == false) { return this; } return append(Float.floatToIntBits(lhs), Float.floatToIntBits(rhs)); } /** *

Test if two booleanss are equal.

* * @param lhs the left hand boolean * @param rhs the right hand boolean * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(boolean lhs, boolean rhs) { if (isEquals == false) { return this; } isEquals = (lhs == rhs); return this; } /** *

Performs a deep comparison of two Object arrays.

* *

This also will be called for the top level of * multi-dimensional, ragged, and multi-typed arrays.

* * @param lhs the left hand Object[] * @param rhs the right hand Object[] * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(Object[] lhs, Object[] rhs) { if (isEquals == false) { return this; } if (lhs == rhs) { return this; } if (lhs == null || rhs == null) { this.setEquals(false); return this; } if (lhs.length != rhs.length) { this.setEquals(false); return this; } for (int i = 0; i < lhs.length && isEquals; ++i) { append(lhs[i], rhs[i]); } return this; } /** *

Deep comparison of array of long. Length and all * values are compared.

* *

The method {@link #append(long, long)} is used.

* * @param lhs the left hand long[] * @param rhs the right hand long[] * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(long[] lhs, long[] rhs) { if (isEquals == false) { return this; } if (lhs == rhs) { return this; } if (lhs == null || rhs == null) { this.setEquals(false); return this; } if (lhs.length != rhs.length) { this.setEquals(false); return this; } for (int i = 0; i < lhs.length && isEquals; ++i) { append(lhs[i], rhs[i]); } return this; } /** *

Deep comparison of array of int. Length and all * values are compared.

* *

The method {@link #append(int, int)} is used.

* * @param lhs the left hand int[] * @param rhs the right hand int[] * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(int[] lhs, int[] rhs) { if (isEquals == false) { return this; } if (lhs == rhs) { return this; } if (lhs == null || rhs == null) { this.setEquals(false); return this; } if (lhs.length != rhs.length) { this.setEquals(false); return this; } for (int i = 0; i < lhs.length && isEquals; ++i) { append(lhs[i], rhs[i]); } return this; } /** *

Deep comparison of array of short. Length and all * values are compared.

* *

The method {@link #append(short, short)} is used.

* * @param lhs the left hand short[] * @param rhs the right hand short[] * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(short[] lhs, short[] rhs) { if (isEquals == false) { return this; } if (lhs == rhs) { return this; } if (lhs == null || rhs == null) { this.setEquals(false); return this; } if (lhs.length != rhs.length) { this.setEquals(false); return this; } for (int i = 0; i < lhs.length && isEquals; ++i) { append(lhs[i], rhs[i]); } return this; } /** *

Deep comparison of array of char. Length and all * values are compared.

* *

The method {@link #append(char, char)} is used.

* * @param lhs the left hand char[] * @param rhs the right hand char[] * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(char[] lhs, char[] rhs) { if (isEquals == false) { return this; } if (lhs == rhs) { return this; } if (lhs == null || rhs == null) { this.setEquals(false); return this; } if (lhs.length != rhs.length) { this.setEquals(false); return this; } for (int i = 0; i < lhs.length && isEquals; ++i) { append(lhs[i], rhs[i]); } return this; } /** *

Deep comparison of array of byte. Length and all * values are compared.

* *

The method {@link #append(byte, byte)} is used.

* * @param lhs the left hand byte[] * @param rhs the right hand byte[] * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(byte[] lhs, byte[] rhs) { if (isEquals == false) { return this; } if (lhs == rhs) { return this; } if (lhs == null || rhs == null) { this.setEquals(false); return this; } if (lhs.length != rhs.length) { this.setEquals(false); return this; } for (int i = 0; i < lhs.length && isEquals; ++i) { append(lhs[i], rhs[i]); } return this; } /** *

Deep comparison of array of double. Length and all * values are compared.

* *

The method {@link #append(double, double)} is used.

* * @param lhs the left hand double[] * @param rhs the right hand double[] * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(double[] lhs, double[] rhs) { if (isEquals == false) { return this; } if (lhs == rhs) { return this; } if (lhs == null || rhs == null) { this.setEquals(false); return this; } if (lhs.length != rhs.length) { this.setEquals(false); return this; } for (int i = 0; i < lhs.length && isEquals; ++i) { append(lhs[i], rhs[i]); } return this; } /** *

Deep comparison of array of float. Length and all * values are compared.

* *

The method {@link #append(float, float)} is used.

* * @param lhs the left hand float[] * @param rhs the right hand float[] * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(float[] lhs, float[] rhs) { if (isEquals == false) { return this; } if (lhs == rhs) { return this; } if (lhs == null || rhs == null) { this.setEquals(false); return this; } if (lhs.length != rhs.length) { this.setEquals(false); return this; } for (int i = 0; i < lhs.length && isEquals; ++i) { append(lhs[i], rhs[i]); } return this; } /** *

Deep comparison of array of boolean. Length and all * values are compared.

* *

The method {@link #append(boolean, boolean)} is used.

* * @param lhs the left hand boolean[] * @param rhs the right hand boolean[] * @return EqualsBuilder - used to chain calls. */ public EqualsBuilder append(boolean[] lhs, boolean[] rhs) { if (isEquals == false) { return this; } if (lhs == rhs) { return this; } if (lhs == null || rhs == null) { this.setEquals(false); return this; } if (lhs.length != rhs.length) { this.setEquals(false); return this; } for (int i = 0; i < lhs.length && isEquals; ++i) { append(lhs[i], rhs[i]); } return this; } /** *

Returns true if the fields that have been checked * are all equal.

* * @return boolean */ public boolean isEquals() { return this.isEquals; } /** * Sets the isEquals value. * * @param isEquals The value to set. * @since 2.1 */ protected void setEquals(boolean isEquals) { this.isEquals = isEquals; } }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy