-
Notifications
You must be signed in to change notification settings - Fork 4.6k
/
ProblemSpec.java
203 lines (186 loc) · 6.41 KB
/
ProblemSpec.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
/*
* Copyright 2023 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.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.
*/
package org.gradle.api.problems;
import org.gradle.api.Incubating;
/**
* Provides options to configure problems.
* <p>
*
* @see ProblemReporter
* @since 8.6
*/
@Incubating
public interface ProblemSpec {
/**
* Declares a short message for this problem.
* <p>
* The label is the main, human-readable representation of the problem.
* It is a mandatory property to configure when emitting a problem with {@link ProblemReporter}.
*
* @param label the short message
* @return this
* @since 8.6
*/
ProblemSpec label(String label);
/**
* A category groups related problems together.
* <p>
* Category is a mandatory property to configure when emitting a problem with {@link ProblemReporter}.
* <p>
* A category defines the following hierarchical elements to distinguish instances:
* <ul>
* <li>namespace</li>
* <li>category</li>
* <li>subcategories</li>
* </ul>
* <p>
* The namespace provides separation for identical problems emitted from different components.
* Problems emitted from Gradle core will use the {@code org.gradle} namespace.
* Third party plugins are expected to use their plugin id for namespace.
* Problems emitted from build scripts should use the {@code buildscript} namespace.
* The namespace is bound to {@link ProblemReporter}, hence it is absent from the argument list.
* <p>
* A category should contain the most broad term describing the problem.
* A few examples are: {@code compilation}, {@code deprecation}, {@code task-validation}.
* <p>
* The problem category can be refined with an optional hierarchy of subcategories.
* For example, a problem covering a java compilation warning can be denoted with the following subcategories: {@code [java, unused-variable]}.
* <p>
* The categorization depends on the domain and don't have any constraints. Clients (i.e. IDEs) receiving problems should use the category information for
* properly group and sort the received instances.
* However, we recommend to use the same conventions as the problems emitted from Gradle core use.
* <ul>
* <li>Entries should be all-lowercase using a dash for separator (i.e. kebab-case)</li>
* <li>Should be strictly hierarchical: the category declares the domain and subcategories provide further refinement</li>
* </ul>
* A few examples with a path-like notation (i.e. {@code category:subcategory1:subcategory2}).
* <ul>
* <li>compilation:groovy-dsl</li>
* <li>compilation:java:unused-import</li>
* <li>deprecation:user-code-direct</li>
* <li>task-selection:no-matches</li>
* </ul>
*
* @param category the type name
* @param subcategories the type subcategories
* @return this
* @since 8.6
*/
ProblemSpec category(String category, String... subcategories);
/**
* Declares where this problem is documented.
*
* @return this
* @since 8.6
*/
ProblemSpec documentedAt(String url);
/**
* Declares that this problem is in a file.
*
* @param path the file location
* @return this
* @since 8.6
*/
ProblemSpec fileLocation(String path);
/**
* Declares that this problem is in a file on a line.
*
* @param path the file location
* @param line the one-indexed line number
* @return this
* @since 8.6
*/
ProblemSpec lineInFileLocation(String path, int line);
/**
* Declares that this problem is in a file with on a line at a certain position.
* <p>
*
* @param path the file location
* @param line the one-indexed line number
* @param column the one-indexed column
* @return this
* @since 8.6
*/
ProblemSpec lineInFileLocation(String path, int line, int column);
/**
* Declares that this problem is in a file with on a line at a certain position.
*
* @param path the file location
* @param line the one-indexed line number
* @param column the one-indexed column
* @param length the length of the text
* @return this
* @since 8.6
*/
ProblemSpec lineInFileLocation(String path, int line, int column, int length);
/**
* Declares that this problem is in a file at a certain global position with a given length.
*
* @param path the file location
* @param offset the zero-indexed global offset from the beginning of the file
* @param length the length of the text
* @return this
* @since 8.6
*/
ProblemSpec offsetInFileLocation(String path, int offset, int length);
/**
* Declares that this problem is emitted while applying a plugin.
*
* @param pluginId the ID of the applied plugin
* @return this
* @since 8.6
*/
ProblemSpec pluginLocation(String pluginId);
/**
* Declares that this problem should automatically collect the location information based on the current stack trace.
*
* @return this
* @since 8.6
*/
ProblemSpec stackLocation();
/**
* The long description of this problem.
*
* @param details the details
* @return this
* @since 8.6
*/
ProblemSpec details(String details);
/**
* A description of how to solve this problem.
*
* @param solution the solution.
* @return this
* @since 8.6
*/
ProblemSpec solution(String solution);
/**
* The exception causing this problem.
*
* @param e the exception.
* @return this
* @since 8.6
*/
ProblemSpec withException(RuntimeException e);
/**
* Declares the severity of the problem.
*
* @param severity the severity
* @return this
* @since 8.6
*/
ProblemSpec severity(Severity severity);
}