de.thetaphi.forbiddenapis.gradle
Class CheckForbiddenApis

java.lang.Object
  org.gradle.api.internal.AbstractTask
      org.gradle.api.DefaultTask
          de.thetaphi.forbiddenapis.gradle.CheckForbiddenApis
All Implemented Interfaces:
de.thetaphi.forbiddenapis.Constants, java.lang.Comparable<org.gradle.api.Task>, org.gradle.api.internal.DynamicObjectAware, org.gradle.api.internal.TaskInternal, org.gradle.api.plugins.ExtensionAware, org.gradle.api.Task, org.gradle.api.tasks.util.PatternFilterable, org.gradle.api.tasks.VerificationTask, org.gradle.util.Configurable<org.gradle.api.Task>

public class CheckForbiddenApis
extends org.gradle.api.DefaultTask
implements org.gradle.api.tasks.util.PatternFilterable, org.gradle.api.tasks.VerificationTask, de.thetaphi.forbiddenapis.Constants

ForbiddenApis Gradle Task (requires at least Gradle v2.3)

The plugin registers a separate task for each defined sourceSet using the default task naming convention. For default Java projects, two tasks are created: forbiddenApisMain and forbiddenApisTest. Additional source sets will produce a task with similar names ('forbiddenApis' + nameOfSourceSet). All tasks are added as dependencies to the check default Gradle task. For convenience, the plugin also defines an additional task forbiddenApis that runs checks on all source sets.

Installation can be done from your build.gradle file using the Gradle plugin DSL:

 plugins {
  id 'de.thetaphi.forbiddenapis' version '2.7'
 }
 
Alternatively, you can use the following script snippet if dynamic configuration is required (e.g., for own tasks):
 buildscript {
  repositories {
   mavenCentral()
  }
  dependencies {
   classpath 'de.thetaphi:forbiddenapis:2.7'
  }
 }
 
 apply plugin: 'de.thetaphi.forbiddenapis'
 
After that you can add the following task configuration closures:
 forbiddenApisMain {
  bundledSignatures += 'jdk-system-out'
 }
 
(using the '+=' notation, you can add additional bundled signatures to the defaults).

To define those defaults, which are used by all source sets, you can use the extension / convention mapping provided by CheckForbiddenApisExtension:

 forbiddenApis {
  bundledSignatures = [ 'jdk-unsafe', 'jdk-deprecated' ]
  signaturesFiles = files('path/to/my/signatures.txt')
  ignoreFailures = false
 }
 

Since:
2.0

Nested Class Summary
 
Nested classes/interfaces inherited from interface org.gradle.api.Task
org.gradle.api.Task.Namer
 
Field Summary
 
Fields inherited from interface de.thetaphi.forbiddenapis.Constants
BS_JDK_NONPORTABLE, CLASS_CONSTRUCTOR_METHOD_NAME, CONSTRUCTOR_METHOD_NAME, DEPRECATED_DESCRIPTOR, DEPRECATED_TYPE, DEPRECATED_WARN_INTERNALRUNTIME, JDK_SIG_PATTERN, LAMBDA_META_FACTORY_INTERNALNAME, LAMBDA_METHOD_NAME_PREFIX, SIGNATURE_POLYMORPHIC_DESCRIPTOR, SIGNATURE_POLYMORPHIC_PKG_INTERNALNAME
 
Fields inherited from interface org.gradle.api.Task
TASK_ACTION, TASK_DEPENDS_ON, TASK_DESCRIPTION, TASK_GROUP, TASK_NAME, TASK_OVERWRITE, TASK_TYPE
 
Constructor Summary
CheckForbiddenApis()
           
 
Method Summary
 void checkForbidden()
          Executes the forbidden apis task.
 CheckForbiddenApis exclude(groovy.lang.Closure arg0)
           
 CheckForbiddenApis exclude(java.lang.Iterable<java.lang.String> arg0)
           
 CheckForbiddenApis exclude(org.gradle.api.specs.Spec<org.gradle.api.file.FileTreeElement> arg0)
           
 CheckForbiddenApis exclude(java.lang.String... arg0)
           
 java.util.Set<java.lang.String> getBundledSignatures()
          Specifies built-in signatures files (e.g., deprecated APIs for specific Java versions, unsafe method calls using default locale, default charset,...)
 java.io.File getClassesDir()
          Deprecated. use getClassesDirs() instead. If there are more than one classesDir set by setClassesDirs(FileCollection), this getter may throw an exception!
 org.gradle.api.file.FileCollection getClassesDirs()
          Directories with the class files to check.
 org.gradle.api.file.FileTree getClassFiles()
          Returns the classes to check.
 org.gradle.api.file.FileCollection getClasspath()
          A FileCollection used to configure the classpath.
 boolean getDisableClassloadingCache()
          Disable the internal JVM classloading cache when getting bytecode from the classpath.
 java.util.Set<java.lang.String> getExcludes()
          
 boolean getFailOnMissingClasses()
          Fail the build, if a class referenced in the scanned code is missing.
 boolean getFailOnUnresolvableSignatures()
          Fail the build if a signature is not resolving.
 boolean getFailOnUnsupportedJava()
          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.
 boolean getIgnoreFailures()
          
 java.util.Set<java.lang.String> getIncludes()
          
 boolean getInternalRuntimeForbidden()
          Deprecated. Use bundled signatures "jdk-non-portable" or "jdk-internal" instead.
 org.gradle.api.tasks.util.PatternSet getPatternSet()
          Returns the pattern set to match against class files in getClassesDir().
 java.util.List<java.lang.String> getSignatures()
          Gives multiple API signatures that are joined with newlines and parsed like a single getSignaturesFiles().
 org.gradle.api.file.FileCollection getSignaturesFiles()
          A FileCollection containing all files, which contain signatures and comments for forbidden API calls.
 java.util.Set<java.net.URL> getSignaturesURLs()
          A list of references to URLs, which contain signatures and comments for forbidden API calls.
 java.util.Set<java.lang.String> getSuppressAnnotations()
          List of a custom Java annotations (full class names) that are used in the checked code to suppress errors.
 java.lang.String getTargetCompatibility()
          The default compiler target version used to expand references to bundled JDK signatures.
 CheckForbiddenApis include(groovy.lang.Closure arg0)
           
 CheckForbiddenApis include(java.lang.Iterable<java.lang.String> arg0)
           
 CheckForbiddenApis include(org.gradle.api.specs.Spec<org.gradle.api.file.FileTreeElement> arg0)
           
 CheckForbiddenApis include(java.lang.String... arg0)
           
 void setBundledSignatures(java.util.Set<java.lang.String> bundledSignatures)
           
 void setClassesDir(java.io.File classesDir)
          Deprecated. use setClassesDirs(FileCollection) instead.
 void setClassesDirs(org.gradle.api.file.FileCollection classesDirs)
           
 void setClasspath(org.gradle.api.file.FileCollection classpath)
           
 void setDisableClassloadingCache(boolean disableClassloadingCache)
           
 CheckForbiddenApis setExcludes(java.lang.Iterable<java.lang.String> excludes)
           
 void setFailOnMissingClasses(boolean failOnMissingClasses)
           
 void setFailOnUnresolvableSignatures(boolean failOnUnresolvableSignatures)
           
 void setFailOnUnsupportedJava(boolean failOnUnsupportedJava)
           
 void setIgnoreFailures(boolean ignoreFailures)
           
 CheckForbiddenApis setIncludes(java.lang.Iterable<java.lang.String> includes)
           
 void setInternalRuntimeForbidden(boolean internalRuntimeForbidden)
          Deprecated. Use bundled signatures "jdk-non-portable" or "jdk-internal" instead.
 void setPatternSet(org.gradle.api.tasks.util.PatternSet patternSet)
           
 void setSignatures(java.util.List<java.lang.String> signatures)
           
 void setSignaturesFiles(org.gradle.api.file.FileCollection signaturesFiles)
           
 void setSignaturesURLs(java.util.Set<java.net.URL> signaturesURLs)
           
 void setSuppressAnnotations(java.util.Set<java.lang.String> suppressAnnotations)
           
 void setTargetCompatibility(java.lang.String targetCompatibility)
           
 
Methods inherited from class org.gradle.api.internal.AbstractTask
addValidator, appendParallelSafeAction, compareTo, configure, deleteAllActions, dependsOn, dependsOnTaskDidWork, doFirst, doFirst, doLast, doLast, execute, executeWithoutThrowingTaskFailure, finalizedBy, getActions, getAnt, getAsDynamicObject, getConvention, getDependsOn, getDescription, getDidWork, getEnabled, getExecuter, getExtensions, getFinalizedBy, getGroup, getImpliesSubProjects, getInputs, getLogger, getLogging, getMustRunAfter, getName, getOnlyIf, getOutputs, getPath, getProject, getShouldRunAfter, getStandardOutputCapture, getState, getTaskActions, getTaskDependencies, getTemporaryDir, getTemporaryDirFactory, getValidators, hasProperty, injectIntoNewInstance, isEnabled, isHasCustomActions, leftShift, mustRunAfter, onlyIf, onlyIf, prependParallelSafeAction, property, setActions, setDependsOn, setDescription, setDidWork, setEnabled, setExecuter, setFinalizedBy, setGroup, setImpliesSubProjects, setMustRunAfter, setName, setOnlyIf, setOnlyIf, setProject, setProperty, setShouldRunAfter, shouldRunAfter, toString
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

CheckForbiddenApis

public CheckForbiddenApis()
Method Detail

getClassesDirs

@OutputDirectories
public org.gradle.api.file.FileCollection getClassesDirs()
Directories with the class files to check. Defaults to current sourseSet's output directory (Gradle 2/3) or output directories (Gradle 4.0+).


setClassesDirs

public void setClassesDirs(org.gradle.api.file.FileCollection classesDirs)
See Also:
getClassesDirs()

getClassesDir

@Deprecated
public java.io.File getClassesDir()
Deprecated. use getClassesDirs() instead. If there are more than one classesDir set by setClassesDirs(FileCollection), this getter may throw an exception!

Directory with the class files to check. Defaults to current sourseSet's output directory (Gradle 2/3 only).


setClassesDir

@Deprecated
public void setClassesDir(java.io.File classesDir)
Deprecated. use setClassesDirs(FileCollection) instead.

Sets the directory where to look for classes. Overwrites any value set by setClassesDirs(FileCollection)!

See Also:
getClassesDir()

getPatternSet

public org.gradle.api.tasks.util.PatternSet getPatternSet()
Returns the pattern set to match against class files in getClassesDir().


setPatternSet

public void setPatternSet(org.gradle.api.tasks.util.PatternSet patternSet)
See Also:
getPatternSet()

getClasspath

@InputFiles
public org.gradle.api.file.FileCollection getClasspath()
A FileCollection used to configure the classpath. Defaults to current sourseSet's compile classpath.


setClasspath

public void setClasspath(org.gradle.api.file.FileCollection classpath)
See Also:
getClasspath()

getSignaturesFiles

@InputFiles
@Optional
public org.gradle.api.file.FileCollection getSignaturesFiles()
A FileCollection containing all files, which contain signatures and comments for forbidden API calls. The signatures are resolved against getClasspath().


setSignaturesFiles

public void setSignaturesFiles(org.gradle.api.file.FileCollection signaturesFiles)
See Also:
getSignaturesFiles()

getSignaturesURLs

@Input
@Optional
@Incubating
public java.util.Set<java.net.URL> getSignaturesURLs()
A list of references to URLs, which contain signatures and comments for forbidden API calls. The signatures are resolved against getClasspath().

This property is useful to refer to resources in plugin classpath, e.g., using Class.getResource(String). It is not useful for general gradle builds. Especially, don't use it to refer to resources on foreign servers!


setSignaturesURLs

public void setSignaturesURLs(java.util.Set<java.net.URL> signaturesURLs)
See Also:
getSignaturesURLs()

getSignatures

@Input
@Optional
public java.util.List<java.lang.String> getSignatures()
Gives multiple API signatures that are joined with newlines and parsed like a single getSignaturesFiles(). The signatures are resolved against getClasspath().


setSignatures

public void setSignatures(java.util.List<java.lang.String> signatures)
See Also:
getSignatures()

getBundledSignatures

@Input
@Optional
public java.util.Set<java.lang.String> getBundledSignatures()
Specifies built-in signatures files (e.g., deprecated APIs for specific Java versions, unsafe method calls using default locale, default charset,...)


setBundledSignatures

public void setBundledSignatures(java.util.Set<java.lang.String> bundledSignatures)
See Also:
getBundledSignatures()

getInternalRuntimeForbidden

@Deprecated
@Input
public boolean getInternalRuntimeForbidden()
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. Defaults to false.


setInternalRuntimeForbidden

@Deprecated
public void setInternalRuntimeForbidden(boolean internalRuntimeForbidden)
Deprecated. Use bundled signatures "jdk-non-portable" or "jdk-internal" instead.

See Also:
getInternalRuntimeForbidden()

getFailOnUnsupportedJava

@Input
public boolean getFailOnUnsupportedJava()
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. Defaults to false.


setFailOnUnsupportedJava

public void setFailOnUnsupportedJava(boolean failOnUnsupportedJava)
See Also:
getFailOnUnsupportedJava()

getFailOnMissingClasses

@Input
public boolean getFailOnMissingClasses()
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 task (Gradle does this by default). Defaults to true.


setFailOnMissingClasses

public void setFailOnMissingClasses(boolean failOnMissingClasses)
See Also:
getFailOnMissingClasses()

getFailOnUnresolvableSignatures

@Input
public boolean getFailOnUnresolvableSignatures()
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. Defaults to true.


setFailOnUnresolvableSignatures

public void setFailOnUnresolvableSignatures(boolean failOnUnresolvableSignatures)
See Also:
getFailOnUnresolvableSignatures()

getIgnoreFailures

@Input
public boolean getIgnoreFailures()

This setting is to conform with VerificationTask interface. Other ForbiddenApis implementations use another name: failOnViolation Default is false.

Specified by:
getIgnoreFailures in interface org.gradle.api.tasks.VerificationTask

setIgnoreFailures

public void setIgnoreFailures(boolean ignoreFailures)
Specified by:
setIgnoreFailures in interface org.gradle.api.tasks.VerificationTask

getDisableClassloadingCache

@Input
public boolean getDisableClassloadingCache()
Disable the internal JVM classloading cache when getting bytecode from the classpath. This setting slows down checks, but may work around issues with other plugin, 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.

The default is false, unless the plugin detects that your build is running in the Gradle Daemon (which has this problem), setting the default to true as a consequence.

Since:
2.2

setDisableClassloadingCache

public void setDisableClassloadingCache(boolean disableClassloadingCache)
See Also:
getDisableClassloadingCache()

getSuppressAnnotations

@Input
@Optional
public java.util.Set<java.lang.String> getSuppressAnnotations()
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).


setSuppressAnnotations

public void setSuppressAnnotations(java.util.Set<java.lang.String> suppressAnnotations)
See Also:
getSuppressAnnotations()

getTargetCompatibility

@Input
@Optional
public java.lang.String getTargetCompatibility()
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 task. Defaults to project.targetCompatibility.


setTargetCompatibility

public void setTargetCompatibility(java.lang.String targetCompatibility)
See Also:
getTargetCompatibility()

getIncludes

@Input
public java.util.Set<java.lang.String> getIncludes()

Set 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'

Specified by:
getIncludes in interface org.gradle.api.tasks.util.PatternFilterable

setIncludes

public CheckForbiddenApis setIncludes(java.lang.Iterable<java.lang.String> includes)
Specified by:
setIncludes in interface org.gradle.api.tasks.util.PatternFilterable

getExcludes

@Input
public java.util.Set<java.lang.String> getExcludes()

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

Specified by:
getExcludes in interface org.gradle.api.tasks.util.PatternFilterable

setExcludes

public CheckForbiddenApis setExcludes(java.lang.Iterable<java.lang.String> excludes)
Specified by:
setExcludes in interface org.gradle.api.tasks.util.PatternFilterable

exclude

public CheckForbiddenApis exclude(java.lang.String... arg0)
Specified by:
exclude in interface org.gradle.api.tasks.util.PatternFilterable

exclude

public CheckForbiddenApis exclude(java.lang.Iterable<java.lang.String> arg0)
Specified by:
exclude in interface org.gradle.api.tasks.util.PatternFilterable

exclude

public CheckForbiddenApis exclude(org.gradle.api.specs.Spec<org.gradle.api.file.FileTreeElement> arg0)
Specified by:
exclude in interface org.gradle.api.tasks.util.PatternFilterable

exclude

public CheckForbiddenApis exclude(groovy.lang.Closure arg0)
Specified by:
exclude in interface org.gradle.api.tasks.util.PatternFilterable

include

public CheckForbiddenApis include(java.lang.String... arg0)
Specified by:
include in interface org.gradle.api.tasks.util.PatternFilterable

include

public CheckForbiddenApis include(java.lang.Iterable<java.lang.String> arg0)
Specified by:
include in interface org.gradle.api.tasks.util.PatternFilterable

include

public CheckForbiddenApis include(org.gradle.api.specs.Spec<org.gradle.api.file.FileTreeElement> arg0)
Specified by:
include in interface org.gradle.api.tasks.util.PatternFilterable

include

public CheckForbiddenApis include(groovy.lang.Closure arg0)
Specified by:
include in interface org.gradle.api.tasks.util.PatternFilterable

getClassFiles

@InputFiles
@SkipWhenEmpty
public org.gradle.api.file.FileTree getClassFiles()
Returns the classes to check.


checkForbidden

public void checkForbidden()
                    throws de.thetaphi.forbiddenapis.ForbiddenApiException
Executes the forbidden apis task.

Throws:
de.thetaphi.forbiddenapis.ForbiddenApiException