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}