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.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 * <div>
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 * </div>
040 *
041 * <p>
042 * Rationale: The contract of {@code equals()} and {@code hashCode()} requires that
043 * equal objects have the same hashCode. Therefore, whenever you override
044 * {@code equals()} you must override {@code hashCode()} to ensure that your class can
045 * be used in hash-based collections.
046 * </p>
047 *
048 * <p>
049 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
050 * </p>
051 *
052 * <p>
053 * Violation Message Keys:
054 * </p>
055 * <ul>
056 * <li>
057 * {@code equals.noEquals}
058 * </li>
059 * <li>
060 * {@code equals.noHashCode}
061 * </li>
062 * </ul>
063 *
064 * @since 3.0
065 */
066@FileStatefulCheck
067public class EqualsHashCodeCheck
068        extends AbstractCheck {
069
070    // implementation note: we have to use the following members to
071    // keep track of definitions in different inner classes
072
073    /**
074     * A key is pointing to the warning message text in "messages.properties"
075     * file.
076     */
077    public static final String MSG_KEY_HASHCODE = "equals.noHashCode";
078
079    /**
080     * A key is pointing to the warning message text in "messages.properties"
081     * file.
082     */
083    public static final String MSG_KEY_EQUALS = "equals.noEquals";
084
085    /** Maps OBJ_BLOCK to the method definition of equals(). */
086    private final Map<DetailAST, DetailAST> objBlockWithEquals = new HashMap<>();
087
088    /** Maps OBJ_BLOCKs to the method definition of hashCode(). */
089    private final Map<DetailAST, DetailAST> objBlockWithHashCode = new HashMap<>();
090
091    @Override
092    public int[] getDefaultTokens() {
093        return getRequiredTokens();
094    }
095
096    @Override
097    public int[] getAcceptableTokens() {
098        return getRequiredTokens();
099    }
100
101    @Override
102    public int[] getRequiredTokens() {
103        return new int[] {TokenTypes.METHOD_DEF};
104    }
105
106    @Override
107    public void beginTree(DetailAST rootAST) {
108        objBlockWithEquals.clear();
109        objBlockWithHashCode.clear();
110    }
111
112    @Override
113    public void visitToken(DetailAST ast) {
114        if (isEqualsMethod(ast)) {
115            objBlockWithEquals.put(ast.getParent(), ast);
116        }
117        else if (isHashCodeMethod(ast)) {
118            objBlockWithHashCode.put(ast.getParent(), ast);
119        }
120    }
121
122    /**
123     * Determines if an AST is a valid Equals method implementation.
124     *
125     * @param ast the AST to check
126     * @return true if the {code ast} is an Equals method.
127     */
128    private static boolean isEqualsMethod(DetailAST ast) {
129        final DetailAST modifiers = ast.getFirstChild();
130        final DetailAST parameters = ast.findFirstToken(TokenTypes.PARAMETERS);
131
132        return CheckUtil.isEqualsMethod(ast)
133                && isObjectParam(parameters.getFirstChild())
134                && (ast.findFirstToken(TokenTypes.SLIST) != null
135                        || modifiers.findFirstToken(TokenTypes.LITERAL_NATIVE) != null);
136    }
137
138    /**
139     * Determines if an AST is a valid HashCode method implementation.
140     *
141     * @param ast the AST to check
142     * @return true if the {code ast} is a HashCode method.
143     */
144    private static boolean isHashCodeMethod(DetailAST ast) {
145        final DetailAST modifiers = ast.getFirstChild();
146        final DetailAST methodName = ast.findFirstToken(TokenTypes.IDENT);
147        final DetailAST parameters = ast.findFirstToken(TokenTypes.PARAMETERS);
148
149        return "hashCode".equals(methodName.getText())
150                && parameters.getFirstChild() == null
151                && (ast.findFirstToken(TokenTypes.SLIST) != null
152                        || modifiers.findFirstToken(TokenTypes.LITERAL_NATIVE) != null);
153    }
154
155    /**
156     * Determines if an AST is a formal param of type Object.
157     *
158     * @param paramNode the AST to check
159     * @return true if firstChild is a parameter of an Object type.
160     */
161    private static boolean isObjectParam(DetailAST paramNode) {
162        final DetailAST typeNode = paramNode.findFirstToken(TokenTypes.TYPE);
163        final FullIdent fullIdent = FullIdent.createFullIdentBelow(typeNode);
164        final String name = fullIdent.getText();
165        return "Object".equals(name) || "java.lang.Object".equals(name);
166    }
167
168    @Override
169    public void finishTree(DetailAST rootAST) {
170        objBlockWithEquals
171            .entrySet().stream().filter(detailASTDetailASTEntry -> {
172                return objBlockWithHashCode.remove(detailASTDetailASTEntry.getKey()) == null;
173            }).forEach(detailASTDetailASTEntry -> {
174                final DetailAST equalsAST = detailASTDetailASTEntry.getValue();
175                log(equalsAST, MSG_KEY_HASHCODE);
176            });
177        objBlockWithHashCode.forEach((key, equalsAST) -> log(equalsAST, MSG_KEY_EQUALS));
178    }
179
180}