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