Element Filter

Extension: revapi.filter

This extension provides a highly configurable element filter (see architecture) that can be used to either filter out certain elements in the APIs from the analysis or to actually restrict the analysis only to configured elements.

If no include or exclude filters are defined, everything is included. If at least 1 include filter is defined, only the matching elements are included. Out of the included elements, some may be further excluded by the provided exclude filters (if any). If only exclude filters are defined, everything but the elements matching the exclude filters is included.

Sample Configuration

[
  {
    "extension": "revapi.filter",
    "configuration" : {
      "elements" : {
        "include" : ["REGEX_ON_ELEMENT_FULL_REPRESENTATIONS", "ANOTHER_REGEX_ON_ELEMENT_FULL_REPRESENTATIONS"],
        "exclude" : [
            "REGEX_ON_ELEMENT_FULL_REPRESENTATIONS",
            "ANOTHER_REGEX_ON_ELEMENT_FULL_REPRESENTATIONS",
            {
                "matcher": "java",
                "match": "@Beta ^*;"
            }
        ]
      },
      "archives" : {
        "include" : ["REGEX_ON_ARCHIVE_NAMES", "ANOTHER_REGEX_ON_ARCHIVE_NAMES"],
        "exclude" : ["REGEX_ON_ARCHIVE_NAMES", "ANOTHER_REGEX_ON_ARCHIVE_NAMES"]
      }
    }
  }
]

<analysisConfiguration>
  <revapi.filter>
    <elements>
      <include>
        <item>REGEX_ON_ELEMENT_FULL_REPRESENTATIONS</item>
        <item>ANOTHER_REGEX_ON_ELEMENT_FULL_REPRESENTATIONS</item>
      </include>
      <exclude>
        <item>REGEX_ON_ELEMENT_FULL_REPRESENTATIONS</item>
        <item>ANOTHER_REGEX_ON_ELEMENT_FULL_REPRESENTATIONS</item>
        <item>
            <matcher>java</matcher>
            <match>@Beta ^*;</match>
        </item>
      </exclude>
    </elements>
    <archives>
      <include>
        <item>REGEX_ON_ARCHIVE_NAMES</item>
        <item>ANOTHER_REGEX_ON_ARCHIVE_NAMES</item>
      </include>
      <exclude>
        <item>REGEX_ON_ARCHIVE_NAMES</item>
        <item>ANOTHER_REGEX_ON_ARCHIVE_NAMES</item>
      </exclude>
    </archives>
  </revapi.filter>
</analysisConfiguration>

Properties

elements

This provides the include/exclude configuration on the individual API elements level.

include: The array of regular expressions (matching the textual representation of elements) or element matcher definitions for elements to be included in the analysis.
exclude: The array of regular expressions (matching the textual representation of elements) or element matcher definitions for elements to be excluded from the analysis.

archives

This provides a way to include/exclude whole archives or elements (i.e. whole maven modules)

include: The array of regular expressions that the archive names need to match to be included in the analysis.
exclude: The array of regular expressions that the archive names need to match to be excluded from the analysis.

Example

By specifying the following configuration:

<analysisConfiguration>
  <revapi.filter>
    <elements>
      <exclude>
        <item>class my\.great\.app\..*\.impl\..*</item>
        <item>
            <matcher>java</matcher>
            <match>type ^* extends my.great.app.InternalProcessor {}</match>
        </item>
      </exclude>
    </elements>
    <archives>
      <include>
        <item>com\.acme:acme-foo:.*</item>
      </include>
    </archives>
  </revapi.filter>
</analysisConfiguration>

or equivalently

[
  {
    "extension": "revapi.filter",
    "configuration": {
      "elements": {
        "exclude" : [
            "class my\\.great\\.app\\..*\\.impl\\..*",
            {
                "matcher": "java",
                "match": "type ^* extends my.great.app.InternalProcessor {}"
            }
        ]
      },
      "archives": {
        "include" : ["com\\.acme:acme-foo:.*"]
      }
    }
  }
]

all the java classes in any of the impl packages under my.great.app package will be excluded from API checking. Additionaly any subclass of the my.great.app.InternalProcessor will also be excluded from the analysis. In addition, the analysis will only check elements from the specified archives. In this example we suppose the configuration is for the maven plugin which recognizes archives by GAVs. In the example therefore we’re limiting the checks to the archives with the groupId com.acme and artifactId acme-foo in any packaging type and version.

To learn more about the element matching, read Matching Elements.