Package com.arc_e_tect.gradle.shadow

Class DetectShadowApisTask

java.lang.Object
org.gradle.api.internal.AbstractTask
org.gradle.api.DefaultTask
com.arc_e_tect.gradle.shadow.DetectShadowApisTask
All Implemented Interfaces:
Comparable<org.gradle.api.Task>, org.gradle.api.internal.DynamicObjectAware, org.gradle.api.internal.TaskInternal, org.gradle.api.Named, org.gradle.api.plugins.ExtensionAware, org.gradle.api.Task, org.gradle.util.Configurable<org.gradle.api.Task>
@DisableCachingByDefault(because="Report depends on source and OpenAPI document content and is cheap to regenerate") public abstract class DetectShadowApisTask extends org.gradle.api.DefaultTask
Gradle task that scans @RestController classes, compares the endpoints they expose against the configured OpenAPI documentation, and writes an AsciiDoc report of every endpoint that is not described - the "shadow APIs".

Registered automatically by ShadowApiDetectorPlugin under the name detectShadowApis.

  • Nested Class Summary

    Nested classes/interfaces inherited from interface org.gradle.api.Named

    org.gradle.api.Named.Namer

  • Field Summary

    Fields inherited from interface org.gradle.api.Task

    TASK_ACTION, TASK_CONSTRUCTOR_ARGS, TASK_DEPENDS_ON, TASK_DESCRIPTION, TASK_GROUP, TASK_NAME, TASK_OVERWRITE, TASK_TYPE

  • Constructor Summary

    Constructors
    Constructor
    Description
    DetectShadowApisTask()
    Creates the task.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    applyFailOnShadowOverride(boolean value)
    CLI entry point for getFailOnShadowOverride().
    void
    applyScanForShadows(String value)
    CLI entry point for getScanForShadows().
    void
    applyUpdateContractHistoryOverride(boolean value)
    CLI entry point for getUpdateContractHistoryOverride().
    void
    generate()
    Task action: either scans a single controller named or pathed by getScanForShadows() and prints its findings to the console (see scanSingleController(String)), or - when that property is unset - scans every @RestController class under getControllerDirs(), loads the configured OpenAPI documentation, and writes the shadow API report.
    abstract org.gradle.api.file.RegularFileProperty
    getContractHistoryFile()
    File that the persisted contract progress history is read from and, when getUpdateContractHistory() is true, written back to.
    String
    getContractHistoryFilePath()
    The absolute path of getContractHistoryFile(), tracked as a plain @Input value - not the file's content, which getContractHistoryFile() itself is deliberately excluded from up-to-date checking for.
    abstract org.gradle.api.file.ConfigurableFileCollection
    getControllerDirs()
    Directories to search recursively for @RestController classes.
    abstract org.gradle.api.provider.Property<Boolean>
    getFailOnShadow()
    Whether the build should fail when shadow APIs are found.
    abstract org.gradle.api.provider.Property<Boolean>
    getFailOnShadowOverride()
    Single-run override of getFailOnShadow(), settable only from the command line via --failOnShadow/--no-failOnShadow - never wired from the DSL, and unset by default.
    abstract org.gradle.api.file.DirectoryProperty
    getOpenApiDir()
    Directory where OpenAPI descriptions are stored, tracked so that changes to any document reachable from getRootDocument() invalidate the task's cached result.
    abstract org.gradle.api.file.DirectoryProperty
    getProjectDirectory()
    The project directory, used only to resolve a relative getScanForShadows() path against - never against this process's own working directory, which need not be the project directory at all (e.g.
    abstract org.gradle.api.file.DirectoryProperty
    getReportDir()
    Directory the AsciiDoc report is written to.
    abstract org.gradle.api.provider.Property<String>
    getReportFileName()
    Name of the generated AsciiDoc report file (without path).
    abstract org.gradle.api.file.RegularFileProperty
    getRootDocument()
    The root OpenAPI document describing the API.
    abstract org.gradle.api.provider.Property<String>
    getScanForShadows()
    The name or path of a single @RestController class to scan for shadow APIs, settable only from the command line via --scanForShadows=<name-or-path> - never wired from the DSL, and unset by default.
    abstract org.gradle.api.provider.Property<String>
    getSystemUnderTestVersion()
    Version of the system under test whose @RestController classes were scanned, printed in the generated report as e.g.
    abstract org.gradle.api.provider.Property<Boolean>
    getTrackContractHistory()
    Whether to persist, across builds, a history of when each endpoint first reached each stage of its contract lifecycle - declared, implemented, verified.
    abstract org.gradle.api.provider.Property<Boolean>
    getUpdateContractHistory()
    Whether getContractHistoryFile() is written back to disk after being updated with the current run's endpoints.
    abstract org.gradle.api.provider.Property<Boolean>
    getUpdateContractHistoryOverride()
    Single-run override of getUpdateContractHistory(), settable only from the command line via --updateContractHistory/--no-updateContractHistory - never wired from the DSL, and unset by default.

    Methods inherited from class org.gradle.api.DefaultTask

    compareTo, configure, dependsOn, doFirst, doFirst, doFirst, doLast, doLast, doLast, finalizedBy, getActions, getAnt, getDependsOn, getDescription, getDestroyables, getDidWork, getEnabled, getExtensions, getFinalizedBy, getGroup, getInputs, getLocalState, getLogger, getLogging, getMustRunAfter, getName, getOutputs, getPath, getProject, getShouldRunAfter, getState, getTaskDependencies, getTemporaryDir, getTimeout, hasProperty, mustRunAfter, onlyIf, onlyIf, onlyIf, property, setActions, setDependsOn, setDescription, setDidWork, setEnabled, setFinalizedBy, setGroup, setMustRunAfter, setOnlyIf, setOnlyIf, setOnlyIf, setProperty, setShouldRunAfter, shouldRunAfter, usesService

    Methods inherited from class org.gradle.api.internal.AbstractTask

    acceptServiceReferences, appendParallelSafeAction, doNotTrackState, doNotTrackStateIf, getAsDynamicObject, getIdentityPath, getImpliesSubProjects, getLifecycleDependencies, getOnlyIf, getReasonNotToTrackState, getReasonsNotToTrackState, getReasonTaskIsIncompatibleWithConfigurationCache, getRequiredServices, getServices, getSharedResources, getStandardOutputCapture, getTaskActions, getTaskIdentity, getTemporaryDirFactory, hasTaskActions, injectIntoNewInstance, isCompatibleWithConfigurationCache, isEnabled, isHasCustomActions, notCompatibleWithConfigurationCache, prependParallelSafeAction, restoreOnlyIf, restoreTaskActions, setImpliesSubProjects

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface org.gradle.api.Task

    doNotTrackState, notCompatibleWithConfigurationCache

  • Constructor Details

    • DetectShadowApisTask

      @Inject public DetectShadowApisTask()
      Creates the task. Instantiated by Gradle infrastructure via Inject.

  • Method Details

    • getControllerDirs

      @InputFiles @PathSensitive(RELATIVE) public abstract org.gradle.api.file.ConfigurableFileCollection getControllerDirs()
      Directories to search recursively for @RestController classes.
      Returns:
      mutable file collection of controller source directories

    • getRootDocument

      @InputFile @PathSensitive(RELATIVE) public abstract org.gradle.api.file.RegularFileProperty getRootDocument()
      The root OpenAPI document describing the API.
      Returns:
      mutable file property for the root OpenAPI document

    • getOpenApiDir

      @Optional @InputDirectory @PathSensitive(RELATIVE) public abstract org.gradle.api.file.DirectoryProperty getOpenApiDir()
      Directory where OpenAPI descriptions are stored, tracked so that changes to any document reachable from getRootDocument() invalidate the task's cached result.
      Returns:
      mutable directory property for the OpenAPI description directory

    • getFailOnShadow

      @Input public abstract org.gradle.api.provider.Property<Boolean> getFailOnShadow()
      Whether the build should fail when shadow APIs are found.
      Returns:
      mutable boolean property controlling whether the build fails on shadow APIs

    • getReportDir

      @OutputDirectory public abstract org.gradle.api.file.DirectoryProperty getReportDir()
      Directory the AsciiDoc report is written to.
      Returns:
      mutable directory property for the report output directory

    • getReportFileName

      @Input public abstract org.gradle.api.provider.Property<String> getReportFileName()
      Name of the generated AsciiDoc report file (without path).
      Returns:
      mutable string property for the report file name

    • getSystemUnderTestVersion

      @Input public abstract org.gradle.api.provider.Property<String> getSystemUnderTestVersion()
      Version of the system under test whose @RestController classes were scanned, printed in the generated report as e.g. System Under Test version: v1.0.0.
      Returns:
      mutable string property for the system-under-test version

    • getTrackContractHistory

      @Input public abstract org.gradle.api.provider.Property<Boolean> getTrackContractHistory()
      Whether to persist, across builds, a history of when each endpoint first reached each stage of its contract lifecycle - declared, implemented, verified.
      Returns:
      mutable boolean property controlling whether contract progress history is tracked

    • getContractHistoryFile

      @Internal public abstract org.gradle.api.file.RegularFileProperty getContractHistoryFile()
      File that the persisted contract progress history is read from and, when getUpdateContractHistory() is true, written back to. Deliberately not declared as an @InputFile/@OutputFile: the file legitimately may not exist yet (treated as an empty history, not an error) and is only conditionally written back, so it's read and written directly in generate() instead of through Gradle's file-content-based up-to-date checking. Its configured path - as opposed to the file's content - is still tracked as a plain input via getContractHistoryFilePath(), so that renaming or relocating it is itself enough to invalidate this task's up-to-date state.
      Returns:
      mutable file property for the contract history file

    • getContractHistoryFilePath

      @Input @Optional public String getContractHistoryFilePath()
      The absolute path of getContractHistoryFile(), tracked as a plain @Input value - not the file's content, which getContractHistoryFile() itself is deliberately excluded from up-to-date checking for. Without this, renaming or relocating contractHistoryFile in the build script - with no other configured input having changed - would leave this task UP-TO-DATE and silently skip writing history to the newly configured location.
      Returns:
      the contract history file's absolute path, or null if unset

    • getUpdateContractHistory

      @Input public abstract org.gradle.api.provider.Property<Boolean> getUpdateContractHistory()
      Whether getContractHistoryFile() is written back to disk after being updated with the current run's endpoints. Only consulted when getTrackContractHistory() is true; the history file is always read regardless.
      Returns:
      mutable boolean property controlling whether the contract history file is written back

    • getUpdateContractHistoryOverride

      @Input @Optional public abstract org.gradle.api.provider.Property<Boolean> getUpdateContractHistoryOverride()
      Single-run override of getUpdateContractHistory(), settable only from the command line via --updateContractHistory/--no-updateContractHistory - never wired from the DSL, and unset by default. When present, takes precedence over getUpdateContractHistory() for this run only, without changing the build script - typically used from CI to advance the committed history only on the branch(es) whose pipeline should, since the plugin itself has no notion of which branch is currently checked out.

      Tracked as @Input, not @Internal: without that, passing a different value on the command line between two otherwise-identical runs would leave the task UP-TO-DATE and silently skip re-executing with the new override.

      Returns:
      mutable, normally-unset boolean property overriding getUpdateContractHistory() for a single run

    • applyUpdateContractHistoryOverride

      public void applyUpdateContractHistoryOverride(boolean value)
      CLI entry point for getUpdateContractHistoryOverride(). Not meant to be called directly - Gradle invokes it when --updateContractHistory/--no-updateContractHistory is passed on the command line.

      Deliberately not named setUpdateContractHistoryOverride - a method matching the getUpdateContractHistoryOverride()/setUpdateContractHistoryOverride(...) JavaBean getter/setter naming convention makes Gradle's task class generator treat the pair as a plain boolean property and reject getUpdateContractHistoryOverride() for being abstract, even though it is a perfectly ordinary managed Property<Boolean>.

      Parameters:
      value - the value to override getUpdateContractHistory() with for this run

    • getFailOnShadowOverride

      @Input @Optional public abstract org.gradle.api.provider.Property<Boolean> getFailOnShadowOverride()
      Single-run override of getFailOnShadow(), settable only from the command line via --failOnShadow/--no-failOnShadow - never wired from the DSL, and unset by default. When present, takes precedence over getFailOnShadow() for this run only, without changing the build script - applies equally to a full-project scan and to a getScanForShadows() single-controller scan.

      Tracked as @Input, not @Internal - see getUpdateContractHistoryOverride() for why.

      Returns:
      mutable, normally-unset boolean property overriding getFailOnShadow() for a single run

    • applyFailOnShadowOverride

      public void applyFailOnShadowOverride(boolean value)
      CLI entry point for getFailOnShadowOverride(). Not meant to be called directly - Gradle invokes it when --failOnShadow/--no-failOnShadow is passed on the command line. See applyUpdateContractHistoryOverride(boolean) for why this is deliberately not named setFailOnShadowOverride.
      Parameters:
      value - the value to override getFailOnShadow() with for this run

    • getScanForShadows

      @Input @Optional public abstract org.gradle.api.provider.Property<String> getScanForShadows()
      The name or path of a single @RestController class to scan for shadow APIs, settable only from the command line via --scanForShadows=<name-or-path> - never wired from the DSL, and unset by default. When present, generate() scans only this controller instead of every file under getControllerDirs(), and prints its findings to the console instead of writing getReportDir()'s AsciiDoc report - see scanSingleController(String).

      Two forms are accepted:

      • A path ending in .java - scanned directly, regardless of getControllerDirs(). Fails clearly if the file does not exist.
      • A bare class name (e.g. OrderController) - every <name>.java file found anywhere under getControllerDirs() is scanned; there may be more than one, e.g. same-named controllers in different packages, in which case every match is scanned and their findings combined. Fails clearly if no file named <name>.java is found.

      Tracked as @Input, not @Internal - see getUpdateContractHistoryOverride() for why.

      Returns:
      mutable, normally-unset string property naming or pathing a single controller to scan

    • getProjectDirectory

      @Internal public abstract org.gradle.api.file.DirectoryProperty getProjectDirectory()
      The project directory, used only to resolve a relative getScanForShadows() path against - never against this process's own working directory, which need not be the project directory at all (e.g. when Gradle is invoked with --project-dir from elsewhere) and, unlike the project directory, isn't necessarily stable in a configuration-cache-compatible way. Wired once by ShadowApiDetectorPlugin at configuration time; not itself part of the public DSL.
      Returns:
      directory property for the project directory

    • applyScanForShadows

      public void applyScanForShadows(String value)
      CLI entry point for getScanForShadows(). Not meant to be called directly - Gradle invokes it when --scanForShadows=<value> is passed on the command line. See applyUpdateContractHistoryOverride(boolean) for why this is deliberately not named setScanForShadows.
      Parameters:
      value - the controller name or .java path to scan

    • generate

      public void generate()
      Task action: either scans a single controller named or pathed by getScanForShadows() and prints its findings to the console (see scanSingleController(String)), or - when that property is unset - scans every @RestController class under getControllerDirs(), loads the configured OpenAPI documentation, and writes the shadow API report. Either way, fails the build if any shadow API was found and the effective getFailOnShadow() (accounting for getFailOnShadowOverride()) is true.