SONAR-8777 New API to set the history of a web service action

3 files changed, 85 insertions, 0 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/Changelog.java b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/Changelog.java
new file mode 100644
index 00000000000..f2e3177d605
--- /dev/null
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/Changelog.java
@@ -0,0 +1,47 @@
+/*
+ * SonarQube
+ * Copyright (C) 2009-2017 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+
+package org.sonar.api.server.ws;
+
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * Used to describe the changes that occurred on a web service action
+ *
+ * @since 6.4
+ */
+@Immutable
+public class Changelog {
+  private final String version;
+  private final String description;
+
+  public Changelog(String version, String description) {
+    this.version = version;
+    this.description = description;
+  }
+
+  public String getVersion() {
+    return version;
+  }
+
+  public String getDescription() {
+    return description;
+  }
+}
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 4ed296fcab1..c6a8b538839 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
@@ -27,11 +27,15 @@ import com.google.common.collect.Sets;
 import java.io.IOException;
 import java.net.URL;
 import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 import java.util.Set;
+import java.util.stream.Collectors;
 import javax.annotation.CheckForNull;
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
@@ -48,6 +52,7 @@ import static com.google.common.base.Preconditions.checkState;
 import static com.google.common.base.Strings.isNullOrEmpty;
 import static java.lang.String.format;
 import static java.util.Arrays.asList;
+import static java.util.Objects.requireNonNull;
 
 /**
  * Defines a web service.
@@ -251,6 +256,7 @@ public interface WebService extends Definable<WebService.Context> {
     private RequestHandler handler;
     private Map<String, NewParam> newParams = Maps.newHashMap();
     private URL responseExample = null;
+    private List<Changelog> history = new ArrayList<>();
 
     private NewAction(String key) {
       this.key = key;
@@ -325,6 +331,19 @@ public interface WebService extends Definable<WebService.Context> {
       return this;
     }
 
+    /**
+     * List of changes made to the contract or valuable insight. Example: changes to the response format.
+     *
+     * @since 6.4
+     */
+    public NewAction setHistory(Changelog... changelogs) {
+      this.history = Arrays.stream(requireNonNull(changelogs))
+        .filter(Objects::nonNull)
+        .collect(Collectors.toList());
+
+      return this;
+    }
+
     public NewParam createParam(String paramKey) {
       checkState(!newParams.containsKey(paramKey), "The parameter '%s' is defined multiple times in the action '%s'", paramKey, key);
       NewParam newParam = new NewParam(paramKey);
@@ -470,6 +489,7 @@ public interface WebService extends Definable<WebService.Context> {
     private final RequestHandler handler;
     private final Map<String, Param> params;
     private final URL responseExample;
+    private final List<Changelog> history;
 
     private Action(Controller controller, NewAction newAction) {
       this.key = newAction.key;
@@ -482,6 +502,7 @@ public interface WebService extends Definable<WebService.Context> {
       this.isInternal = newAction.isInternal;
       this.responseExample = newAction.responseExample;
       this.handler = newAction.handler;
+      this.history = newAction.history;
 
       checkState(this.handler != null, "RequestHandler is not set on action %s", path);
       logWarningIf(isNullOrEmpty(this.description), "Description is not set on action " + path);
@@ -536,6 +557,14 @@ public interface WebService extends Definable<WebService.Context> {
     }
 
     /**
+     * @see NewAction#setHistory(Changelog...)  
+     * @since 6.4
+     */
+    public List<Changelog> history() {
+      return history;
+    }
+
+    /**
      * @see NewAction#setInternal(boolean)
      */
     public boolean isInternal() {
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 015115e17e0..7caeab68bcd 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
@@ -34,6 +34,7 @@ import org.sonar.api.utils.log.LogTester;
 import org.sonar.api.utils.log.LoggerLevel;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.tuple;
 import static org.junit.Assert.fail;
 import static org.mockito.Mockito.mock;
 
@@ -74,6 +75,7 @@ public class WebServiceTest {
     assertThat(showAction.responseExampleFormat()).isNotEmpty();
     assertThat(showAction.responseExampleAsString()).isNotEmpty();
     assertThat(showAction.deprecatedSince()).isNull();
+    assertThat(showAction.history()).isEmpty();
     // same as controller
     assertThat(showAction.since()).isEqualTo("4.2");
     assertThat(showAction.isPost()).isFalse();
@@ -88,6 +90,8 @@ public class WebServiceTest {
     assertThat(createAction.since()).isEqualTo("4.1");
     assertThat(createAction.isPost()).isTrue();
     assertThat(createAction.isInternal()).isTrue();
+    assertThat(createAction.history()).extracting(Changelog::getVersion, Changelog::getDescription).containsOnly(
+      tuple("6.4", "Last event"), tuple("6.0", "Old event"), tuple("4.5.6", "Very old event"));
   }
 
   @Test
@@ -197,6 +201,7 @@ public class WebServiceTest {
       newAction.addPagingParams(20);
       newAction.addFieldsParam(Arrays.asList("name", "severity"));
       newAction.addSortParams(Arrays.asList("name", "updatedAt", "severity"), "updatedAt", false);
+
       newController.done();
     }).define(context);
 
@@ -470,6 +475,10 @@ public class WebServiceTest {
         .setPost(true)
         .setInternal(true)
         .setResponseExample(getClass().getResource("WebServiceTest/response-example.txt"))
+        .setHistory(
+          new Changelog("6.4", "Last event"),
+          new Changelog("6.0", "Old event"),
+          new Changelog("4.5.6", "Very old event"))
         .setHandler(new RequestHandler() {
           @Override
           public void handle(Request request, Response response) {