public interface

PullRequestService

implements PullRequestSupplier
com.atlassian.bitbucket.pull.PullRequestService

Class Overview

A service for the management of pull requests and their comments.

About pull request IDs: Each pull request has two repositories associated with it: The repository commits will be merged from, and the repository they will be merged to. Pull request IDs are scoped to the target repository, and each method accepting a repository ID, unless otherwise documented, expects the ID of that repository. Also note that pull request IDs start from 1 in each target repository; they are not globally unique.

Summary

Public Methods
@Nonnull Comment addComment(int repositoryId, long pullRequestId, String commentText)
Adds a general comment to the pull request.
@Nonnull Comment addDiffComment(int repositoryId, long pullRequestId, AddDiffCommentRequest request)
Adds a line comment to a diff in a pull request.
@Nonnull Comment addFileComment(int repositoryId, long pullRequestId, AddFileCommentRequest request)
Adds a file-level comment to the pull request.
@Nonnull Comment addReply(int repositoryId, long pullRequestId, long commentId, String commentText)
Adds a reply to a comment
@Nonnull PullRequestParticipant addReviewer(int repositoryId, long pullRequestId, String username)
Adds the user specified by 'username' as REVIEWER to the provided PR.
@Nonnull @Deprecated PullRequestParticipant approve(int repositoryId, long pullRequestId)
This method is deprecated. in 4.2, to be removed in 5.0. Use setReviewerStatus(int, long, PullRequestParticipantStatus) instead.
@Nonnull @Deprecated PullRequestParticipant assignRole(int repositoryId, long pullRequestId, String username, PullRequestRole role)
This method is deprecated. in 4.2 for removal in 5.0. Use addReviewer(int, long, String) instead.
PullRequestMergeability canMerge(int repositoryId, long pullRequestId)
Retrieves a flag indicating whether the specified pull request can be merged by the system or must be manually merged by a user.
long count(PullRequestSearchRequest request)
Counts the number of pull requests which match the specified search criteria.
long countCommits(int repositoryId, long pullRequestId)
Counts the number of commits a pull request has.
@Nonnull TaskCount countTasks(PullRequestTaskSearchRequest searchRequest)
Counts the number of tasks in a pull request.
@Nonnull PullRequest create(String title, String description, Set<String> reviewers, Repository fromRepository, String fromBranchId, Repository toRepository, String toBranchId)
Creates a pull request from the supplied repository and branch to the supplied repository and branch with the given title and description.
@Nonnull PullRequest decline(PullRequestDeclineRequest request)
Declines a pull request.
boolean deleteComment(int repositoryId, long pullRequestId, long commentId, int commentVersion)
Deletes a pull request comment
@Nonnull Iterable<DiffCommentAnchor> findCommentAnchors(int repositoryId, long pullRequestId, String path)
Get diff anchors for a given pull request and a path affected by that pull request.
@Nonnull Page<PullRequestActivity> getActivities(int repositoryId, long pullRequestId, PageRequest pageRequest)
Retrieves a page of the activities for a given pull request.
@Nonnull Set<PullRequestActivity> getActivitiesById(int repositoryId, long pullRequestId, Set<Long> activityIds)
Retrieves the specified activities of the given pull request.
@Nonnull PullRequestActivityPage<PullRequestActivity> getActivitiesStartingAt(int repositoryId, long pullRequestId, PullRequestEntityType fromType, long fromId, PageRequest pageRequest)
Retrieves the page of activities that start with an entity (given its type and id) for the given pull request.
@Nullable PullRequest getById(int repositoryId, long pullRequestId)
Retrieves a pull request by its ID, within the specified repository.
@Nonnull Comment getComment(int repositoryId, long pullRequestId, long commentId)
Retrieves a comment for the given comment id and pull request id.
@Nonnull Page<Commit> getCommits(int repositoryId, long pullRequestId, PageRequest pageRequest)
Retrieves a page of the commits for a given pull request.
@Nonnull Page<PullRequestParticipant> getParticipants(int repositoryId, long pullRequestId, PageRequest pageRequest)
Retrieves a page of the participants for a given pull request.
@Nonnull PullRequest merge(PullRequestMergeRequest request)
Merges a pull request.
void removeReviewer(int repositoryId, long pullRequestId, String username)
Removes a REVIEWER from a pull request.
@Nonnull PullRequest reopen(int repositoryId, long pullRequestId, int version)
Reopens a pull request.
@Nonnull Page<PullRequest> search(PullRequestSearchRequest request, PageRequest pageRequest)
Finds a single page of pull requests depending on the request passed in.
@Nonnull Page<PullRequestActivity> searchActivities(PullRequestActivitySearchRequest request, PageRequest pageRequest)
Finds a single page of pull request activities depending on the request passed in.
@Nonnull Page<Task> searchTasks(PullRequestTaskSearchRequest searchRequest, PageRequest pageRequest)
Finds a single page of @{link Task tasks} belonging to this pull request depending on the request passed in.
@Nonnull Page<ApplicationUser> searchUsers(PullRequestParticipantSearchRequest searchRequest, PageRequest pageRequest)
Finds users who have participated in pull requests based on the provided search request.
@Nonnull PullRequestParticipant setReviewerStatus(int repositoryId, long pullRequestId, PullRequestParticipantStatus status)
Allows a user to update their participation status in a pull request.
void streamChanges(PullRequestChangesRequest request, ChangeCallback callback)
Streams changes for the specified PullRequest to the provided ChangeCallback.
void streamCommits(int repositoryId, long pullRequestId, CommitCallback callback)
Streams commits for the specified pull request.
void streamDiff(PullRequestDiffRequest request, DiffContentCallback callback)
Streams the Diff for the specified file path within the PullRequest to the provided DiffContentCallback.
@Deprecated void unassignRole(int repositoryId, long pullRequestId, String username)
This method is deprecated. in 4.2 for removal in 5.0. Use removeReviewer(int, long, String) instead
boolean unwatch(int repositoryId, long pullRequestId)
Removes the current user as a watcher of the given pull request.
@Nonnull PullRequest update(PullRequestUpdateRequest request)
Updates a pull request's title and description.
@Nonnull Comment updateComment(int repositoryId, long pullRequestId, long commentId, int commentVersion, String commentText)
Updates the pull request comment's text
@Nonnull Watcher watch(int repositoryId, long pullRequestId)
Adds the current user as a watcher of the given pull request.
@Nonnull @Deprecated PullRequestParticipant withdrawApproval(int repositoryId, long pullRequestId)
This method is deprecated. in 4.2, to be removed in 5.0. Use setReviewerStatus(int, long, PullRequestParticipantStatus) instead.
[Expand]
Inherited Methods
From interface com.atlassian.bitbucket.pull.PullRequestSupplier

Public Methods

@Nonnull public Comment addComment (int repositoryId, long pullRequestId, String commentText)

Adds a general comment to the pull request.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
commentText the comment text
Returns
  • the created comment
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository

@Nonnull public Comment addDiffComment (int repositoryId, long pullRequestId, AddDiffCommentRequest request)

Adds a line comment to a diff in a pull request.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
request a request describing the comment to create
Returns
  • the created line comment
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository
ArgumentValidationException if the request contains invalid data

@Nonnull public Comment addFileComment (int repositoryId, long pullRequestId, AddFileCommentRequest request)

Adds a file-level comment to the pull request.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
request a request describing the comment to create
Returns
  • the created comment
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository

@Nonnull public Comment addReply (int repositoryId, long pullRequestId, long commentId, String commentText)

Adds a reply to a comment

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
commentId the ID of the comment being replied to
commentText the comment text
Returns
  • the created comment
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository
NoSuchCommentException if no comment exists with the specified ID

@Nonnull public PullRequestParticipant addReviewer (int repositoryId, long pullRequestId, String username)

Adds the user specified by 'username' as REVIEWER to the provided PR. If the user is already a reviewer this method has no effect.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
username the username for the user to be added as a reviewer
Returns
  • the newly created or updated participant entity
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository
UnmodifiablePullRequestRoleException if the participant is already assigned the AUTHOR role.
InvalidPullRequestParticipantException if the user cannot be made a reviewer because they have insufficient access to the repository
IllegalPullRequestStateException if the pull request is either MERGED or DECLINED

@Nonnull @Deprecated public PullRequestParticipant approve (int repositoryId, long pullRequestId)

This method is deprecated.
in 4.2, to be removed in 5.0. Use setReviewerStatus(int, long, PullRequestParticipantStatus) instead.

Allows a user to give their approval to a pull request. If they aren't already a participant of the pull request they are made one first. If the user has already already provided their approval this operation has no effect. A user may only approve a pull request which is in open.

Since 4.2 authors may not have their status changed.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
Returns
  • the newly created or updated participant entity
Throws
InvalidPullRequestParticipantException if the user cannot be made a participant because they have insufficient privileges to read the repository
IllegalPullRequestStateException if the pull request is not open

@Nonnull @Deprecated public PullRequestParticipant assignRole (int repositoryId, long pullRequestId, String username, PullRequestRole role)

This method is deprecated.
in 4.2 for removal in 5.0. Use addReviewer(int, long, String) instead.

Assigns a participant to an explicit role in pull request. Currently only reviewers may be assigned. If the user is not yet a participant in the pull request, they are made one and assigned the supplied role. If the user is already a participant in the pull request, their previous role is replaced with the supplied role unless they are already assigned the AUTHOR role which cannot be changed and will result in an UnmodifiablePullRequestRoleException being thrown.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
username the participant's user name
role the participant's role in the pull request
Returns
  • the newly created or updated participant
Throws
InvalidPullRequestRoleException if the role is not the REVIEWER role.
InvalidPullRequestParticipantException if the user cannot be made a participant because they have insufficient privileges to read the repository
UnmodifiablePullRequestRoleException if the participant is already assigned the AUTHOR role.
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository

public PullRequestMergeability canMerge (int repositoryId, long pullRequestId)

Retrieves a flag indicating whether the specified pull request can be merged by the system or must be manually merged by a user.

Even if this method returns true, there are still a variety of reasons for which merging may fail, including but not limited to:

  • The version supplied when merging is out of date
  • Additional changes have been pushed to the pull request's target branch and the pull request has not yet been updated accordingly
The goal for this method is to serve as a hint as to whether or not a given pull request can be merged by the system, rather than as an ironclad assurance that it can be.

Note: If the specified pull request is declined or MERGED, this method will always return false.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
Returns
  • the mergeability of the pull request, taking into account if it is open, has conflicts and any vetoes that MergeRequestChecks may have raised
Throws
IllegalPullRequestStateException if the pull request is not open

public long count (PullRequestSearchRequest request)

Counts the number of pull requests which match the specified search criteria.

Parameters
request the search criteria to use
Returns
  • the number of pull requests that match the search criteria

public long countCommits (int repositoryId, long pullRequestId)

Counts the number of commits a pull request has.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
Returns
  • the number of commits in the pull request
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository

@Nonnull public TaskCount countTasks (PullRequestTaskSearchRequest searchRequest)

Counts the number of tasks in a pull request.

Parameters
searchRequest the search criteria to use
Returns
  • a TaskCount object containing the number of tasks in each state
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository

@Nonnull public PullRequest create (String title, String description, Set<String> reviewers, Repository fromRepository, String fromBranchId, Repository toRepository, String toBranchId)

Creates a pull request from the supplied repository and branch to the supplied repository and branch with the given title and description.

Events raised:

Parameters
title the title of the pull request
description the optional description of the pull request
reviewers the set of usernames of the users to add as a reviewer
fromRepository the repository from which the changes come
fromBranchId the branch of the fromRepository from which the changes come
toRepository the repository changes are to be merged to
toBranchId the branch of the toRepository to which changes are merged
Returns
  • the created pull request
Throws
DuplicatePullRequestException if there is already an open pull request with identical to and from repositories and branches
EmptyPullRequestException if the to branch is up-to-date with all of the changes on the from branch, resulting in a pull request with nothing to merge
InvalidPullRequestTargetException if the from or to repositories are not the same or if the from and to branches are the same
InvalidPullRequestReviewersException if one or more of the reviewers could not be added
PullRequestOpenCanceledException if opening the pull request is canceled by an event listener
NoSuchCommitException if the the from or to branches do not exist

@Nonnull public PullRequest decline (PullRequestDeclineRequest request)

Declines a pull request. The pull request must be open or an exception is thrown. The expected version of the pull request must be supplied to ensure the client is not operating on stale information.

Parameters
request details for declining a pull request
Returns
  • the updated pull request
Throws
IllegalPullRequestStateException if the pull request is not open
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository
PullRequestOutOfDateException if the version of the specified pull request does not match the expected version

public boolean deleteComment (int repositoryId, long pullRequestId, long commentId, int commentVersion)

Deletes a pull request comment

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
commentId the ID of the comment
commentVersion the expected version of the comment
Returns
  • true if the comment existed (and thus was deleted), false otherwise
Throws
CommentDeletionException if the comment has replies
CommentOutOfDateException if the version of the specified comment does not match the expected version

@Nonnull public Iterable<DiffCommentAnchor> findCommentAnchors (int repositoryId, long pullRequestId, String path)

Get diff anchors for a given pull request and a path affected by that pull request.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
path the path of the file modified by the pull request, for which the anchors should be retrieved
Returns
  • all anchors (representing comments) for the path in the pull request identified by repositoryId and pullRequestId
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository

@Nonnull public Page<PullRequestActivity> getActivities (int repositoryId, long pullRequestId, PageRequest pageRequest)

Retrieves a page of the activities for a given pull request.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
pageRequest the request specifying the start and limit of the page
Returns
  • the page of activities

@Nonnull public Set<PullRequestActivity> getActivitiesById (int repositoryId, long pullRequestId, Set<Long> activityIds)

Retrieves the specified activities of the given pull request.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
activityIds the activity IDs that should be retrieved
Returns
  • the activities that could be found. Note: There may be fewer returned activities than supplied IDs where an unknown ID is specified or where activities have since been deleted.

@Nonnull public PullRequestActivityPage<PullRequestActivity> getActivitiesStartingAt (int repositoryId, long pullRequestId, PullRequestEntityType fromType, long fromId, PageRequest pageRequest)

Retrieves the page of activities that start with an entity (given its type and id) for the given pull request.

Entity types currently accepted:

  • ACTIVITY to search for the page of activities starting with the supplied activity
  • COMMENT to search for the page of activities starting with the activity of the supplied comment. If the comment is not a root comment, the comment's root's activity is used.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
fromType the type of the entity to search for
fromId ID of the entity to search for - either a comment ID or activity ID
pageRequest the request specifying the limit of the page. Note: the start property is ignored.
Returns
  • the page of activities that contains the given activity. This page provides the ability to calculate both the next page and the previous page of results as the page may be
Throws
NoSuchEntityException if the activity can't be found.

@Nullable public PullRequest getById (int repositoryId, long pullRequestId)

Retrieves a pull request by its ID, within the specified repository.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
Returns
  • the pull request found or null if there is no pull request that matches the given id

@Nonnull public Comment getComment (int repositoryId, long pullRequestId, long commentId)

Retrieves a comment for the given comment id and pull request id.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
commentId the ID of the comment to retrieve
Returns
  • the comment
Throws
NoSuchCommentException if the comment can not be found
NoSuchPullRequestException if the pull request can not be found

@Nonnull public Page<Commit> getCommits (int repositoryId, long pullRequestId, PageRequest pageRequest)

Retrieves a page of the commits for a given pull request.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
pageRequest the request specifying the start and limit of the page
Returns
  • the page of commits
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository

@Nonnull public Page<PullRequestParticipant> getParticipants (int repositoryId, long pullRequestId, PageRequest pageRequest)

Retrieves a page of the participants for a given pull request.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
pageRequest the request specifying the start and limit of the page
Returns
  • the page of participants

@Nonnull public PullRequest merge (PullRequestMergeRequest request)

Merges a pull request. The pull request must be open or an exception is thrown. The expected version of the pull request must be supplied to ensure the client is not operating on stale information.

Parameters
request details for merging the pull request, specifying the pull request to merge, the expected version, and, optionally, a commit message and additional context
Returns
  • the updated pull request
Throws
IllegalPullRequestStateException if the pull request is not open
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository
PullRequestMergeCanceledException if the merge was canceled by an event listener
PullRequestMergeVetoedException if any MergeRequestChecks vetoed the merge
PullRequestOutOfDateException if the version of the specified pull request does not match the expected version

public void removeReviewer (int repositoryId, long pullRequestId, String username)

Removes a REVIEWER from a pull request.

If the user is the AUTHOR of the PR this method will throw IllegalPullRequestStateException.

If the user has no activity items associated with them in the pull request they will be completely removed.

Otherwise they will be made a PARTICIPANT

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
username the reviewer's user name
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository
UnmodifiablePullRequestRoleException if the user is the AUTHOR of the PR
IllegalPullRequestStateException if the pull request is either MERGED or DECLINED

@Nonnull public PullRequest reopen (int repositoryId, long pullRequestId, int version)

Reopens a pull request. The pull request must be declined or an exception is thrown. The expected version of the pull request must be supplied to ensure the client is not operating on stale information.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
version the expected version of the pull request
Returns
  • the updated pull request
Throws
IllegalPullRequestStateException if the pull request is not declined
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository
PullRequestOutOfDateException if the version of the specified pull request does not match the expected version

@Nonnull public Page<PullRequest> search (PullRequestSearchRequest request, PageRequest pageRequest)

Finds a single page of pull requests depending on the request passed in. If the request specifies that the results should be sorted by participant status then only one participant may be specified in the request

Parameters
request the search criteria to use
pageRequest the request specifying the start and limit of the search
Returns
  • a page of pull requests
Throws
IllegalPullRequestSearchRequestException if PARTICIPANT_STATUS order was requested but getParticipants() is empty or contains more than one participant (since 4.4)

@Nonnull public Page<PullRequestActivity> searchActivities (PullRequestActivitySearchRequest request, PageRequest pageRequest)

Finds a single page of pull request activities depending on the request passed in.

Parameters
request the search criteria to use
pageRequest the request specifying the start and limit of the search
Returns
  • a page of pull request activities

@Nonnull public Page<Task> searchTasks (PullRequestTaskSearchRequest searchRequest, PageRequest pageRequest)

Finds a single page of @{link Task tasks} belonging to this pull request depending on the request passed in.

Parameters
searchRequest the search criteria to use
pageRequest the request specifying the start and limit of the search
Returns
  • a page of pull request activities

@Nonnull public Page<ApplicationUser> searchUsers (PullRequestParticipantSearchRequest searchRequest, PageRequest pageRequest)

Finds users who have participated in pull requests based on the provided search request.

Parameters
searchRequest the search criteria to use
pageRequest the request specifying the start and limit of the search
Returns
  • a page of pull request participant users

@Nonnull public PullRequestParticipant setReviewerStatus (int repositoryId, long pullRequestId, PullRequestParticipantStatus status)

Allows a user to update their participation status in a pull request. If they aren't already a participant of the pull request they are made one first. A non-reviewer may not set their status to UNAPPROVED. A user may only update their status if a pull request is OPEN. This operation has no effect if the user already has their status set to the provided value.

Authors may not have their status changed.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
status the participant status to set for the current user
Returns
  • the newly created or updated participant entity
Throws
InvalidPullRequestParticipantException if the user cannot be made a participant because they have insufficient privileges to read the repository
IllegalPullRequestStateException if the pull request is not open

public void streamChanges (PullRequestChangesRequest request, ChangeCallback callback)

Streams changes for the specified PullRequest to the provided ChangeCallback.

Note: Internal hard limits are applied to the number of changes which will be returned. When changes are truncated for exceeding those limits, it will be signalled to the callback.

Parameters
request the repository, pull request and other properties describing the changes to stream
callback the callback to receive changes
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository

public void streamCommits (int repositoryId, long pullRequestId, CommitCallback callback)

Streams commits for the specified pull request.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
callback the request specifying the start and limit of the page
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository

public void streamDiff (PullRequestDiffRequest request, DiffContentCallback callback)

Streams the Diff for the specified file path within the PullRequest to the provided DiffContentCallback. Comment anchors will be offered to the callback prior to streaming the diff, allowing them to be merged into the diff output as desired.

If the Change indicated the path being diffed was moved/renamed or copied, the srcPath should also be provided. Failure to provide both paths may result in an incorrect diff in some SCMs.

Note: Internal hard limits are applied to the diff being streamed, limiting the number of lines that can be returned. When a diff is truncated for exceeding those limits, it will be signalled to the callback.

Parameters
request the repository, pull request, path and other properties describing the diff to stream
callback the callback to receive the streamed Diff
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository

@Deprecated public void unassignRole (int repositoryId, long pullRequestId, String username)

This method is deprecated.
in 4.2 for removal in 5.0. Use removeReviewer(int, long, String) instead

Unassigns a participant from any role they may have been given in a pull request. If the user is not a participant this method has no effect. An attempt to unassign a participant from the AUTHOR role will result in an UnmodifiablePullRequestRoleException being thrown. Since 4.2 if the user is not an AUTHOR and they have no activity items associated with them in the pull request they will be completely removed. If the user has the PARTICIPANT role and they have activity items associated with them in the pull request this method has no effect. If the user has the REVIEWER role and they have activity items associated with them in the pull request this method will simply update their role to PARTICIPANT.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
username the participant's user name
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository
UnmodifiablePullRequestRoleException if the participant is already an AUTHOR

public boolean unwatch (int repositoryId, long pullRequestId)

Removes the current user as a watcher of the given pull request.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
Returns
  • true if the watcher existed (and thus was removed), false otherwise

@Nonnull public PullRequest update (PullRequestUpdateRequest request)

Updates a pull request's title and description.

This method will fire:

Parameters
request details for updating a pull request, including a title, description and reviewers.
Returns
  • the updated pull request
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository
PullRequestOutOfDateException if the version of the specified pull request does not match the expected version
InvalidPullRequestReviewersException if one or more of the reviewers could not be added
DuplicatePullRequestException if there is already an open pull request with an identical to branch
InvalidPullRequestTargetException if the from and new to branch are the same
EmptyPullRequestException if the new destination branch up-to-date is up-to-date with all of the changes from the from branch, resulting in a pull request with nothing to merge

@Nonnull public Comment updateComment (int repositoryId, long pullRequestId, long commentId, int commentVersion, String commentText)

Updates the pull request comment's text

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
commentId the ID of the comment to update
commentVersion the expected version of the comment
commentText the new text of the comment
Returns
  • the updated comment
Throws
CommentOutOfDateException if the version of the specified comment does not match the expected version
NoSuchCommentException if no comment exists with the specified ID

@Nonnull public Watcher watch (int repositoryId, long pullRequestId)

Adds the current user as a watcher of the given pull request.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
Returns
  • the created watcher
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository

@Nonnull @Deprecated public PullRequestParticipant withdrawApproval (int repositoryId, long pullRequestId)

This method is deprecated.
in 4.2, to be removed in 5.0. Use setReviewerStatus(int, long, PullRequestParticipantStatus) instead.

Allows the current user to withdraw their approval of a pull request. The user must already be a participant of the pull request else an exception is thrown. If the user has already withdrawn their approval this operation has no effect. A participant may only withdraw approval for a pull request if it open.

Since 4.2 authors may not have their status changed and non-participants may not withdraw approvals.

Parameters
repositoryId the ID of the repository to which the pull request will be merged
pullRequestId the ID of the pull request within the repository
Returns
  • the updated participant entity
Throws
NoSuchParticipantException if the user is not a participant in the pull request and thus cannot withdraw their approval
IllegalPullRequestStateException if the pull request is not open