// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.0/
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[part6_writing_tasks]]
= Part 6: Writing Tasks

Learn the basics of authoring Gradle tasks by creating a simple one in your Build script.

****
**In this section, you will:**

- Understand Tasks
- Create a custom Task for the Plugin
****

[[part6_begin]]
== Step 0. Before you Begin

1. You initialized your Java app in <<part1_gradle_init_project.adoc#part1_begin,part 1>>.
2. You understand the Gradle Build Lifecycle from <<part2_build_lifecycle.adoc#part2_begin,part 2>>.
3. You added a subproject and a separate Build in <<part3_multi_project_builds#part3_begin, part3>>.
4. You viewed a Settings file in <<part4_settings_file.adoc#part4_begin,part 4>>.
5. You authored a Build script in <<part5_build_scripts.adoc#part5_begin,part 5>>.

== Step 1. Understand Tasks
A Task is an executable piece of code that contains sequences of actions.

Actions are added to a Task via the `doFirst{}` and `doLast{}` closures.

A Task can depend on other tasks.

== Step 2. Register and Configure Tasks

Early on in the tutorial, we registered and configured `task1` in the `app` build script:

[.multi-language-sample]
=====
.app/build.gradle.kts
[source,kotlin]
----
tasks.register("task1"){  // <1>
    println("REGISTER TASK1: This is executed during the configuration phase")
}

tasks.named("task1"){  // <2>
    println("NAMED TASK1: This is executed during the configuration phase")
    doFirst {
        println("NAMED TASK1 - doFirst: This is executed during the execution phase")
    }
    doLast {
        println("NAMED TASK1 - doLast: This is executed during the execution phase")
    }
}
----
<1> You can use the link:{kotlinDslPath}/gradle/org.gradle.api.tasks/-task-container/index.html[register()] method to create new tasks.
<2> You can use the link:{kotlinDslPath}/gradle/org.gradle.api.tasks/-task-collection/index.html[named()] method to configure existing tasks.
=====
[.multi-language-sample]
=====
.app/build.gradle
[source, groovy]
----
tasks.register("task1") {  // <1>
    println("REGISTER TASK1: This is executed during the configuration phase")
}

tasks.named("task1") {  // <2>
    println("NAMED TASK1: This is executed during the configuration phase")
    doFirst {
        println("NAMED TASK1 - doFirst: This is executed during the execution phase")
    }
    doLast {
        println("NAMED TASK1 - doLast: This is executed during the execution phase")
    }
}
----
<1> You can use the link:{groovyDslPath}/org.gradle.api.tasks.TaskContainer.html#org.gradle.api.tasks.TaskContainer:register(java.lang.String)[register()] method to create new tasks.
<2> You can use the link:{groovyDslPath}/org.gradle.api.tasks.TaskContainer.html#org.gradle.api.tasks.TaskContainer:named(java.lang.String)[named()] method to configure existing tasks.
=====

== Step 3. Create a custom Task

To create a custom task, you must subclass link:{groovyDslPath}/org.gradle.api.DefaultTask.html#org.gradle.api.DefaultTask[`DefaultTask`] in Groovy DSL or link:{kotlinDslPath}/gradle/org.gradle.api/-default-task/index.html[`DefaultTask`] in Kotlin DSL.

Create a custom class called `LicenseTask` with the code below and add it to the bottom of the `gradle/license-plugin/plugin/src/main/kotlin/license/LicensePlugin.kt` or `gradle/license-plugin/plugin/src/main/groovy/license/LicensePlugin.groovy` file:

[.multi-language-sample]
=====
.gradle/license-plugin/plugin/src/main/kotlin/license/LicensePlugin.kt
[source,kotlin]
----
import org.gradle.api.Project
import org.gradle.api.Plugin
import org.gradle.api.DefaultTask
import org.gradle.api.tasks.Input
import org.gradle.api.tasks.TaskAction
import java.io.File
import java.io.InputStream
import java.nio.charset.Charset

class LicensePlugin: Plugin<Project> {
    // Don't change anything here
}

abstract class LicenseTask : DefaultTask() {
    @Input
    val licenseFilePath = project.layout.settingsDirectory.file("license.txt").asFile.path

    @TaskAction
    fun action() {
        // Read the license text
        val licenseText = File(licenseFilePath).readText()
        // Walk the directories looking for java files
        project.layout.settingsDirectory.asFile.walk().forEach {
            if (it.extension == "java") {
                // Read the source code
                var ins: InputStream = it.inputStream()
                var content = ins.readBytes().toString(Charset.defaultCharset())
                // Write the license and the source code to the file
                it.writeText(licenseText + content)
            }
        }
    }
}
----
=====
[.multi-language-sample]
=====
.gradle/license-plugin/plugin/src/main/groovy/license/LicensePlugin.groovy
[source, groovy]
----
import org.gradle.api.Project
import org.gradle.api.Plugin
import org.gradle.api.DefaultTask
import org.gradle.api.tasks.Input
import org.gradle.api.tasks.TaskAction

class LicensePlugin implements Plugin<Project> {
    // Don't change anything here
}

abstract class LicenseTask extends DefaultTask {
    @Input
    def licenseFilePath = project.layout.settingsDirectory.file("license.txt").asFile.path

    @TaskAction
    void action() {
        // Read the license text
        def licenseText = new File(licenseFilePath).text
        // Walk the directories looking for java files
        project.layout.settingsDirectory.asFile.eachFileRecurse { file ->
            int lastIndexOf = file.getName().lastIndexOf('.')
            if ((lastIndexOf != -1) && (file.getName().substring(lastIndexOf)) == ".java") {// Read the source code
                def content = file.getText()
                //println(licenseText + '\n' + content)
                // Write the license and the source code to the file
                file.text = licenseText + '\n' + content
            }
        }
    }
}
----
=====

The `LicenseTask` class encapsulates the task action logic and declares any inputs and outputs the task expects.

The task action is annotated with `@TaskAction`.
Inside, the logic first finds a file called "license.txt".
This file contains text for an Apache license:

.license.txt
[source,text]
----
/*
* Licensed under the Apache License
*/
----

The task then looks for files with the extension `.java` and adds a license header.

The task has a single input, the license file name, annotated with `@Input`.

Gradle uses the `@Input` annotation to determine if the task needs to run.
If the task has not run before or if the input value has changed since the previous execution, then Gradle will execute the task.

While a custom class has been created, it is not yet added to the `LicensePlugin`.
Running `LicenseTask` is not currently possible.

All you can do for now is make sure `./gradlew build` runs without failing:

[source,bash]
----
$ ./gradlew build
----
[source,text]
----
SETTINGS FILE: This is executed during the initialization phase

> Configure project :app
BUILD SCRIPT: This is executed during the configuration phase

BUILD SUCCESSFUL in 1s
13 actionable tasks: 6 executed, 7 up-to-date
----

[.text-right]
**Next Step:** <<part7_writing_plugins#part7_writing_plugins,Writing Plugins>> >>
