# Interface ProblemSpec

@Incubating public interface ProblemSpec
Provides options to configure problems.

Since:
  8.6
See Also:
  - `ProblemReporter`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<T extends AdditionalData>
  ProblemSpec`
  `additionalData(Class<T> type, Action<? super T> config)`
  Declares additional data attached to the problem.
  `ProblemSpec`
  `contextualLabel(String contextualLabel)`
  Declares a short, but context-dependent message for this problem.
  `ProblemSpec`
  `details(String details)`
  Declares a long description detailing the problem.
  `ProblemSpec`
  `documentedAt(String url)`
  Declares where this problem is documented.
  `ProblemSpec`
  `fileLocation(String path)`
  Declares that this problem is in a file.
  `ProblemSpec`
  `lineInFileLocation(String path, int line)`
  Declares that this problem is in a file on a line.
  `ProblemSpec`
  `lineInFileLocation(String path, int line, int column)`
  Declares that this problem is in a file with on a line at a certain position.
  `ProblemSpec`
  `lineInFileLocation(String path, int line, int column, int length)`
  Declares that this problem is in a file with on a line at a certain position.
  `ProblemSpec`
  `offsetInFileLocation(String path, int offset, int length)`
  Declares that this problem is in a file at a certain global position with a given length.
  `ProblemSpec`
  `severity(Severity severity)`
  Deprecated.
  Severity is now determined automatically: use `ProblemReporter.report(ProblemId, Action)` for warnings and `ProblemReporter.throwing(Throwable, ProblemId, Action)` for errors.
  `ProblemSpec`
  `solution(String solution)`
  Declares solutions and advice that contain context-sensitive data, e.g.
  `ProblemSpec`
  `stackLocation()`
  Declares that this problem is at the same place where it's reported.
  `ProblemSpec`
  `withException(Throwable t)`
  Declares the exception causing this problem.

- ## Method Details

  - ### contextualLabel

    ProblemSpec contextualLabel(String contextualLabel)
    Declares a short, but context-dependent message for this problem.

    The label is expected to span a single line. Any newline characters will be removed.

    Parameters:
      `contextualLabel` - the short message
    Returns:
      this
    Since:
      8.8

  - ### documentedAt

    ProblemSpec documentedAt(String url)
    Declares where this problem is documented.
    Returns:
      this
    Since:
      8.6

  - ### fileLocation

    ProblemSpec fileLocation(String path)
    Declares that this problem is in a file.
    Parameters:
      `path` - the file location
    Returns:
      this
    Since:
      8.6

  - ### lineInFileLocation

    ProblemSpec lineInFileLocation(String path, int line)
    Declares that this problem is in a file on a line.
    Parameters:
      `path` - the file location
      `line` - the one-indexed line number
    Returns:
      this
    Since:
      8.6

  - ### lineInFileLocation

    ProblemSpec lineInFileLocation(String path, int line, int column)
    Declares that this problem is in a file with on a line at a certain position.
    Parameters:
      `path` - the file location
      `line` - the one-indexed line number
      `column` - the one-indexed column
    Returns:
      this
    Since:
      8.6

  - ### lineInFileLocation

    ProblemSpec lineInFileLocation(String path, int line, int column, int length)
    Declares that this problem is in a file with on a line at a certain position.
    Parameters:
      `path` - the file location
      `line` - the one-indexed line number
      `column` - the one-indexed column
      `length` - the length of the text
    Returns:
      this
    Since:
      8.6

  - ### offsetInFileLocation

    ProblemSpec offsetInFileLocation(String path, int offset, int length)
    Declares that this problem is in a file at a certain global position with a given length.
    Parameters:
      `path` - the file location
      `offset` - the zero-indexed global offset from the beginning of the file
      `length` - the length of the text
    Returns:
      this
    Since:
      8.6

  - ### stackLocation

    ProblemSpec stackLocation()
    Declares that this problem is at the same place where it's reported. The stack trace will be used to determine the location.
    Returns:
      this
    Since:
      8.6

  - ### details

    ProblemSpec details(String details)
    Declares a long description detailing the problem.

    Details can elaborate on the problem, and provide more information about the problem. They can be multiple lines long, but should not detail solutions; for that, use `solution(String)`.

    Parameters:
      `details` - the details
    Returns:
      this
    Since:
      8.6

  - ### solution

    ProblemSpec solution(String solution)
    Declares solutions and advice that contain context-sensitive data, e.g. the message contains references to variables, locations, etc.
    Parameters:
      `solution` - the solution.
    Returns:
      this
    Since:
      8.6

  - ### additionalData

    <T extends AdditionalData> ProblemSpec additionalData(Class<T> type, Action<? super T> config)
    Declares additional data attached to the problem.
    Parameters:
      `type` - The type of the additional data. This can be any type that implements `AdditionalData` including `abstract` classes and interfaces. This type will be instantiated and provided as an argument for the `Action` passed as the second argument.

      The type can have the following properties:

      - getters and setters for collections, simple types and other types that itself follow these restrictions
        - simple types: `String`, `Integer`, `Boolean`, etc.
        - collections: `List`, `Set`, `Map`
        - primitives: `int`, `boolean`, etc.
      - Provider API types
        - `Property`
        - `ListProperty`
        - `SetProperty`
        - `MapProperty`
      `config` - The configuration action for the additional data.
    Returns:
      this
    Since:
      8.13

  - ### withException

    ProblemSpec withException(Throwable t)
    Declares the exception causing this problem.
    Parameters:
      `t` - the exception.
    Returns:
      this
    Since:
      8.11

  - ### severity

    @Deprecated ProblemSpec severity(Severity severity)
    Deprecated.
    Severity is now determined automatically: use `ProblemReporter.report(ProblemId, Action)` for warnings and `ProblemReporter.throwing(Throwable, ProblemId, Action)` for errors.
    Declares the severity of the problem.
    Parameters:
      `severity` - the severity
    Returns:
      this
    Since:
      8.6