001/*
002 * SonarQube
003 * Copyright (C) 2009-2017 SonarSource SA
004 * mailto:info AT sonarsource DOT com
005 *
006 * This program is free software; you can redistribute it and/or
007 * modify it under the terms of the GNU Lesser General Public
008 * License as published by the Free Software Foundation; either
009 * version 3 of the License, or (at your option) any later version.
010 *
011 * This program is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014 * Lesser General Public License for more details.
015 *
016 * You should have received a copy of the GNU Lesser General Public License
017 * along with this program; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
019 */
020package org.sonar.api.server.debt;
021
022import javax.annotation.CheckForNull;
023
024/**
025 * Function used to calculate the remediation cost of an issue. See {@link Type} for details.
026 * <p>The gap multiplier and base effort involved in the functions are durations. They are defined in hours, minutes and/or
027 * seconds. Examples: "5min", "1h 10min". Supported units are "d" (days), "h" (hour), and "min" (minutes).
028 *
029 * @since 4.3
030 */
031public interface DebtRemediationFunction {
032
033  enum Type {
034
035    /**
036     * The cost to fix an issue of this type depends on the magnitude of the issue.
037     * For instance, an issue related to file size might be linear, with the total cost-to-fix incrementing
038     * (by the gap multiplier amount) for each line of code above the allowed threshold.
039     * The rule must provide the "gap" value when raising an issue.
040     */
041    LINEAR(true, false),
042
043    /**
044     * It takes a certain amount of time to deal with an issue of this type (this is the gap multiplier).
045     * Then, the magnitude of the issue comes in to play. For instance, an issue related to complexity might be linear with offset.
046     * So the total cost to fix is the time to make the basic analysis (the base effort) plus the time required to deal
047     * with each complexity point above the allowed value.
048     * <p>
049     * <code>Total remediation cost = base effort + (number of noncompliance x gap multiplier)</code>
050     * 
051     * <p>The rule must provide the "gap" value when raising an issue. Let’s take as a example the “Paragraphs should not be too complex” rule.
052     * If you set the rule threshold to 20, and you have a paragraph with a complexity of 27, you have 7 points of complexity
053     * to remove. Internally, this is called the Gap. In that case, if you use the LINEAR_OFFSET configuration
054     * with an base effort of 4h and a remediation cost of 1mn, the effort for this issue related to a
055     * too-complex block of code will be: (7 complexity points x 1min) + 4h = 4h and 7mn
056     * 
057     */
058    LINEAR_OFFSET(true, true),
059
060    /**
061     * The cost to fix all the issues of the rule is the same whatever the number of issues
062     * of this rule in the file. Total remediation cost by file = constant
063     */
064    CONSTANT_ISSUE(false, true);
065
066    private final boolean usesGapMultiplier;
067    private final boolean usesBaseEffort;
068
069    Type(boolean usesGapMultiplier, boolean usesBaseEffort) {
070      this.usesGapMultiplier = usesGapMultiplier;
071      this.usesBaseEffort = usesBaseEffort;
072    }
073
074    /**
075     * @deprecated since 5.5, replaced by {@link #usesGapMultiplier()}
076     */
077    @Deprecated
078    public boolean usesCoefficient() {
079      return usesGapMultiplier();
080    }
081
082    /**
083     * @since 5.5
084     */
085    public boolean usesGapMultiplier() {
086      return usesGapMultiplier;
087    }
088
089    /**
090     * @deprecated since 5.5, replaced by {@link #usesBaseEffort()}
091     */
092    @Deprecated
093    public boolean usesOffset() {
094      return usesBaseEffort();
095    }
096
097    /**
098     * @since 5.5
099     */
100    public boolean usesBaseEffort() {
101      return usesBaseEffort;
102    }
103
104  }
105
106  /**
107   * @since 5.5
108   */
109  Type type();
110
111  /**
112   * @deprecated since 5.5, replaced by {@link #gapMultiplier()}
113   */
114  @Deprecated
115  @CheckForNull
116  String coefficient();
117
118  /**
119   * Non-null value on {@link Type#LINEAR} and {@link Type#LINEAR_OFFSET} functions, else {@code null}.
120   *
121   * @since 5.5
122   */
123  @CheckForNull
124  String gapMultiplier();
125
126  /**
127   * @deprecated since 5.5, replaced by {@link #baseEffort()}
128   */
129  @Deprecated
130  @CheckForNull
131  String offset();
132
133  /**
134   * Non-null value on {@link Type#LINEAR_OFFSET} and {@link Type#CONSTANT_ISSUE} functions, else {@code null}.
135   *
136   * @since 5.5
137   */
138  @CheckForNull
139  String baseEffort();
140
141}