001///////////////////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
003// Copyright (C) 2001-2025 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.ArrayList;
023import java.util.Collections;
024import java.util.List;
025import java.util.Optional;
026
027import com.puppycrawl.tools.checkstyle.StatelessCheck;
028import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
029import com.puppycrawl.tools.checkstyle.api.DetailAST;
030import com.puppycrawl.tools.checkstyle.api.TokenTypes;
031import com.puppycrawl.tools.checkstyle.utils.TokenUtil;
032
033/**
034 * <div>
035 * Checks that a given switch statement or expression that use a reference type in its selector
036 * expression has a {@code null} case label.
037 * </div>
038 *
039 * <p>
040 * Rationale: switch statements and expressions in Java throw a
041 * {@code NullPointerException} if the selector expression evaluates to {@code null}.
042 * As of Java 21, it is now possible to integrate a null check within the switch,
043 * eliminating the risk of {@code NullPointerException} and simplifies the code
044 * as there is no need for an external null check before entering the switch.
045 * </p>
046 *
047 * <p>
048 * See the <a href="https://docs.oracle.com/javase/specs/jls/se22/html/jls-15.html#jls-15.28">
049 * Java Language Specification</a> for more information about switch statements and expressions.
050 * </p>
051 *
052 * <p>
053 * Specifically, this check validates switch statement or expression
054 * that use patterns or strings in their case labels.
055 * </p>
056 *
057 * <p>
058 * Due to Checkstyle not being type-aware, this check cannot validate other reference types,
059 * such as enums; syntactically, these are no different from other constants.
060 * </p>
061 *
062 * <p>
063 * <b>Attention</b>: this Check should be activated only on source code
064 * that is compiled by jdk21 or above.
065 * </p>
066 *
067 * @since 10.18.0
068 */
069
070@StatelessCheck
071public class MissingNullCaseInSwitchCheck extends AbstractCheck {
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 = "missing.switch.nullcase";
078
079    @Override
080    public int[] getDefaultTokens() {
081        return getRequiredTokens();
082    }
083
084    @Override
085    public int[] getAcceptableTokens() {
086        return getRequiredTokens();
087    }
088
089    @Override
090    public int[] getRequiredTokens() {
091        return new int[] {TokenTypes.LITERAL_SWITCH};
092    }
093
094    @Override
095    public void visitToken(DetailAST ast) {
096        final List<DetailAST> caseLabels = getAllCaseLabels(ast);
097        final boolean hasNullCaseLabel = caseLabels.stream()
098                .anyMatch(MissingNullCaseInSwitchCheck::hasLiteralNull);
099        if (!hasNullCaseLabel) {
100            final boolean hasPatternCaseLabel = caseLabels.stream()
101                .anyMatch(MissingNullCaseInSwitchCheck::hasPatternCaseLabel);
102            final boolean hasStringCaseLabel = caseLabels.stream()
103                .anyMatch(MissingNullCaseInSwitchCheck::hasStringCaseLabel);
104            if (hasPatternCaseLabel || hasStringCaseLabel) {
105                log(ast, MSG_KEY);
106            }
107        }
108    }
109
110    /**
111     * Gets all case labels in the given switch AST node.
112     *
113     * @param switchAST the AST node representing {@code LITERAL_SWITCH}
114     * @return a list of all case labels in the switch
115     */
116    private static List<DetailAST> getAllCaseLabels(DetailAST switchAST) {
117        final List<DetailAST> caseLabels = new ArrayList<>();
118        DetailAST ast = switchAST.getFirstChild();
119        while (ast != null) {
120            // case group token may have several LITERAL_CASE tokens
121            TokenUtil.forEachChild(ast, TokenTypes.LITERAL_CASE, caseLabels::add);
122            ast = ast.getNextSibling();
123        }
124        return Collections.unmodifiableList(caseLabels);
125    }
126
127    /**
128     * Checks if the given case AST node has a null label.
129     *
130     * @param caseAST the AST node representing {@code LITERAL_CASE}
131     * @return true if the case has {@code null} label, false otherwise
132     */
133    private static boolean hasLiteralNull(DetailAST caseAST) {
134        return Optional.ofNullable(caseAST.findFirstToken(TokenTypes.EXPR))
135                .map(exp -> exp.findFirstToken(TokenTypes.LITERAL_NULL))
136                .isPresent();
137    }
138
139    /**
140     * Checks if the given case AST node has a pattern variable declaration label
141     * or record pattern definition label.
142     *
143     * @param caseAST the AST node representing {@code LITERAL_CASE}
144     * @return true if case has a pattern in its label
145     */
146    private static boolean hasPatternCaseLabel(DetailAST caseAST) {
147        return caseAST.findFirstToken(TokenTypes.RECORD_PATTERN_DEF) != null
148               || caseAST.findFirstToken(TokenTypes.PATTERN_VARIABLE_DEF) != null
149               || caseAST.findFirstToken(TokenTypes.PATTERN_DEF) != null;
150    }
151
152    /**
153     * Checks if the given case contains a string in its label.
154     * It may contain a single string literal or a string literal
155     * in a concatenated expression.
156     *
157     * @param caseAST the AST node representing {@code LITERAL_CASE}
158     * @return true if switch block contains a string case label
159     */
160    private static boolean hasStringCaseLabel(DetailAST caseAST) {
161        DetailAST curNode = caseAST;
162        boolean hasStringCaseLabel = false;
163        boolean exitCaseLabelExpression = false;
164        while (!exitCaseLabelExpression) {
165            DetailAST toVisit = curNode.getFirstChild();
166            if (curNode.getType() == TokenTypes.STRING_LITERAL) {
167                hasStringCaseLabel = true;
168                break;
169            }
170            while (toVisit == null) {
171                toVisit = curNode.getNextSibling();
172                curNode = curNode.getParent();
173            }
174            curNode = toVisit;
175            exitCaseLabelExpression = TokenUtil.isOfType(curNode, TokenTypes.COLON,
176                                                                        TokenTypes.LAMBDA);
177        }
178        return hasStringCaseLabel;
179    }
180}