com.atlassian.bitbucket.pull.PullRequestService |
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 ID
s 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.
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Adds a general comment to the pull request.
| |||||||||||
Adds a line comment to a diff in a pull request.
| |||||||||||
Adds a file-level comment to the pull request.
| |||||||||||
Adds a reply to a comment
| |||||||||||
Allows a user to give their approval to a pull request.
| |||||||||||
Assigns a participant to an explicit role in pull request.
| |||||||||||
Retrieves a flag indicating whether the specified pull request can be #merge(int, long, int) merged
by the system or must be manually merged by a user.
| |||||||||||
Counts the number of pull requests which match the specified search criteria.
| |||||||||||
Counts the number of commits a pull request has.
| |||||||||||
Counts the number of tasks in a pull request.
| |||||||||||
Creates a pull request from the supplied repository and branch to the supplied repository and branch with the
given title and description.
| |||||||||||
Declines a pull request.
| |||||||||||
Deletes a pull request comment
| |||||||||||
Get diff anchors for a given pull request and a path affected by that pull request.
| |||||||||||
Retrieves a page of the activities for a given pull request.
| |||||||||||
Retrieves the specified activities of the given pull request.
| |||||||||||
Retrieves the page of activities that start with an entity (given its type and id) for the given pull request.
| |||||||||||
Retrieves a pull request by its ID, within the specified repository.
| |||||||||||
Retrieves a comment for the given comment id and pull request id.
| |||||||||||
Retrieves a page of the commits for a given pull request.
| |||||||||||
Retrieves a page of the participants for a given pull request.
| |||||||||||
Merges a pull request.
| |||||||||||
Reopens a pull request.
| |||||||||||
Finds a single page of pull requests depending on the
request passed in. | |||||||||||
Finds a single page of pull request activities depending on the
request passed in. | |||||||||||
Finds a single page of @{link Task tasks} belonging to this pull request depending on the
request passed in. | |||||||||||
Streams commits for the specified pull request.
| |||||||||||
Streams the
Diff for the specified file path within the PullRequest to the provided
DiffContentCallback . | |||||||||||
Unassigns a participant from any explicit role they may have been given in a pull request.
| |||||||||||
Removes the current user as a watcher of the given pull request.
| |||||||||||
Updates a pull request's title and description.
| |||||||||||
Updates the pull request comment's text
| |||||||||||
Adds the current user as a watcher of the given pull request.
| |||||||||||
Allows the current user to withdraw their approval of a pull request.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From interface
com.atlassian.bitbucket.pull.PullRequestSupplier
|
Adds a general comment to the pull request.
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 |
NoSuchPullRequestException | if no pull request with the specified ID can be found in the repository |
---|
Adds a line comment to a diff in a pull request.
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 |
NoSuchPullRequestException | if no pull request with the specified ID can be found in the repository |
---|---|
ArgumentValidationException | if the request contains invalid data
|
Adds a file-level comment to the pull request.
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 |
NoSuchPullRequestException | if no pull request with the specified ID can be found in the repository |
---|
Adds a reply to a comment
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 |
NoSuchPullRequestException | if no pull request with the specified ID can be found in the repository |
---|---|
NoSuchCommentException | if no comment exists with the specified ID |
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.
repositoryId | the ID of the repository to which the pull request will be merged |
---|---|
pullRequestId | the ID of the pull request within the repository |
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 |
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.
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 |
InvalidPullRequestRoleException | if the role is not the REVIEWER role. |
---|---|
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 |
Retrieves a flag indicating whether the specified pull request can be #merge(int, long, int) 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:
Note: If the specified pull request is declined
or
MERGED
, this method will always return false
.
repositoryId | the ID of the repository to which the pull request will be merged |
---|---|
pullRequestId | the ID of the pull request within the repository |
MergeRequestCheck
s may have raisedIllegalPullRequestStateException | if the pull request is not open |
---|
Counts the number of pull requests which match the specified search criteria.
request | the search criteria to use |
---|
Counts the number of commits a pull request has.
repositoryId | the ID of the repository to which the pull request will be merged |
---|---|
pullRequestId | the ID of the pull request within the repository |
NoSuchPullRequestException | if no pull request with the specified ID can be found in the repository |
---|
Counts the number of tasks in a pull request.
searchRequest | the search criteria to use |
---|
TaskCount
object containing the number of tasks in each stateNoSuchPullRequestException | if no pull request with the specified ID can be found in the repository |
---|
Creates a pull request from the supplied repository and branch to the supplied repository and branch with the given title and description.
Events raised:
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 |
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 |
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.
request | details for declining a pull request |
---|
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 |
Deletes a pull request comment
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 |
true
if the comment existed (and thus was deleted), false
otherwiseCommentDeletionException | if the comment has replies |
---|---|
CommentOutOfDateException | if the version of the specified comment does not match the expected version |
Get diff anchors for a given pull request and a path affected by that pull request.
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 |
path
in the pull request identified by
repositoryId
and pullRequestId
NoSuchPullRequestException | if no pull request with the specified ID can be found in the repository |
---|
Retrieves a page of the activities for a given pull request.
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 |
Retrieves the specified activities of the given pull request.
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 |
Retrieves the page of activities that start with an entity (given its type and id) for the given pull request.
Entity types currently accepted:
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. |
NoSuchEntityException | if the activity can't be found. |
---|
Retrieves a pull request by its ID, within the specified repository.
repositoryId | the ID of the repository to which the pull request will be merged |
---|---|
pullRequestId | the ID of the pull request within the repository |
Retrieves a comment for the given comment id and pull request id.
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 |
NoSuchCommentException | if the comment can not be found |
---|---|
NoSuchPullRequestException | if the pull request can not be found |
Retrieves a page of the commits for a given pull request.
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 |
NoSuchPullRequestException | if no pull request with the specified ID can be found in the repository |
---|
Retrieves a page of the participants for a given pull request.
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 |
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.
request | details for merging the pull request, specifying the pull request to merge, the expected version, and, optionally, a commit message and additional context |
---|
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 MergeRequestCheck s vetoed the merge |
PullRequestOutOfDateException | if the version of the specified pull request does not match the expected 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.
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 |
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 |
Finds a single page of pull requests depending on the request
passed in.
request | the search criteria to use |
---|---|
pageRequest | the request specifying the start and limit of the search |
Finds a single page of pull request activities depending on the request
passed in.
request | the search criteria to use |
---|---|
pageRequest | the request specifying the start and limit of the search |
Finds a single page of @{link Task tasks} belonging to this pull request depending on the request
passed in.
searchRequest | the search criteria to use |
---|---|
pageRequest | the request specifying the start and limit of the search |
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.
request | the repository, pull request and other properties describing the changes to stream |
---|---|
callback | the callback to receive changes |
NoSuchPullRequestException | if no pull request with the specified ID can be found in the repository |
---|
Streams commits for the specified pull request.
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 |
NoSuchPullRequestException | if no pull request with the specified ID can be found in the repository |
---|
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.
request | the repository, pull request, path and other properties describing the diff to stream |
---|---|
callback | the callback to receive the streamed Diff |
NoSuchPullRequestException | if no pull request with the specified ID can be found in the repository |
---|
Unassigns a participant from any explicit role they may have been given in a pull request.
An explicit role is one other than PARTICIPANT
.
Currently the only explicit role that may be unassigned is the REVIEWER
role
as the AUTHOR
role is fixed. An attempt to unassign a participant from this role
will result in an UnmodifiablePullRequestRoleException
being thrown.
If the participant has no explicit role this method has no effect.
Afterwards, the user will still remain a participant in the pull request but their role will be reduced to
PARTICIPANT
. This is because once made a participant of a pull request,
a user will forever remain a participant. Only their role may be altered.
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 |
NoSuchPullRequestException | if no pull request with the specified ID can be found in the repository |
---|---|
UnmodifiablePullRequestRoleException | if the participant is already an AUTHOR
|
Removes the current user as a watcher of the given pull request.
repositoryId | the ID of the repository to which the pull request will be merged |
---|---|
pullRequestId | the ID of the pull request within the repository |
Updates a pull request's title and description.
This method will fire:
PullRequestUpdatedEvent
to inform listeners that the title or description have changedPullRequestRolesUpdatedEvent
to inform listeners of any reviewers assigned or unassigned from this rolePullRequestParticipantsAddedEvent
to inform listeners of any users who have participated in the pull request for the first timePullRequestRescopedEvent
to inform listeners the the destination branch has been updated and rescope has occurredrequest | details for updating a pull request, including a title, description and reviewers. |
---|
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 |
Updates the pull request comment's text
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 |
CommentOutOfDateException | if the version of the specified comment does not match the expected version |
---|---|
NoSuchCommentException | if no comment exists with the specified ID |
Adds the current user as a watcher of the given pull request.
repositoryId | the ID of the repository to which the pull request will be merged |
---|---|
pullRequestId | the ID of the pull request within the repository |
NoSuchPullRequestException | if no pull request with the specified ID can be found in the repository |
---|
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.
repositoryId | the ID of the repository to which the pull request will be merged |
---|---|
pullRequestId | the ID of the pull request within the repository |
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 |