SONAR-6820 document page size limitation in WS

13 files changed, 47 insertions, 20 deletions

diff --git a/server/sonar-server/src/main/java/org/sonar/server/activity/ws/SearchAction.java b/server/sonar-server/src/main/java/org/sonar/server/activity/ws/SearchAction.java
index e57c94aea74..e33c13fd9d4 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/activity/ws/SearchAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/activity/ws/SearchAction.java
@@ -33,6 +33,8 @@ import org.sonar.server.es.SearchResult;
 import org.sonar.server.search.QueryContext;
 import org.sonar.server.user.UserSession;
 
+import static org.sonar.server.es.SearchOptions.MAX_LIMIT;
+
 public class SearchAction implements RequestHandler {
 
   public static final String PARAM_TYPE = "type";
@@ -61,7 +63,7 @@ public class SearchAction implements RequestHandler {
       .setDescription("Activity type")
       .setPossibleValues(Activity.Type.values());
 
-    action.addPagingParams(10);
+    action.addPagingParams(10, MAX_LIMIT);
     action.addFieldsParam(docToJsonMapping.supportedFields());
   }
 
diff --git a/server/sonar-server/src/main/java/org/sonar/server/component/ws/SearchViewComponentsAction.java b/server/sonar-server/src/main/java/org/sonar/server/component/ws/SearchViewComponentsAction.java
index ca5fe49c506..d866bf59b7d 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/component/ws/SearchViewComponentsAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/component/ws/SearchViewComponentsAction.java
@@ -43,6 +43,7 @@ import org.sonar.server.user.UserSession;
 import static com.google.common.collect.Sets.newLinkedHashSet;
 import static org.sonar.api.server.ws.WebService.Param.PAGE;
 import static org.sonar.api.server.ws.WebService.Param.PAGE_SIZE;
+import static org.sonar.server.es.SearchOptions.MAX_LIMIT;
 
 public class SearchViewComponentsAction implements RequestHandler {
 
@@ -80,7 +81,7 @@ public class SearchViewComponentsAction implements RequestHandler {
       .setDescription("UTF-8 search query")
       .setExampleValue("sonar");
 
-    action.addPagingParams(10);
+    action.addPagingParams(10, MAX_LIMIT);
   }
 
   @Override
diff --git a/server/sonar-server/src/main/java/org/sonar/server/issue/ws/SearchAction.java b/server/sonar-server/src/main/java/org/sonar/server/issue/ws/SearchAction.java
index 91a99ee4f9e..a14cbacf138 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/issue/ws/SearchAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/issue/ws/SearchAction.java
@@ -54,6 +54,7 @@ import static com.google.common.collect.FluentIterable.from;
 import static com.google.common.collect.Iterables.concat;
 import static java.util.Collections.singletonList;
 import static org.sonar.api.utils.Paging.forPageIndex;
+import static org.sonar.server.es.SearchOptions.MAX_LIMIT;
 import static org.sonar.server.ws.WsUtils.writeProtobuf;
 import static org.sonarqube.ws.client.issue.IssueFilterParameters.ACTION_PLANS;
 import static org.sonarqube.ws.client.issue.IssueFilterParameters.ADDITIONAL_FIELDS;
@@ -119,7 +120,7 @@ public class SearchAction implements IssuesWsAction {
       .setSince("3.6")
       .setResponseExample(Resources.getResource(this.getClass(), "example-search.json"));
 
-    action.addPagingParams(100);
+    action.addPagingParams(100, MAX_LIMIT);
     action.createParam(Param.FACETS)
       .setDescription("Comma-separated list of the facets to be computed. No facet is computed by default.")
       .setPossibleValues(IssueIndex.SUPPORTED_FACETS);
diff --git a/server/sonar-server/src/main/java/org/sonar/server/measure/custom/ws/SearchAction.java b/server/sonar-server/src/main/java/org/sonar/server/measure/custom/ws/SearchAction.java
index d62c3894c01..6d28e6923fc 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/measure/custom/ws/SearchAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/measure/custom/ws/SearchAction.java
@@ -47,6 +47,7 @@ import org.sonar.server.user.UserSession;
 import org.sonar.server.user.index.UserIndex;
 
 import static com.google.common.collect.Sets.newHashSet;
+import static org.sonar.server.es.SearchOptions.MAX_LIMIT;
 import static org.sonar.server.measure.custom.ws.CustomMeasureValidator.checkPermissions;
 
 public class SearchAction implements CustomMeasuresWsAction {
@@ -76,7 +77,7 @@ public class SearchAction implements CustomMeasuresWsAction {
         "Requires 'Administer System' permission or 'Administer' permission on the project.")
       .setSince("5.2")
       .addFieldsParam(CustomMeasureJsonWriter.OPTIONAL_FIELDS)
-      .addPagingParams(100)
+      .addPagingParams(100, MAX_LIMIT)
       .setResponseExample(getClass().getResource("example-search.json"))
       .setHandler(this);
 
diff --git a/server/sonar-server/src/main/java/org/sonar/server/metric/ws/SearchAction.java b/server/sonar-server/src/main/java/org/sonar/server/metric/ws/SearchAction.java
index 03aa5e668b7..8ade82fe78b 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/metric/ws/SearchAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/metric/ws/SearchAction.java
@@ -35,16 +35,9 @@ import org.sonar.server.db.DbClient;
 import org.sonar.server.es.SearchOptions;
 
 import static com.google.common.collect.Sets.newHashSet;
-import static org.sonar.server.metric.ws.MetricJsonWriter.FIELD_CUSTOM;
-import static org.sonar.server.metric.ws.MetricJsonWriter.FIELD_DESCRIPTION;
-import static org.sonar.server.metric.ws.MetricJsonWriter.FIELD_DIRECTION;
-import static org.sonar.server.metric.ws.MetricJsonWriter.FIELD_DOMAIN;
-import static org.sonar.server.metric.ws.MetricJsonWriter.FIELD_HIDDEN;
+import static org.sonar.server.es.SearchOptions.MAX_LIMIT;
 import static org.sonar.server.metric.ws.MetricJsonWriter.FIELD_ID;
 import static org.sonar.server.metric.ws.MetricJsonWriter.FIELD_KEY;
-import static org.sonar.server.metric.ws.MetricJsonWriter.FIELD_NAME;
-import static org.sonar.server.metric.ws.MetricJsonWriter.FIELD_QUALITATIVE;
-import static org.sonar.server.metric.ws.MetricJsonWriter.FIELD_TYPE;
 
 public class SearchAction implements MetricsWsAction {
 
@@ -69,7 +62,7 @@ public class SearchAction implements MetricsWsAction {
       .setSince("5.2")
       .setDescription("Search for metrics")
       .setResponseExample(getClass().getResource("example-search.json"))
-      .addPagingParams(100)
+      .addPagingParams(100, MAX_LIMIT)
       .addFieldsParam(MetricJsonWriter.OPTIONAL_FIELDS)
       .setHandler(this);
 
diff --git a/server/sonar-server/src/main/java/org/sonar/server/project/ws/GhostsAction.java b/server/sonar-server/src/main/java/org/sonar/server/project/ws/GhostsAction.java
index f4b505bef4f..ef30e6b8385 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/project/ws/GhostsAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/project/ws/GhostsAction.java
@@ -39,6 +39,7 @@ import org.sonar.server.es.SearchOptions;
 import org.sonar.server.user.UserSession;
 
 import static com.google.common.collect.Sets.newHashSet;
+import static org.sonar.server.es.SearchOptions.MAX_LIMIT;
 
 public class GhostsAction implements ProjectsWsAction {
   public static final String ACTION = "ghosts";
@@ -59,7 +60,7 @@ public class GhostsAction implements ProjectsWsAction {
       .setDescription("List ghost projects.<br /> Requires 'Administer System' permission.")
       .setResponseExample(Resources.getResource(getClass(), "projects-example-ghosts.json"))
       .setSince("5.2")
-      .addPagingParams(100)
+      .addPagingParams(100, MAX_LIMIT)
       .addFieldsParam(POSSIBLE_FIELDS)
       .addSearchQuery("sonar", "names", "keys")
       .setHandler(this);
diff --git a/server/sonar-server/src/main/java/org/sonar/server/project/ws/ProvisionedAction.java b/server/sonar-server/src/main/java/org/sonar/server/project/ws/ProvisionedAction.java
index 25e402929a1..66a4d3da0c0 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/project/ws/ProvisionedAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/project/ws/ProvisionedAction.java
@@ -38,6 +38,7 @@ import org.sonar.server.es.SearchOptions;
 import org.sonar.server.user.UserSession;
 
 import static com.google.common.collect.Sets.newHashSet;
+import static org.sonar.server.es.SearchOptions.MAX_LIMIT;
 
 public class ProvisionedAction implements ProjectsWsAction {
   private static final Set<String> POSSIBLE_FIELDS = newHashSet("uuid", "key", "name", "creationDate");
@@ -60,7 +61,7 @@ public class ProvisionedAction implements ProjectsWsAction {
       .setSince("5.2")
       .setResponseExample(Resources.getResource(getClass(), "projects-example-provisioned.json"))
       .setHandler(this)
-      .addPagingParams(100)
+      .addPagingParams(100, MAX_LIMIT)
       .addSearchQuery("sonar", "names", "keys")
       .addFieldsParam(POSSIBLE_FIELDS);
   }
diff --git a/server/sonar-server/src/main/java/org/sonar/server/qualityprofile/ws/ChangelogAction.java b/server/sonar-server/src/main/java/org/sonar/server/qualityprofile/ws/ChangelogAction.java
index ee4b2d7ad88..0869ba8db1f 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/qualityprofile/ws/ChangelogAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/qualityprofile/ws/ChangelogAction.java
@@ -45,6 +45,7 @@ import org.sonar.server.qualityprofile.QProfileFactory;
 import org.sonar.server.search.Result;
 
 import static org.sonar.api.utils.Paging.forPageIndex;
+import static org.sonar.server.es.SearchOptions.MAX_LIMIT;
 
 public class ChangelogAction implements QProfileWsAction {
 
@@ -74,7 +75,7 @@ public class ChangelogAction implements QProfileWsAction {
 
     QProfileIdentificationParamUtils.defineProfileParams(changelog, languages);
 
-    changelog.addPagingParams(50);
+    changelog.addPagingParams(50, MAX_LIMIT);
 
     changelog.createParam(PARAM_SINCE)
       .setDescription("Start date for the changelog.")
diff --git a/server/sonar-server/src/main/java/org/sonar/server/rule/ws/SearchAction.java b/server/sonar-server/src/main/java/org/sonar/server/rule/ws/SearchAction.java
index 00439eb0f9b..dc6cf929fe7 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/rule/ws/SearchAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/rule/ws/SearchAction.java
@@ -56,6 +56,7 @@ import org.sonar.server.user.UserSession;
 import org.sonarqube.ws.Common;
 import org.sonarqube.ws.Rules.SearchResponse;
 
+import static org.sonar.server.search.QueryContext.MAX_LIMIT;
 import static org.sonar.server.ws.WsUtils.writeProtobuf;
 
 /**
@@ -97,7 +98,7 @@ public class SearchAction implements RulesWsAction {
   @Override
   public void define(WebService.NewController controller) {
     WebService.NewAction action = controller.createAction(ACTION)
-      .addPagingParams(100)
+      .addPagingParams(100, MAX_LIMIT)
       .setHandler(this);
 
     Collection<String> possibleFacets = possibleFacets();
diff --git a/server/sonar-server/src/main/java/org/sonar/server/test/ws/ListAction.java b/server/sonar-server/src/main/java/org/sonar/server/test/ws/ListAction.java
index da29bcaafe9..7a9ae4616f6 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/test/ws/ListAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/test/ws/ListAction.java
@@ -50,6 +50,8 @@ import org.sonar.server.ws.WsUtils;
 import org.sonarqube.ws.Common;
 import org.sonarqube.ws.WsTests;
 
+import static org.sonar.server.es.SearchOptions.MAX_LIMIT;
+
 public class ListAction implements TestsWsAction {
   public static final String TEST_ID = "testId";
   public static final String TEST_FILE_ID = "testFileId";
@@ -85,7 +87,7 @@ public class ListAction implements TestsWsAction {
       .setSince("5.2")
       .setResponseExample(Resources.getResource(getClass(), "tests-example-list.json"))
       .setHandler(this)
-      .addPagingParams(100);
+      .addPagingParams(100, MAX_LIMIT);
 
     action
       .createParam(TEST_FILE_ID)
diff --git a/server/sonar-server/src/main/java/org/sonar/server/user/ws/SearchAction.java b/server/sonar-server/src/main/java/org/sonar/server/user/ws/SearchAction.java
index f5bbe77ccd0..2e891ec89a3 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/user/ws/SearchAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/user/ws/SearchAction.java
@@ -41,6 +41,8 @@ import org.sonar.server.es.SearchResult;
 import org.sonar.server.user.index.UserDoc;
 import org.sonar.server.user.index.UserIndex;
 
+import static org.sonar.server.es.SearchOptions.MAX_LIMIT;
+
 public class SearchAction implements UsersWsAction {
 
   private final UserIndex userIndex;
@@ -62,7 +64,7 @@ public class SearchAction implements UsersWsAction {
       .setResponseExample(getClass().getResource("example-search.json"));
 
     action.addFieldsParam(UserJsonWriter.FIELDS);
-    action.addPagingParams(50);
+    action.addPagingParams(50, MAX_LIMIT);
 
     action.createParam(Param.TEXT_QUERY)
       .setDescription("Filter on login or name.");
diff --git a/server/sonar-server/src/main/java/org/sonar/server/usergroups/ws/SearchAction.java b/server/sonar-server/src/main/java/org/sonar/server/usergroups/ws/SearchAction.java
index c2da27123e6..5990ddc88b4 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/usergroups/ws/SearchAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/usergroups/ws/SearchAction.java
@@ -40,6 +40,8 @@ import org.sonar.db.MyBatis;
 import org.sonar.db.user.GroupDto;
 import org.sonar.server.es.SearchOptions;
 
+import static org.sonar.server.es.SearchOptions.MAX_LIMIT;
+
 public class SearchAction implements UserGroupsWsAction {
 
   private static final String FIELD_ID = "id";
@@ -62,7 +64,7 @@ public class SearchAction implements UserGroupsWsAction {
       .setResponseExample(getClass().getResource("example-search.json"))
       .setSince("5.2")
       .addFieldsParam(ALL_FIELDS)
-      .addPagingParams(100)
+      .addPagingParams(100, MAX_LIMIT)
       .addSearchQuery("sonar-users", "names");
   }
 
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 6141bed8d8f..0fe59142154 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
@@ -364,6 +364,25 @@ public interface WebService extends Definable<WebService.Context> {
     }
 
     /**
+     * Add predefined parameters related to pagination of results with a maximum page size.
+     * Note the maximum is a documentation only feature. It does not check anything.
+     */
+    public NewAction addPagingParams(int defaultPageSize, int maxPageSize) {
+      createParam(Param.PAGE)
+        .setDescription("1-based page number")
+        .setExampleValue("42")
+        .setDeprecatedKey("pageIndex")
+        .setDefaultValue("1");
+
+      createParam(Param.PAGE_SIZE)
+        .setDescription("Page size. Must be greater than 0 and less than " + maxPageSize)
+        .setExampleValue("20")
+        .setDeprecatedKey("pageSize")
+        .setDefaultValue(String.valueOf(defaultPageSize));
+      return this;
+    }
+
+    /**
      * Creates the parameter {@link org.sonar.api.server.ws.WebService.Param#FIELDS}, which is
      * used to restrict the number of fields returned in JSON response.
      */