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 futher 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"]
      },
      "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>
      </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.
archives: This provides a way to include/exclude whole archives or elements (i.e. whole maven modules)
include: The array of (java) regular expressions that the elements or archives need to match to be included in the analysis.
exclude: The array of (java) regular expressions that the elements or archives 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>
      </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\\..*"]
      },
      "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. In addition, the analysis will only check elements from the archive specified archive. In this example we’re supposing the configuration is for the maven plugin which recognizes archives by GAVs. In the example therefore we’re limiting the checks to the archive with the groupId com.acme and artifactId acme-foo in any packaging type and version.