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.design;
021
022import java.util.ArrayDeque;
023import java.util.Deque;
024import java.util.regex.Pattern;
025
026import com.puppycrawl.tools.checkstyle.FileStatefulCheck;
027import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
028import com.puppycrawl.tools.checkstyle.api.DetailAST;
029import com.puppycrawl.tools.checkstyle.api.TokenTypes;
030
031/**
032 * <div>
033 * Ensures that exception classes (classes with names conforming to some pattern
034 * and explicitly extending classes with names conforming to other
035 * pattern) are immutable, that is, that they have only final fields.
036 * </div>
037 *
038 * <p>
039 * The current algorithm is very simple: it checks that all members of exception are final.
040 * The user can still mutate an exception's instance (e.g. Throwable has a method called
041 * {@code setStackTrace} which changes the exception's stack trace). But, at least, all
042 * information provided by this exception type is unchangeable.
043 * </p>
044 *
045 * <p>
046 * Rationale: Exception instances should represent an error
047 * condition. Having non-final fields not only allows the state to be
048 * modified by accident and therefore mask the original condition but
049 * also allows developers to accidentally forget to set the initial state.
050 * In both cases, code catching the exception could draw incorrect
051 * conclusions based on the state.
052 * </p>
053 * <ul>
054 * <li>
055 * Property {@code extendedClassNameFormat} - Specify pattern for extended class names.
056 * Type is {@code java.util.regex.Pattern}.
057 * Default value is {@code "^.*Exception$|^.*Error$|^.*Throwable$"}.
058 * </li>
059 * <li>
060 * Property {@code format} - Specify pattern for exception class names.
061 * Type is {@code java.util.regex.Pattern}.
062 * Default value is {@code "^.*Exception$|^.*Error$|^.*Throwable$"}.
063 * </li>
064 * </ul>
065 *
066 * <p>
067 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
068 * </p>
069 *
070 * <p>
071 * Violation Message Keys:
072 * </p>
073 * <ul>
074 * <li>
075 * {@code mutable.exception}
076 * </li>
077 * </ul>
078 *
079 * @since 3.2
080 */
081@FileStatefulCheck
082public final class MutableExceptionCheck extends AbstractCheck {
083
084    /**
085     * A key is pointing to the warning message text in "messages.properties"
086     * file.
087     */
088    public static final String MSG_KEY = "mutable.exception";
089
090    /** Default value for format and extendedClassNameFormat properties. */
091    private static final String DEFAULT_FORMAT = "^.*Exception$|^.*Error$|^.*Throwable$";
092    /** Stack of checking information for classes. */
093    private final Deque<Boolean> checkingStack = new ArrayDeque<>();
094    /** Specify pattern for extended class names. */
095    private Pattern extendedClassNameFormat = Pattern.compile(DEFAULT_FORMAT);
096    /** Should we check current class or not. */
097    private boolean checking;
098    /** Specify pattern for exception class names. */
099    private Pattern format = extendedClassNameFormat;
100
101    /**
102     * Setter to specify pattern for extended class names.
103     *
104     * @param extendedClassNameFormat a {@code String} value
105     * @since 6.2
106     */
107    public void setExtendedClassNameFormat(Pattern extendedClassNameFormat) {
108        this.extendedClassNameFormat = extendedClassNameFormat;
109    }
110
111    /**
112     * Setter to specify pattern for exception class names.
113     *
114     * @param pattern the new pattern
115     * @since 3.2
116     */
117    public void setFormat(Pattern pattern) {
118        format = pattern;
119    }
120
121    @Override
122    public int[] getDefaultTokens() {
123        return getRequiredTokens();
124    }
125
126    @Override
127    public int[] getRequiredTokens() {
128        return new int[] {TokenTypes.CLASS_DEF, TokenTypes.VARIABLE_DEF};
129    }
130
131    @Override
132    public int[] getAcceptableTokens() {
133        return getRequiredTokens();
134    }
135
136    @Override
137    public void visitToken(DetailAST ast) {
138        switch (ast.getType()) {
139            case TokenTypes.CLASS_DEF:
140                visitClassDef(ast);
141                break;
142            case TokenTypes.VARIABLE_DEF:
143                visitVariableDef(ast);
144                break;
145            default:
146                throw new IllegalStateException(ast.toString());
147        }
148    }
149
150    @Override
151    public void leaveToken(DetailAST ast) {
152        if (ast.getType() == TokenTypes.CLASS_DEF) {
153            leaveClassDef();
154        }
155    }
156
157    /**
158     * Called when we start processing class definition.
159     *
160     * @param ast class definition node
161     */
162    private void visitClassDef(DetailAST ast) {
163        checkingStack.push(checking);
164        checking = isNamedAsException(ast) && isExtendedClassNamedAsException(ast);
165    }
166
167    /** Called when we leave class definition. */
168    private void leaveClassDef() {
169        checking = checkingStack.pop();
170    }
171
172    /**
173     * Checks variable definition.
174     *
175     * @param ast variable def node for check
176     */
177    private void visitVariableDef(DetailAST ast) {
178        if (checking && ast.getParent().getType() == TokenTypes.OBJBLOCK) {
179            final DetailAST modifiersAST =
180                ast.findFirstToken(TokenTypes.MODIFIERS);
181
182            if (modifiersAST.findFirstToken(TokenTypes.FINAL) == null) {
183                log(ast, MSG_KEY, ast.findFirstToken(TokenTypes.IDENT).getText());
184            }
185        }
186    }
187
188    /**
189     * Checks that a class name conforms to specified format.
190     *
191     * @param ast class definition node
192     * @return true if a class name conforms to specified format
193     */
194    private boolean isNamedAsException(DetailAST ast) {
195        final String className = ast.findFirstToken(TokenTypes.IDENT).getText();
196        return format.matcher(className).find();
197    }
198
199    /**
200     * Checks that if extended class name conforms to specified format.
201     *
202     * @param ast class definition node
203     * @return true if extended class name conforms to specified format
204     */
205    private boolean isExtendedClassNamedAsException(DetailAST ast) {
206        boolean result = false;
207        final DetailAST extendsClause = ast.findFirstToken(TokenTypes.EXTENDS_CLAUSE);
208        if (extendsClause != null) {
209            DetailAST currentNode = extendsClause;
210            while (currentNode.getLastChild() != null) {
211                currentNode = currentNode.getLastChild();
212            }
213            final String extendedClassName = currentNode.getText();
214            result = extendedClassNameFormat.matcher(extendedClassName).matches();
215        }
216        return result;
217    }
218
219}