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.ce.posttask;
021
022import java.util.Collection;
023import javax.annotation.CheckForNull;
024import org.sonar.api.measures.Metric;
025
026/**
027 * @since 5.5
028 */
029public interface QualityGate {
030  /**
031   * The unique identifier of the Quality Gate.
032   */
033  String getId();
034
035  /**
036   * Name of the Quality Gate.
037   */
038  String getName();
039
040  /**
041   * Status of the Quality Gate for the current project processing.
042   */
043  Status getStatus();
044
045  /**
046   * Conditions of the Quality Gate.
047   */
048  Collection<Condition> getConditions();
049
050  enum Status {
051    /** at least one threshold is defined, no threshold is reached */
052    OK,
053    /** at least one warning threshold is reached, no error threshold is reached */
054    WARN,
055    /** at least one error threshold is reached */
056    ERROR
057  }
058
059  interface Condition {
060    /**
061     * Evaluation status of this condition
062     */
063    EvaluationStatus getStatus();
064
065    /**
066     * The key of the metric this condition has been evaluated on.
067     * <p>
068     * The {@link org.sonar.api.measures.Metric} for the returned key can be retrieved using a
069     * {@link org.sonar.api.measures.MetricFinder} instance.
070     * 
071     *
072     * @see org.sonar.api.batch.measure.MetricFinder#findByKey(String)
073     */
074    String getMetricKey();
075
076    /**
077     * The operator used to evaluate the error and/or warning thresholds against the value of the measure
078     */
079    Operator getOperator();
080
081    /**
082     * <p>
083     * At least one of {@link #getErrorThreshold()} and {@link #getWarningThreshold()} is guaranteed to be non {@code null}.
084     * 
085     *
086     * @see #getWarningThreshold()
087     */
088    @CheckForNull
089    String getErrorThreshold();
090
091    /**
092     *
093     * <p>
094     * At least one of {@link #getErrorThreshold()} and {@link #getWarningThreshold()} is guaranteed to be non {@code null}.
095     * 
096     *
097     * @see #getErrorThreshold()
098     */
099    @CheckForNull
100    String getWarningThreshold();
101
102    /**
103     * Whether this condition is defined on the leak period or on an absolute value
104     */
105    boolean isOnLeakPeriod();
106
107    /**
108     * The value of the measure.
109     * <p>
110     * If the type of the metric (which key is provided by {@link #getMetricKey()}) is numerical, the value can be parsed
111     * using {@link Integer#valueOf(String)}, {@link Long#valueOf(String)} or {@link Double#valueOf(String)}.
112     * 
113     *
114     * @throws IllegalStateException if {@link #getStatus()} is {@link EvaluationStatus#NO_VALUE}
115     *
116     * @see Metric#getType() 
117     */
118    String getValue();
119
120  }
121
122  /**
123   * Quality Gate condition operator.
124   */
125  enum Operator {
126    EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN
127  }
128
129  /**
130   * Quality gate condition evaluation status.
131   */
132  enum EvaluationStatus {
133    /**
134     * No measure found or measure had no value. The condition has not been evaluated and therefor ignored in
135     * the computation of the Quality Gate status.
136     */
137    NO_VALUE,
138    /**
139     * Condition evaluated as OK, neither error nor warning thresholds have been reached.
140     */
141    OK,
142    /**
143     * Condition evaluated as WARN, only warning thresholds has been reached.
144     */
145    WARN,
146    /**
147     * Condition evaluated as ERROR, error thresholds has been reached (and most likely warning thresholds too).
148     */
149    ERROR
150  }
151}