Linkage Checker Exclusion File

A Linkage Checker exclusion file is an XML file to specify exclusion rules for linkage errors.

A linkage error is an invalid reference from a class to a symbol in another class. A symbol may be a class, a method, or a field. We call the referencing class “source”, and the referenced symbol as “target”. The relationship is illustrated below. The allow indicates an invalid reference from a source class to a target symbol.

For the example usage of this file, refer to Default Exclusion Rules section.

Format

The exclusion file is an XML file (See a complete example file is in Example). Its top-level element is LinkageCheckerFilter.

Elements

• A LinkageCheckerFilter element has zero or more LinkageError elements.
• A LinkageError element has at least one of Target element and Source element. It also has optional Reason element.
• A Target element has one Package, Class, Method, and Field elements.
• A Source element has one Package, and Class elements.
• A Reason element has a text node to explain why it is fine to suppress the linkage error.

Attributes

• Package, Class, Method, and Field elements have “name” attribute.
  • A package's name works as a prefix match. Package name "com.google" matches "com.google.common.ImmutableList", for exmaple.
• Method and Field elements have “className” attribute.

Example

Here is an excerpt from the default exclusion XML file. It filters linkage error by source and target.

<LinkageCheckerFilter>
  <LinkageError>
    <Source>
      <Package name="reactor.core.publisher" />
    </Source>
    <Reason>
      reactor-core's Traces catches Throwable to detect classes available in
      Java 9+. As Linkage Checker targets Java 8, it ignores these errors to avoid
      false positives.
      https://github.com/GoogleCloudPlatform/cloud-opensource-java/issues/816
    </Reason>
  </LinkageError>

  <LinkageError>
    <Target>
      <Package name="jdk.vm.ci" />
    </Target>
    <Source>
      <Package name="com.oracle.svm" />
    </Source>
    <Reason>
      GraalVM-related libraries depend on Java Compiler Interface (JVMCI) that
      only exists in special JDK. These missing classes are false positives, because
      the code is only invoked when running in a GraalVM.
      https://github.com/GoogleCloudPlatform/cloud-opensource-java/issues/929
    </Reason>
  </LinkageError>
</LinkageCheckerFilter>

Default Exclusion Rules

By default, Linkage Checker uses exclusion rules in linkage-checker-exclusion-default.xml.