forbiddenapis-3.8.src.main.docs.ant-task.html Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of forbiddenapis

Allows to parse Java byte code to find invocations of method/class/field signatures and fail build (Apache Ant, Apache Maven, Gradle, or CLI)

The newest version!





Ant Task Documentation



Ant Task Documentation

Description

Task to check if a set of class files contains calls to forbidden APIs
from a given classpath and list of API signatures (either inline or as pointer to files).
In contrast to other ANT tasks, this tool does only visit the given classpath
and the system classloader, not ANT's class loader.

Parameters




  Name
  Type
  Default
  Description



  dir
  File
  
  Directory to scan for class files. This directory is automatically converted to a FileSet with **/*.class as include pattern.



  signaturesFile
  File
  
  A single signatures file.



  bundledSignatures
  String
  
  Name of a built-in signatures file.



  classpath
  Path
  
  Classpath in ANT format. Should be identical to classpath used for compiling the class files.



  classpathref
  Reference
  
  Reference to a path defined anywhere else. Should be identical to classpath used for compiling the class files.



  disableClassloadingCache
  boolean
  false
  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.



  failOnUnsupportedJava
  boolean
  false
  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.



  failOnMissingClasses
  boolean
  true
  Fail the build, if a referenced class is missing. This requires that you pass the whole classpath including all dependencies.
  If you don't have all classes in the filesets, the application classes must be reachable through this classpath, too.



  failOnUnresolvableSignatures
  boolean
  true
  Fail the build if a signature is not resolving. If this parameter is set to
   to false, then such signatures are ignored.

   When disabling this setting, the task still prints a warning to inform the user about
   broken signatures. This cannot be disabled. There is a second setting
   ignoreSignaturesOfMissingClasses that can be used to silently ignore
   signatures that refer to methods or field in classes that are not on classpath,
   e.g. This is useful in multi-module builds where a common set of signatures is used,
   that are not part of every sub-modules dependencies.

  Deprecated. Use ignoreSignaturesOfMissingClasses instead.



  failOnViolation
  boolean
  true
  Fail the build if violations have been found. If this parameter is set to false, then the build will continue even if violations have been found.



  restrictClassFilename
  boolean
  true
  Automatically restrict resource names included to files with a name ending in '.class'. This makes filesets easier, as the includes="**/*.class" is not needed.



  ignoreEmptyFileset
  boolean
  false
  Ignore empty fileset/resource collection and print a warning instead.



  ignoreSignaturesOfMissingClasses
  boolean
  false
  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
   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.



  suppressAnnotation
  class name
  
  Class name of a custom Java annotation that are used in the checked
  code to suppress errors. This annotation must have at least
  RetentionPolicy#CLASS. It 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
  
  The 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 when invoking javac.




Parameters specified as nested elements

This task supports all Ant resource types
(fileset, filelist, file, tarfileset, zipfileset,...)
and uses all class files from them. It automatically adds an implcit filter to file names ending in '.class',
so you don't need to add this as include attribute to those collections.

You can also pass one or multiple classpath elements to form a classpath. Ideally use the same configuration like the javac task.

To pass in signatures, you have several possibilities:


  Use bundledSignatures element to pass a built-in signatures file, e.g. <bundledsignatures name="jdk-unsafe" targetVersion="1.7"/>
  Use signatures element to wrap any valid Ant resource type (filesets,..). May also be used to wrap <bundled name="jdk-unsafe" targetVersion="1.7"/>
  Alternatively, use signaturesFileSet, signaturesFileList, signaturesFile elements to pass in collections of signatures files. Those elements behave like the corresponding standard Ant types.
  Place signatures as plain text (use CDATA sections) inside the forbiddenapis element.


You can include multiple <suppressAnnotation classname="..."> elements to specify class names of custom Java annotations 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).

Name	Type	Default	Description
dir	`File`		Directory to scan for class files. This directory is automatically converted to a `FileSet` with `*/.class` as include pattern.
signaturesFile	`File`		A single signatures file.
bundledSignatures	`String`		Name of a built-in signatures file.
classpath	`Path`		Classpath in ANT format. Should be identical to classpath used for compiling the class files.
classpathref	`Reference`		Reference to a `path` defined anywhere else. Should be identical to classpath used for compiling the class files.
disableClassloadingCache	`boolean`	`false`	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 `FileNotFoundException`s related to non-existent JAR entries you can try to work around using this setting.
failOnUnsupportedJava	`boolean`	`false`	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.
failOnMissingClasses	`boolean`	`true`	Fail the build, if a referenced class is missing. This requires that you pass the whole classpath including all dependencies. If you don't have all classes in the filesets, the application classes must be reachable through this classpath, too.
failOnUnresolvableSignatures	`boolean`	`true`	Fail the build if a signature is not resolving. If this parameter is set to to false, then such signatures are ignored. When disabling this setting, the task still prints a warning to inform the user about broken signatures. This cannot be disabled. There is a second setting `ignoreSignaturesOfMissingClasses` that can be used to silently ignore signatures that refer to methods or field in classes that are not on classpath, e.g. This is useful in multi-module builds where a common set of signatures is used, that are not part of every sub-modules dependencies. Deprecated. Use `ignoreSignaturesOfMissingClasses` instead.
failOnViolation	`boolean`	`true`	Fail the build if violations have been found. If this parameter is set to `false`, then the build will continue even if violations have been found.
restrictClassFilename	`boolean`	`true`	Automatically restrict resource names included to files with a name ending in `'.class'`. This makes filesets easier, as the `includes="*/.class"` is not needed.
ignoreEmptyFileset	`boolean`	`false`	Ignore empty fileset/resource collection and print a warning instead.
ignoreSignaturesOfMissingClasses	`boolean`	`false`	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 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.
suppressAnnotation	`class name`		Class name of a custom Java annotation that are used in the checked code to suppress errors. This annotation must have at least `RetentionPolicy#CLASS`. It 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`		The 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 when invoking `javac`.