Class 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.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      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 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
      • 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.