SONAR-5954 Deprecate and update description of issue search WS parameters

diff --git a/server/sonar-server/src/main/java/org/sonar/server/issue/IssueQueryService.java b/server/sonar-server/src/main/java/org/sonar/server/issue/IssueQueryService.java
index f49a2798f3f8753378723809bd98e89fed6eacec..df2eb281259de01bc1a4c58775c558b658793986 100644 (file)
--- a/server/sonar-server/src/main/java/org/sonar/server/issue/IssueQueryService.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/issue/IssueQueryService.java
@@ -20,6 +20,8 @@
 
 package org.sonar.server.issue;
 
+import org.apache.commons.lang.ObjectUtils;
+
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.Function;
 import com.google.common.base.Splitter;
@@ -77,11 +79,37 @@ public class IssueQueryService implements ServerComponent {
         .createdAfter(RubyUtils.toDate(params.get(IssueFilterParameters.CREATED_AFTER)))
         .createdBefore(RubyUtils.toDate(params.get(IssueFilterParameters.CREATED_BEFORE)));
       addProjectUuids(builder, session,
-        RubyUtils.toStrings(params.get(IssueFilterParameters.PROJECT_UUIDS)), RubyUtils.toStrings(params.get(IssueFilterParameters.PROJECTS)));
+        RubyUtils.toStrings(params.get(IssueFilterParameters.PROJECT_UUIDS)),
+        RubyUtils.toStrings(
+          ObjectUtils.defaultIfNull(
+            params.get(IssueFilterParameters.PROJECT_KEYS),
+            params.get(IssueFilterParameters.PROJECTS)
+          )
+        )
+      );
       addComponentUuids(builder, session,
-        RubyUtils.toStrings(params.get(IssueFilterParameters.COMPONENT_UUIDS)), RubyUtils.toStrings(params.get(IssueFilterParameters.COMPONENTS)));
+        RubyUtils.toStrings(params.get(IssueFilterParameters.COMPONENT_UUIDS)),
+        RubyUtils.toStrings(
+          ObjectUtils.defaultIfNull(
+            params.get(IssueFilterParameters.COMPONENT_KEYS),
+            params.get(IssueFilterParameters.COMPONENTS)
+          )
+        )
+      );
       addComponentRootUuids(builder, session,
-        RubyUtils.toStrings(params.get(IssueFilterParameters.COMPONENT_ROOT_UUIDS)), RubyUtils.toStrings(params.get(IssueFilterParameters.COMPONENT_ROOTS)));
+        RubyUtils.toStrings(
+          ObjectUtils.defaultIfNull(
+            params.get(IssueFilterParameters.MODULE_UUIDS),
+            params.get(IssueFilterParameters.COMPONENT_ROOT_UUIDS)
+          )
+        ),
+        RubyUtils.toStrings(
+          ObjectUtils.defaultIfNull(
+            params.get(IssueFilterParameters.MODULE_KEYS),
+            params.get(IssueFilterParameters.COMPONENT_ROOTS)
+          )
+        )
+      );
       String sort = (String) params.get(IssueFilterParameters.SORT);
       if (!Strings.isNullOrEmpty(sort)) {
         builder.sort(sort);
@@ -120,11 +148,11 @@ public class IssueQueryService implements ServerComponent {
         .createdBefore(request.paramAsDateTime(IssueFilterParameters.CREATED_BEFORE))
         .ignorePaging(request.paramAsBoolean(IssueFilterParameters.IGNORE_PAGING));
       addProjectUuids(builder, session,
-        request.paramAsStrings(IssueFilterParameters.PROJECT_UUIDS), request.paramAsStrings(IssueFilterParameters.PROJECTS));
+        request.paramAsStrings(IssueFilterParameters.PROJECT_UUIDS), request.paramAsStrings(IssueFilterParameters.PROJECT_KEYS));
       addComponentUuids(builder, session,
-        request.paramAsStrings(IssueFilterParameters.COMPONENT_UUIDS), request.paramAsStrings(IssueFilterParameters.COMPONENTS));
+        request.paramAsStrings(IssueFilterParameters.COMPONENT_UUIDS), request.paramAsStrings(IssueFilterParameters.COMPONENT_KEYS));
       addComponentRootUuids(builder, session,
-        request.paramAsStrings(IssueFilterParameters.COMPONENT_ROOT_UUIDS), request.paramAsStrings(IssueFilterParameters.COMPONENT_ROOTS));
+        request.paramAsStrings(IssueFilterParameters.MODULE_UUIDS), request.paramAsStrings(IssueFilterParameters.MODULE_KEYS));
       String sort = request.param(SearchRequestHandler.PARAM_SORT);
       if (!Strings.isNullOrEmpty(sort)) {
         builder.sort(sort);

diff --git a/server/sonar-server/src/main/java/org/sonar/server/issue/filter/IssueFilterParameters.java b/server/sonar-server/src/main/java/org/sonar/server/issue/filter/IssueFilterParameters.java
index 8dbe5d1776cbe813a2b52885821886aaab18e391..d56999fcc88e5de95197eec4aa7fa0abb644685c 100644 (file)
--- a/server/sonar-server/src/main/java/org/sonar/server/issue/filter/IssueFilterParameters.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/issue/filter/IssueFilterParameters.java
@@ -39,11 +39,16 @@ public class IssueFilterParameters {
   public static final String RESOLUTIONS = "resolutions";
   public static final String RESOLVED = "resolved";
   public static final String COMPONENTS = "components";
+  public static final String COMPONENT_KEYS = "componentKeys";
   public static final String COMPONENT_UUIDS = "componentUuids";
   public static final String COMPONENT_ROOTS = "componentRoots";
   public static final String COMPONENT_ROOT_UUIDS = "componentRootUuids";
+  public static final String MODULE_KEYS = "moduleKeys";
+  public static final String MODULE_UUIDS = "moduleUuids";
   public static final String PROJECTS = "projects";
+  public static final String PROJECT_KEYS = "projectKeys";
   public static final String PROJECT_UUIDS = "projectUuids";
+  public static final String ON_COMPONENT_ONLY = "onComponentOnly";
   public static final String RULES = "rules";
   public static final String ACTION_PLANS = "actionPlans";
   public static final String REPORTERS = "reporters";
@@ -64,7 +69,7 @@ public class IssueFilterParameters {
 
   public static final List<String> ALL = ImmutableList.of(ISSUES, SEVERITIES, STATUSES, RESOLUTIONS, RESOLVED, COMPONENTS, COMPONENT_ROOTS, RULES, ACTION_PLANS, REPORTERS, TAGS,
     ASSIGNEES, LANGUAGES, ASSIGNED, PLANNED, HIDE_RULES, CREATED_AT, CREATED_AFTER, CREATED_BEFORE, PAGE_SIZE, PAGE_INDEX, SORT, ASC, COMPONENT_UUIDS, COMPONENT_ROOT_UUIDS,
-    PROJECTS, PROJECT_UUIDS, IGNORE_PAGING);
+    PROJECTS, PROJECT_UUIDS, IGNORE_PAGING, PROJECT_KEYS, COMPONENT_KEYS, MODULE_KEYS, MODULE_UUIDS);
 
   public static final List<String> ALL_WITHOUT_PAGINATION = newArrayList(Iterables.filter(ALL, new Predicate<String>() {
     @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 ee67474e55733025d5fd819b146c4c723ce8db30..a63cacee26714a83a7415f0098234ba907620932 100644 (file)
--- 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
@@ -124,6 +124,7 @@ public class SearchAction extends SearchRequestHandler<IssueQuery, Issue> {
       .setSince("3.6")
       .setResponseExample(Resources.getResource(this.getClass(), "example-search.json"));
 
+    addComponentRelatedParams(action);
     action.createParam(IssueFilterParameters.ISSUES)
       .setDescription("Comma-separated list of issue keys")
       .setExampleValue("5bccd6e8-f525-43a2-8d76-fcb13dde79ef");
@@ -142,34 +143,6 @@ public class SearchAction extends SearchRequestHandler<IssueQuery, Issue> {
     action.createParam(IssueFilterParameters.RESOLVED)
       .setDescription("To match resolved or unresolved issues")
       .setBooleanPossibleValues();
-    action.createParam(IssueFilterParameters.COMPONENTS)
-      .setDescription("To retrieve issues associated to a specific list of components (comma-separated list of component keys). " +
-        "Note that if you set the value to a project key, only issues associated to this project are retrieved. " +
-        "Issues associated to its sub-components (such as files, packages, etc.) are not retrieved. See also componentRoots. " +
-        "If this parameter is set, componentUuids must not be set.")
-      .setExampleValue("org.apache.struts:struts:org.apache.struts.Action");
-    action.createParam(IssueFilterParameters.PROJECTS)
-      .setDescription("To retrieve issues associated to a specific list of projects (comma-separated list of project keys). " +
-        "If this parameter is set, projectUuids must not be set.")
-      .setExampleValue("org.apache.struts:struts:org.apache.struts.Action");
-    action.createParam(IssueFilterParameters.COMPONENT_ROOTS)
-      .setDescription("To retrieve issues associated to a specific list of components and their sub-components (comma-separated list of component keys). " +
-        "Views are not supported. If this parameter is set, componentRootUuids must not be set.")
-      .setExampleValue("org.apache.struts:struts");
-    action.createParam(IssueFilterParameters.COMPONENT_UUIDS)
-      .setDescription("To retrieve issues associated to a specific list of components (comma-separated list of component UUIDs). " +
-        "Note that if you set the value to a project UUID, only issues associated to this project are retrieved. " +
-        "Issues associated to its sub-components (such as files, packages, etc.) are not retrieved. See also componentRootUuids. " +
-        "If this parameter is set, components must not be set.")
-      .setExampleValue("584a89f2-8037-4f7b-b82c-8b45d2d63fb2");
-    action.createParam(IssueFilterParameters.COMPONENT_ROOT_UUIDS)
-      .setDescription("To retrieve issues associated to a specific list of components and their sub-components (comma-separated list of component UUIDs). " +
-        "Views are not supported. If this parameter is set, componentRoots must not be set.")
-      .setExampleValue("7d8749e8-3070-4903-9188-bdd82933bb92");
-    action.createParam(IssueFilterParameters.PROJECT_UUIDS)
-      .setDescription("To retrieve issues associated to a specific list of projects (comma-separated list of project UUIDs). " +
-        "Views are not supported. If this parameter is set, projects must not be set.")
-      .setExampleValue("7d8749e8-3070-4903-9188-bdd82933bb92");
     action.createParam(IssueFilterParameters.RULES)
       .setDescription("Comma-separated list of coding rule keys. Format is <repository>:<rule>")
       .setExampleValue("squid:AvoidCycles");
@@ -226,6 +199,59 @@ public class SearchAction extends SearchRequestHandler<IssueQuery, Issue> {
       .setDescription("Only json format is available. This parameter is kept only for backward compatibility and shouldn't be used anymore");
   }
 
+  private void addComponentRelatedParams(WebService.NewAction action) {
+    action.createParam(IssueFilterParameters.COMPONENT_KEYS)
+      .setDescription("To retrieve issues associated to a specific list of components (comma-separated list of component keys). " +
+        "A component can be a project, module, directory or file." +
+        "If this parameter is set, componentUuids must not be set.")
+      .setDeprecatedKey(IssueFilterParameters.COMPONENTS)
+      .setExampleValue("org.apache.struts:struts:org.apache.struts.Action");
+    action.createParam(IssueFilterParameters.COMPONENTS)
+      .setDescription("Deprecated since 5.1. See componentKeys.");
+    action.createParam(IssueFilterParameters.COMPONENT_UUIDS)
+      .setDescription("To retrieve issues associated to a specific list of components (comma-separated list of component UUIDs). " +
+        "This parameter is mostly used by the Issues page, please prefer usage of the componentKeys parameter." +
+        "A component can be a project, module, directory or file." +
+        "If this parameter is set, componentKeys must not be set.")
+      .setExampleValue("584a89f2-8037-4f7b-b82c-8b45d2d63fb2");
+
+    action.createParam(IssueFilterParameters.PROJECTS)
+      .setDescription("Deprecated since 5.1. See projectKeys");
+    action.createParam(IssueFilterParameters.PROJECT_KEYS)
+      .setDescription("To retrieve issues associated to a specific list of projects (comma-separated list of project keys). " +
+        "This parameter is mostly used by the Issues page, please prefer usage of the componentKeys parameter." +
+        "If this parameter is set, projectUuids must not be set.")
+      .setDeprecatedKey(IssueFilterParameters.PROJECTS)
+      .setExampleValue("org.apache.struts:struts:org.apache.struts.Action");
+    action.createParam(IssueFilterParameters.PROJECT_UUIDS)
+      .setDescription("To retrieve issues associated to a specific list of projects (comma-separated list of project UUIDs). " +
+        "This parameter is mostly used by the Issues page, please prefer usage of the componentKeys parameter." +
+        "Views are not supported. If this parameter is set, projectKeys must not be set.")
+      .setExampleValue("7d8749e8-3070-4903-9188-bdd82933bb92");
+
+    action.createParam(IssueFilterParameters.COMPONENT_ROOTS)
+      .setDescription("Deprecated since 5.1. See moduleKeys.");
+    action.createParam(IssueFilterParameters.COMPONENT_ROOT_UUIDS)
+      .setDescription("Deprecated since 5.1. See moduleUuids.");
+    action.createParam(IssueFilterParameters.MODULE_KEYS)
+      .setDescription("To retrieve issues associated to a specific list of modules (comma-separated list of module keys). " +
+        "This parameter is mostly used by the Issues page, please prefer usage of the componentKeys parameter." +
+        "Views are not supported. If this parameter is set, componentRootUuids must not be set.")
+      .setDeprecatedKey(IssueFilterParameters.COMPONENT_ROOTS)
+      .setExampleValue("org.apache.struts:struts");
+    action.createParam(IssueFilterParameters.MODULE_UUIDS)
+      .setDescription("To retrieve issues associated to a specific list of components and their sub-components (comma-separated list of component UUIDs). " +
+        "This parameter is mostly used by the Issues page, please prefer usage of the componentKeys parameter." +
+        "Views are not supported. If this parameter is set, moduleKeys must not be set.")
+      .setDeprecatedKey(IssueFilterParameters.COMPONENT_ROOT_UUIDS)
+      .setExampleValue("7d8749e8-3070-4903-9188-bdd82933bb92");
+
+    action.createParam(IssueFilterParameters.ON_COMPONENT_ONLY)
+      .setDescription("Return only issues at the component's level, not on its descendants (modules, directories, files, etc.)")
+      .setBooleanPossibleValues()
+      .setDefaultValue("false");
+  }
+
   @Override
   protected IssueQuery doQuery(Request request) {
     return issueQueryService.createFromRequest(request);

diff --git a/server/sonar-server/src/test/java/org/sonar/server/issue/ws/SearchActionMediumTest.java b/server/sonar-server/src/test/java/org/sonar/server/issue/ws/SearchActionMediumTest.java
index 67efbf1325e12d8138de9f7ec4d055b097446fc6..79485339107232fde378dc724c7635f67a4b954c 100644 (file)
--- a/server/sonar-server/src/test/java/org/sonar/server/issue/ws/SearchActionMediumTest.java
+++ b/server/sonar-server/src/test/java/org/sonar/server/issue/ws/SearchActionMediumTest.java
@@ -132,7 +132,7 @@ public class SearchActionMediumTest {
     assertThat(show.isPost()).isFalse();
     assertThat(show.isInternal()).isFalse();
     assertThat(show.responseExampleAsString()).isNotEmpty();
-    assertThat(show.params()).hasSize(32);
+    assertThat(show.params()).hasSize(37);
   }
 
   @Test