org.gradle.problems.Problem Maven / Gradle / Ivy
/*
* Copyright 2021 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.problems;
import java.util.Collections;
import java.util.List;
import java.util.Optional;
/**
* This interface represents the model of a problem which needs to be reported to a user.
* A problem must:
*
*
* - be associated with a {@link #getSeverity() severity} (e.g, critical, warning, deprecation, ...)
* - have a unique {@link #getId() ID}
* - have a {@link #getWhere() location}, represented by its "context"
* - have a {@link #getWhat() short description} ("what happened")
*
*
* In addition, it is strongly recommended that problems carry:
*
*
* - a description of {@link #getWhy() why} the problem happened
* - a {@link #getLongDescription() longer description} of the problem
* - a link to {@link #getDocumentationLink() documentation} providing throughful explanation of the problem
* - a list of {@link #getPossibleSolutions() possible solutions to the problem}
*
*
* Each of the solutions, themselves, provide a short and a long description, as well as
* an optional documentation link.
*
* It is expected that different problem categories are represented by different concrete
* instantiations of this interface, where the generic type representation go away.
*
* The problem ID doesn't have to be displayed to the user, but it can be useful. There
* are often problems which are the same but are expressed differently depending on the
* context. Therefore, assigning a unique id is a good way to uniquely identify a problem.
* It can also be useful to put in place mechanisms to silence particular problems (for
* example, suppress warnings for a specific problem).
*
* The combination of (id, context) can also be used to pinpoint a particular problem.
*
* As many different projects have a different opinion on what severity levels exist,
* or what kind of problems we can find, the severity is a generic type argument which
* should be specified by your application.
*
* @param an ID enumeration. Each problem should be uniquely identified by ID.
* @param the severity type
* @param the type of the context, representing where the problem happened
*/
public interface Problem, SEVERITY extends Enum, CONTEXT> extends WithId, WithDescription, WithDocumentationLink {
/**
* @return How severe is the problem
*/
SEVERITY getSeverity();
/**
* Where did the problem surface?
* @return can refer to a source file, a plugin, or any place which lets the user
* understand where a problem happened
*/
CONTEXT getWhere();
/**
* Should return a short, human-understandable description of the problem.
* By default, this returns the short description.
* @return what problem happened
*/
default String getWhat() {
return getShortDescription();
}
/**
* If possible, a problem should tell why it happened
* @return a description of the why the problem happened
*/
default Optional getWhy() {
return Optional.empty();
}
/**
* A list of solutions, or potential solutions to the reported problem.
* @return a list of solutions. Shouldn't be null.
*/
default List getPossibleSolutions() {
return Collections.emptyList();
}
/**
* If this problem is a consequence of another problem, return the
* originating problem.
* @return a problem which caused the current one to show up, if any.
*/
default Optional> getCause() {
return Optional.empty();
}
}