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 }