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