SONAR-7636 Deprecate org.sonar.api.measures.Measure + many small API improvements

plugins/sonar-xoo-plugin/src/test/java/org/sonar/xoo/lang/MeasureSensorTest.java

@@ -19,6 +19,8 @@
  */
 package org.sonar.xoo.lang;
 
+import java.io.File;
+import java.io.IOException;
 import org.apache.commons.io.FileUtils;
 import org.junit.Before;
 import org.junit.Rule;
@@ -32,9 +34,6 @@ import org.sonar.api.batch.sensor.internal.SensorContextTester;
 import org.sonar.api.measures.CoreMetrics;
 import org.sonar.api.measures.Metric;
 
-import java.io.File;
-import java.io.IOException;
-
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.when;
@@ -83,10 +82,10 @@ public class MeasureSensorTest {
     Metric<Boolean> booleanMetric = new Metric.Builder("bool", "Bool", Metric.ValueType.BOOL)
       .create();
 
-    when(metricFinder.findByKey("ncloc")).thenReturn(CoreMetrics.NCLOC);
-    when(metricFinder.findByKey("branch_coverage")).thenReturn(CoreMetrics.BRANCH_COVERAGE);
-    when(metricFinder.findByKey("sqale_index")).thenReturn(CoreMetrics.TECHNICAL_DEBT);
-    when(metricFinder.findByKey("bool")).thenReturn(booleanMetric);
+    when(metricFinder.<Integer>findByKey("ncloc")).thenReturn(CoreMetrics.NCLOC);
+    when(metricFinder.<Double>findByKey("branch_coverage")).thenReturn(CoreMetrics.BRANCH_COVERAGE);
+    when(metricFinder.<Long>findByKey("sqale_index")).thenReturn(CoreMetrics.TECHNICAL_DEBT);
+    when(metricFinder.<Boolean>findByKey("bool")).thenReturn(booleanMetric);
 
     sensor.execute(context);
 

sonar-plugin-api/src/main/java/org/sonar/api/batch/measure/MetricFinder.java

@@ -19,12 +19,11 @@
  */
 package org.sonar.api.batch.measure;
 
-import org.sonar.api.batch.BatchSide;
-
-import javax.annotation.CheckForNull;
-
+import java.io.Serializable;
 import java.util.Collection;
 import java.util.List;
+import javax.annotation.CheckForNull;
+import org.sonar.api.batch.BatchSide;
 
 /**
  * @since 4.5
@@ -33,9 +32,9 @@ import java.util.List;
 public interface MetricFinder {
 
   @CheckForNull
-  Metric findByKey(String key);
+  <G extends Serializable> Metric<G> findByKey(String key);
 
-  Collection<Metric> findAll(List<String> metricKeys);
+  Collection<Metric<Serializable>> findAll(List<String> metricKeys);
 
-  Collection<Metric> findAll();
+  Collection<Metric<Serializable>> findAll();
 }

sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/measure/NewMeasure.java

@@ -22,6 +22,7 @@ package org.sonar.api.batch.sensor.measure;
 import java.io.Serializable;
 import org.sonar.api.batch.fs.InputComponent;
 import org.sonar.api.batch.measure.Metric;
+import org.sonar.api.batch.measure.MetricFinder;
 
 /**
  * Builder to create new Measure.
@@ -36,7 +37,7 @@ public interface NewMeasure<G extends Serializable> {
   NewMeasure<G> on(InputComponent component);
 
   /**
-   * Set the metric this measure belong to.
+   * Set the metric this measure belong to. To find a metric based on its key you can use {@link MetricFinder}.
    */
   NewMeasure<G> forMetric(Metric<G> metric);
 

sonar-plugin-api/src/main/java/org/sonar/api/measures/CountDistributionBuilder.java

@@ -33,7 +33,9 @@ import org.sonar.api.utils.SonarException;
  * <p>An example of usage : you wish to record the number of violations for each level of rules priority
  *
  * @since 1.10
+ * @deprecated since 5.6. Scanner side is not responsible to aggregate measures since 5.2.
  */
+@Deprecated
 public class CountDistributionBuilder implements MeasureBuilder {
 
   private final Metric metric;

sonar-plugin-api/src/main/java/org/sonar/api/measures/Measure.java

@@ -26,12 +26,15 @@ import javax.annotation.CheckForNull;
 import javax.annotation.Nullable;
 import org.apache.commons.lang.builder.ReflectionToStringBuilder;
 import org.apache.commons.lang.math.NumberUtils;
+import org.sonar.api.batch.sensor.SensorContext;
 
 /**
  * A class to handle measures.
  *
  * @since 1.10
+ * @deprecated since 5.6. To create a new measure on scanner side use {@link SensorContext#newMeasure()}
  */
+@Deprecated
 public class Measure<G extends Serializable> implements Serializable {
   private static final String INDEX_SHOULD_BE_IN_RANGE_FROM_1_TO_5 = "Index should be in range from 1 to 5";
 

sonar-plugin-api/src/main/java/org/sonar/api/measures/MeasureBuilder.java

@@ -19,11 +19,15 @@
  */
 package org.sonar.api.measures;
 
+import org.sonar.api.batch.sensor.SensorContext;
+
 /**
  * MeasureBuilder helps to build complex measures.
  *
  * @since 1.10
+ * @deprecated since 5.6. To create a new measure on scanner side use {@link SensorContext#newMeasure()}
  */
+@Deprecated
 public interface MeasureBuilder {
   Measure build();
 }

sonar-plugin-api/src/main/java/org/sonar/api/measures/MeasureUtils.java

@@ -19,17 +19,17 @@
  */
 package org.sonar.api.measures;
 
-import org.apache.commons.lang.StringUtils;
-
-import javax.annotation.Nullable;
-
 import java.util.Collection;
+import javax.annotation.Nullable;
+import org.apache.commons.lang.StringUtils;
 
 /**
  * An utility class to manipulate measures
  *
  * @since 1.10
+ * @deprecated since 5.6. {@link Measure} is deprecated.
  */
+@Deprecated
 public final class MeasureUtils {
 
   /**

sonar-plugin-api/src/main/java/org/sonar/api/measures/MeasuresFilter.java

@@ -23,7 +23,9 @@ import java.util.Collection;
 
 /**
  * @since 1.10
+ * @deprecated since 5.6. Sensor should only save measures and not read them.
  */
+@Deprecated
 public interface MeasuresFilter<M> {
 
   M filter(Collection<Measure> measures);

sonar-plugin-api/src/main/java/org/sonar/api/measures/MeasuresFilters.java

@@ -27,7 +27,9 @@ import org.sonar.api.rules.Rule;
 
 /**
  * @since 1.10
+ * @deprecated since 5.6. Sensor should only save measures and not read them.
  */
+@Deprecated
 public final class MeasuresFilters {
 
   private MeasuresFilters() {

sonar-plugin-api/src/main/java/org/sonar/api/measures/Metric.java

@@ -38,6 +38,10 @@ import static com.google.common.base.Objects.firstNonNull;
 import static com.google.common.base.Preconditions.checkArgument;
 import static org.apache.commons.lang.StringUtils.isNotBlank;
 
+/**
+ * Used to define a metric in a plugin. Should be used with {@link Metrics} extension point.
+ * Should no more be used on scanner side. Use {@link org.sonar.api.batch.measure.Metric} instead. 
+ */
 @BatchSide
 @InstantiationStrategy(InstantiationStrategy.PER_BATCH)
 @ServerSide

sonar-plugin-api/src/main/java/org/sonar/api/measures/MetricFinder.java

@@ -28,7 +28,7 @@ import org.sonar.api.server.ServerSide;
 
 /**
  * @since 2.5
- * @deprecated since 5.1 use {@link org.sonar.api.batch.measure.MetricFinder} on batch side
+ * @deprecated since 5.1 use {@link org.sonar.api.batch.measure.MetricFinder} on scanner side.
  */
 @Deprecated
 @BatchSide

sonar-plugin-api/src/main/java/org/sonar/api/measures/Metrics.java

@@ -27,6 +27,7 @@ import org.sonar.api.ce.ComputeEngineSide;
 import org.sonar.api.server.ServerSide;
 
 /**
+ * This is the extension point used by plugins to declare new metrics.
  * @since 1.10
  */
 @BatchSide

sonar-plugin-api/src/main/java/org/sonar/api/measures/PersistenceMode.java

@@ -28,7 +28,9 @@ package org.sonar.api.measures;
  * </ul>
  *
  * @since 1.10
+ * @deprecated since 5.6. No more used since 5.2.
  */
+@Deprecated
 public enum PersistenceMode {
   MEMORY, DATABASE, FULL;
 

sonar-plugin-api/src/main/java/org/sonar/api/measures/PropertiesBuilder.java

@@ -19,14 +19,15 @@
  */
 package org.sonar.api.measures;
 
-import org.sonar.api.utils.KeyValueFormat;
-
 import java.util.Map;
 import java.util.TreeMap;
+import org.sonar.api.utils.KeyValueFormat;
 
 /**
  * @since 1.10
+ * @deprecated since 5.6. Use directly {@link KeyValueFormat}.
  */
+@Deprecated
 public class PropertiesBuilder<K, V> {
   private Metric metric;
   private Map<K, V> props;

sonar-scanner-engine/src/main/java/org/sonar/batch/scan/measure/DefaultMetricFinder.java

@@ -20,18 +20,19 @@
 package org.sonar.batch.scan.measure;
 
 import com.google.common.collect.Lists;
-import org.sonar.api.batch.measure.Metric;
-import org.sonar.api.batch.measure.MetricFinder;
-import org.sonar.api.measures.Metric.ValueType;
-import org.sonar.scanner.protocol.input.GlobalRepositories;
+import java.io.Serializable;
 import java.util.Collection;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import org.sonar.api.batch.measure.Metric;
+import org.sonar.api.batch.measure.MetricFinder;
+import org.sonar.api.measures.Metric.ValueType;
+import org.sonar.scanner.protocol.input.GlobalRepositories;
 
 public class DefaultMetricFinder implements MetricFinder {
 
-  private Map<String, Metric> metricsByKey = new LinkedHashMap<>();
+  private Map<String, Metric<Serializable>> metricsByKey = new LinkedHashMap<>();
 
   public DefaultMetricFinder(GlobalRepositories globalReferentials) {
     for (org.sonar.scanner.protocol.input.Metric metric : globalReferentials.metrics()) {
@@ -40,15 +41,15 @@ public class DefaultMetricFinder implements MetricFinder {
   }
 
   @Override
-  public Metric findByKey(String key) {
+  public Metric<Serializable> findByKey(String key) {
     return metricsByKey.get(key);
   }
 
   @Override
-  public Collection<Metric> findAll(List<String> metricKeys) {
-    List<Metric> result = Lists.newLinkedList();
+  public Collection<Metric<Serializable>> findAll(List<String> metricKeys) {
+    List<Metric<Serializable>> result = Lists.newLinkedList();
     for (String metricKey : metricKeys) {
-      Metric metric = findByKey(metricKey);
+      Metric<Serializable> metric = findByKey(metricKey);
       if (metric != null) {
         result.add(metric);
       }
@@ -57,7 +58,7 @@ public class DefaultMetricFinder implements MetricFinder {
   }
 
   @Override
-  public Collection<Metric> findAll() {
+  public Collection<Metric<Serializable>> findAll() {
     return metricsByKey.values();
   }
 

sonar-scanner-engine/src/main/java/org/sonar/batch/scan/measure/MeasureCache.java

@@ -64,8 +64,8 @@ public class MeasureCache {
   }
 
   @CheckForNull
-  public Measure byMetric(String resourceKey, String metricKey) {
-    return cache.get(resourceKey, metricKey);
+  public Measure byMetric(String componentKey, String metricKey) {
+    return cache.get(componentKey, metricKey);
   }
 
   public MeasureCache put(Resource resource, Measure measure) {

sonar-scanner-engine/src/test/java/org/sonar/batch/scan/measure/MeasureCacheTest.java

@@ -53,7 +53,7 @@ public class MeasureCacheTest extends AbstractCachesTest {
   public void start() {
     super.start();
     metricFinder = mock(MetricFinder.class);
-    when(metricFinder.findByKey(CoreMetrics.NCLOC_KEY)).thenReturn(CoreMetrics.NCLOC);
+    when(metricFinder.<Integer>findByKey(CoreMetrics.NCLOC_KEY)).thenReturn(CoreMetrics.NCLOC);
     measureCache = new MeasureCache(caches, metricFinder);
   }
 

sonar-scanner-engine/src/test/java/org/sonar/batch/sensor/DefaultSensorContextTest.java

@@ -61,8 +61,8 @@ public class DefaultSensorContextTest {
     activeRules = new ActiveRulesBuilder().build();
     fs = new DefaultFileSystem(temp.newFolder().toPath());
     MetricFinder metricFinder = mock(MetricFinder.class);
-    when(metricFinder.findByKey(CoreMetrics.NCLOC_KEY)).thenReturn(CoreMetrics.NCLOC);
-    when(metricFinder.findByKey(CoreMetrics.FUNCTION_COMPLEXITY_DISTRIBUTION_KEY)).thenReturn(CoreMetrics.FUNCTION_COMPLEXITY_DISTRIBUTION);
+    when(metricFinder.<Integer>findByKey(CoreMetrics.NCLOC_KEY)).thenReturn(CoreMetrics.NCLOC);
+    when(metricFinder.<String>findByKey(CoreMetrics.FUNCTION_COMPLEXITY_DISTRIBUTION_KEY)).thenReturn(CoreMetrics.FUNCTION_COMPLEXITY_DISTRIBUTION);
     settings = new Settings();
     sensorStorage = mock(SensorStorage.class);
     analysisMode = mock(AnalysisMode.class);

sonar-scanner-engine/src/test/java/org/sonar/batch/sensor/DefaultSensorStorageTest.java

@@ -75,8 +75,8 @@ public class DefaultSensorStorageTest {
     activeRules = new ActiveRulesBuilder().build();
     fs = new DefaultFileSystem(temp.newFolder().toPath());
     MetricFinder metricFinder = mock(MetricFinder.class);
-    when(metricFinder.findByKey(CoreMetrics.NCLOC_KEY)).thenReturn(CoreMetrics.NCLOC);
-    when(metricFinder.findByKey(CoreMetrics.FUNCTION_COMPLEXITY_DISTRIBUTION_KEY)).thenReturn(CoreMetrics.FUNCTION_COMPLEXITY_DISTRIBUTION);
+    when(metricFinder.<Integer>findByKey(CoreMetrics.NCLOC_KEY)).thenReturn(CoreMetrics.NCLOC);
+    when(metricFinder.<String>findByKey(CoreMetrics.FUNCTION_COMPLEXITY_DISTRIBUTION_KEY)).thenReturn(CoreMetrics.FUNCTION_COMPLEXITY_DISTRIBUTION);
     settings = new Settings();
     moduleIssues = mock(ModuleIssues.class);
     project = new Project("myProject");