SONAR-3755 refactor comments

4 files changed, 69 insertions, 32 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueFinder.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueFinder.java
index f9f6ff4a3b2..0260bffcd7d 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueFinder.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueFinder.java
@@ -39,28 +39,6 @@ import java.util.List;
  */
 public interface IssueFinder extends ServerComponent {
 
-  interface Results {
-    List<Issue> issues();
+  IssueQueryResult find(IssueQuery query);
 
-    Rule rule(Issue issue);
-
-    Collection<Rule> rules();
-
-    Component component(Issue issue);
-
-    Collection<Component> components();
-
-    ActionPlan actionPlan(Issue issue);
-
-    Collection<ActionPlan> actionPlans();
-
-    Paging paging();
-
-    boolean securityExclusions();
-  }
-
-  Results find(IssueQuery query, @Nullable Integer currentUserId, String role);
-
-  @CheckForNull
-  Issue findByKey(String key /* TODO @Nullable Integer currentUserId */);
 }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueQuery.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueQuery.java
index 87f0e462347..f7d01025b57 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueQuery.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueQuery.java
@@ -17,20 +17,18 @@
  * 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.issue;
 
 import com.google.common.base.Preconditions;
 import org.apache.commons.lang.builder.ReflectionToStringBuilder;
 import org.sonar.api.rule.RuleKey;
 
+import javax.annotation.CheckForNull;
 import javax.annotation.Nullable;
 import java.util.Collection;
 import java.util.Date;
 
 /**
- * TODO add javadoc
- *
  * @since 3.6
  */
 public class IssueQuery {
@@ -55,6 +53,7 @@ public class IssueQuery {
   private final Date createdBefore;
   private final Sort sort;
   private final boolean asc;
+  private final String requiredRole;
 
   // max results per page
   private final int pageSize;
@@ -81,6 +80,7 @@ public class IssueQuery {
     this.asc = builder.asc;
     this.pageSize = builder.pageSize;
     this.pageIndex = builder.pageIndex;
+    this.requiredRole = builder.requiredRole;
   }
 
   public Collection<String> issueKeys() {
@@ -155,6 +155,11 @@ public class IssueQuery {
     return pageIndex;
   }
 
+  @CheckForNull
+  public String requiredRole() {
+    return requiredRole;
+  }
+
   @Override
   public String toString() {
     return ReflectionToStringBuilder.toString(this);
@@ -164,10 +169,6 @@ public class IssueQuery {
     return new Builder();
   }
 
-
-  /**
-   * @since 3.6
-   */
   public static class Builder {
 
     private static final int DEFAULT_PAGE_SIZE = 100;
@@ -193,6 +194,7 @@ public class IssueQuery {
     private boolean asc = false;
     private int pageSize = DEFAULT_PAGE_SIZE;
     private int pageIndex = DEFAULT_PAGE_INDEX;
+    private String requiredRole;
 
     private Builder() {
     }
@@ -296,6 +298,11 @@ public class IssueQuery {
       return this;
     }
 
+    public Builder requiredRole(@Nullable String s) {
+      this.requiredRole = s;
+      return this;
+    }
+
     public IssueQuery build() {
       Preconditions.checkArgument(pageSize > 0, "Page size must be greater than 0 (got " + pageSize + ")");
       Preconditions.checkArgument(pageSize < MAX_PAGE_SIZE, "Page size must be less than " + MAX_PAGE_SIZE + " (got " + pageSize + ")");
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueQueryResult.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueQueryResult.java
new file mode 100644
index 00000000000..612de445dfb
--- /dev/null
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueQueryResult.java
@@ -0,0 +1,52 @@
+/*
+ * SonarQube, open source software quality management tool.
+ * Copyright (C) 2008-2013 SonarSource
+ * mailto:contact AT sonarsource DOT com
+ *
+ * SonarQube 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.
+ *
+ * SonarQube 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.issue;
+
+import org.sonar.api.component.Component;
+import org.sonar.api.rules.Rule;
+import org.sonar.api.utils.Paging;
+
+import javax.annotation.CheckForNull;
+import java.util.Collection;
+import java.util.List;
+
+/**
+ * @since 3.6
+ */
+public interface IssueQueryResult {
+  List<Issue> issues();
+
+  Rule rule(Issue issue);
+
+  Collection<Rule> rules();
+
+  Component component(Issue issue);
+
+  Collection<Component> components();
+
+  @CheckForNull
+  ActionPlan actionPlan(Issue issue);
+
+  Collection<ActionPlan> actionPlans();
+
+  Paging paging();
+
+  boolean securityExclusions();
+}
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/WebIssues.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/RubyIssueService.java
index 67932f0fe59..6f5d6f6a573 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/WebIssues.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/RubyIssueService.java
@@ -31,7 +31,7 @@ import java.util.Map;
  *
  * @since 3.6
  */
-public interface WebIssues extends ServerComponent {
+public interface RubyIssueService extends ServerComponent {
 
   /**
    * Search for issues.
@@ -42,6 +42,6 @@ public interface WebIssues extends ServerComponent {
    * TODO document parameters
    * </ul>
    */
-  IssueFinder.Results find(Map<String, Object> parameters);
+  IssueQueryResult find(Map<String, Object> parameters);
 
 }