1 /////////////////////////////////////////////////////////////////////////////////////////////// 2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules. 3 // Copyright (C) 2001-2024 the original author or authors. 4 // 5 // This library is free software; you can redistribute it and/or 6 // modify it under the terms of the GNU Lesser General Public 7 // License as published by the Free Software Foundation; either 8 // version 2.1 of the License, or (at your option) any later version. 9 // 10 // This library is distributed in the hope that it will be useful, 11 // but WITHOUT ANY WARRANTY; without even the implied warranty of 12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 // Lesser General Public License for more details. 14 // 15 // You should have received a copy of the GNU Lesser General Public 16 // License along with this library; if not, write to the Free Software 17 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 18 /////////////////////////////////////////////////////////////////////////////////////////////// 19 20 package com.puppycrawl.tools.checkstyle.checks.coding; 21 22 import java.util.HashSet; 23 import java.util.Set; 24 25 import com.puppycrawl.tools.checkstyle.FileStatefulCheck; 26 import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 27 import com.puppycrawl.tools.checkstyle.api.DetailAST; 28 import com.puppycrawl.tools.checkstyle.api.FullIdent; 29 import com.puppycrawl.tools.checkstyle.api.TokenTypes; 30 import com.puppycrawl.tools.checkstyle.utils.CheckUtil; 31 32 /** 33 * <p> 34 * Checks that classes and records which define a covariant {@code equals()} method 35 * also override method {@code equals(Object)}. 36 * </p> 37 * <p> 38 * Covariant {@code equals()} - method that is similar to {@code equals(Object)}, 39 * but with a covariant parameter type (any subtype of Object). 40 * </p> 41 * <p> 42 * <strong>Notice</strong>: the enums are also checked, 43 * even though they cannot override {@code equals(Object)}. 44 * The reason is to point out that implementing {@code equals()} in enums 45 * is considered an awful practice: it may cause having two different enum values 46 * that are equal using covariant enum method, and not equal when compared normally. 47 * </p> 48 * <p> 49 * Inspired by <a href="https://www.cs.jhu.edu/~daveho/pubs/oopsla2004.pdf"> 50 * Finding Bugs is Easy, chapter '4.5 Bad Covariant Definition of Equals (Eq)'</a>: 51 * </p> 52 * <p> 53 * Java classes and records may override the {@code equals(Object)} method to define 54 * a predicate for object equality. This method is used by many of the Java 55 * runtime library classes; for example, to implement generic containers. 56 * </p> 57 * <p> 58 * Programmers sometimes mistakenly use the type of their class {@code Foo} 59 * as the type of the parameter to {@code equals()}: 60 * </p> 61 * <pre> 62 * public boolean equals(Foo obj) {...} 63 * </pre> 64 * <p> 65 * This covariant version of {@code equals()} does not override the version in 66 * the {@code Object} class, and it may lead to unexpected behavior at runtime, 67 * especially if the class is used with one of the standard collection classes 68 * which expect that the standard {@code equals(Object)} method is overridden. 69 * </p> 70 * <p> 71 * This kind of bug is not obvious because it looks correct, and in circumstances 72 * where the class is accessed through the references of the class type (rather 73 * than a supertype), it will work correctly. However, the first time it is used 74 * in a container, the behavior might be mysterious. For these reasons, this type 75 * of bug can elude testing and code inspections. 76 * </p> 77 * <p> 78 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 79 * </p> 80 * <p> 81 * Violation Message Keys: 82 * </p> 83 * <ul> 84 * <li> 85 * {@code covariant.equals} 86 * </li> 87 * </ul> 88 * 89 * @since 3.2 90 */ 91 @FileStatefulCheck 92 public class CovariantEqualsCheck extends AbstractCheck { 93 94 /** 95 * A key is pointing to the warning message text in "messages.properties" 96 * file. 97 */ 98 public static final String MSG_KEY = "covariant.equals"; 99 100 /** Set of equals method definitions. */ 101 private final Set<DetailAST> equalsMethods = new HashSet<>(); 102 103 @Override 104 public int[] getDefaultTokens() { 105 return getRequiredTokens(); 106 } 107 108 @Override 109 public int[] getRequiredTokens() { 110 return new int[] { 111 TokenTypes.CLASS_DEF, 112 TokenTypes.LITERAL_NEW, 113 TokenTypes.ENUM_DEF, 114 TokenTypes.RECORD_DEF, 115 }; 116 } 117 118 @Override 119 public int[] getAcceptableTokens() { 120 return getRequiredTokens(); 121 } 122 123 @Override 124 public void visitToken(DetailAST ast) { 125 equalsMethods.clear(); 126 127 // examine method definitions for equals methods 128 final DetailAST objBlock = ast.findFirstToken(TokenTypes.OBJBLOCK); 129 if (objBlock != null) { 130 DetailAST child = objBlock.getFirstChild(); 131 boolean hasEqualsObject = false; 132 while (child != null) { 133 if (CheckUtil.isEqualsMethod(child)) { 134 if (isFirstParameterObject(child)) { 135 hasEqualsObject = true; 136 } 137 else { 138 equalsMethods.add(child); 139 } 140 } 141 child = child.getNextSibling(); 142 } 143 144 // report equals method definitions 145 if (!hasEqualsObject) { 146 for (DetailAST equalsAST : equalsMethods) { 147 final DetailAST nameNode = equalsAST 148 .findFirstToken(TokenTypes.IDENT); 149 log(nameNode, MSG_KEY); 150 } 151 } 152 } 153 } 154 155 /** 156 * Tests whether a method's first parameter is an Object. 157 * 158 * @param methodDefAst the method definition AST to test. 159 * Precondition: ast is a TokenTypes.METHOD_DEF node. 160 * @return true if ast has first parameter of type Object. 161 */ 162 private static boolean isFirstParameterObject(DetailAST methodDefAst) { 163 final DetailAST paramsNode = methodDefAst.findFirstToken(TokenTypes.PARAMETERS); 164 165 // parameter type "Object"? 166 final DetailAST paramNode = 167 paramsNode.findFirstToken(TokenTypes.PARAMETER_DEF); 168 final DetailAST typeNode = paramNode.findFirstToken(TokenTypes.TYPE); 169 final FullIdent fullIdent = FullIdent.createFullIdentBelow(typeNode); 170 final String name = fullIdent.getText(); 171 return "Object".equals(name) || "java.lang.Object".equals(name); 172 } 173 174 }