OutOperationRequest

Added in 4.2.0

interface OutOperationRequest<FileTypeT : FileSystemLocation>

Operations performed by a Task with a single RegularFile or Directory output.

Task is not consuming existing version of the target SingleArtifact.

Summary

Public functions
Unit
<ArtifactTypeT : Artifact.Multiple<FileTypeT> & Artifact.Appendable> toAppendTo(
    type: ArtifactTypeT
)

Initiates an append request to a Artifact.Multiple artifact type.
Unit
<ArtifactTypeT : Artifact.Single<FileTypeT> & Artifact.Replaceable> toCreate(
    type: ArtifactTypeT
)

Initiates a creation request for a single Artifact.Replaceable artifact type.
Unit
@Incubating
<ArtifactTypeT : Artifact.Single<FileTypeT>> toListenTo(
    type: ArtifactTypeT
)

Initiates a reactive request where the Task used in the Artifacts.use method will be executed once the final version of the type artifact has been produced.

Public functions

toAppendTo

Added in 7.0.0
fun <ArtifactTypeT : Artifact.Multiple<FileTypeT> & Artifact.Appendable> toAppendTo(
    type: ArtifactTypeT
): Unit

Initiates an append request to a Artifact.Multiple artifact type.

Parameters
type: ArtifactTypeT

The Artifact of FileTypeT identifying the artifact to append to.

The artifact type must be Artifact.Multiple and Artifact.Appendable.

As an example, let's take a Task that outputs a org.gradle.api.file.RegularFile:

    abstract class MyTask: DefaultTask() {
         @get:OutputFile abstract val outputFile: RegularFileProperty

         @TaskAction fun taskAction() {
             ... outputFile.get().asFile.write( ... ) ...
         }
    }

and an ArtifactType defined as follows :

    sealed class ArtifactType<T: FileSystemLocation>(
         val kind: ArtifactKind
    ): MultipleArtifactType {
         object MULTIPLE_FILE_ARTIFACT:
                 ArtifactType<RegularFile>(FILE), Appendable
    }

You can then register the above task as a Provider of org.gradle.api.file.RegularFile for that artifact type:

    val taskProvider= projects.tasks.register(MyTask::class.java, "appendTask")
    artifacts.use(taskProvider)
     .wiredWith(MyTask::outputFile)
     .toAppendTo(ArtifactType.MULTIPLE_FILE_ARTIFACT)

toCreate

Added in 7.0.0
fun <ArtifactTypeT : Artifact.Single<FileTypeT> & Artifact.Replaceable> toCreate(
    type: ArtifactTypeT
): Unit

Initiates a creation request for a single Artifact.Replaceable artifact type.

Parameters
type: ArtifactTypeT

The Artifact of FileTypeT identifying the artifact to replace.

The artifact type must be Artifact.Replaceable

A creation request does not care about the existing producer, since it replaces the existing producer. Therefore, the existing producer task will not execute (unless it produces other outputs). Please note that when such replace requests are made, the Task will replace initial AGP providers.

You cannot replace the Artifact.Multiple artifact type; therefore, you must instead combine it using the TaskBasedOperation.wiredWith API.

For example, let's take a Task that outputs a org.gradle.api.file.RegularFile:

    abstract class MyTask: DefaultTask() {
         @get:OutputFile abstract val outputFile: RegularFileProperty

         @TaskAction fun taskAction() {
             ... write outputFile ...
         }
    }

An SingleArtifact is defined as follows:

    sealed class ArtifactType<T: FileSystemLocation>(val kind: ArtifactKind) {
         object SINGLE_FILE_ARTIFACT:
                 ArtifactType<RegularFile>(FILE), Replaceable
    }

You can register a transform to the collection of org.gradle.api.file.RegularFile:

    val taskProvider= projects.tasks.register(MyTask::class.java, "replaceTask")
    artifacts.use(taskProvider)
     .wiredWith(MyTask::outputFile)
     .toCreate(ArtifactType.SINGLE_FILE_ARTIFACT)

toListenTo

Added in 8.3.2
@Incubating
fun <ArtifactTypeT : Artifact.Single<FileTypeT>> toListenTo(
    type: ArtifactTypeT
): Unit

Initiates a reactive request where the Task used in the Artifacts.use method will be executed once the final version of the type artifact has been produced.

The final version artifact will be injected in the Task.

Remember that an artifact is not always produced, for instance, an artifact related to minification will not be produced unless minification is turned on.

When an artifact is not produced in the current build flow, the Task will NOT be invoked.

For example, let's take a Task that wants to listen to the merged manifest file production :

        abstract class MyTask: DefaultTask() {
             @get:InputFile abstract val mergedManifestFile: RegularFileProperty

             @TaskAction fun taskAction() {
                 ... verify that manifest is correct ...
             }
        }

    You can register a transform to the collection of [org.gradle.api.file.RegularFile]:

    ```kotlin
        val taskProvider= projects.tasks.register(MyTask::class.java, "verifyManifestTask")
        artifacts.use(taskProvider)
         .wiredWith(MyTask::mergedManifestFile)
         .toListenTo(SingleArtifact.MERGED_MANIFEST)

Task will be registered as a finalizer task for the final producer of the type artifact using Gradle's Task.finalizedBy API.

Parameters
type: ArtifactTypeT

the Artifact.Single artifact identifier.