diff options
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. * + * <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> + * <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> + * </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; * <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; * </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(); /** |