SONAR-5864 API cleanup

  * add a proper way to create perspective on InputFile
  * add a proper way to convert InputFile to resource
  * deprecate colorizer

9 files changed, 70 insertions, 10 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/Decorator.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/Decorator.java
index b3f2792b507..d6337af5bc2 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/Decorator.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/Decorator.java
@@ -24,7 +24,10 @@ import org.sonar.api.resources.Resource;
 
 /**
  * @since 1.10
+ * @deprecated since 4.5.2. Starting from SQ 5.x aggregation/computation of data will be mostly done on server side.
+ * As a result Decoration on batch side will be dropped at some point.
  */
+@Deprecated
 public interface Decorator extends BatchExtension, CheckProject {
 
   /**
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/PostJob.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/PostJob.java
index 52eff7acc68..5de94ebd007 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/PostJob.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/PostJob.java
@@ -30,7 +30,10 @@ import org.sonar.api.resources.Project;
  * </p>
  *
  * @since 1.10
+ * @deprecated since 4.5.2. Starting from SQ 5.0 a big part of project analysis will be processed asynchnonously on server side. As
+ * a result batch analysis will ends very quickly and probably before analysis results are persisted in SQ server referentials.
  */
+@Deprecated
 public interface PostJob extends BatchExtension {
 
   void executeOn(Project project, SensorContext context);
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/SensorContext.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/SensorContext.java
index c76eaf47138..a21d421e6ac 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/SensorContext.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/SensorContext.java
@@ -19,8 +19,8 @@
  */
 package org.sonar.api.batch;
 
-import com.google.common.annotations.Beta;
 import org.sonar.api.batch.fs.InputFile;
+import org.sonar.api.batch.fs.InputPath;
 import org.sonar.api.design.Dependency;
 import org.sonar.api.measures.Measure;
 import org.sonar.api.measures.MeasuresFilter;
@@ -252,16 +252,20 @@ public interface SensorContext {
   void deleteEvent(Event event);
 
   /**
-   * Experimental - do not use
+   * Save measure on {@link InputFile}
    * @since 4.2
    */
-  @Beta
   Measure saveMeasure(InputFile inputFile, Metric metric, Double value);
 
   /**
-   * Experimental - do not use
+   * Save measure on {@link InputFile}
    * @since 4.2
    */
-  @Beta
   Measure saveMeasure(InputFile inputFile, Measure measure);
+
+  /**
+   * Allow to get {@link Resource} corresponding to provided {@link InputPath}.
+   * @since 4.5.2
+   */
+  Resource getResource(InputPath inputPath);
 }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/SonarIndex.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/SonarIndex.java
index cbe29014b2f..39124edb2ab 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/SonarIndex.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/SonarIndex.java
@@ -36,6 +36,10 @@ import java.util.Date;
 import java.util.List;
 import java.util.Set;
 
+/**
+ * @deprecated since 4.5.2 should not be used by plugins.
+ */
+@Deprecated
 public abstract class SonarIndex implements DirectedGraphAccessor<Resource, Dependency> {
 
   /**
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/component/ResourcePerspectives.java b/sonar-plugin-api/src/main/java/org/sonar/api/component/ResourcePerspectives.java
index d992b571001..18bce8f9e36 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/component/ResourcePerspectives.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/component/ResourcePerspectives.java
@@ -19,17 +19,54 @@
  */
 package org.sonar.api.component;
 
+import org.sonar.api.batch.fs.InputFile;
+import org.sonar.api.batch.fs.InputPath;
+import org.sonar.api.issue.Issuable;
 import org.sonar.api.resources.Resource;
+import org.sonar.api.source.Highlightable;
+import org.sonar.api.source.Symbolizable;
+import org.sonar.api.test.TestPlan;
+import org.sonar.api.test.Testable;
 
 import javax.annotation.CheckForNull;
 
 /**
+ * Use this component to create perspective from resources or {@link InputPath}
  * Only on batch-side.
+ * 
+ * <pre>
+ * public class MySensor implements Sensor {
+ *   private final ResourcePerspectives perspectives;
  *
+ *   public MySensor(ResourcePerspectives perspectives) {
+ *     this.perspectives = perspectives;
+ *   }
+ *   
+ *   public void analyse(Project module, SensorContext context) {
+ *      // Get some Resource or InputFile/InputPath
+ *      Highlightable highlightable = perspectives.as(Highlightable.class, inputPath);
+ *      if (highlightable != null) {
+ *        ...
+ *      }
+ *   }
+ * }
+ * </pre>
+ * @see Issuable
+ * @see Highlightable
+ * @see Symbolizable
+ * @see Testable
+ * @see TestPlan
  * @since 3.5
  */
 public interface ResourcePerspectives extends Perspectives {
 
   @CheckForNull
   <P extends Perspective> P as(Class<P> perspectiveClass, Resource resource);
+
+  /**
+   * Allow to create perspective from {@link InputPath}. In particular from {@link InputFile}.
+   * @since 4.5.2
+   */
+  @CheckForNull
+  <P extends Perspective> P as(Class<P> perspectiveClass, InputPath inputPath);
 }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/measures/CoreMetrics.java b/sonar-plugin-api/src/main/java/org/sonar/api/measures/CoreMetrics.java
index 3269bd99336..a2a677d7151 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/measures/CoreMetrics.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/measures/CoreMetrics.java
@@ -1319,7 +1319,7 @@ public final class CoreMetrics {
     .create();
 
   /**
-   * @deprecated since 4.5. Internal storage of duplication is not an API. No more available on batch side.
+   * @deprecated since 4.5. Internal storage of duplication is not an API.
    */
   @Deprecated
   public static final String DUPLICATIONS_DATA_KEY = "duplications_data";
@@ -1340,7 +1340,7 @@ public final class CoreMetrics {
    *   </duplications>
    * </pre>
    * </p>
-   * @deprecated since 4.5. Internal storage of duplication is not an API. No more available on batch side.
+   * @deprecated since 4.5. Internal storage of duplication is not an API.
    */
   @Deprecated
   public static final Metric<String> DUPLICATIONS_DATA = new Metric.Builder(DUPLICATIONS_DATA_KEY, "Duplications details", Metric.ValueType.DATA)
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/source/Highlightable.java b/sonar-plugin-api/src/main/java/org/sonar/api/source/Highlightable.java
index 0ab229be03c..6c843b4ba26 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/source/Highlightable.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/source/Highlightable.java
@@ -20,8 +20,11 @@
 package org.sonar.api.source;
 
 import org.sonar.api.component.Perspective;
+import org.sonar.api.component.ResourcePerspectives;
 
 /**
+ * Use this perspective to save syntax highlighting on files.
+ * See {@link ResourcePerspectives}.
  * @since 3.6
  */
 public interface Highlightable extends Perspective {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/source/Symbolizable.java b/sonar-plugin-api/src/main/java/org/sonar/api/source/Symbolizable.java
index 3a49ada34df..1cc82162047 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/source/Symbolizable.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/source/Symbolizable.java
@@ -20,10 +20,13 @@
 package org.sonar.api.source;
 
 import org.sonar.api.component.Perspective;
+import org.sonar.api.component.ResourcePerspectives;
 
 import java.util.List;
 
 /**
+ * Use this perspective to save symbol references on files.
+ * See {@link ResourcePerspectives}.
  * @since 3.6
  */
 public interface Symbolizable extends Perspective {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/web/CodeColorizerFormat.java b/sonar-plugin-api/src/main/java/org/sonar/api/web/CodeColorizerFormat.java
index 26544ad5c50..4c6c32a278a 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/web/CodeColorizerFormat.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/web/CodeColorizerFormat.java
@@ -19,17 +19,20 @@
  */
 package org.sonar.api.web;
 
-import java.util.List;
-
 import com.google.common.base.Objects;
 import org.sonar.api.ServerExtension;
+import org.sonar.api.source.Highlightable;
 import org.sonar.colorizer.Tokenizer;
 
+import java.util.List;
+
 /**
  * Extend the library sonar-colorizer to support new languages. By default only Java sources are colorized in Sonar.
  * 
  * @since 1.12
+ * @deprecated since 4.5.2 use {@link Highlightable}
  */
+@Deprecated
 public abstract class CodeColorizerFormat implements ServerExtension {
 
   private String languageKey;
@@ -57,7 +60,7 @@ public abstract class CodeColorizerFormat implements ServerExtension {
     if (this == o) {
       return true;
     }
-    if ( !(o instanceof CodeColorizerFormat)) {
+    if (!(o instanceof CodeColorizerFormat)) {
       return false;
     }