Package com.puppycrawl.tools.checkstyle.filters

Class SuppressionCommentFilter

java.lang.Object

com.puppycrawl.tools.checkstyle.AbstractAutomaticBean

com.puppycrawl.tools.checkstyle.filters.SuppressionCommentFilter

All Implemented Interfaces:

Configurable, Contextualizable, TreeWalkerFilter

public class SuppressionCommentFilter
extends AbstractAutomaticBean
implements TreeWalkerFilter

Filter SuppressionCommentFilter uses pairs of comments to suppress audit events.

Rationale: Sometimes there are legitimate reasons for violating a check. When this is a matter of the code in question and not personal preference, the best place to override the policy is in the code itself. Semi-structured comments can be associated with the check. This is sometimes superior to a separate suppressions file, which must be kept up-to-date as the source file is edited.

Note that the suppression comment should be put before the violation. You can use more than one suppression comment each on separate line.

Attention: This filter may only be specified within the TreeWalker module (<module name="TreeWalker"/>) and only applies to checks which are also defined within this module. To filter non-TreeWalker checks like RegexpSingleline, a SuppressWithPlainTextCommentFilter or similar filter must be used.

offCommentFormat and onCommentFormat must have equal paren counts.

SuppressionCommentFilter can suppress Checks that have Treewalker as parent module.

• Property offCommentFormat - Specify comment pattern to trigger filter to begin suppression. Type is java.util.regex.Pattern. Default value is "CHECKSTYLE:OFF".
• Property onCommentFormat - Specify comment pattern to trigger filter to end suppression. Type is java.util.regex.Pattern. Default value is "CHECKSTYLE:ON".
• Property checkFormat - Specify check pattern to suppress. Type is java.util.regex.Pattern. Default value is ".*".
• Property messageFormat - Specify message pattern to suppress. Type is java.util.regex.Pattern. Default value is null.
• Property idFormat - Specify check ID pattern to suppress. Type is java.util.regex.Pattern. Default value is null.
• Property checkCPP - Control whether to check C++ style comments (//). Type is boolean. Default value is true.
• Property checkC - Control whether to check C style comments (/* ... */). Type is boolean. Default value is true.

To configure a filter to suppress audit events (MemberNameCheck, ConstantNameCheck and IllegalCatchCheck have been taken here for reference) between a comment containing CHECKSTYLE:OFF and a comment containing CHECKSTYLE:ON:

   <module name="SuppressionCommentFilter"/>
   <module name="MemberName"/>
   <module name="ConstantName"/>
   <module name="IllegalCatch"/>
 

 class InputSuppressionCommentFilter
 {
  int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //CHECKSTYLE:OFF
  int VAR2; // suppressed violation
  //CHECKSTYLE:ON

  public static final int var3;
  // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

  //CHECKSTYLE:OFF
  public static final int var4; // suppressed violation
  //CHECKSTYLE:ON

  public void method1()
  {
    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed

    //CHECKSTYLE:OFF

    try {}
    catch(Exception ex) {} // suppressed violation
    catch(Error err) {} // suppressed violation

    //CHECKSTYLE:ON
  }
 }
 

To configure a filter so that // stop constant check and // resume constant check marks legitimate constant names:

 <module name="SuppressionCommentFilter">
   <property name="offCommentFormat" value="stop constant check"/>
   <property name="onCommentFormat" value="resume constant check"/>
   <property name="checkFormat" value="ConstantNameCheck"/>
 </module>
 <module name="MemberName"/>
 <module name="ConstantName"/>
 <module name="IllegalCatch"/>
 

 class InputSuppressionCommentFilter
 {
  int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //stop constant check
  int VAR2; // violation , Name 'VAR2' must match pattern '^[a-z][a-zA-Z0-9]*$'
  //resume constant check

  public static final int var3;
  // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

  //stop constant check
  public static final int var4; // suppressed violation
  //resume constant check

  public void method1()
  {
    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed

    //stop constant check

    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed
    catch(Error err) {} // violation , Catching 'Error' is not allowed

    //resume constant check
  }
 }
 

To configure a filter so that UNUSED OFF: <i>var</i> and UNUSED ON: <i>var</i> marks a variable or parameter known not to be used by the code by matching the variable name in the message through a specified message in messageFormat:

 <module name="SuppressionCommentFilter">
   <property name="offCommentFormat" value="ILLEGAL OFF\: (\w+)"/>
   <property name="onCommentFormat" value="ILLEGAL ON\: (\w+)"/>
   <property name="checkFormat" value="IllegalCatch"/>
   <property name="messageFormat" value="^Catching '$1' is not allowed.$"/>
 </module>
 <module name="MemberName"/>
 <module name="ConstantName"/>
 <module name="IllegalCatch"/>
 

 class InputSuppressionCommentFilter
 {
  int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //ILLEGAL OFF: Exception
  int VAR2; // violation , Name 'VAR2' must match pattern '^[a-z][a-zA-Z0-9]*$'
  //ILLEGAL ON: Exception

  public static final int var3;
  // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

  //ILLEGAL OFF: Exception
  public static final int var4;
  // violation above ,  Name 'var4' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'
  //ILLEGAL ON: Exception

  public void method1()
  {
    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed

    //ILLEGAL OFF: Exception

    try {}
    catch(Exception ex) {} // suppressed violation
    catch(Error err) {} // violation , Catching 'Error' is not allowed

    //ILLEGAL ON: Exception
  }
 }
 

To configure a filter so that name of suppressed check mentioned in comment CSOFF: <i>regexp</i> and CSON: <i>regexp</i> mark a matching check:

 <module name="SuppressionCommentFilter">
   <property name="offCommentFormat" value="CSOFF\: ([\w\|]+)"/>
   <property name="onCommentFormat" value="CSON\: ([\w\|]+)"/>
   <property name="checkFormat" value="$1"/>
 </module>
 <module name="MemberName"/>
 <module name="ConstantName"/>
 <module name="IllegalCatch"/>
 

 class InputSuppressionCommentFilter
 {
  int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //CSOFF: MemberName
  int VAR2; // suppressed violation
  //CSON: MemberName

  public static final int var3;
  // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

  //CSOFF: ConstantName
  public static final int var4; // suppressed violation
  //CSON: ConstantName

  public void method1()
  {
    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed

    //CSOFF: IllegalCatch

    try {}
    catch(Exception ex) {} // suppressed violation
    catch(Error err) {} // suppressed violation

    //CSON: IllegalCatch
  }
 }
 

To configure a filter to suppress all audit events between a comment containing CHECKSTYLE_OFF: ALMOST_ALL and a comment containing CHECKSTYLE_OFF: ALMOST_ALL except for the ConstantName check:

 <module name="SuppressionCommentFilter">
   <property name="offCommentFormat" value="CHECKSTYLE_OFF: ALMOST_ALL"/>
   <property name="onCommentFormat" value="CHECKSTYLE_ON: ALMOST_ALL"/>
   <property name="checkFormat" value="^((?!(ConstantName)).)*$"/>
 </module>
 <module name="MemberName"/>
 <module name="ConstantName"/>
 <module name="IllegalCatch"/>
 

 class InputSuppressionCommentFilter
 {
  int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //CHECKSTYLE_OFF: ALMOST_ALL
  int VAR2; // suppressed violation
  //CHECKSTYLE_ON: ALMOST_ALL

  public static final int var3;
  // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

  //CHECKSTYLE_OFF: ALMOST_ALL
  public static final int var4;
  // violation above , Name 'var4' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'
  //CHECKSTYLE_ON: ALMOST_ALL

  public void method1()
  {
    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed

    //CHECKSTYLE_OFF: ALMOST_ALL

    try {}
    catch(Exception ex) {} // suppressed violation
    catch(Error err) {} // suppressed violation

    //CHECKSTYLE_ON: ALMOST_ALL
  }
 }
 

It is possible to specify an ID of checks, so that it can be leveraged by the SuppressionCommentFilter to skip validations. The following examples show how to skip validations near code that is surrounded with // CSOFF <ID> and // CSON <ID>, where ID is the ID of checks you want to suppress. In the config of SuppressionCommentFilter, checkFormat is set to '$1' which points to the ID written in the offCommentFormat and onCommentFormat. Config for such a case is written below:

 <module name="SuppressionCommentFilter">
   <property name="offCommentFormat" value="CSOFF (\w+)"/>
   <property name="onCommentFormat" value="CSON (\w+)"/>
   <property name="idFormat" value="$1"/>
 </module>
 <module name="MemberName">
   <property name="id" value="MemberID"/>
 </module>
 <module name="ConstantName">
   <property name="id" value="ConstantID"/>
 </module>
 <module name="IllegalCatch">
   <property name="id" value="IllegalID"/>
 </module>
 

 class InputSuppressionCommentFilter
 {
  int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //CSOFF MemberID
  int VAR2; // suppressed violation
  //CSON: MemberID

  public static final int var3;
  // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

  //CSOFF ConstantID
  public static final int var4; // suppressed violation
  //CSON ConstantID

  public void method1()
  {
    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed

    //CSOFF IllegalID

    try {}
    catch(Exception ex) {} // suppressed violation
    catch(Error err) {} // suppressed violation

    //CSON IllegalID
  }
 }
 

Example of how to configure the check to suppress checks by name defined in comment.

 <module name="SuppressionCommentFilter">
   <property name="offCommentFormat" value="csoff (\w+)"/>
   <property name="onCommentFormat" value="cson (\w+)"/>
   <property name="checkFormat" value="$1"/>
 </module>
   <module name="MemberName"/>
   <module name="ConstantName"/>
   <module name="IllegalCatch"/>
 

 class InputSuppressionCommentFilter
 {
  int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //csoff MemberName
  int VAR2; // suppressed violation
  //cson MemberName

  public static final int var3;
  // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

  //csoff ConstantName
  //csoff IllegalCatch

  public static final int var4; // suppressed violation

  public void method1()
  {
    try {}
    catch(Exception ex) {} // suppressed violation

    try {}
    catch(Exception ex) {} // suppressed violation
    catch(Error err) {} // suppressed violation
  }

    //cson ConstantName
    //cson IllegalCatch

 }
 

Example depicting use of checkC and checkCPP style comments

 <module name="SuppressionCommentFilter">
   <property name="checkC" value="true"/>
   <property name="checkCPP" value="false"/>
 </module>
 <module name="MemberName"/>
 <module name="ConstantName"/>
 <module name="IllegalCatch"/>
 

 class InputSuppressionCommentFilter
 {
  int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$'

  //CHECKSTYLE:OFF
  int VAR2; // violation , Name 'VAR2' must match pattern '^[a-z][a-zA-Z0-9]*$'
  //CHECKSTYLE:ON

  public static final int var3;
  // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

  /*CHECKSTYLE:OFF*/
  public static final int var4; // suppressed violation
  /*CHECKSTYLE:ON*/

  public void method1()
  {
    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed

    //CHECKSTYLE:OFF

    try {}
    catch(Exception ex) {} // violation , Catching 'Exception' is not allowed
    catch(Error err) {} // violation , Catching 'Error' is not allowed

    //CHECKSTYLE:ON
  }
 }
 

Parent is com.puppycrawl.tools.checkstyle.TreeWalker

Since:

3.5

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static class	SuppressionCommentFilter.Tag	A Tag holds a suppression comment and its location, and determines whether the suppression turns checkstyle reporting on or off.
static class	SuppressionCommentFilter.TagType	Enum to be used for switching checkstyle reporting for tags.

Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.AbstractAutomaticBean

AbstractAutomaticBean.OutputStreamOptions

Field Summary

Fields

Modifier and Type	Field	Description
private boolean	checkC	Control whether to check C style comments (/* ... */).
private boolean	checkCPP	Control whether to check C++ style comments (//).
private java.lang.String	checkFormat	Specify check pattern to suppress.
private static java.lang.String	DEFAULT_CHECK_FORMAT	Control all checks.
private static java.lang.String	DEFAULT_OFF_FORMAT	Turns checkstyle reporting off.
private static java.lang.String	DEFAULT_ON_FORMAT	Turns checkstyle reporting on.
private java.lang.ref.WeakReference<FileContents>	fileContentsReference	References the current FileContents for this filter.
private java.lang.String	idFormat	Specify check ID pattern to suppress.
private java.lang.String	messageFormat	Specify message pattern to suppress.
private java.util.regex.Pattern	offCommentFormat	Specify comment pattern to trigger filter to begin suppression.
private java.util.regex.Pattern	onCommentFormat	Specify comment pattern to trigger filter to end suppression.
private java.util.List<SuppressionCommentFilter.Tag>	tags	Tagged comments.

Constructor Summary

Constructors

Constructor	Description
SuppressionCommentFilter()

Method Summary

Modifier and Type	Method	Description
boolean	accept(TreeWalkerAuditEvent event)	Determines whether or not a filtered TreeWalkerAuditEvent is accepted.
private void	addTag(java.lang.String text, int line, int column, SuppressionCommentFilter.TagType reportingOn)	Adds a Tag to the list of all tags.
private SuppressionCommentFilter.Tag	findNearestMatch(TreeWalkerAuditEvent event)	Finds the nearest comment text tag that matches an audit event.
protected void	finishLocalSetup()	Provides a hook to finish the part of this component's setup that was not handled by the bean introspection.
private FileContents	getFileContents()	Returns FileContents for this filter.
void	setCheckC(boolean checkC)	Setter to control whether to check C style comments (/* ... */).
void	setCheckCPP(boolean checkCpp)	Setter to control whether to check C++ style comments (//).
void	setCheckFormat(java.lang.String format)	Setter to specify check pattern to suppress.
void	setFileContents(FileContents fileContents)	Set the FileContents for this filter.
void	setIdFormat(java.lang.String format)	Setter to specify check ID pattern to suppress.
void	setMessageFormat(java.lang.String format)	Setter to specify message pattern to suppress.
void	setOffCommentFormat(java.util.regex.Pattern pattern)	Setter to specify comment pattern to trigger filter to begin suppression.
void	setOnCommentFormat(java.util.regex.Pattern pattern)	Setter to specify comment pattern to trigger filter to end suppression.
private void	tagCommentLine(java.lang.String text, int line, int column)	Tags a string if it matches the format for turning checkstyle reporting on or the format for turning reporting off.
private void	tagSuppressions()	Collects all the suppression tags for all comments into a list and sorts the list.
private void	tagSuppressions(java.util.Collection<TextBlock> comments)	Appends the suppressions in a collection of comments to the full set of suppression tags.

Methods inherited from class com.puppycrawl.tools.checkstyle.AbstractAutomaticBean

configure, contextualize, getConfiguration, setupChild

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_OFF_FORMAT

private static final java.lang.String DEFAULT_OFF_FORMAT

Turns checkstyle reporting off.

See Also:

Constant Field Values

DEFAULT_ON_FORMAT

private static final java.lang.String DEFAULT_ON_FORMAT

Turns checkstyle reporting on.

See Also:

Constant Field Values

DEFAULT_CHECK_FORMAT

private static final java.lang.String DEFAULT_CHECK_FORMAT

Control all checks.

See Also:

Constant Field Values

tags

private final java.util.List<SuppressionCommentFilter.Tag> tags

Tagged comments.

checkC

private boolean checkC

Control whether to check C style comments (/* ... */).

checkCPP

private boolean checkCPP

Control whether to check C++ style comments (//).

offCommentFormat

private java.util.regex.Pattern offCommentFormat

Specify comment pattern to trigger filter to begin suppression.

onCommentFormat

private java.util.regex.Pattern onCommentFormat

Specify comment pattern to trigger filter to end suppression.

checkFormat

private java.lang.String checkFormat

Specify check pattern to suppress.

messageFormat

private java.lang.String messageFormat

Specify message pattern to suppress.

idFormat

private java.lang.String idFormat

Specify check ID pattern to suppress.

fileContentsReference

private java.lang.ref.WeakReference<FileContents> fileContentsReference

References the current FileContents for this filter. Since this is a weak reference to the FileContents, the FileContents can be reclaimed as soon as the strong references in TreeWalker are reassigned to the next FileContents, at which time filtering for the current FileContents is finished.

Constructor Detail

SuppressionCommentFilter

public SuppressionCommentFilter()

Method Detail

setOffCommentFormat

public final void setOffCommentFormat(java.util.regex.Pattern pattern)

Setter to specify comment pattern to trigger filter to begin suppression.

Parameters:

pattern - a pattern.

setOnCommentFormat

public final void setOnCommentFormat(java.util.regex.Pattern pattern)

Setter to specify comment pattern to trigger filter to end suppression.

Parameters:

pattern - a pattern.

getFileContents

private FileContents getFileContents()

Returns FileContents for this filter.

Returns:

the FileContents for this filter.

setFileContents

public void setFileContents(FileContents fileContents)

Set the FileContents for this filter.

Parameters:

fileContents - the FileContents for this filter.

setCheckFormat

public final void setCheckFormat(java.lang.String format)

Setter to specify check pattern to suppress.

Parameters:

format - a String value

setMessageFormat

public void setMessageFormat(java.lang.String format)

Setter to specify message pattern to suppress.

Parameters:

format - a String value

setIdFormat

public void setIdFormat(java.lang.String format)

Setter to specify check ID pattern to suppress.

Parameters:

format - a String value

setCheckCPP

public void setCheckCPP(boolean checkCpp)

Setter to control whether to check C++ style comments (//).

Parameters:

checkCpp - true if C++ comments are checked.

setCheckC

public void setCheckC(boolean checkC)

Setter to control whether to check C style comments (/* ... */).

Parameters:

checkC - true if C comments are checked.

finishLocalSetup

protected void finishLocalSetup()

Description copied from class: AbstractAutomaticBean

Provides a hook to finish the part of this component's setup that was not handled by the bean introspection.

The default implementation does nothing.

Specified by:

finishLocalSetup in class AbstractAutomaticBean

accept

public boolean accept(TreeWalkerAuditEvent event)

Description copied from interface: TreeWalkerFilter

Determines whether or not a filtered TreeWalkerAuditEvent is accepted.

Specified by:

accept in interface TreeWalkerFilter

Parameters:

event - the TreeWalkerAuditEvent to filter.

Returns:

true if the event is accepted.

findNearestMatch

private SuppressionCommentFilter.Tag findNearestMatch(TreeWalkerAuditEvent event)

Finds the nearest comment text tag that matches an audit event. The nearest tag is before the line and column of the event.

Parameters:

event - the TreeWalkerAuditEvent to match.

Returns:

The Tag nearest event.

tagSuppressions

private void tagSuppressions()

Collects all the suppression tags for all comments into a list and sorts the list.

tagSuppressions

private void tagSuppressions(java.util.Collection<TextBlock> comments)

Appends the suppressions in a collection of comments to the full set of suppression tags.

Parameters:

comments - the set of comments.

tagCommentLine

private void tagCommentLine(java.lang.String text,
                            int line,
                            int column)

Tags a string if it matches the format for turning checkstyle reporting on or the format for turning reporting off.

Parameters:

text - the string to tag.

line - the line number of text.

column - the column number of text.

addTag

private void addTag(java.lang.String text,
                    int line,
                    int column,
                    SuppressionCommentFilter.TagType reportingOn)

Adds a Tag to the list of all tags.

Parameters:

text - the text of the tag.

line - the line number of the tag.

column - the column number of the tag.

reportingOn - true if the tag turns checkstyle reporting on.