001/*
002 * Sonar, open source software quality management tool.
003 * Copyright (C) 2008-2012 SonarSource
004 * mailto:contact AT sonarsource DOT com
005 *
006 * Sonar 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 * Sonar 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
017 * License along with Sonar; if not, write to the Free Software
018 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02
019 */
020package org.sonar.api.web;
021
022import com.google.common.base.Joiner;
023
024import com.google.common.base.Preconditions;
025import com.google.common.collect.ImmutableSortedSet;
026
027import java.util.Set;
028
029/**
030 * Definition of a criterion to be used to narrow down a {@see Filter}.
031 *
032 * @since 3.1
033 */
034public final class Criterion {
035  public static final String EQ = "eq";
036  public static final String GT = "gt";
037  public static final String GTE = "gte";
038  public static final String LT = "lt";
039  public static final String LTE = "lte";
040  public static final Set<String> OPERATORS = ImmutableSortedSet.of(EQ, GT, GTE, LT, LTE);
041
042  private final String family;
043  private final String key;
044  private final String operator;
045  private final Float value;
046  private final String textValue;
047  private final boolean variation;
048
049  private Criterion(String family, String key, String operator, Float value, String textValue, boolean variation) {
050    Preconditions.checkArgument(OPERATORS.contains(operator), "Valid operators are %s, not '%s'", OPERATORS, operator);
051
052    this.family = family;
053    this.key = key;
054    this.operator = operator;
055    this.value = value;
056    this.textValue = textValue;
057    this.variation = variation;
058  }
059
060  /**
061   * Creates a new {@link Criterion} with a numerical value.
062   *
063   * <p>Valid values for the {@code operator} are {@value #EQ}, {@value #GT}, {@value #GTE}, {@value #LT} and {@value #LTE}</p>
064   *
065   * @throws IllegalArgumentException if {@code operator} is not valid
066   */
067  public static Criterion create(String family, String key, String operator, Float value, boolean variation) {
068    return new Criterion(family, key, operator, value, null, variation);
069  }
070
071  /**
072   * Creates a new {@link Criterion} with a text value.
073   *
074   * <p>Valid values for the {@code operator} are {@value #EQ}, {@value #GT}, {@value #GTE}, {@value #LT} and {@value #LTE}</p>
075   *
076   * @throws IllegalArgumentException if {@code operator} is not valid
077   */
078  public static Criterion create(String family, String key, String operator, String textValue, boolean variation) {
079    return new Criterion(family, key, operator, null, textValue, variation);
080  }
081
082  /**
083   * Creates a new {@link Criterion} on a metric, with a numerical value.
084   *
085   * <p>Valid values for the {@code operator} are {@value #EQ}, {@value #GT}, {@value #GTE}, {@value #LT} and {@value #LTE}</p>
086   *
087   * @throws IllegalArgumentException if {@code operator} is not valid
088   */
089  public static Criterion createForMetric(String key, String operator, Float value, boolean variation) {
090    return new Criterion("metric", key, operator, value, null, variation);
091  }
092
093  /**
094   * Creates a new {@link Criterion} on a metric, with a text value.
095   *
096   * <p>Valid values for the {@code operator} are {@value #EQ}, {@value #GT}, {@value #GTE}, {@value #LT} and {@value #LTE}</p>
097   *
098   * @throws IllegalArgumentException if {@code operator} is not valid
099   */
100  public static Criterion createForMetric(String key, String operator, String textValue, boolean variation) {
101    return new Criterion("metric", key, operator, null, textValue, variation);
102  }
103
104  /**
105   * Creates a new {@link Criterion} on a qualifier.
106   */
107  public static Criterion createForQualifier(Object... values) {
108    return new Criterion("qualifier", null, EQ, null, Joiner.on(',').join(values), false);
109  }
110
111  /**
112   * Get the the criterion's family.
113   * 
114   * @return the family
115   */
116  public String getFamily() {
117    return family;
118  }
119
120  /**
121   * Get the the criterion's key.
122   * 
123   * @return the key
124   */
125  public String getKey() {
126    return key;
127  }
128
129  /**
130   * Get the the criterion's operator.
131   *
132   * <p>Valid values for the {@code operator} are {@value #EQ}, {@value #GT}, {@value #GTE}, {@value #LT} and {@value #LTE}</p>
133   *
134   * @return the operator
135   */
136  public String getOperator() {
137    return operator;
138  }
139
140  /**
141   * Get the the criterion's value.
142   * 
143   * @return the value
144   */
145  public Float getValue() {
146    return value;
147  }
148
149  /**
150   * Get the the criterion's value as text.
151   * 
152   * @return the value as text
153   */
154  public String getTextValue() {
155    return textValue;
156  }
157
158  /**
159   * A criterion can be based on the varation of a value rather than on the value itself.
160   * 
161   * @return <code>true</code> when the variation is used rather than the value
162   */
163  public boolean isVariation() {
164    return variation;
165  }
166}