1 ///////////////////////////////////////////////////////////////////////////////////////////////
2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
3 // Copyright (C) 2001-2025 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.ArrayDeque;
23 import java.util.Deque;
24 import java.util.Optional;
25
26 import com.puppycrawl.tools.checkstyle.FileStatefulCheck;
27 import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
28 import com.puppycrawl.tools.checkstyle.api.DetailAST;
29 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
30 import com.puppycrawl.tools.checkstyle.utils.TokenUtil;
31
32 /**
33 * <div>
34 * Ensures that catch parameters that are not used are declared as an unnamed variable.
35 * </div>
36 *
37 * <p>
38 * Rationale:
39 * </p>
40 * <ul>
41 * <li>
42 * Improves code readability by clearly indicating which parameters are unused.
43 * </li>
44 * <li>
45 * Follows Java conventions for denoting unused parameters with an underscore ({@code _}).
46 * </li>
47 * </ul>
48 *
49 * <p>
50 * See the <a href="https://docs.oracle.com/en/java/javase/21/docs/specs/unnamed-jls.html">
51 * Java Language Specification</a> for more information about unnamed variables.
52 * </p>
53 *
54 * <p>
55 * <b>Attention</b>: This check should be activated only on source code
56 * that is compiled by jdk21 or higher;
57 * unnamed catch parameters came out as the first preview in Java 21.
58 * </p>
59 *
60 * @since 10.18.0
61 */
62
63 @FileStatefulCheck
64 public class UnusedCatchParameterShouldBeUnnamedCheck extends AbstractCheck {
65
66 /**
67 * A key is pointing to the warning message text in "messages.properties"
68 * file.
69 */
70 public static final String MSG_UNUSED_CATCH_PARAMETER = "unused.catch.parameter";
71
72 /**
73 * Invalid parents of the catch parameter identifier.
74 */
75 private static final int[] INVALID_CATCH_PARAM_IDENT_PARENTS = {
76 TokenTypes.DOT,
77 TokenTypes.LITERAL_NEW,
78 TokenTypes.METHOD_CALL,
79 TokenTypes.TYPE,
80 };
81
82 /**
83 * Keeps track of the catch parameters in a block.
84 */
85 private final Deque<CatchParameterDetails> catchParameters = new ArrayDeque<>();
86
87 @Override
88 public int[] getDefaultTokens() {
89 return getRequiredTokens();
90 }
91
92 @Override
93 public int[] getAcceptableTokens() {
94 return getRequiredTokens();
95 }
96
97 @Override
98 public int[] getRequiredTokens() {
99 return new int[] {
100 TokenTypes.LITERAL_CATCH,
101 TokenTypes.IDENT,
102 };
103 }
104
105 @Override
106 public void beginTree(DetailAST rootAST) {
107 catchParameters.clear();
108 }
109
110 @Override
111 public void visitToken(DetailAST ast) {
112 if (ast.getType() == TokenTypes.LITERAL_CATCH) {
113 final CatchParameterDetails catchParameter = new CatchParameterDetails(ast);
114 catchParameters.push(catchParameter);
115 }
116 else if (isCatchParameterIdentifierCandidate(ast) && !isLeftHandOfAssignment(ast)) {
117 // we do not count reassignment as usage
118 catchParameters.stream()
119 .filter(parameter -> parameter.getName().equals(ast.getText()))
120 .findFirst()
121 .ifPresent(CatchParameterDetails::registerAsUsed);
122 }
123 }
124
125 @Override
126 public void leaveToken(DetailAST ast) {
127 if (ast.getType() == TokenTypes.LITERAL_CATCH) {
128 final Optional<CatchParameterDetails> unusedCatchParameter =
129 Optional.ofNullable(catchParameters.peek())
130 .filter(parameter -> !parameter.isUsed())
131 .filter(parameter -> !"_".equals(parameter.getName()));
132
133 unusedCatchParameter.ifPresent(parameter -> {
134 log(parameter.getParameterDefinition(),
135 MSG_UNUSED_CATCH_PARAMETER,
136 parameter.getName());
137 });
138 catchParameters.pop();
139 }
140 }
141
142 /**
143 * Visit ast of type {@link TokenTypes#IDENT}
144 * and check if it is a candidate for a catch parameter identifier.
145 *
146 * @param identifierAst token representing {@link TokenTypes#IDENT}
147 * @return true if the given {@link TokenTypes#IDENT} could be a catch parameter identifier
148 */
149 private static boolean isCatchParameterIdentifierCandidate(DetailAST identifierAst) {
150 // we should ignore the ident if it is in the exception declaration
151 return identifierAst.getParent().getParent().getType() != TokenTypes.LITERAL_CATCH
152 && (!TokenUtil.isOfType(identifierAst.getParent(), INVALID_CATCH_PARAM_IDENT_PARENTS)
153 || isMethodInvocation(identifierAst));
154 }
155
156 /**
157 * Check if the given {@link TokenTypes#IDENT} is a child of a dot operator
158 * and is a candidate for catch parameter.
159 *
160 * @param identAst token representing {@link TokenTypes#IDENT}
161 * @return true if the given {@link TokenTypes#IDENT} is a child of a dot operator
162 * and a candidate for catch parameter.
163 */
164 private static boolean isMethodInvocation(DetailAST identAst) {
165 final DetailAST parent = identAst.getParent();
166 return parent.getType() == TokenTypes.DOT
167 && identAst.equals(parent.getFirstChild());
168 }
169
170 /**
171 * Check if the given {@link TokenTypes#IDENT} is a left hand side value.
172 *
173 * @param identAst token representing {@link TokenTypes#IDENT}
174 * @return true if the given {@link TokenTypes#IDENT} is a left hand side value.
175 */
176 private static boolean isLeftHandOfAssignment(DetailAST identAst) {
177 final DetailAST parent = identAst.getParent();
178 return parent.getType() == TokenTypes.ASSIGN
179 && !identAst.equals(parent.getLastChild());
180 }
181
182 /**
183 * Maintains information about the catch parameter.
184 */
185 private static final class CatchParameterDetails {
186
187 /**
188 * The name of the catch parameter.
189 */
190 private final String name;
191
192 /**
193 * Ast of type {@link TokenTypes#PARAMETER_DEF} to use it when logging.
194 */
195 private final DetailAST parameterDefinition;
196
197 /**
198 * Is the variable used.
199 */
200 private boolean used;
201
202 /**
203 * Create a new catch parameter instance.
204 *
205 * @param enclosingCatchClause ast of type {@link TokenTypes#LITERAL_CATCH}
206 */
207 private CatchParameterDetails(DetailAST enclosingCatchClause) {
208 parameterDefinition =
209 enclosingCatchClause.findFirstToken(TokenTypes.PARAMETER_DEF);
210 name = parameterDefinition.findFirstToken(TokenTypes.IDENT).getText();
211 }
212
213 /**
214 * Register the catch parameter as used.
215 */
216 private void registerAsUsed() {
217 used = true;
218 }
219
220 /**
221 * Get the name of the catch parameter.
222 *
223 * @return the name of the catch parameter
224 */
225 private String getName() {
226 return name;
227 }
228
229 /**
230 * Check if the catch parameter is used.
231 *
232 * @return true if the catch parameter is used
233 */
234 private boolean isUsed() {
235 return used;
236 }
237
238 /**
239 * Get the parameter definition token of the catch parameter
240 * represented by ast of type {@link TokenTypes#PARAMETER_DEF}.
241 *
242 * @return the ast of type {@link TokenTypes#PARAMETER_DEF}
243 */
244 private DetailAST getParameterDefinition() {
245 return parameterDefinition;
246 }
247 }
248 }