001///////////////////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
003// Copyright (C) 2001-2022 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.HashMap;
023import java.util.Map;
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 that either override {@code equals()} or {@code hashCode()} also
035 * overrides the other.
036 * This check only verifies that the method declarations match {@code Object.equals(Object)} and
037 * {@code Object.hashCode()} exactly to be considered an override. This check does not verify
038 * invalid method names, parameters other than {@code Object}, or anything else.
039 * </p>
040 * <p>
041 * Rationale: The contract of {@code equals()} and {@code hashCode()} requires that
042 * equal objects have the same hashCode. Therefore, whenever you override
043 * {@code equals()} you must override {@code hashCode()} to ensure that your class can
044 * be used in hash-based collections.
045 * </p>
046 * <p>
047 * To configure the check:
048 * </p>
049 * <pre>
050 * &lt;module name=&quot;EqualsHashCode&quot;/&gt;
051 * </pre>
052 * <p>Example:</p>
053 * <pre>
054 * public static class Example1 {
055 *     public int hashCode() {
056 *         // code
057 *     }
058 *     public boolean equals(String o) { // violation, overloaded implementation of 'equals'
059 *         // code
060 *     }
061 * }
062 * public static class Example2 {
063 *     public boolean equals(Object o) { // violation, no 'hashCode'
064 *         // code
065 *     }
066 *     public boolean equals(String o) {
067 *         // code
068 *     }
069 * }
070 * public static class Example3 {
071 *     public int hashCode() {
072 *         // code
073 *     }
074 *     public boolean equals(Object o) { // OK
075 *         // code
076 *     }
077 *     public boolean equals(String o) {
078 *         // code
079 *     }
080 * }
081 * public static class Example4 {
082 *     public int hashCode() {
083 *         // code
084 *     }
085 *     public boolean equals(java.lang.Object o) { // OK
086 *         // code
087 *    }
088 * }
089 * public static class Example5 {
090 *     public static int hashCode(int i) {
091 *         // code
092 *     }
093 *     public boolean equals(Object o) { // violation, overloaded implementation of 'hashCode'
094 *         // code
095 *     }
096 * }
097 * public static class Example6 {
098 *     public int hashCode() { // violation, overloaded implementation of 'equals'
099 *         // code
100 *     }
101 *     public static boolean equals(Object o, Object o2) {
102 *         // code
103 *     }
104 * }
105 * </pre>
106 * <p>
107 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
108 * </p>
109 * <p>
110 * Violation Message Keys:
111 * </p>
112 * <ul>
113 * <li>
114 * {@code equals.noEquals}
115 * </li>
116 * <li>
117 * {@code equals.noHashCode}
118 * </li>
119 * </ul>
120 *
121 * @since 3.0
122 */
123@FileStatefulCheck
124public class EqualsHashCodeCheck
125        extends AbstractCheck {
126
127    // implementation note: we have to use the following members to
128    // keep track of definitions in different inner classes
129
130    /**
131     * A key is pointing to the warning message text in "messages.properties"
132     * file.
133     */
134    public static final String MSG_KEY_HASHCODE = "equals.noHashCode";
135
136    /**
137     * A key is pointing to the warning message text in "messages.properties"
138     * file.
139     */
140    public static final String MSG_KEY_EQUALS = "equals.noEquals";
141
142    /** Maps OBJ_BLOCK to the method definition of equals(). */
143    private final Map<DetailAST, DetailAST> objBlockWithEquals = new HashMap<>();
144
145    /** Maps OBJ_BLOCKs to the method definition of hashCode(). */
146    private final Map<DetailAST, DetailAST> objBlockWithHashCode = new HashMap<>();
147
148    @Override
149    public int[] getDefaultTokens() {
150        return getRequiredTokens();
151    }
152
153    @Override
154    public int[] getAcceptableTokens() {
155        return getRequiredTokens();
156    }
157
158    @Override
159    public int[] getRequiredTokens() {
160        return new int[] {TokenTypes.METHOD_DEF};
161    }
162
163    @Override
164    public void beginTree(DetailAST rootAST) {
165        objBlockWithEquals.clear();
166        objBlockWithHashCode.clear();
167    }
168
169    @Override
170    public void visitToken(DetailAST ast) {
171        if (isEqualsMethod(ast)) {
172            objBlockWithEquals.put(ast.getParent(), ast);
173        }
174        else if (isHashCodeMethod(ast)) {
175            objBlockWithHashCode.put(ast.getParent(), ast);
176        }
177    }
178
179    /**
180     * Determines if an AST is a valid Equals method implementation.
181     *
182     * @param ast the AST to check
183     * @return true if the {code ast} is an Equals method.
184     */
185    private static boolean isEqualsMethod(DetailAST ast) {
186        final DetailAST modifiers = ast.getFirstChild();
187        final DetailAST parameters = ast.findFirstToken(TokenTypes.PARAMETERS);
188
189        return CheckUtil.isEqualsMethod(ast)
190                && isObjectParam(parameters.getFirstChild())
191                && (ast.findFirstToken(TokenTypes.SLIST) != null
192                        || modifiers.findFirstToken(TokenTypes.LITERAL_NATIVE) != null);
193    }
194
195    /**
196     * Determines if an AST is a valid HashCode method implementation.
197     *
198     * @param ast the AST to check
199     * @return true if the {code ast} is a HashCode method.
200     */
201    private static boolean isHashCodeMethod(DetailAST ast) {
202        final DetailAST modifiers = ast.getFirstChild();
203        final DetailAST methodName = ast.findFirstToken(TokenTypes.IDENT);
204        final DetailAST parameters = ast.findFirstToken(TokenTypes.PARAMETERS);
205
206        return "hashCode".equals(methodName.getText())
207                && parameters.getFirstChild() == null
208                && (ast.findFirstToken(TokenTypes.SLIST) != null
209                        || modifiers.findFirstToken(TokenTypes.LITERAL_NATIVE) != null);
210    }
211
212    /**
213     * Determines if an AST is a formal param of type Object.
214     *
215     * @param paramNode the AST to check
216     * @return true if firstChild is a parameter of an Object type.
217     */
218    private static boolean isObjectParam(DetailAST paramNode) {
219        final DetailAST typeNode = paramNode.findFirstToken(TokenTypes.TYPE);
220        final FullIdent fullIdent = FullIdent.createFullIdentBelow(typeNode);
221        final String name = fullIdent.getText();
222        return "Object".equals(name) || "java.lang.Object".equals(name);
223    }
224
225    @Override
226    public void finishTree(DetailAST rootAST) {
227        objBlockWithEquals
228            .entrySet().stream().filter(detailASTDetailASTEntry -> {
229                return objBlockWithHashCode.remove(detailASTDetailASTEntry.getKey()) == null;
230            }).forEach(detailASTDetailASTEntry -> {
231                final DetailAST equalsAST = detailASTDetailASTEntry.getValue();
232                log(equalsAST, MSG_KEY_HASHCODE);
233            });
234        objBlockWithHashCode.forEach((key, equalsAST) -> log(equalsAST, MSG_KEY_EQUALS));
235    }
236
237}