support create PR review in single API call & remove @Preview

src/main/java/org/kohsuke/github/GHPullRequest.java

@@ -23,6 +23,7 @@
  */
 package org.kohsuke.github;
 
+import javax.annotation.Nullable;
 import java.io.IOException;
 import java.net.URL;
 import java.util.ArrayList;
@@ -35,13 +36,16 @@
 
 /**
  * A pull request.
- * 
+ *
  * @author Kohsuke Kawaguchi
  * @see GHRepository#getPullRequest(int)
  */
 @SuppressWarnings({"UnusedDeclaration"})
 public class GHPullRequest extends GHIssue {
 
+    private static final String COMMENTS_ACTION = "/comments";
+    private static final String COMMIT_ID_FIELD = "commit_id";
+
     private String patch_url, diff_url, issue_url;
     private GHCommitPointer base;
     private String merged_at;
@@ -245,7 +249,6 @@ public PagedIterable<GHPullRequestReview> listReviews() {
         return new PagedIterable<GHPullRequestReview>() {
             public PagedIterator<GHPullRequestReview> _iterator(int pageSize) {
                 return new PagedIterator<GHPullRequestReview>(root.retrieve()
-                        .withPreview(BLACK_CAT)
                         .asIterator(String.format("%s/reviews", getApiRoute()),
                         GHPullRequestReview[].class, pageSize)) {
                     @Override
@@ -265,7 +268,7 @@ protected void wrapUp(GHPullRequestReview[] page) {
     public PagedIterable<GHPullRequestReviewComment> listReviewComments() throws IOException {
         return new PagedIterable<GHPullRequestReviewComment>() {
             public PagedIterator<GHPullRequestReviewComment> _iterator(int pageSize) {
-                return new PagedIterator<GHPullRequestReviewComment>(root.retrieve().asIterator(getApiRoute() + "/comments",
+                return new PagedIterator<GHPullRequestReviewComment>(root.retrieve().asIterator(getApiRoute() + COMMENTS_ACTION,
                         GHPullRequestReviewComment[].class, pageSize)) {
                     protected void wrapUp(GHPullRequestReviewComment[] page) {
                         for (GHPullRequestReviewComment c : page)
@@ -295,37 +298,58 @@ protected void wrapUp(GHPullRequestCommitDetail[] page) {
         };
     }
 
-    @Preview
-    @Deprecated
-    public GHPullRequestReview createReview(String body, GHPullRequestReviewComment... comments)
+    public GHPullRequestReview createReview(@Nullable String commitId, String body, GHPullRequestReviewEvent event,
+                                            GHPullRequestReviewComment... comments) throws IOException {
+        return createReview(commitId, body, event, Arrays.asList(comments));
+    }
+
+    public GHPullRequestReview createReview(@Nullable String commitId, String body, GHPullRequestReviewEvent event,
+                                            List<GHPullRequestReviewComment> comments) throws IOException {
+        List<DraftReviewComment> draftComments = toDraftReviewComments(comments);
+        return new Requester(root).method("POST")
+                .with(COMMIT_ID_FIELD, commitId)
+                .with("body", body)
+                .with("event", event.action())
+                ._with("comments", draftComments)
+                .to(getApiRoute() + "/reviews", GHPullRequestReview.class)
+                .wrapUp(this);
+    }
+
+    public GHPullRequestReviewDraft newDraftReview(@Nullable String commitId, String body, GHPullRequestReviewComment... comments)
             throws IOException {
-        return createReview(body, Arrays.asList(comments));
+        return newDraftReview(commitId, body, Arrays.asList(comments));
     }
 
-    @Preview
-    @Deprecated
-    public GHPullRequestReview createReview(String body, List<GHPullRequestReviewComment> comments)
+    public GHPullRequestReviewDraft newDraftReview(@Nullable String commitId, String body, List<GHPullRequestReviewComment> comments)
             throws IOException {
+        List<DraftReviewComment> draftComments = toDraftReviewComments(comments);
+        return new Requester(root).method("POST")
+                .with(COMMIT_ID_FIELD, commitId)
+                .with("body", body)
+                ._with("comments", draftComments)
+                .to(getApiRoute() + "/reviews", GHPullRequestReviewDraft.class)
+                .wrapUp(this);
+    }
+
+    private static List<DraftReviewComment> toDraftReviewComments(List<GHPullRequestReviewComment> comments) {
         List<DraftReviewComment> draftComments = new ArrayList<DraftReviewComment>(comments.size());
         for (GHPullRequestReviewComment c : comments) {
             Integer position = c.getPosition();
-            draftComments.add(new DraftReviewComment(c.getBody(), c.getPath(), position == null ? 0 : position /*FIXME do not use GHPullRequestReviewComment for new comments*/));
+            if (position == null) {
+                throw new IllegalArgumentException("GHPullRequestReviewComment must have a position");
+            }
+            draftComments.add(new DraftReviewComment(c.getBody(), c.getPath(), position));
         }
-        return new Requester(root).method("POST")
-                .with("body", body)
-                //.with("event", event.name())
-                ._with("comments", draftComments)
-                .withPreview(BLACK_CAT)
-                .to(getApiRoute() + "/reviews", GHPullRequestReview.class).wrapUp(this);
+        return draftComments;
     }
 
     public GHPullRequestReviewComment createReviewComment(String body, String sha, String path, int position) throws IOException {
         return new Requester(root).method("POST")
                 .with("body", body)
-                .with("commit_id", sha)
+                .with(COMMIT_ID_FIELD, sha)
                 .with("path", path)
                 .with("position", position)
-                .to(getApiRoute() + "/comments", GHPullRequestReviewComment.class).wrapUp(this);
+                .to(getApiRoute() + COMMENTS_ACTION, GHPullRequestReviewComment.class).wrapUp(this);
     }
 
     /**
@@ -335,7 +359,7 @@ public GHPullRequestReviewComment createReviewCommentReply(GHPullRequestReviewCo
         return new Requester(owner.root).method("POST")
                 .with("body", body)
                 .with("in_reply_to", comment.getId())
-                .to(getApiRoute() + "/comments", GHPullRequestReviewComment.class)
+                .to(getApiRoute() + COMMENTS_ACTION, GHPullRequestReviewComment.class)
                 .wrapUp(this);
     }
 
@@ -377,10 +401,10 @@ public void merge(String msg, String sha) throws IOException {
      */
     public void merge(String msg, String sha, MergeMethod method) throws IOException {
         new Requester(root).method("PUT")
-                .with("commit_message",msg)
-                .with("sha",sha)
-                .with("merge_method",method)
-                .to(getApiRoute()+"/merge");
+                .with("commit_message", msg)
+                .with("sha", sha)
+                .with("merge_method", method)
+                .to(getApiRoute() + "/merge");
     }
 
     public enum MergeMethod{ MERGE, SQUASH, REBASE }

src/main/java/org/kohsuke/github/GHPullRequestReview.java

@@ -24,127 +24,34 @@
 package org.kohsuke.github;
 
 import java.io.IOException;
-import java.net.URL;
-import javax.annotation.CheckForNull;
-
-import static org.kohsuke.github.Previews.*;
+import java.util.List;
 
 /**
  * Review to the pull request
  *
  * @see GHPullRequest#listReviews()
- * @see GHPullRequest#createReview(String, GHPullRequestReviewComment...)
+ * @see GHPullRequest#createReview(String, String, GHPullRequestReviewEvent, List)
  */
-public class GHPullRequestReview extends GHObject {
-    GHPullRequest owner;
-
-    private String body;
-    private GHUser user;
-    private String commit_id;
+public class GHPullRequestReview extends GHPullRequestReviewAbstract {
     private GHPullRequestReviewState state;
 
-    /*package*/ GHPullRequestReview wrapUp(GHPullRequest owner) {
-        this.owner = owner;
-        return this;
-    }
-
-    /**
-     * Gets the pull request to which this review is associated.
-     */
-    public GHPullRequest getParent() {
-        return owner;
-    }
-
-    /**
-     * The comment itself.
-     */
-    public String getBody() {
-        return body;
-    }
-
-    /**
-     * Gets the user who posted this review.
-     */
-    public GHUser getUser() throws IOException {
-        return owner.root.getUser(user.getLogin());
-    }
-
-    public String getCommitId() {
-        return commit_id;
-    }
-
-    @CheckForNull
+    @Override
     public GHPullRequestReviewState getState() {
         return state;
     }
 
-    @Override
-    public URL getHtmlUrl() {
-        return null;
-    }
-
-    protected String getApiRoute() {
-        return owner.getApiRoute()+"/reviews/"+id;
-    }
-
-    /**
-     * Updates the comment.
-     */
-    @Preview
-    @Deprecated
-    public void submit(String body, GHPullRequestReviewEvent event) throws IOException {
-        new Requester(owner.root).method("POST")
-                .with("body", body)
-                .with("event", event.action())
-                .withPreview("application/vnd.github.black-cat-preview+json")
-                .to(getApiRoute()+"/events",this);
-        this.body = body;
-    }
-
-    /**
-     * Deletes this review.
-     */
-    @Preview
-    @Deprecated
-    public void delete() throws IOException {
-        new Requester(owner.root).method("DELETE")
-                .withPreview(BLACK_CAT)
-                .to(getApiRoute());
+    GHPullRequestReview wrapUp(GHPullRequest owner) {
+        this.owner = owner;
+        return this;
     }
 
     /**
      * Dismisses this review.
      */
-    @Preview
-    @Deprecated
     public void dismiss(String message) throws IOException {
         new Requester(owner.root).method("PUT")
                 .with("message", message)
-                .withPreview(BLACK_CAT)
-                .to(getApiRoute()+"/dismissals");
+                .to(getApiRoute() + "/dismissals");
         state = GHPullRequestReviewState.DISMISSED;
     }
-
-    /**
-     * Obtains all the review comments associated with this pull request review.
-     */
-    @Preview
-    @Deprecated
-    public PagedIterable<GHPullRequestReviewComment> listReviewComments() throws IOException {
-        return new PagedIterable<GHPullRequestReviewComment>() {
-            public PagedIterator<GHPullRequestReviewComment> _iterator(int pageSize) {
-                return new PagedIterator<GHPullRequestReviewComment>(
-                        owner.root.retrieve()
-                                .withPreview(BLACK_CAT)
-                                .asIterator(getApiRoute() + "/comments",
-                                GHPullRequestReviewComment[].class, pageSize)) {
-                    protected void wrapUp(GHPullRequestReviewComment[] page) {
-                        for (GHPullRequestReviewComment c : page)
-                            c.wrapUp(owner);
-                    }
-                };
-            }
-        };
-    }
-
 }

src/main/java/org/kohsuke/github/GHPullRequestReviewAbstract.java

@@ -0,0 +1,97 @@
+/*
+ * GitHub API for Java
+ * 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.kohsuke.github;
+
+import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+
+import java.io.IOException;
+import java.net.URL;
+
+@SuppressFBWarnings(value = {"UWF_UNWRITTEN_FIELD"}, justification = "JSON API")
+public abstract class GHPullRequestReviewAbstract extends GHObject {
+    protected GHPullRequest owner;
+
+    protected String body;
+    private GHUser user;
+    private String commit_id;
+
+    public abstract GHPullRequestReviewState getState();
+
+    /**
+     * Gets the pull request to which this review is associated.
+     */
+    public GHPullRequest getParent() {
+        return owner;
+    }
+
+    /**
+     * The comment itself.
+     */
+    public String getBody() {
+        return body;
+    }
+
+    /**
+     * Gets the user who posted this review.
+     */
+    public GHUser getUser() throws IOException {
+        return owner.root.getUser(user.getLogin());
+    }
+
+    public String getCommitId() {
+        return commit_id;
+    }
+
+    @Override
+    public URL getHtmlUrl() {
+        return null;
+    }
+
+    String getApiRoute() {
+        return owner.getApiRoute() + "/reviews/" + id;
+    }
+
+    /**
+     * Deletes this review.
+     */
+    public void delete() throws IOException {
+        new Requester(owner.root).method("DELETE")
+                .to(getApiRoute());
+    }
+
+    /**
+     * Obtains all the review comments associated with this pull request review.
+     */
+    public PagedIterable<GHPullRequestReviewComment> listReviewComments() {
+        return new PagedIterable<GHPullRequestReviewComment>() {
+            public PagedIterator<GHPullRequestReviewComment> _iterator(int pageSize) {
+                return new PagedIterator<GHPullRequestReviewComment>(
+                        owner.root.retrieve()
+                                .asIterator(getApiRoute() + "/comments",
+                                        GHPullRequestReviewComment[].class, pageSize)) {
+                    protected void wrapUp(GHPullRequestReviewComment[] page) {
+                        for (GHPullRequestReviewComment c : page)
+                            c.wrapUp(owner);
+                    }
+                };
+            }
+        };
+    }
+}