Package com.puppycrawl.tools.checkstyle.filters

Class SuppressionXpathFilter

java.lang.Object
com.puppycrawl.tools.checkstyle.AbstractAutomaticBean
com.puppycrawl.tools.checkstyle.filters.SuppressionXpathFilter
All Implemented Interfaces:
Configurable, Contextualizable, ExternalResourceHolder, TreeWalkerFilter
public class SuppressionXpathFilter extends AbstractAutomaticBean implements TreeWalkerFilter, ExternalResourceHolder
Filter SuppressionXpathFilter works as SuppressionFilter, but also processes suppress-xpath elements, which contain xpath-expressions. Xpath-expressions are queries for suppressed nodes inside the AST tree.

Currently, filter does not support the following checks:

  • NoCodeInFile (reason is that AST is not generated for a file not containing code)
  • Regexp (reason is at #7759)
  • RegexpSinglelineJava (reason is at #7759)

Also, the filter does not support suppressions inside javadoc reported by Javadoc checks:

  • AtclauseOrder
  • JavadocBlockTagLocation
  • JavadocMethod
  • JavadocMissingLeadingAsterisk
  • JavadocMissingWhitespaceAfterAsterisk
  • JavadocParagraph
  • JavadocStyle
  • JavadocTagContinuationIndentation
  • JavadocType
  • MissingDeprecated
  • NonEmptyAtclauseDescription
  • RequireEmptyLineBeforeBlockTagGroup
  • SingleLineJavadoc
  • SummaryJavadoc
  • WriteTag

Note, that support for these Checks will be available after resolving issue #5770.

Currently, filter supports the following xpath axes:

  • ancestor
  • ancestor-or-self
  • attribute
  • child
  • descendant
  • descendant-or-self
  • following
  • following-sibling
  • parent
  • preceding
  • preceding-sibling
  • self

You can use the command line helper tool to generate xpath suppressions based on your configuration file and input files. See here for more details.

Notes: The suppression file location is checked in following order:

  1. as a filesystem location
  2. if no file found, and the location starts with either http:// or https://, then it is interpreted as a URL
  3. if no file found, then passed to the ClassLoader.getResource() method.

SuppressionXpathFilter can suppress Checks that have Treewalker as parent module.

A suppressions XML document contains a set of suppress and suppress-xpath elements, where each suppress-xpath element can have the following attributes:

  • files - a Pattern matched against the file name associated with an audit event. It is optional.
  • checks - a Pattern matched against the name of the check associated with an audit event. Optional as long as id or message is specified.
  • message - a Pattern matched against the message of the check associated with an audit event. Optional as long as checks or id is specified.
  • id - a String matched against the ID of the check associated with an audit event. Optional as long as checks or message is specified.
  • query - a String xpath query. It is optional.

Each audit event is checked against each suppress and suppress-xpath element. It is suppressed if all specified attributes match against the audit event.

ATTENTION: filtering by message is dependent on runtime locale. If project is running in different languages it is better to avoid filtering by message.

Since:
8.6

  • Field Details

    • filters

      private final Set<TreeWalkerFilter> filters
      Set of individual xpath suppresses.

    • file

      private String file
      Specify the location of the suppressions XML document file.

    • optional

      private boolean optional
      Control what to do when the file is not existing. If optional is set to false the file must exist, or else it ends with error. On the other hand if optional is true and file is not found, the filter accepts all audit events.

  • Constructor Details

  • Method Details

    • setFile

      public void setFile(String fileName)
      Setter to specify the location of the suppressions XML document file.
      Parameters:
      fileName - name of the suppressions file.
      Since:
      8.6

    • setOptional

      public void setOptional(boolean optional)
      Setter to control what to do when the file is not existing. If optional is set to false the file must exist, or else it ends with error. On the other hand if optional is true and file is not found, the filter accepts all audit events.
      Parameters:
      optional - tells if config file existence is optional.
      Since:
      8.6

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • accept

      public boolean accept(TreeWalkerAuditEvent treeWalkerAuditEvent)
      Description copied from interface: TreeWalkerFilter
      Determines whether or not a filtered TreeWalkerAuditEvent is accepted.
      Specified by:
      accept in interface TreeWalkerFilter
      Parameters:
      treeWalkerAuditEvent - the TreeWalkerAuditEvent to filter.
      Returns:
      true if the event is accepted.

    • getExternalResourceLocations

      public Set<String> getExternalResourceLocations()
      Description copied from interface: ExternalResourceHolder
      Returns a set of external configuration resource locations which are used by the module. ATTENTION! If 'getExternalResourceLocations()' return null, there will be NullPointerException in Checker. Such behaviour will signal that your module (check or filter) is designed incorrectly. It makes sense to return an empty set from 'getExternalResourceLocations()' only for composite modules like TreeWalker.
      Specified by:
      getExternalResourceLocations in interface ExternalResourceHolder
      Returns:
      a set of external configuration resource locations which are used by the module.

    • finishLocalSetup

      protected void finishLocalSetup() throws CheckstyleException
      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
      Throws:
      CheckstyleException - if there is a configuration error.