Package com.puppycrawl.tools.checkstyle.filters

Class SuppressWithPlainTextCommentFilter

java.lang.Object

com.puppycrawl.tools.checkstyle.AbstractAutomaticBean

com.puppycrawl.tools.checkstyle.filters.SuppressWithPlainTextCommentFilter

All Implemented Interfaces:

Configurable, Contextualizable, Filter

public class SuppressWithPlainTextCommentFilter
extends AbstractAutomaticBean
implements Filter

Filter SuppressWithPlainTextCommentFilter uses plain text to suppress audit events. The filter can be used only to suppress audit events received from the checks which implement FileSetCheck interface. In other words, the checks which have Checker as a parent module. The filter knows nothing about AST, it treats only plain text comments and extracts the information required for suppression from the plain text comments. Currently, the filter supports only single-line comments.

Please, be aware of the fact that, it is not recommended to use the filter for Java code anymore, however you still are able to use it to suppress audit events received from the checks which implement FileSetCheck interface.

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.

Properties offCommentFormat and onCommentFormat must have equal paren counts.

SuppressionWithPlainTextCommentFilter can suppress Checks that have Treewalker or Checker as parent module.

• Property checkFormat - Specify check pattern to suppress. Type is java.util.regex.Pattern. Default value is ".*".
• Property idFormat - Specify check ID pattern to suppress. Type is java.util.regex.Pattern. Default value is null.
• Property messageFormat - Specify message pattern to suppress. Type is java.util.regex.Pattern. Default value is null.
• 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".

Parent is com.puppycrawl.tools.checkstyle.Checker

Since:

8.6

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static final class	SuppressWithPlainTextCommentFilter.Suppression	The class which represents the suppression.
private static enum	SuppressWithPlainTextCommentFilter.SuppressionType	Enum which represents the type of the suppression.

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

AbstractAutomaticBean.OutputStreamOptions

Field Summary

Fields

Modifier and Type	Field	Description
private String	checkFormat	Specify check pattern to suppress.
private static final String	DEFAULT_CHECK_FORMAT	Default check format to suppress.
private static final String	DEFAULT_OFF_FORMAT	Comment format which turns checkstyle reporting off.
private static final String	DEFAULT_ON_FORMAT	Comment format which turns checkstyle reporting on.
private String	idFormat	Specify check ID pattern to suppress.
private String	messageFormat	Specify message pattern to suppress.
private Pattern	offCommentFormat	Specify comment pattern to trigger filter to begin suppression.
private Pattern	onCommentFormat	Specify comment pattern to trigger filter to end suppression.

Constructor Summary

Constructors

Constructor	Description
SuppressWithPlainTextCommentFilter()

Method Summary

Modifier and Type	Method	Description
boolean	accept(AuditEvent event)	Determines whether or not a filtered AuditEvent is accepted.
protected void	finishLocalSetup()	Provides a hook to finish the part of this component's setup that was not handled by the bean introspection.
private static FileText	getFileText(String fileName)	Returns FileText instance created based on the given file name.
private static SuppressWithPlainTextCommentFilter.Suppression	getNearestSuppression(Collection<SuppressWithPlainTextCommentFilter.Suppression> suppressions, AuditEvent event)	Finds the nearest SuppressWithPlainTextCommentFilter.Suppression instance which can suppress the given AuditEvent.
private Optional<SuppressWithPlainTextCommentFilter.Suppression>	getSuppression(FileText fileText, int lineNo)	Tries to extract the suppression from the given line.
private List<SuppressWithPlainTextCommentFilter.Suppression>	getSuppressions(FileText fileText)	Returns the list of SuppressWithPlainTextCommentFilter.Suppression instances retrieved from the given FileText.
final void	setCheckFormat(String format)	Setter to specify check pattern to suppress.
final void	setIdFormat(String format)	Setter to specify check ID pattern to suppress.
final void	setMessageFormat(String format)	Setter to specify message pattern to suppress.
final void	setOffCommentFormat(Pattern pattern)	Setter to specify comment pattern to trigger filter to begin suppression.
final void	setOnCommentFormat(Pattern pattern)	Setter to specify comment pattern to trigger filter to end suppression.

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 Details

DEFAULT_OFF_FORMAT

private static final String DEFAULT_OFF_FORMAT

Comment format which turns checkstyle reporting off.

See Also:

• Constant Field Values

DEFAULT_ON_FORMAT

private static final String DEFAULT_ON_FORMAT

Comment format which turns checkstyle reporting on.

See Also:

• Constant Field Values

DEFAULT_CHECK_FORMAT

private static final String DEFAULT_CHECK_FORMAT

Default check format to suppress. By default, the filter suppress all checks.

See Also:

• Constant Field Values

offCommentFormat

private Pattern offCommentFormat

Specify comment pattern to trigger filter to begin suppression.

onCommentFormat

private Pattern onCommentFormat

Specify comment pattern to trigger filter to end suppression.

checkFormat

private String checkFormat

Specify check pattern to suppress.

messageFormat

private String messageFormat

Specify message pattern to suppress.

idFormat

private String idFormat

Specify check ID pattern to suppress.

Constructor Details

SuppressWithPlainTextCommentFilter

public SuppressWithPlainTextCommentFilter()

Method Details

setOffCommentFormat

public final void setOffCommentFormat(Pattern pattern)

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

Parameters:

pattern - off comment format pattern.

Since:

8.6

setOnCommentFormat

public final void setOnCommentFormat(Pattern pattern)

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

Parameters:

pattern - on comment format pattern.

Since:

8.6

setCheckFormat

public final void setCheckFormat(String format)

Setter to specify check pattern to suppress.

Parameters:

format - pattern for check format.

Since:

8.6

setMessageFormat

public final void setMessageFormat(String format)

Setter to specify message pattern to suppress.

Parameters:

format - pattern for message format.

Since:

8.6

setIdFormat

public final void setIdFormat(String format)

Setter to specify check ID pattern to suppress.

Parameters:

format - pattern for check ID format

Since:

8.24

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.

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

getFileText

private static FileText getFileText(String fileName)

Returns FileText instance created based on the given file name.

Parameters:

fileName - the name of the file.

Returns:

FileText instance.

Throws:

IllegalStateException - if the file could not be read.

getSuppressions

private List<SuppressWithPlainTextCommentFilter.Suppression> getSuppressions(FileText fileText)

Returns the list of SuppressWithPlainTextCommentFilter.Suppression instances retrieved from the given FileText.

Parameters:

fileText - FileText instance.

Returns:

list of SuppressWithPlainTextCommentFilter.Suppression instances.

getSuppression

private Optional<SuppressWithPlainTextCommentFilter.Suppression> getSuppression(FileText fileText,
 int lineNo)

Tries to extract the suppression from the given line.

Parameters:

fileText - FileText instance.

lineNo - line number.

Returns:

Optional of SuppressWithPlainTextCommentFilter.Suppression.

getNearestSuppression

private static SuppressWithPlainTextCommentFilter.Suppression getNearestSuppression(Collection<SuppressWithPlainTextCommentFilter.Suppression> suppressions,
 AuditEvent event)

Finds the nearest SuppressWithPlainTextCommentFilter.Suppression instance which can suppress the given AuditEvent. The nearest suppression is the suppression which scope is before the line and column of the event.

Parameters:

suppressions - collection of SuppressWithPlainTextCommentFilter.Suppression instances.

event - AuditEvent instance.

Returns:

SuppressWithPlainTextCommentFilter.Suppression instance.