--- /dev/null
+/*
+ * 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;
+ }
+}
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;
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.
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;
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);
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;
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);
return post;
}
+ /**
+ * @see NewAction#setHistory(Changelog...)
+ * @since 6.4
+ */
+ public List<Changelog> history() {
+ return history;
+ }
+
/**
* @see NewAction#setInternal(boolean)
*/
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;
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();
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
newAction.addPagingParams(20);
newAction.addFieldsParam(Arrays.asList("name", "severity"));
newAction.addSortParams(Arrays.asList("name", "updatedAt", "severity"), "updatedAt", false);
+
newController.done();
}).define(context);
.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) {