From 86ea84aacc37279b3d992b28a80a7aeab405e5e7 Mon Sep 17 00:00:00 2001 From: Simon Brandhof Date: Thu, 28 Jul 2016 11:23:21 +0200 Subject: Revert deprecation of SonarQubeVersion so that compatibility with 5.6 does not need to call deprecated code. --- .../src/main/java/org/sonar/api/Plugin.java | 9 +- .../main/java/org/sonar/api/SonarQubeVersion.java | 106 ++++++++++++++++++++- .../src/main/java/org/sonar/api/SonarRuntime.java | 33 ++++--- .../org/sonar/api/batch/sensor/SensorContext.java | 5 +- 4 files changed, 132 insertions(+), 21 deletions(-) (limited to 'sonar-plugin-api/src') 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. * + *

+ * 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. + *

+ * 
+ * // 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();
+ *     }
+ *   }
+ * }
+ *
+ * + *

+ * Note that {@link Sensor} extensions can directly get {@link SonarQubeVersion} through + * {@link SensorContext#getSonarQubeVersion()}, without using constructor injection: + *

+ * 
+ * public class MySensor implements Sensor {
+ *
+ *   public void execute(SensorContext context) {
+ *     if (context.getSonarQubeVersion().isGreaterThanOrEqual(Version.create(6, 0)) {
+ *       context.newMethodIntroducedIn6_0();
+ *     }
+ *   }
+ *
+ * }
+ *
+ *

+ * 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+: + *

+ * 

+ * <packaging>sonar-plugin</packaging>
+ *
+ * <dependencies>
+ *   <dependency>
+ *     <groupId>org.sonarsource.sonarqube</groupId>
+ *     <artifactId>sonar-plugin-api</artifactId>
+ *     <version>6.0</version>
+ *     <scope>provided</scope>
+ *   </dependency>
+ * </dependencies>
+ *
+ * <build>
+ *  <plugins>
+ *    <plugin>
+ *      <groupId>org.sonarsource.sonar-packaging-maven-plugin</groupId>
+ *      <artifactId>sonar-packaging-maven-plugin</artifactId>
+ *      <version>1.16</version>
+ *      <extensions>true</extensions>
+ *      <configuration>
+ *        <!-- Override the default value 6.0 which is guessed from sonar-plugin-api dependency -->
+ *        <sonarQubeMinVersion>5.6</sonarQubeMinVersion>
+ *      </configuration>
+ *    </plugin>
+ *  </plugins>
+ * </build>
+ *
+ * + *

+ * 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. + *

+ * + * @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; *

* *

- * 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. *

* 
  * // 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;
  *
  * 

  * 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+:
  * 

@@ -103,7 +103,7 @@ import org.sonarsource.api.sonarlint.SonarLintSide;
  *   <dependency>
  *     <groupId>org.sonarsource.sonarqube</groupId>
  *     <artifactId>sonar-plugin-api</artifactId>
- *     <version>6.0</version>
+ *     <version>6.1</version>
  *     <scope>provided</scope>
  *   </dependency>
  * </dependencies>
@@ -116,8 +116,8 @@ import org.sonarsource.api.sonarlint.SonarLintSide;
  *      <version>1.16</version>
  *      <extensions>true</extensions>
  *      <configuration>
- *        <!-- Override the default value 5.6 which is guessed from sonar-plugin-api dependency -->
- *        <sonarQubeMinVersion>5.6</sonarQubeMinVersion>
+ *        <!-- Override the default value 6.0 which is guessed from sonar-plugin-api dependency -->
+ *        <sonarQubeMinVersion>6.0</sonarQubeMinVersion>
  *      </configuration>
  *    </plugin>
  *  </plugins>
@@ -125,6 +125,13 @@ import org.sonarsource.api.sonarlint.SonarLintSide;
  *
* *

+ * 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()}. + *

+ * + *

* Unit tests of plugin extensions can create instances of {@link SonarRuntime} * via {@link org.sonar.api.internal.SonarRuntimeImpl}. *

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(); /** -- cgit v1.2.3