MavenUsage

Maven Usage Instructions

To use the forbidden API checker in Maven, use the following template to include the plugin:

<properties>
  <!-- 
   It is recommended to set the compiler version globally,
   as the compiler plugin and the forbidden API checker both
   use this version
  -->
  <maven.compiler.target>1.7</maven.compiler.target>
</properties>

<build>
  <plugins>
    <plugin>
      <groupId>de.thetaphi</groupId>
      <artifactId>forbiddenapis</artifactId>
      <version>3.8</version>
      <configuration>
        <!--
          if the used Java version is too new,
          don't fail, just do nothing:
        -->
        <failOnUnsupportedJava>false</failOnUnsupportedJava>
        <!--
          If a class is missing while parsing signatures files, all methods
          and fields from this class are silently ignored. This is useful
          in multi-module Maven projects where only some modules have the
          dependency to which the signature file(s) apply.
          
          This settings prints no warning at all, so verify the signatures
          at least once with full dependencies.
        -->
        <ignoreSignaturesOfMissingClasses>true</ignoreSignaturesOfMissingClasses>
        <bundledSignatures>
          <!--
            This will automatically choose the right
            signatures based on 'maven.compiler.target':
          -->
          <bundledSignature>jdk-unsafe</bundledSignature>
          <bundledSignature>jdk-deprecated</bundledSignature>
          <!-- disallow undocumented classes like sun.misc.Unsafe: -->
          <bundledSignature>jdk-non-portable</bundledSignature>
          <!-- don't allow unsafe reflective access: -->
          <bundledSignature>jdk-reflection</bundledSignature>
        </bundledSignatures>
        <signaturesFiles>
          <signaturesFile>./rel/path/to/signatures.txt</signaturesFile>
        </signaturesFiles>
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>check</goal>
            <goal>testCheck</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
  <!-- more build settings here... -->
</build>

The possible <bundledSignatures> can be found on a separate page. You can also give your own signatures in separate files from your project directory.

Since version 1.2 the goal was renamed to "check" and "testCheck" (to check the test classes) was added. Since version 2.0, the plugin runs by default in the verify lifecycle phase. Of course, you can assign any other phase, like the previous process-classes / process-test-classes.

The detailed documentation (based on nightly snapshots) can be found here: https://jenkins.thetaphi.de/job/Forbidden-APIs/javadoc/

Suppression of specific classes

Suppression of generated classes

You can suppress generated classes by using an annotation. Unfortunately this only works, if those classes are annotated with at least a CLASS or RUNTIME annotation. SOURCE annotations do not work.

Those usually have one of those annotations:

<build>
  <plugins>
    <plugin>
      <groupId>de.thetaphi</groupId>
      <artifactId>forbiddenapis</artifactId>
      <configuration>
        <suppressAnnotations>
          <!-- immutables.org -->
          <suppressAnnotation>org.immutables.value.Generated</suppressAnnotation>
          <!-- Project Lombok -->
          <suppressAnnotation>api.lombok.Generated</suppressAnnotation>
          <!-- The following ones do not work (source only): -->
          <!--<suppressAnnotation>javax.processing.Generated</suppressAnnotation>-->
          <!--<suppressAnnotation>javax.annotation.processing.Generated</suppressAnnotation>-->
        </suppressAnnotations>
      </configuration>
    </plugin>
  </plugins>
</build>