OutOperationRequest

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.

Public functions

toAppendTo

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

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)