forbiddenapis:check

Full name:

de.thetaphi:forbiddenapis:2.7:check

Description:

Mojo to check if no project generated class files (compile scope) contain calls to forbidden APIs from the project classpath and a list of API signatures (either inline or as pointer to files or bundled signatures). At least one signature must be given, using any of the corresponding optional parameters.

This Mojo exists since version 1.2, replacing the old forbiddenapis:forbiddenapis goal. In most cases its enough to rename the goal on update, the older v1.0 properties are still available.

Since version 2.0 this Mojo defaults to run in the 'verify' lifecycle phase, before it was done in 'process-classes' phase, which caused problems for some users (especially debugging tests).

Attributes:

Optional Parameters

Name Type Since Description
bundledSignatures String[] 1.0 Specifies built-in signatures files (e.g., deprecated APIs for specific Java versions, unsafe method calls using default locale, default charset,...)
classesDirectory File 1.2 Directory with the class files to check.
Default value is: ${project.build.outputDirectory}.
disableClassloadingCache boolean 2.2 Disable the internal JVM classloading cache when getting bytecode from the classpath. This setting slows down checks, but may work around issues with other Mojos, that do not close their class loaders. If you get FileNotFoundExceptions related to non-existent JAR entries you can try to work around using this setting.
Default value is: false.
excludes String[] 1.0 List of patterns matching class files to be excluded from checking.
failOnMissingClasses boolean 1.0 Fail the build, if a class referenced in the scanned code is missing. This requires that you pass the whole classpath including all dependencies to this Mojo (Maven does this by default).
Default value is: true.
failOnUnresolvableSignatures boolean 1.4 Fail the build if a signature is not resolving. If this parameter is set to to false, then such signatures 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.
Default value is: true.
failOnUnsupportedJava boolean 1.0 Fail the build, if the bundled ASM library cannot read the class file format of the runtime library or the runtime library cannot be discovered.
Default value is: false.
failOnViolation boolean 2.0 Fail the build if violations have been found. Defaults to true.
Default value is: true.
User property is: forbiddenapis.failOnViolation.
includes String[] 1.0 List of patterns matching all class files to be parsed from the classesDirectory. Can be changed to e.g. exclude several files (using excludes). The default is a single include with pattern '**/*.class'
internalRuntimeForbidden boolean 1.0 Deprecated. Use bundled signatures "jdk-non-portable" or "jdk-internal" instead.
Default value is: false.
signatures String 1.0 Gives a multiline list of signatures, inline in the pom.xml. Use an XML CDATA section to do that! The signatures are resolved against the compile classpath.
signaturesArtifacts SignaturesArtifact[] 2.0 Lists all Maven artifacts, which contain signatures and comments for forbidden API calls. The artifact needs to be specified like a Maven dependency. Resolution is not transitive. You can refer to plain text Maven artifacts (type="txt", e.g., with a separate classifier):
<signaturesArtifact>
  <groupId>org.apache.foobar</groupId>
  <artifactId>example</artifactId>
  <version>1.0</version>
  <classifier>signatures</classifier>
  <type>txt</type>
</signaturesArtifact>
Alternatively, refer to signatures files inside JAR artifacts. In that case, the additional parameter path has to be given:
<signaturesArtifact>
  <groupId>org.apache.foobar</groupId>
  <artifactId>example</artifactId>
  <version>1.0</version>
  <type>jar</type>
  <path>path/inside/jar/file/signatures.txt</path>
</signaturesArtifact>

The signatures are resolved against the compile classpath.


signaturesFiles File[] 1.0 Lists all files, which contain signatures and comments for forbidden API calls. The signatures are resolved against the compile classpath.
skip boolean 1.6 Skip entire check. Most useful on the command line via "-Dforbiddenapis.skip=true".
Default value is: false.
User property is: forbiddenapis.skip.
suppressAnnotations String[] 1.8 List of a custom Java annotations (full class names) that are used in the checked code to suppress errors. Those annotations must have at least RetentionPolicy.CLASS. They can be applied to classes, their methods, or fields. By default, @de.thetaphi.forbiddenapis.SuppressForbidden can always be used, but needs the forbidden-apis.jar file in classpath of compiled project, which may not be wanted. Instead of a full class name, a glob pattern may be used (e.g., **.SuppressForbidden).
targetVersion String 1.0 The default compiler target version used to expand references to bundled JDK signatures. E.g., if you use "jdk-deprecated", it will expand to this version. This setting should be identical to the target version used in the compiler plugin.
Default value is: ${maven.compiler.target}.

Parameter Details

bundledSignatures:

Specifies built-in signatures files (e.g., deprecated APIs for specific Java versions, unsafe method calls using default locale, default charset,...)

classesDirectory:

Directory with the class files to check.

disableClassloadingCache:

Disable the internal JVM classloading cache when getting bytecode from the classpath. This setting slows down checks, but may work around issues with other Mojos, that do not close their class loaders. If you get FileNotFoundExceptions related to non-existent JAR entries you can try to work around using this setting.

excludes:

List of patterns matching class files to be excluded from checking.

failOnMissingClasses:

Fail the build, if a class referenced in the scanned code is missing. This requires that you pass the whole classpath including all dependencies to this Mojo (Maven does this by default).

failOnUnresolvableSignatures:

Fail the build if a signature is not resolving. If this parameter is set to to false, then such signatures 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.

failOnUnsupportedJava:

Fail the build, if the bundled ASM library cannot read the class file format of the runtime library or the runtime library cannot be discovered.

failOnViolation:

Fail the build if violations have been found. Defaults to true.

includes:

List of patterns matching all class files to be parsed from the classesDirectory. Can be changed to e.g. exclude several files (using excludes). The default is a single include with pattern '**/*.class'

internalRuntimeForbidden:

Deprecated. Use bundled signatures "jdk-non-portable" or "jdk-internal" instead.
Forbids calls to non-portable runtime APIs (like sun.misc.Unsafe). Please note: This enables "jdk-non-portable" bundled signatures for backwards compatibility.

signatures:

Gives a multiline list of signatures, inline in the pom.xml. Use an XML CDATA section to do that! The signatures are resolved against the compile classpath.

signaturesArtifacts:

Lists all Maven artifacts, which contain signatures and comments for forbidden API calls. The artifact needs to be specified like a Maven dependency. Resolution is not transitive. You can refer to plain text Maven artifacts (type="txt", e.g., with a separate classifier):
<signaturesArtifact>
  <groupId>org.apache.foobar</groupId>
  <artifactId>example</artifactId>
  <version>1.0</version>
  <classifier>signatures</classifier>
  <type>txt</type>
</signaturesArtifact>
Alternatively, refer to signatures files inside JAR artifacts. In that case, the additional parameter path has to be given:
<signaturesArtifact>
  <groupId>org.apache.foobar</groupId>
  <artifactId>example</artifactId>
  <version>1.0</version>
  <type>jar</type>
  <path>path/inside/jar/file/signatures.txt</path>
</signaturesArtifact>

The signatures are resolved against the compile classpath.


signaturesFiles:

Lists all files, which contain signatures and comments for forbidden API calls. The signatures are resolved against the compile classpath.

skip:

Skip entire check. Most useful on the command line via "-Dforbiddenapis.skip=true".

suppressAnnotations:

List of a custom Java annotations (full class names) that are used in the checked code to suppress errors. Those annotations must have at least RetentionPolicy.CLASS. They can be applied to classes, their methods, or fields. By default, @de.thetaphi.forbiddenapis.SuppressForbidden can always be used, but needs the forbidden-apis.jar file in classpath of compiled project, which may not be wanted. Instead of a full class name, a glob pattern may be used (e.g., **.SuppressForbidden).

targetVersion:

The default compiler target version used to expand references to bundled JDK signatures. E.g., if you use "jdk-deprecated", it will expand to this version. This setting should be identical to the target version used in the compiler plugin.