Package com.puppycrawl.tools.checkstyle.filters

Class SuppressionCommentFilter

java.lang.Object

com.puppycrawl.tools.checkstyle.api.AutomaticBean

com.puppycrawl.tools.checkstyle.filters.SuppressionCommentFilter

All Implemented Interfaces:

Configurable, Contextualizable, Filter

public class SuppressionCommentFilter
extends AutomaticBean
implements Filter

A filter that uses 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.

Usage: This check only works in conjunction with the FileContentsHolder module since that module makes the suppression comments in the .java files available sub rosa.

See Also:

FileContentsHolder

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	SuppressionCommentFilter.Tag	A Tag holds a suppression comment and its location, and determines whether the suppression turns checkstyle reporting on or off.

Field Summary

Fields

Modifier and Type	Field	Description
private boolean	checkC	Whether to look in comments of the C type.
private boolean	checkCPP	Whether to look in comments of the C++ type.
private java.lang.String	checkFormat	The check format 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	messageFormat	The message format to suppress.
private java.util.regex.Pattern	offCommentFormat	Parsed comment regexp that turns checkstyle reporting off.
private java.util.regex.Pattern	onCommentFormat	Parsed comment regexp that turns checkstyle reporting on.
private java.util.List<SuppressionCommentFilter.Tag>	tags	Tagged comments.

Constructor Summary

Constructors

Constructor	Description
SuppressionCommentFilter()

Method Summary

Modifier and Type	Method	Description
boolean	accept(AuditEvent event)	Determines whether or not a filtered AuditEvent is accepted.
private void	addTag(java.lang.String text, int line, int column, boolean reportingOn)	Adds a Tag to the list of all tags.
private SuppressionCommentFilter.Tag	findNearestMatch(AuditEvent event)	Finds the nearest comment text tag that matches an audit event.
FileContents	getFileContents()	Returns FileContents for this filter.
void	setCheckC(boolean checkC)	Set whether to look in C comments.
void	setCheckCPP(boolean checkCpp)	Set whether to look in C++ comments.
void	setCheckFormat(java.lang.String format)	Set the format for a check.
void	setFileContents(FileContents fileContents)	Set the FileContents for this filter.
void	setMessageFormat(java.lang.String format)	Set the format for a message.
void	setOffCommentFormat(java.util.regex.Pattern pattern)	Set the format for a comment that turns off reporting.
void	setOnCommentFormat(java.util.regex.Pattern pattern)	Set the format for a comment that turns on reporting.
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.api.AutomaticBean

configure, contextualize, finishLocalSetup, 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

Whether to look in comments of the C type.

checkCPP

private boolean checkCPP

Whether to look in comments of the C++ type.

offCommentFormat

private java.util.regex.Pattern offCommentFormat

Parsed comment regexp that turns checkstyle reporting off.

onCommentFormat

private java.util.regex.Pattern onCommentFormat

Parsed comment regexp that turns checkstyle reporting on.

checkFormat

private java.lang.String checkFormat

The check format to suppress.

messageFormat

private java.lang.String messageFormat

The message format 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 and FileContentsHolder 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)

Set the format for a comment that turns off reporting.

Parameters:

pattern - a pattern.

setOnCommentFormat

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

Set the format for a comment that turns on reporting.

Parameters:

pattern - a pattern.

getFileContents

public 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)

Set the format for a check.

Parameters:

format - a String value

setMessageFormat

public void setMessageFormat(java.lang.String format)

Set the format for a message.

Parameters:

format - a String value

setCheckCPP

public void setCheckCPP(boolean checkCpp)

Set whether to look in C++ comments.

Parameters:

checkCpp - true if C++ comments are checked.

setCheckC

public void setCheckC(boolean checkC)

Set whether to look in C comments.

Parameters:

checkC - true if C comments are checked.

accept

public boolean accept(AuditEvent event)

Description copied from interface: Filter

Determines whether or not a filtered AuditEvent is accepted.

Specified by:

accept in interface Filter

Parameters:

event - the AuditEvent to filter.

Returns:

true if the event is accepted.

findNearestMatch

private SuppressionCommentFilter.Tag findNearestMatch(AuditEvent 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 AuditEvent 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,
                    boolean 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.