001//////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code for adherence to a set of rules. 003// Copyright (C) 2001-2020 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.filters; 021 022import com.puppycrawl.tools.checkstyle.api.AuditEvent; 023import com.puppycrawl.tools.checkstyle.api.AutomaticBean; 024import com.puppycrawl.tools.checkstyle.api.Filter; 025import com.puppycrawl.tools.checkstyle.checks.SuppressWarningsHolder; 026 027/** 028 * <p> 029 * Filter {@code SuppressWarningsFilter} uses annotation 030 * {@code SuppressWarnings} to suppress audit events. 031 * </p> 032 * <p> 033 * Rationale: Same as for {@code SuppressionCommentFilter}. In the contrary to it here, 034 * comments are not used comments but the builtin syntax of {@code @SuppressWarnings}. 035 * This can be perceived as a more elegant solution than using comments. 036 * Also this approach maybe supported by various IDE. 037 * </p> 038 * <p> 039 * Usage: This filter only works in conjunction with a 040 * <a href="https://checkstyle.org/config_annotation.html#SuppressWarningsHolder"> 041 * SuppressWarningsHolder</a>, 042 * since that check finds the annotations in the Java files and makes them available for the filter. 043 * Because of that, a configuration that includes this filter must also include 044 * {@code SuppressWarningsHolder} as a child module of the {@code TreeWalker}. 045 * Name of check in annotation is case-insensitive and should be written with 046 * any dotted prefix or "Check" suffix removed. 047 * </p> 048 * <p> 049 * To configure the check that makes tha annotations available to the filter. 050 * </p> 051 * <pre> 052 * <module name="TreeWalker"> 053 * ... 054 * <module name="SuppressWarningsHolder" /> 055 * ... 056 * </module> 057 * </pre> 058 * <p> 059 * To configure filter to suppress audit events for annotations add: 060 * </p> 061 * <pre> 062 * <module name="SuppressWarningsFilter" /> 063 * </pre> 064 * <pre> 065 * @SuppressWarnings({"memberName"}) 066 * private int J; // should NOT fail MemberNameCheck 067 * 068 * @SuppressWarnings({"MemberName"}) 069 * @SuppressWarnings({"NoWhitespaceAfter"}) 070 * private int [] ARRAY; // should NOT fail MemberNameCheck and NoWhitespaceAfterCheck 071 * </pre> 072 * <p> 073 * It is possible to specify an ID of checks, so that it can be leveraged by 074 * the SuppressWarningsFilter to skip validations. The following examples show how to 075 * skip validations near code that has {@code @SuppressWarnings("checkstyle:<ID>")} 076 * or just {@code @SuppressWarnings("<ID>")} annotation, where ID is the ID 077 * of checks you want to suppress. 078 * </p> 079 * <p> 080 * Example of Checkstyle check configuration: 081 * </p> 082 * <pre> 083 * <module name="RegexpSinglelineJava"> 084 * <property name="id" value="systemout"/> 085 * <property name="format" value="^.*System\.(out|err).*$"/> 086 * <property name="message" 087 * value="Don't use System.out/err, use SLF4J instead."/> 088 * </module> 089 * </pre> 090 * <p> 091 * To make the annotations available to the filter. 092 * </p> 093 * <pre> 094 * <module name="TreeWalker"> 095 * ... 096 * <module name="SuppressWarningsHolder" /> 097 * ... 098 * </module> 099 * </pre> 100 * <p> 101 * To configure filter to suppress audit events for annotations add: 102 * </p> 103 * <pre> 104 * <module name="SuppressWarningsFilter" /> 105 * </pre> 106 * <pre> 107 * @SuppressWarnings("checkstyle:systemout") 108 * public static void foo() { 109 * System.out.println("Debug info."); // should NOT fail RegexpSinglelineJava 110 * } 111 * </pre> 112 * 113 * @since 5.7 114 */ 115public class SuppressWarningsFilter 116 extends AutomaticBean 117 implements Filter { 118 119 @Override 120 protected void finishLocalSetup() { 121 // No code by default 122 } 123 124 @Override 125 public boolean accept(AuditEvent event) { 126 return !SuppressWarningsHolder.isSuppressed(event); 127 } 128 129}