Revert deprecation of SonarQubeVersion

so that compatibility with 5.6 does not need
to call deprecated code.

4 files changed, 132 insertions, 21 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/Plugin.java b/sonar-plugin-api/src/main/java/org/sonar/api/Plugin.java
index 965a1b13b01..5704668577b 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/Plugin.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/Plugin.java
@@ -37,7 +37,7 @@ import static java.util.Objects.requireNonNull;
  *  {@literal @}Override
  *   public void define(Context context) {
  *     context.addExtensions(MySensor.class, MyRules.class);
- *     if (context.getRuntime().getApiVersion().isGreaterThanOrEqual(Version.create(6, 0))) {
+ *     if (context.getSonarQubeVersion().isGreaterThanOrEqual(Version.create(6, 0))) {
  *       // Extension which supports only versions 6.0 and greater
  *       // See org.sonar.api.SonarRuntime for more details.
  *       context.addExtension(MyNewExtension.class);
@@ -93,9 +93,12 @@ public interface Plugin {
     }
 
     /**
-     * @deprecated replaced by {@link #getRuntime()}.getApiVersion() in 6.0
+     * Shortcut on {@code getRuntime().getApiVersion()} since version 6.0.
+     *
+     * @see #getRuntime()
+     * @since 5.5
+     * @return the version of SonarQube API at runtime, not at compilation time
      */
-    @Deprecated
     public Version getSonarQubeVersion() {
       return sonarRuntime.getApiVersion();
     }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/SonarQubeVersion.java b/sonar-plugin-api/src/main/java/org/sonar/api/SonarQubeVersion.java
index 6b4e100939f..b6f79dc74bc 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/SonarQubeVersion.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/SonarQubeVersion.java
@@ -21,6 +21,8 @@ package org.sonar.api;
 
 import javax.annotation.concurrent.Immutable;
 import org.sonar.api.batch.ScannerSide;
+import org.sonar.api.batch.sensor.Sensor;
+import org.sonar.api.batch.sensor.SensorContext;
 import org.sonar.api.ce.ComputeEngineSide;
 import org.sonar.api.server.ServerSide;
 import org.sonar.api.utils.Version;
@@ -28,25 +30,123 @@ import org.sonar.api.utils.Version;
 import static java.util.Objects.requireNonNull;
 
 /**
- * Version of SonarQube at runtime. Replaced by {@link SonarRuntime#getApiVersion()}.
+ * Version of SonarQube at runtime, but not at compilation time.
+ * This component can be injected as a dependency of plugin extensions.
+ * The main usage for a plugin is to benefit from new APIs
+ * while keeping backward-compatibility with previous versions of API.
  *
+ * <p>
+ * Example: a plugin extension needs a new feature of API 6.0 without
+ * breaking compatibility with version 5.6 at runtime. This new feature
+ * would be disabled when plugin is executed within SonarQube 5.6.
+ * </p>
+ * <pre>
+ * // Component provided by sonar-plugin-api
+ * // @since 5.6
+ * public interface AnApi {
+ *   // implicitly since 5.6
+ *   public void foo();
+ *
+ *   // @since 6.0
+ *   public void bar();
+ * }
+ *
+ * // Component provided by plugin
+ * public class MyExtension {
+ *   private final SonarQubeVersion sonarQubeVersion;
+ *   private final AnApi api;
+ *
+ *   public MyExtension(SonarQubeVersion sonarQubeVersion, AnApi api) {
+ *     this.sonarQubeVersion = sonarQubeVersion;
+ *     this.api = api;
+ *   }
+ *
+ *   public void doSomething() {
+ *     // assume that runtime is 5.6+
+ *     api.foo();
+ *
+ *     if (sonarQubeVersion.isGreaterThanOrEqual(Version.create(6, 0))) {
+ *       api.bar();
+ *     }
+ *   }
+ * }
+ * </pre>
+ *
+ * <p>
+ *   Note that {@link Sensor} extensions can directly get {@link SonarQubeVersion} through
+ * {@link SensorContext#getSonarQubeVersion()}, without using constructor injection:
+ * </p>
+ * <pre>
+ * public class MySensor implements Sensor {
+ *
+ *   public void execute(SensorContext context) {
+ *     if (context.getSonarQubeVersion().isGreaterThanOrEqual(Version.create(6, 0)) {
+ *       context.newMethodIntroducedIn6_0();
+ *     }
+ *   }
+ *
+ * }
+ * </pre>
+ * <p>
+ * The minimal supported version of SonarQube is verified at runtime. As plugin is built
+ * with sonar-plugin-api 6.0, we assume that the plugin requires v6.0 or greater at runtime.
+ * As the plugin codebase is compatible with 5.6, the plugin must define what is the
+ * effective minimal supported version through the configuration of sonar-packaging-maven-plugin 1.16+:
+ * <p>
+ * <pre>
+ * &lt;packaging&gt;sonar-plugin&lt;/packaging&gt;
+ *
+ * &lt;dependencies&gt;
+ *   &lt;dependency&gt;
+ *     &lt;groupId&gt;org.sonarsource.sonarqube&lt;/groupId&gt;
+ *     &lt;artifactId&gt;sonar-plugin-api&lt;/artifactId&gt;
+ *     &lt;version&gt;6.0&lt;/version&gt;
+ *     &lt;scope&gt;provided&lt;/scope&gt;
+ *   &lt;/dependency&gt;
+ * &lt;/dependencies&gt;
+ *
+ * &lt;build&gt;
+ *  &lt;plugins&gt;
+ *    &lt;plugin&gt;
+ *      &lt;groupId&gt;org.sonarsource.sonar-packaging-maven-plugin&lt;/groupId&gt;
+ *      &lt;artifactId&gt;sonar-packaging-maven-plugin&lt;/artifactId&gt;
+ *      &lt;version&gt;1.16&lt;/version&gt;
+ *      &lt;extensions&gt;true&lt;/extensions&gt;
+ *      &lt;configuration&gt;
+ *        &lt;!-- Override the default value 6.0 which is guessed from sonar-plugin-api dependency --&gt;
+ *        &lt;sonarQubeMinVersion&gt;5.6&lt;/sonarQubeMinVersion&gt;
+ *      &lt;/configuration&gt;
+ *    &lt;/plugin&gt;
+ *  &lt;/plugins&gt;
+ * &lt;/build&gt;
+ * </pre>
+ *
+ * <p>
+ * The component {@link SonarRuntime}, introduced in version 6.0, is more complete.
+ * It is preferred over {@link SonarQubeVersion} if compatibility with version 5.6 Long Term Support
+ * is not required.
+ * </p>
+ *
+ * @see SonarRuntime
  * @since 5.5
- * @deprecated replaced by {@link SonarRuntime} in version 6.0
  */
 @ScannerSide
 @ServerSide
 @ComputeEngineSide
 @Immutable
-@Deprecated
 public class SonarQubeVersion {
   /**
    * Constant for version 5.5
+   * @deprecated in 6.0. Please define your own constants.
    */
+  @Deprecated
   public static final Version V5_5 = Version.create(5, 5);
 
   /**
    * Constant for version 5.6
+   * @deprecated in 6.0. Please define your own constants.
    */
+  @Deprecated
   public static final Version V5_6 = Version.create(5, 6);
 
   private final Version version;
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/SonarRuntime.java b/sonar-plugin-api/src/main/java/org/sonar/api/SonarRuntime.java
index b2663ca1da8..fdae32f5f5f 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/SonarRuntime.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/SonarRuntime.java
@@ -37,18 +37,18 @@ import org.sonarsource.api.sonarlint.SonarLintSide;
  * </p>
  *
  * <p>
- * Example: a plugin extension wants to use a new feature of API 6.0 without
- * breaking compatibility with version 5.6 at runtime. This new feature
- * would be enabled only in 6.0 and greater runtimes.
+ * Example: a plugin extension wants to use a new feature of API 6.1 without
+ * breaking compatibility with version 6.0 at runtime. This new feature
+ * would be enabled only in 6.1 and greater runtimes.
  * </p>
  * <pre>
  * // Component provided by sonar-plugin-api
- * // @since 5.6
+ * // @since 6.0
  * public interface AnApi {
- *   // implicitly since 5.6
+ *   // implicitly since 6.0
  *   public void foo();
  *
- *   // @since 6.0
+ *   // @since 6.1
  *   public void bar();
  * }
  * 
@@ -63,10 +63,10 @@ import org.sonarsource.api.sonarlint.SonarLintSide;
  *   }
  *
  *   public void doSomething() {
- *     // assume that minimal supported runtime is 5.6
+ *     // assume that minimal supported runtime is 6.0
  *     api.foo();
  *
- *     if (sonarRuntime.getApiVersion().isGreaterThanOrEqual(Version.create(6, 0))) {
+ *     if (sonarRuntime.getApiVersion().isGreaterThanOrEqual(Version.create(6, 1))) {
  *       api.bar();
  *     }
  *   }
@@ -82,7 +82,7 @@ import org.sonarsource.api.sonarlint.SonarLintSide;
  * public class MySensor implements Sensor {
  *
  *   public void execute(SensorContext context) {
- *     if (context.runtime().getApiVersion().isGreaterThanOrEqual(Version.create(6, 0)) {
+ *     if (context.runtime().getApiVersion().isGreaterThanOrEqual(Version.create(6, 1)) {
  *       context.newMethodIntroducedIn6_0();
  *     }
  *   }
@@ -92,7 +92,7 @@ import org.sonarsource.api.sonarlint.SonarLintSide;
  *
  * <p>
  * The minimal supported version of plugin API is verified at runtime. As plugin is built
- * with sonar-plugin-api 6.0, we assume that the plugin requires v6.0 or greater at runtime.
+ * with sonar-plugin-api 6.1, we assume that the plugin requires v6.1 or greater at runtime.
  * For this reason the plugin must override the minimal supported version
  * in the configuration of sonar-packaging-maven-plugin 1.16+:
  * <p>
@@ -103,7 +103,7 @@ import org.sonarsource.api.sonarlint.SonarLintSide;
  *   &lt;dependency&gt;
  *     &lt;groupId&gt;org.sonarsource.sonarqube&lt;/groupId&gt;
  *     &lt;artifactId&gt;sonar-plugin-api&lt;/artifactId&gt;
- *     &lt;version&gt;6.0&lt;/version&gt;
+ *     &lt;version&gt;6.1&lt;/version&gt;
  *     &lt;scope&gt;provided&lt;/scope&gt;
  *   &lt;/dependency&gt;
  * &lt;/dependencies&gt;
@@ -116,8 +116,8 @@ import org.sonarsource.api.sonarlint.SonarLintSide;
  *      &lt;version&gt;1.16&lt;/version&gt;
  *      &lt;extensions&gt;true&lt;/extensions&gt;
  *      &lt;configuration&gt;
- *        &lt;!-- Override the default value 5.6 which is guessed from sonar-plugin-api dependency --&gt;
- *        &lt;sonarQubeMinVersion&gt;5.6&lt;/sonarQubeMinVersion&gt;
+ *        &lt;!-- Override the default value 6.0 which is guessed from sonar-plugin-api dependency --&gt;
+ *        &lt;sonarQubeMinVersion&gt;6.0&lt;/sonarQubeMinVersion&gt;
  *      &lt;/configuration&gt;
  *    &lt;/plugin&gt;
  *  &lt;/plugins&gt;
@@ -125,6 +125,13 @@ import org.sonarsource.api.sonarlint.SonarLintSide;
  * </pre>
  *
  * <p>
+ *   As this component was introduced in version 6.0, the pattern described above can't be
+ *   exactly applied when plugin must support version 5.6 Long Term Support. In this case plugin
+ *   should use {@link SonarQubeVersion}, for example through {@link Plugin.Context#getSonarQubeVersion()} or
+ *   {@link SensorContext#getSonarQubeVersion()}.
+ * </p>
+ *
+ * <p>
  * Unit tests of plugin extensions can create instances of {@link SonarRuntime}
  * via {@link org.sonar.api.internal.SonarRuntimeImpl}.
  * </p>
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorContext.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorContext.java
index c92ab74a5d9..e11f6da0153 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorContext.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorContext.java
@@ -65,10 +65,11 @@ public interface SensorContext {
   InputModule module();
 
   /**
+   * Version of API at runtime, not at compilation time. It's a shortcut on
+   * {@code runtime().getApiVersion()} since 6.0.
    * @since 5.5
-   * @deprecated replaced by {@link #runtime()}.getApiVersion() in version 6.0.
+   * @see #runtime() since version 6.0.
    */
-  @Deprecated
   Version getSonarQubeVersion();
 
   /**