SONAR-6462 Add deprecated flag on WS and WS parameters

2 files changed, 55 insertions, 15 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java
index bdaa27ff1be..5053284f3bc 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java
@@ -265,6 +265,7 @@ public interface WebService extends Definable<WebService.Context> {
     private String deprecatedKey;
     private String description;
     private String since;
+    private String deprecatedSince;
     private boolean post = false;
     private boolean isInternal = false;
     private RequestHandler handler;
@@ -290,6 +291,11 @@ public interface WebService extends Definable<WebService.Context> {
       return this;
     }
 
+    public NewAction setDeprecatedSince(@Nullable String deprecatedSince) {
+      this.deprecatedSince = deprecatedSince;
+      return this;
+    }
+
     public NewAction setPost(boolean b) {
       this.post = b;
       return this;
@@ -419,6 +425,7 @@ public interface WebService extends Definable<WebService.Context> {
     private final String path;
     private final String description;
     private final String since;
+    private final String deprecatedSince;
     private final boolean post;
     private final boolean isInternal;
     private final RequestHandler handler;
@@ -431,6 +438,7 @@ public interface WebService extends Definable<WebService.Context> {
       this.path = String.format("%s/%s", controller.path(), key);
       this.description = newAction.description;
       this.since = StringUtils.defaultIfBlank(newAction.since, controller.since);
+      this.deprecatedSince = newAction.deprecatedSince;
       this.post = newAction.post;
       this.isInternal = newAction.isInternal;
       this.responseExample = newAction.responseExample;
@@ -472,6 +480,11 @@ public interface WebService extends Definable<WebService.Context> {
       return since;
     }
 
+    @CheckForNull
+    public String deprecatedSince() {
+      return deprecatedSince;
+    }
+
     public boolean isPost() {
       return post;
     }
@@ -535,6 +548,7 @@ public interface WebService extends Definable<WebService.Context> {
 
   class NewParam {
     private String key;
+    private String deprecatedSince;
     private String deprecatedKey;
     private String description;
     private String exampleValue;
@@ -546,6 +560,11 @@ public interface WebService extends Definable<WebService.Context> {
       this.key = key;
     }
 
+    public NewParam setDeprecatedSince(@Nullable String deprecatedSince) {
+      this.deprecatedSince = deprecatedSince;
+      return this;
+    }
+
     /**
      * @since 5.0
      */
@@ -668,6 +687,7 @@ public interface WebService extends Definable<WebService.Context> {
     public static final String SELECTED = "selected";
 
     private final String key;
+    private final String deprecatedSince;
     private final String deprecatedKey;
     private final String description;
     private final String exampleValue;
@@ -677,6 +697,7 @@ public interface WebService extends Definable<WebService.Context> {
 
     protected Param(Action action, NewParam newParam) {
       this.key = newParam.key;
+      this.deprecatedSince = newParam.deprecatedSince;
       this.deprecatedKey = newParam.deprecatedKey;
       this.description = newParam.description;
       this.exampleValue = newParam.exampleValue;
@@ -693,6 +714,14 @@ public interface WebService extends Definable<WebService.Context> {
     }
 
     /**
+     * @since 5.3
+     */
+    @CheckForNull
+    public String deprecatedSince() {
+      return deprecatedSince;
+    }
+
+    /**
      * @since 5.0
      */
     @CheckForNull
diff --git a/sonar-plugin-api/src/test/java/org/sonar/api/server/ws/WebServiceTest.java b/sonar-plugin-api/src/test/java/org/sonar/api/server/ws/WebServiceTest.java
index 2ccfb0a55c9..4455897f769 100644
--- a/sonar-plugin-api/src/test/java/org/sonar/api/server/ws/WebServiceTest.java
+++ b/sonar-plugin-api/src/test/java/org/sonar/api/server/ws/WebServiceTest.java
@@ -19,14 +19,13 @@
  */
 package org.sonar.api.server.ws;
 
-import org.apache.commons.lang.StringUtils;
-import org.junit.Test;
-import org.sonar.api.rule.RuleStatus;
-
 import java.net.MalformedURLException;
 import java.net.URL;
 import java.util.Arrays;
 import java.util.Collections;
+import org.apache.commons.lang.StringUtils;
+import org.junit.Test;
+import org.sonar.api.rule.RuleStatus;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.junit.Assert.fail;
@@ -56,6 +55,7 @@ public class WebServiceTest {
       newController.createAction("create")
         .setDescription("Create metric")
         .setSince("4.1")
+        .setDeprecatedSince("5.3")
         .setPost(true)
         .setInternal(true)
         .setResponseExample(getClass().getResource("/org/sonar/api/server/ws/WebServiceTest/response-example.txt"))
@@ -78,7 +78,6 @@ public class WebServiceTest {
     }
   }
 
-
   WebService.Context context = new WebService.Context();
 
   @Test
@@ -108,6 +107,7 @@ public class WebServiceTest {
     assertThat(showAction.responseExample()).isNull();
     assertThat(showAction.responseExampleFormat()).isNull();
     assertThat(showAction.responseExampleAsString()).isNull();
+    assertThat(showAction.deprecatedSince()).isNull();
     // same as controller
     assertThat(showAction.since()).isEqualTo("3.2");
     assertThat(showAction.isPost()).isFalse();
@@ -117,6 +117,7 @@ public class WebServiceTest {
     assertThat(createAction).isNotNull();
     assertThat(createAction.key()).isEqualTo("create");
     assertThat(createAction.toString()).isEqualTo("api/metric/create");
+    assertThat(createAction.deprecatedSince()).isEqualTo("5.3");
     // overrides controller version
     assertThat(createAction.since()).isEqualTo("4.1");
     assertThat(createAction.isPost()).isTrue();
@@ -259,8 +260,15 @@ public class WebServiceTest {
       public void define(Context context) {
         NewController newController = context.createController("api/rule");
         NewAction newAction = newController.createAction("create").setHandler(mock(RequestHandler.class));
-        newAction.createParam("key").setDescription("Key of the new rule");
-        newAction.createParam("severity").setDefaultValue("MAJOR").setPossibleValues("INFO", "MAJOR", "BLOCKER");
+        newAction
+          .createParam("key")
+          .setDescription("Key of the new rule");
+        newAction
+          .createParam("severity")
+          .setDefaultValue("MAJOR")
+          .setDeprecatedSince("5.3")
+          .setDeprecatedKey("old-severity")
+          .setPossibleValues("INFO", "MAJOR", "BLOCKER");
         newAction.addPagingParams(20);
         newAction.addFieldsParam(Arrays.asList("name", "severity"));
         newAction.addSortParams(Arrays.asList("name", "updatedAt", "severity"), "updatedAt", false);
@@ -271,14 +279,18 @@ public class WebServiceTest {
     WebService.Action action = context.controller("api/rule").action("create");
     assertThat(action.params()).hasSize(7);
 
-    assertThat(action.param("key").key()).isEqualTo("key");
-    assertThat(action.param("key").description()).isEqualTo("Key of the new rule");
-    assertThat(action.param("key").toString()).isEqualTo("key");
+    WebService.Param keyParam = action.param("key");
+    assertThat(keyParam.key()).isEqualTo("key");
+    assertThat(keyParam.description()).isEqualTo("Key of the new rule");
+    assertThat(keyParam.toString()).isEqualTo("key");
 
-    assertThat(action.param("severity").key()).isEqualTo("severity");
-    assertThat(action.param("severity").description()).isNull();
-    assertThat(action.param("severity").defaultValue()).isEqualTo("MAJOR");
-    assertThat(action.param("severity").possibleValues()).containsOnly("INFO", "MAJOR", "BLOCKER");
+    WebService.Param severityParam = action.param("severity");
+    assertThat(severityParam.key()).isEqualTo("severity");
+    assertThat(severityParam.description()).isNull();
+    assertThat(severityParam.deprecatedSince()).isEqualTo("5.3");
+    assertThat(severityParam.deprecatedKey()).isEqualTo("old-severity");
+    assertThat(severityParam.defaultValue()).isEqualTo("MAJOR");
+    assertThat(severityParam.possibleValues()).containsOnly("INFO", "MAJOR", "BLOCKER");
 
     // predefined fields
     assertThat(action.param("p").defaultValue()).isEqualTo("1");
@@ -379,7 +391,6 @@ public class WebServiceTest {
     }
   }
 
-
   @Test
   public void fail_if_duplicated_action_parameters() {
     try {