From 86ea84aacc37279b3d992b28a80a7aeab405e5e7 Mon Sep 17 00:00:00 2001 From: Simon Brandhof Date: Thu, 28 Jul 2016 11:23:21 +0200 Subject: [PATCH] Revert deprecation of SonarQubeVersion so that compatibility with 5.6 does not need to call deprecated code. --- .../main/java/org/sonar/xoo/XooPlugin.java | 2 +- .../sonar/xoo/rule/OneIssuePerLineSensor.java | 4 +- .../src/main/java/org/sonar/api/Plugin.java | 9 +- .../java/org/sonar/api/SonarQubeVersion.java | 106 +++++++++++++++++- .../main/java/org/sonar/api/SonarRuntime.java | 33 +++--- .../sonar/api/batch/sensor/SensorContext.java | 5 +- 6 files changed, 135 insertions(+), 24 deletions(-) diff --git a/plugins/sonar-xoo-plugin/src/main/java/org/sonar/xoo/XooPlugin.java b/plugins/sonar-xoo-plugin/src/main/java/org/sonar/xoo/XooPlugin.java index 06925832258..9a84189608f 100644 --- a/plugins/sonar-xoo-plugin/src/main/java/org/sonar/xoo/XooPlugin.java +++ b/plugins/sonar-xoo-plugin/src/main/java/org/sonar/xoo/XooPlugin.java @@ -144,7 +144,7 @@ public class XooPlugin implements Plugin { DeprecatedResourceApiSensor.class); } - if (context.getRuntime().getApiVersion().isGreaterThanOrEqual(Version.create(5, 5))) { + if (context.getSonarQubeVersion().isGreaterThanOrEqual(Version.create(5, 5))) { context.addExtension(CpdTokenizerSensor.class); } } diff --git a/plugins/sonar-xoo-plugin/src/main/java/org/sonar/xoo/rule/OneIssuePerLineSensor.java b/plugins/sonar-xoo-plugin/src/main/java/org/sonar/xoo/rule/OneIssuePerLineSensor.java index 2b9474ec391..995b10d19d8 100644 --- a/plugins/sonar-xoo-plugin/src/main/java/org/sonar/xoo/rule/OneIssuePerLineSensor.java +++ b/plugins/sonar-xoo-plugin/src/main/java/org/sonar/xoo/rule/OneIssuePerLineSensor.java @@ -19,7 +19,6 @@ */ package org.sonar.xoo.rule; -import org.sonar.api.SonarQubeVersion; import org.sonar.api.batch.fs.FilePredicates; import org.sonar.api.batch.fs.FileSystem; import org.sonar.api.batch.fs.InputFile; @@ -30,6 +29,7 @@ import org.sonar.api.batch.sensor.SensorContext; import org.sonar.api.batch.sensor.SensorDescriptor; import org.sonar.api.batch.sensor.issue.NewIssue; import org.sonar.api.rule.RuleKey; +import org.sonar.api.utils.Version; import org.sonar.xoo.Xoo; import org.sonar.xoo.Xoo2; @@ -73,7 +73,7 @@ public class OneIssuePerLineSensor implements Sensor { .at(file.selectLine(line)) .message("This issue is generated on each line")) .overrideSeverity(severity != null ? Severity.valueOf(severity) : null); - if (context.getSonarQubeVersion().isGreaterThanOrEqual(SonarQubeVersion.V5_5)) { + if (context.getSonarQubeVersion().isGreaterThanOrEqual(Version.create(5, 5))) { newIssue.gap(context.settings().getDouble(EFFORT_TO_FIX_PROPERTY)); } else { newIssue.effortToFix(context.settings().getDouble(EFFORT_TO_FIX_PROPERTY)); 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(); /** -- 2.39.5