GHPullRequestReviewComment.java

/*
 * The MIT License
 *
 * Copyright (c) 2010, Kohsuke Kawaguchi
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
package org.kohsuke.github;

import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
import org.kohsuke.github.internal.EnumUtils;

import java.io.IOException;
import java.net.URL;

// TODO: Auto-generated Javadoc
/**
 * Review comment to the pull request.
 *
 * @author Julien Henry
 * @see GHPullRequest#listReviewComments() GHPullRequest#listReviewComments()
 * @see GHPullRequest#createReviewComment(String, String, String, int) GHPullRequest#createReviewComment(String, String,
 *      String, int)
 */
public class GHPullRequestReviewComment extends GHIssueComment implements Refreshable {

    /**
     * The side of the diff to which the comment applies.
     *
     * @see <a href="https://docs.github.com/en/rest/pulls/comments">Pull Request Review Comments API</a>
     */
    public static enum Side {
        /** Left side */
        LEFT,
        /** Right side */
        RIGHT,
        /** Unknown side */
        UNKNOWN;

        /**
         * From.
         *
         * @param value
         *            the value
         * @return the status
         */
        public static Side from(String value) {
            return EnumUtils.getEnumOrDefault(Side.class, value, Side.UNKNOWN);
        }

    }

    // PR review comment specific fields (not in GHIssueComment)
    private String commitId;
    private String diffHunk;
    private long inReplyToId = -1L;
    private int line = -1;
    private String originalCommitId;
    private int originalLine = -1;
    private int originalPosition = -1;
    private Integer originalStartLine;
    private String path;
    private int position = -1;
    private Long pullRequestReviewId;
    private String pullRequestUrl;
    private GHPullRequestReviewCommentReactions reactions;
    private String side;
    private Integer startLine;
    private String startSide;

    /**
     * Create default GHPullRequestReviewComment instance
     */
    public GHPullRequestReviewComment() {
    }

    /**
     * Creates the reaction.
     *
     * @param content
     *            the content
     * @return the GH reaction
     * @throws IOException
     *             Signals that an I/O exception has occurred.
     */
    @Override
    public GHReaction createReaction(ReactionContent content) throws IOException {
        return owner.root()
                .createRequest()
                .method("POST")
                .with("content", content.getContent())
                .withUrlPath(getApiRoute() + "/reactions")
                .fetch(GHReaction.class);
    }

    /**
     * Deletes this review comment.
     *
     * @throws IOException
     *             the io exception
     */
    @Override
    public void delete() throws IOException {
        owner.root().createRequest().method("DELETE").withUrlPath(getApiRoute()).send();
    }

    /**
     * Delete reaction.
     *
     * @param reaction
     *            the reaction
     * @throws IOException
     *             Signals that an I/O exception has occurred.
     */
    @Override
    public void deleteReaction(GHReaction reaction) throws IOException {
        owner.root()
                .createRequest()
                .method("DELETE")
                .withUrlPath(getApiRoute(), "reactions", String.valueOf(reaction.getId()))
                .send();
    }

    /**
     * Gets commit id.
     *
     * @return the commit id
     */
    public String getCommitId() {
        return commitId;
    }

    /**
     * Gets diff hunk.
     *
     * @return the diff hunk
     */
    public String getDiffHunk() {
        return diffHunk;
    }

    /**
     * Gets in reply to id.
     *
     * @return the in reply to id, or -1 if not a reply
     */
    public long getInReplyToId() {
        return inReplyToId;
    }

    /**
     * Gets The line of the blob to which the comment applies. The last line of the range for a multi-line comment.
     *
     * <p>
     * This field is not available on {@link GHPullRequestReview.ReviewComment} objects returned by
     * {@link GHPullRequestReview#listReviewComments()}. Use
     * {@link GHPullRequestReview.ReviewComment#readPullRequestReviewComment()} or
     * {@link GHPullRequest#listReviewComments()} to obtain this value.
     *
     * @return the line to which the comment applies, or -1 if not available
     */
    public int getLine() {
        return line;
    }

    /**
     * Gets commit id.
     *
     * @return the commit id
     */
    public String getOriginalCommitId() {
        return originalCommitId;
    }

    /**
     * Gets The line of the blob to which the comment applies. The last line of the range for a multi-line comment.
     *
     * <p>
     * This field is not available on {@link GHPullRequestReview.ReviewComment} objects returned by
     * {@link GHPullRequestReview#listReviewComments()}. Use
     * {@link GHPullRequestReview.ReviewComment#readPullRequestReviewComment()} or
     * {@link GHPullRequest#listReviewComments()} to obtain this value.
     *
     * @return the line to which the comment applies, or -1 if not available
     */
    public int getOriginalLine() {
        return originalLine;
    }

    /**
     * Gets original position.
     *
     * @return the original position
     */
    public int getOriginalPosition() {
        return originalPosition;
    }

    /**
     * Gets The first line of the range for a multi-line comment.
     *
     * <p>
     * This field is not available on {@link GHPullRequestReview.ReviewComment} objects returned by
     * {@link GHPullRequestReview#listReviewComments()}. Use
     * {@link GHPullRequestReview.ReviewComment#readPullRequestReviewComment()} or
     * {@link GHPullRequest#listReviewComments()} to obtain this value.
     *
     * @return the original start line, or -1 if not available or not a multi-line comment
     */
    public int getOriginalStartLine() {
        return originalStartLine != null ? originalStartLine : -1;
    }

    /**
     * Gets the pull request to which this review comment is associated.
     *
     * @return the parent pull request
     */
    @Override
    @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Expected behavior")
    public GHPullRequest getParent() {
        return (GHPullRequest) owner;
    }

    /**
     * Gets path.
     *
     * @return the path
     */
    public String getPath() {
        return path;
    }

    /**
     * Gets position.
     *
     * @return the position, or -1 if not available
     */
    public int getPosition() {
        return position;
    }

    /**
     * Gets The ID of the pull request review to which the comment belongs.
     *
     * @return {@link Long} the ID of the pull request review
     */
    public Long getPullRequestReviewId() {
        return pullRequestReviewId != null ? pullRequestReviewId : -1;
    }

    /**
     * Gets URL for the pull request that the review comment belongs to.
     *
     * @return {@link URL} the URL of the pull request
     */
    public URL getPullRequestUrl() {
        return GitHubClient.parseURL(pullRequestUrl);
    }

    /**
     * Gets the Reaction Rollup
     *
     * @return {@link GHPullRequestReviewCommentReactions} the reaction rollup
     */
    public GHPullRequestReviewCommentReactions getReactions() {
        return reactions;
    }

    /**
     * Gets The side of the diff to which the comment applies. The side of the last line of the range for a multi-line
     * comment.
     *
     * <p>
     * This field is not available on {@link GHPullRequestReview.ReviewComment} objects returned by
     * {@link GHPullRequestReview#listReviewComments()}. Use
     * {@link GHPullRequestReview.ReviewComment#readPullRequestReviewComment()} or
     * {@link GHPullRequest#listReviewComments()} to obtain this value.
     *
     * @return {@link Side} the side of the diff to which the comment applies, or {@link Side#UNKNOWN} if not available
     */
    public Side getSide() {
        return Side.from(side);
    }

    /**
     * Gets The first line of the range for a multi-line comment.
     *
     * <p>
     * This field is not available on {@link GHPullRequestReview.ReviewComment} objects returned by
     * {@link GHPullRequestReview#listReviewComments()}. Use
     * {@link GHPullRequestReview.ReviewComment#readPullRequestReviewComment()} or
     * {@link GHPullRequest#listReviewComments()} to obtain this value.
     *
     * @return the start line, or -1 if not available or not a multi-line comment
     */
    public int getStartLine() {
        return startLine != null ? startLine : -1;
    }

    /**
     * Gets The side of the first line of the range for a multi-line comment.
     *
     * <p>
     * This field is not available on {@link GHPullRequestReview.ReviewComment} objects returned by
     * {@link GHPullRequestReview#listReviewComments()}. Use
     * {@link GHPullRequestReview.ReviewComment#readPullRequestReviewComment()} or
     * {@link GHPullRequest#listReviewComments()} to obtain this value.
     *
     * @return {@link Side} the side of the first line, or {@link Side#UNKNOWN} if not available
     */
    public Side getStartSide() {
        return Side.from(startSide);
    }

    /**
     * Gets the user who posted this comment.
     *
     * @return the user
     * @throws IOException
     *             the io exception
     */
    @Override
    public GHUser getUser() throws IOException {
        return owner.root().intern(user);
    }

    /**
     * List reactions.
     *
     * @return the paged iterable
     */
    @Override
    public PagedIterable<GHReaction> listReactions() {
        return owner.root()
                .createRequest()
                .withUrlPath(getApiRoute() + "/reactions")
                .toIterable(GHReaction[].class, item -> owner.root());
    }

    /**
     * Refreshes this comment by fetching the full data from the API.
     *
     * <p>
     * This is useful when the comment was obtained via {@link GHPullRequestReview#listReviewComments()}, which uses a
     * GitHub API endpoint that does not return all fields. After calling this method, fields like {@link #getLine()},
     * {@link #getOriginalLine()}, {@link #getSide()}, etc. will return their actual values.
     *
     * @throws IOException
     *             if an I/O error occurs
     * @see GHPullRequest#listReviewComments()
     */
    @Override
    public void refresh() throws IOException {
        owner.root().createRequest().withUrlPath(getApiRoute()).fetchInto(this).wrapUp(getParent());
    }

    /**
     * Create a new comment that replies to this comment.
     *
     * @param body
     *            the body
     * @return the gh pull request review comment
     * @throws IOException
     *             the io exception
     */
    public GHPullRequestReviewComment reply(String body) throws IOException {
        return owner.root()
                .createRequest()
                .method("POST")
                .with("body", body)
                .withUrlPath(getApiRoute(true) + "/replies")
                .fetch(GHPullRequestReviewComment.class)
                .wrapUp(getParent());
    }

    /**
     * Updates the comment.
     *
     * @param body
     *            the body
     * @throws IOException
     *             the io exception
     */
    @Override
    public void update(String body) throws IOException {
        owner.root().createRequest().method("PATCH").with("body", body).withUrlPath(getApiRoute()).fetchInto(this);
        this.body = body;
    }

    /**
     * Gets api route.
     *
     * @return the api route
     */
    protected String getApiRoute() {
        return getApiRoute(false);
    }

    /**
     * Gets api route.
     *
     * @param includePullNumber
     *            if true, includes the owning pull request's number in the route.
     *
     * @return the api route
     */
    protected String getApiRoute(boolean includePullNumber) {
        return "/repos/" + owner.getRepository().getFullName() + "/pulls"
                + (includePullNumber ? "/" + owner.getNumber() : "") + "/comments/" + getId();
    }

    /**
     * Wrap up.
     *
     * @param pullRequest
     *            the pull request owner
     * @return the GH pull request review comment
     */
    GHPullRequestReviewComment wrapUp(GHPullRequest pullRequest) {
        this.owner = pullRequest;
        return this;
    }
}