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.Objects; 023 024import com.puppycrawl.tools.checkstyle.StatelessCheck; 025import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 026import com.puppycrawl.tools.checkstyle.api.DetailAST; 027import com.puppycrawl.tools.checkstyle.api.TokenTypes; 028 029/** 030 * <div> 031 * Restricts throws statements to a specified count. 032 * Methods with "Override" or "java.lang.Override" annotation are skipped 033 * from validation as current class cannot change signature of these methods. 034 * </div> 035 * 036 * <p> 037 * Rationale: 038 * Exceptions form part of a method's interface. Declaring 039 * a method to throw too many differently rooted 040 * exceptions makes exception handling onerous and leads 041 * to poor programming practices such as writing code like 042 * {@code catch(Exception ex)}. 4 is the empirical value which is based 043 * on reports that we had for the ThrowsCountCheck over big projects 044 * such as OpenJDK. This check also forces developers to put exceptions 045 * into a hierarchy such that in the simplest 046 * case, only one type of exception need be checked for by 047 * a caller but any subclasses can be caught 048 * specifically if necessary. For more information on rules 049 * for the exceptions and their issues, see Effective Java: 050 * Programming Language Guide Second Edition 051 * by Joshua Bloch pages 264-273. 052 * </p> 053 * 054 * <p> 055 * <b>ignorePrivateMethods</b> - allows to skip private methods as they do 056 * not cause problems for other classes. 057 * </p> 058 * <ul> 059 * <li> 060 * Property {@code ignorePrivateMethods} - Allow private methods to be ignored. 061 * Type is {@code boolean}. 062 * Default value is {@code true}. 063 * </li> 064 * <li> 065 * Property {@code max} - Specify maximum allowed number of throws statements. 066 * Type is {@code int}. 067 * Default value is {@code 4}. 068 * </li> 069 * </ul> 070 * 071 * <p> 072 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 073 * </p> 074 * 075 * <p> 076 * Violation Message Keys: 077 * </p> 078 * <ul> 079 * <li> 080 * {@code throws.count} 081 * </li> 082 * </ul> 083 * 084 * @since 3.2 085 */ 086@StatelessCheck 087public final class ThrowsCountCheck extends AbstractCheck { 088 089 /** 090 * A key is pointing to the warning message text in "messages.properties" 091 * file. 092 */ 093 public static final String MSG_KEY = "throws.count"; 094 095 /** Default value of max property. */ 096 private static final int DEFAULT_MAX = 4; 097 098 /** Allow private methods to be ignored. */ 099 private boolean ignorePrivateMethods = true; 100 101 /** Specify maximum allowed number of throws statements. */ 102 private int max; 103 104 /** Creates new instance of the check. */ 105 public ThrowsCountCheck() { 106 max = DEFAULT_MAX; 107 } 108 109 @Override 110 public int[] getDefaultTokens() { 111 return getRequiredTokens(); 112 } 113 114 @Override 115 public int[] getRequiredTokens() { 116 return new int[] { 117 TokenTypes.LITERAL_THROWS, 118 }; 119 } 120 121 @Override 122 public int[] getAcceptableTokens() { 123 return getRequiredTokens(); 124 } 125 126 /** 127 * Setter to allow private methods to be ignored. 128 * 129 * @param ignorePrivateMethods whether private methods must be ignored. 130 * @since 6.7 131 */ 132 public void setIgnorePrivateMethods(boolean ignorePrivateMethods) { 133 this.ignorePrivateMethods = ignorePrivateMethods; 134 } 135 136 /** 137 * Setter to specify maximum allowed number of throws statements. 138 * 139 * @param max maximum allowed throws statements. 140 * @since 3.2 141 */ 142 public void setMax(int max) { 143 this.max = max; 144 } 145 146 @Override 147 public void visitToken(DetailAST ast) { 148 if (ast.getType() == TokenTypes.LITERAL_THROWS) { 149 visitLiteralThrows(ast); 150 } 151 else { 152 throw new IllegalStateException(ast.toString()); 153 } 154 } 155 156 /** 157 * Checks number of throws statements. 158 * 159 * @param ast throws for check. 160 */ 161 private void visitLiteralThrows(DetailAST ast) { 162 if ((!ignorePrivateMethods || !isInPrivateMethod(ast)) 163 && !isOverriding(ast)) { 164 // Account for all the commas! 165 final int count = (ast.getChildCount() + 1) / 2; 166 if (count > max) { 167 log(ast, MSG_KEY, count, max); 168 } 169 } 170 } 171 172 /** 173 * Check if a method has annotation @Override. 174 * 175 * @param ast throws, which is being checked. 176 * @return true, if a method has annotation @Override. 177 */ 178 private static boolean isOverriding(DetailAST ast) { 179 final DetailAST modifiers = ast.getParent().findFirstToken(TokenTypes.MODIFIERS); 180 boolean isOverriding = false; 181 DetailAST child = modifiers.getFirstChild(); 182 while (child != null) { 183 if (child.getType() == TokenTypes.ANNOTATION 184 && "Override".equals(getAnnotationName(child))) { 185 isOverriding = true; 186 break; 187 } 188 child = child.getNextSibling(); 189 } 190 return isOverriding; 191 } 192 193 /** 194 * Gets name of an annotation. 195 * 196 * @param annotation to get name of. 197 * @return name of an annotation. 198 */ 199 private static String getAnnotationName(DetailAST annotation) { 200 final DetailAST dotAst = annotation.findFirstToken(TokenTypes.DOT); 201 final DetailAST parent = Objects.requireNonNullElse(dotAst, annotation); 202 return parent.findFirstToken(TokenTypes.IDENT).getText(); 203 } 204 205 /** 206 * Checks if method, which throws an exception is private. 207 * 208 * @param ast throws, which is being checked. 209 * @return true, if method, which throws an exception is private. 210 */ 211 private static boolean isInPrivateMethod(DetailAST ast) { 212 final DetailAST methodModifiers = ast.getParent().findFirstToken(TokenTypes.MODIFIERS); 213 return methodModifiers.findFirstToken(TokenTypes.LITERAL_PRIVATE) != null; 214 } 215 216}