001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2024 the original author or authors. 004// 005// This library is free software; you can redistribute it and/or 006// modify it under the terms of the GNU Lesser General Public 007// License as published by the Free Software Foundation; either 008// version 2.1 of the License, or (at your option) any later version. 009// 010// This library is distributed in the hope that it will be useful, 011// but WITHOUT ANY WARRANTY; without even the implied warranty of 012// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 013// Lesser General Public License for more details. 014// 015// You should have received a copy of the GNU Lesser General Public 016// License along with this library; if not, write to the Free Software 017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 018/////////////////////////////////////////////////////////////////////////////////////////////// 019 020package com.puppycrawl.tools.checkstyle.checks.coding; 021 022import java.util.HashSet; 023import java.util.Set; 024 025import com.puppycrawl.tools.checkstyle.FileStatefulCheck; 026import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 027import com.puppycrawl.tools.checkstyle.api.DetailAST; 028import com.puppycrawl.tools.checkstyle.api.FullIdent; 029import com.puppycrawl.tools.checkstyle.api.TokenTypes; 030import com.puppycrawl.tools.checkstyle.utils.CheckUtil; 031 032/** 033 * <p> 034 * Checks that classes and records which define a covariant {@code equals()} method 035 * also override method {@code equals(Object)}. 036 * </p> 037 * <p> 038 * Covariant {@code equals()} - method that is similar to {@code equals(Object)}, 039 * but with a covariant parameter type (any subtype of Object). 040 * </p> 041 * <p> 042 * <strong>Notice</strong>: the enums are also checked, 043 * even though they cannot override {@code equals(Object)}. 044 * The reason is to point out that implementing {@code equals()} in enums 045 * is considered an awful practice: it may cause having two different enum values 046 * that are equal using covariant enum method, and not equal when compared normally. 047 * </p> 048 * <p> 049 * Inspired by <a href="https://www.cs.jhu.edu/~daveho/pubs/oopsla2004.pdf"> 050 * Finding Bugs is Easy, chapter '4.5 Bad Covariant Definition of Equals (Eq)'</a>: 051 * </p> 052 * <p> 053 * Java classes and records may override the {@code equals(Object)} method to define 054 * a predicate for object equality. This method is used by many of the Java 055 * runtime library classes; for example, to implement generic containers. 056 * </p> 057 * <p> 058 * Programmers sometimes mistakenly use the type of their class {@code Foo} 059 * as the type of the parameter to {@code equals()}: 060 * </p> 061 * <pre> 062 * public boolean equals(Foo obj) {...} 063 * </pre> 064 * <p> 065 * This covariant version of {@code equals()} does not override the version in 066 * the {@code Object} class, and it may lead to unexpected behavior at runtime, 067 * especially if the class is used with one of the standard collection classes 068 * which expect that the standard {@code equals(Object)} method is overridden. 069 * </p> 070 * <p> 071 * This kind of bug is not obvious because it looks correct, and in circumstances 072 * where the class is accessed through the references of the class type (rather 073 * than a supertype), it will work correctly. However, the first time it is used 074 * in a container, the behavior might be mysterious. For these reasons, this type 075 * of bug can elude testing and code inspections. 076 * </p> 077 * <p> 078 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 079 * </p> 080 * <p> 081 * Violation Message Keys: 082 * </p> 083 * <ul> 084 * <li> 085 * {@code covariant.equals} 086 * </li> 087 * </ul> 088 * 089 * @since 3.2 090 */ 091@FileStatefulCheck 092public class CovariantEqualsCheck extends AbstractCheck { 093 094 /** 095 * A key is pointing to the warning message text in "messages.properties" 096 * file. 097 */ 098 public static final String MSG_KEY = "covariant.equals"; 099 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}