:samples-dir: /home/tcagent1/agent/work/64493a816be20d5a/promote-projects/gradle/build/git-checkout/platforms/documentation/docs/build/working/samples/install/problems-api-usage
:gradle-version: 9.2.0-milestone-2

= Reporting and receiving problems via the Problems API Sample

[.download]
- link:zips/sample_problems_api_usage-groovy-dsl.zip[icon:download[] Groovy DSL]
- link:zips/sample_problems_api_usage-kotlin-dsl.zip[icon:download[] Kotlin DSL]

NOTE: You can open this sample in an link:{userManualPath}/gradle_ides.html#gradle_ides[IDE that supports Gradle].

This sample shows how problems can be emitted via the Problems API and how those reports are consumed on the IDE-side.
Visit the user manual to learn more about the link:{userManualPath}/reporting_problems.html#sec:reporting_problems[Problems API].

== Running the sample

To run the sample, execute the `./gradlew :sample-ide:importBuild` command.

== Project structure

The sample consists of multiple, individual builds composed into a composite build with the following layout

* `sample-project`: A Gradle build with plugins that report problems
* `sample-ide`: a project that simulates the IDE functionality. In other words, it uses the Gradle Tooling API to configure and run the `sample-project` build and prints the received problem reports received during the process.
* `reporters/standard-plugin` shows the usage of the Problems API in a standard Gradle plugin.
* `reporters/model-builder-plugin` shows how to use the Problems API to report problems when reading project configuration via the Tooling API.
* `reporters/script-plugin` shows how to use the Problems API in a precompiled script plugin.


== Emitting a problem

Problems can be emitted via an injected `Problems` service.
Here's an example on how to report a problem from a plugin, including adding custom additional data:

====
include::sample[dir="groovy",files="reporters/standard-plugin/src/main/java/reporters/StandardPlugin.java[tags=problems-api-report]"]
====


== Receiving a problem report

Problems are emitted as Tooling API progress events. They can be processed by registering a `ProgressListener`:

====
include::sample[dir="groovy",files="sample-ide/src/main/java/org/gradle/sample/SampleIde.java[tags=problems-tapi-event]"]
====

=== Receiving custom additional data

To read custom additional data on the Tooling API side, you need a **view type**.

A **view type** represents interface or class through which you want to access the underlying data.
The API will return an implementation of this type that provides a specific "view" of the data, allowing for type-safe access to underlying data.
The **view type** must be compatible with the actual data structure.

Your **view type** can include various properties based on the following rules:

* Simple types (`String`, `Integer`, `Boolean`, etc.)
* Collections (`List`, `Set`, `Map`)
* Composite types made up of the above
* Gradle Provider API types, which are automatically mapped to their corresponding types

Also see the link:{javadocPath}/org/gradle/tooling/events/problems/CustomAdditionalData.html[CustomAdditionalData] for more information.

This **view type** can be used to retrieve the additional data stored in the problem instance:

====
include::sample[dir="groovy",files="sample-ide/src/main/java/org/gradle/sample/SampleIde.java[tags=problems-tapi-additional-data-type]"]
====

This **view type** can be used to retrieve the additional data stored in the problem instance:

====
include::sample[dir="groovy",files="sample-ide/src/main/java/org/gradle/sample/SampleIde.java[tags=problems-tapi-additional-data-read]"]
====



