Reporting Plugin Problems with the Problems API

package org.example

import org.gradle.api.DefaultTask
import org.gradle.api.GradleException
import org.gradle.api.Plugin
import org.gradle.api.Project
import org.gradle.api.provider.Property
import org.gradle.api.problems.*
import org.gradle.api.tasks.Input
import org.gradle.api.tasks.TaskAction
import javax.inject.Inject

/**
 * Simple demo plugin for the Gradle Problems API.
 */
abstract class HelloProblemsPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.tasks.register("greet", GreetTask::class.java) {
            group = "demo"
            description = "Greets a recipient. Demonstrates Problems API."
        }
    }
}

/**
 * Extra structured data to attach to problem reports.
 * Tools like Build Scans or IDEs could show this.
 */
interface GreetProblemData : AdditionalData {
    var configuredRecipient: String?
}

/**
 * Custom task that uses the Gradle Problems API.
 */
abstract class GreetTask @Inject constructor(private val problems: Problems) : DefaultTask() {

    @get:Input
    abstract val recipient: Property<String>

    private val problemGroup = problems.groups.others.group("Hello Problems")
    private val warnId = problemGroup.problemId("Recipient not set")
    private val failId = problemGroup.problemId("Forbidden recipient 'fail'")

    @TaskAction
    fun run() {
        val reporter = problems.reporter
        val name = recipient.orNull?.trim().orEmpty()

        // Warning: missing recipient -> provide a helpful suggestion
        if (name.isEmpty()) {
            reporter.report(warnId) {
                details("No recipient configured")
                severity(Severity.WARNING)
                solution("""Set the recipient: tasks.greet { recipient = "World" }""")
                documentedAt("https://gradle.org/hello-problems#recipient")
                additionalData(GreetProblemData::class.java) {
                    configuredRecipient = null
                }
            }
        }

        // Fatal: a specific value is disallowed to show throwing()
        else if (name.equals("fail", ignoreCase = true)) {
            throw reporter.throwing(GradleException("forbidden value"), failId) {
                details("Recipient 'fail' is not allowed")
                severity(Severity.ERROR)
                solution("""Choose another value, e.g. recipient = "World".""")
                documentedAt("https://gradle.org/hello-problems#forbidden")
                additionalData(GreetProblemData::class.java) {
                    configuredRecipient = name
                }
            }
        }

        logger.lifecycle("Hello, $name!")
    }
}

package org.example

import org.gradle.api.DefaultTask
import org.gradle.api.GradleException
import org.gradle.api.Plugin
import org.gradle.api.Project
import org.gradle.api.provider.Property
import org.gradle.api.problems.*
import org.gradle.api.tasks.Input
import org.gradle.api.tasks.TaskAction
import javax.inject.Inject

/**
 * Simple demo plugin for the Gradle Problems API.
 */
class HelloProblemsPlugin implements Plugin<Project> {
    @Override
    void apply(Project project) {
        project.tasks.register("greet", GreetTask) { task ->
            task.group = "demo"
            task.description = "Greets a recipient. Demonstrates Problems API."
        }
    }
}

/**
 * Extra structured data to attach to problem reports.
 * Tools like Build Scans or IDEs could show this.
 */
interface GreetProblemData extends AdditionalData {
    String getConfiguredRecipient()
    void setConfiguredRecipient(String value)
}

/**
 * Custom task that uses the Gradle Problems API.
 */
abstract class GreetTask extends DefaultTask {

    @Input
    abstract Property<String> getRecipient()

    private final Problems problems
    private final ProblemId warnId
    private final ProblemId failId

    @Inject
    GreetTask(Problems problems) {
        this.problems = problems
        def problemGroup = problems.groups.others.group("Hello Problems")
        warnId = problemGroup.problemId("Recipient not set")
        failId = problemGroup.problemId("Forbidden recipient 'fail'")
    }

    @TaskAction
    void run() {
        def reporter = problems.reporter
        def name = recipient.orNull?.trim() ?: ""

        // Warning: missing recipient -> provide a helpful suggestion
        if (name.isEmpty()) {
            reporter.report(warnId) { spec ->
                spec.details("No recipient configured")
                    .solution('Set the recipient: tasks.greet { recipient = "World" }')
                    .documentedAt("https://gradle.org/hello-problems#recipient")
                    .additionalData(GreetProblemData) {
                        it.configuredRecipient = null
                    }
            }
        }
        // Fatal: a specific value is disallowed to show throwing()
        else if (name.equalsIgnoreCase("fail")) {
            throw reporter.throwing(new GradleException("forbidden value"), failId) { spec ->
                spec.details("Recipient 'fail' is not allowed")
                    .solution('Choose another value, e.g. recipient = "World".')
                    .documentedAt("https://gradle.org/hello-problems#forbidden")
                    .additionalData(GreetProblemData) {
                        it.configuredRecipient = name
                    }
            }
        }

        logger.lifecycle("Hello, $name!")
    }
}

ProblemId id = ProblemId.create("sample-error", "FailingTask execution problem", StandardPlugin.PROBLEM_GROUP);
throw getProblems().getReporter().throwing((new RuntimeException("Message from runtime exception")), id, problemSpec -> {
    problemSpec.contextualLabel("This happened because ProblemReporter.throwing() was called")
        .details("This is a demonstration of how to add\ndetailed information to a build failure")
        .documentedAt("https://example.com/docs")
        .solution("Remove the Problems.throwing() method call from the task action");
});