001package org.apache.maven.building;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *   http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022/**
023 * Describes a problem that was encountered during settings building. A problem can either be an exception that was
024 * thrown or a simple string message. In addition, a problem carries a hint about its source, e.g. the settings file
025 * that exhibits the problem.
026 *
027 * @author Benjamin Bentmann
028 * @author Robert Scholte
029 */
030public interface Problem
031{
032
033    /**
034     * The different severity levels for a problem, in decreasing order.
035     */
036    enum Severity
037    {
038
039        FATAL, //
040        ERROR, //
041        WARNING //
042
043    }
044
045    /**
046     * Gets the hint about the source of the problem. While the syntax of this hint is unspecified and depends on the
047     * creator of the problem, the general expectation is that the hint provides sufficient information to the user to
048     * track the problem back to its origin. A concrete example for such a source hint can be the file path or URL from
049     * which the settings were read.
050     *
051     * @return The hint about the source of the problem or an empty string if unknown, never {@code null}.
052     */
053    String getSource();
054
055    /**
056     * Gets the one-based index of the line containing the problem. The line number should refer to some text file that
057     * is given by {@link #getSource()}.
058     *
059     * @return The one-based index of the line containing the problem or a non-positive value if unknown.
060     */
061    int getLineNumber();
062
063    /**
064     * Gets the one-based index of the column containing the problem. The column number should refer to some text file
065     * that is given by {@link #getSource()}.
066     *
067     * @return The one-based index of the column containing the problem or non-positive value if unknown.
068     */
069    int getColumnNumber();
070
071    /**
072     * Gets the location of the problem. The location is a user-friendly combination of the values from
073     * {@link #getSource()}, {@link #getLineNumber()} and {@link #getColumnNumber()}. The exact syntax of the returned
074     * value is undefined.
075     *
076     * @return The location of the problem, never {@code null}.
077     */
078    String getLocation();
079
080    /**
081     * Gets the exception that caused this problem (if any).
082     *
083     * @return The exception that caused this problem or {@code null} if not applicable.
084     */
085    Exception getException();
086
087    /**
088     * Gets the message that describes this problem.
089     *
090     * @return The message describing this problem, never {@code null}.
091     */
092    String getMessage();
093
094    /**
095     * Gets the severity level of this problem.
096     *
097     * @return The severity level of this problem, never {@code null}.
098     */
099    Severity getSeverity();
100
101}