com.atlassian.bitbucket.pull

Interface PullRequestService

All Superinterfaces:

PullRequestSupplier

public interface PullRequestService
extends PullRequestSupplier

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.

Method Summary

Modifier and Type	Method and Description
PullRequestParticipant	addReviewer(int repositoryId, long pullRequestId, String username) Adds the user specified by 'username' as REVIEWER to the provided PR.
boolean	canDelete(int repositoryId, long pullRequestId) Verifies if the current user can delete the specified pull request.
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	countByCommit(PullRequestCommitSearchRequest request) Counts the number of pull requests containing a specified commit which match the given search criteria.
long	countCommits(int repositoryId, long pullRequestId) Counts the number of commits a pull request has.
TaskCount	countTasks(PullRequestTaskSearchRequest searchRequest) Deprecated. in 7.0 for removal in 8.0. Tasks are now managed using comments with BLOCKER severity. App developers should use CommentService to create, retrieve and update BLOCKER comments.
PullRequest	create(PullRequestCreateRequest request) Creates a pull request from the supplied details.
PullRequest	decline(PullRequestDeclineRequest request) Declines a pull request.
void	delete(PullRequestDeleteRequest request) Deletes the specified pull request, removing all activities and comments.
void	deleteMergeConfig(DeletePullRequestMergeConfigRequest request) Deletes the merge configuration for the specified scope.
void	discardReview(PullRequestDiscardReviewRequest request) Discards the pull request review for the authenticated user.
int	finishReview(PullRequestFinishReviewRequest request) Finish a pull request review.
Page<PullRequestActivity>	getActivities(int repositoryId, long pullRequestId, PageRequest pageRequest) Retrieves a page of the activities for a given pull request.
Set<PullRequestActivity>	getActivitiesById(int repositoryId, long pullRequestId, Set<Long> activityIds) Retrieves the specified activities of the given pull request.
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.
PullRequest	getById(int repositoryId, long pullRequestId) Retrieves a pull request by its ID, within the specified repository.
Page<Commit>	getCommits(int repositoryId, long pullRequestId, PageRequest pageRequest) Deprecated. in 6.0 for removal in 8.0. Use getCommits(PullRequestCommitsRequest, PageRequest) instead
Page<Commit>	getCommits(PullRequestCommitsRequest request, PageRequest pageRequest) Retrieves a page of the commits for a given pull request.
PullRequestMergeConfig	getMergeConfig(GetPullRequestMergeConfigRequest request) Retrieves the merge configuration for the specified source.
Page<PullRequestParticipant>	getParticipants(int repositoryId, long pullRequestId, PageRequest pageRequest) Retrieves a page of the participants for a given pull request.
Page<CommentThread>	getReviewThreads(int repositoryId, long pullRequestId, PageRequest pageRequest) Get all the threads which have a comment and the state is pending for the currently authenticated user.
PullRequest	merge(PullRequestMergeRequest request) Merges a pull request.
void	removeReviewer(int repositoryId, long pullRequestId, String username) Removes a REVIEWER from a pull request.
PullRequest	reopen(int repositoryId, long pullRequestId, int version) Reopens a pull request.
Page<PullRequest>	search(PullRequestSearchRequest request, PageRequest pageRequest) Finds a single page of pull requests depending on the request passed in.
Page<PullRequestActivity>	searchActivities(PullRequestActivitySearchRequest request, PageRequest pageRequest) Finds a single page of pull request activities depending on the request passed in.
Page<PullRequest>	searchByCommit(PullRequestCommitSearchRequest request, PageRequest pageRequest) Finds a single page of pull requests containing a specified commit which match the given search criteria.
Page<Task>	searchTasks(PullRequestTaskSearchRequest searchRequest, PageRequest pageRequest) Deprecated. in 7.0 for removal in 8.0. Tasks are now managed using comments with BLOCKER severity. App developers should use CommentService to create, retrieve and update BLOCKER comments.
Page<ApplicationUser>	searchUsers(PullRequestParticipantSearchRequest searchRequest, PageRequest pageRequest) Finds users who have participated in pull requests based on the provided search request.
void	setMergeConfig(SetPullRequestMergeConfigRequest request) Sets the merge configuration for the specified source, setting the default strategy and the complete set of enabled strategies.
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) Deprecated. in 6.0 for removal in 8.0. Use streamCommits(PullRequestCommitsRequest, CommitCallback) instead
void	streamCommits(PullRequestCommitsRequest request, 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.
void	streamDiff(PullRequestDiffRequest request, TypeAwareOutputSupplier outputSupplier) Streams a raw diff for a given PullRequest.
PullRequest	update(PullRequestUpdateRequest request) Updates a pull request's title, description, and participants.

Method Detail

addReviewer

@Nonnull
PullRequestParticipant addReviewer(int repositoryId,
                                            long pullRequestId,
                                            @Nonnull
                                            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

Since:

4.2

canDelete

boolean canDelete(int repositoryId,
                  long pullRequestId)

Verifies if the current user can delete 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

Returns:

true if the current user has sufficient permissions to delete(PullRequestDeleteRequest) delete} the provided pull request, otherwise false. Note that the required permissions may vary depending on the role of the user in the pull request.

Since:

5.1

canMerge

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 PullRequestState.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 RepositoryMergeChecks may have raised

Throws:

IllegalPullRequestStateException - if the pull request is not open

countCommits

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

count

long count(@Nonnull
           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

countByCommit

long countByCommit(@Nonnull
                   PullRequestCommitSearchRequest request)

Counts the number of pull requests containing a specified commit which match the given search criteria. Similar to count(PullRequestSearchRequest), if the request doesn't limit the search to a repository that the user has access to, the count may include pull requests the user can't see.

Parameters:

request - the search request to use

Returns:

the number of pull requests that match the search request

Since:

5.11

countTasks

@Deprecated
 @Nonnull
TaskCount countTasks(@Nonnull
                                           PullRequestTaskSearchRequest searchRequest)

Deprecated. in 7.0 for removal in 8.0. Tasks are now managed using comments with BLOCKER severity. App developers should use CommentService to create, retrieve and update BLOCKER comments.

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

create

@Nonnull
PullRequest create(@Nonnull
                            PullRequestCreateRequest request)

Creates a pull request from the supplied details.

Events raised:

• PullRequestOpenRequestedEvent
• PullRequestOpenedEvent

Parameters:

request - the details for the new pull request

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

decline

@Nonnull
PullRequest decline(@Nonnull
                             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

delete

void delete(@Nonnull
            PullRequestDeleteRequest request)

Deletes the specified pull request, removing all activities and comments.

The from and to refs are not deleted with the pull request, to prevent accidental data loss. However, other SCM-specific data such as cached merges or special refs to provide access to pull request state will be deleted along with the pull request.

Parameters:

request - details for deleting a pull request

Throws:

AuthorisationException - if the current user does not have permission to delete the pull request

NoSuchPullRequestException - if no pull request with the specified ID can be found in the repository

PullRequestDeletionDisabledException - if deletion has been disabled

Since:

5.1

See Also:

canDelete(int, long)

deleteMergeConfig

void deleteMergeConfig(@Nonnull
                       DeletePullRequestMergeConfigRequest request)

Deletes the merge configuration for the specified scope.

Repositories inherit their merge configuration from the nearest configured scope. For example, deleting a repository's merge config may cause it to inherit project or global configuration rather than reverting to the SCM's defaults.

Parameters:

request - describes which merge configuration is to be deleted

Since:

5.2

See Also:

setMergeConfig(SetPullRequestMergeConfigRequest)

discardReview

void discardReview(@Nonnull
                   PullRequestDiscardReviewRequest request)

Discards the pull request review for the authenticated user.

Parameters:

request - describes the pull request discard review request

Since:

7.7

finishReview

int finishReview(@Nonnull
                 PullRequestFinishReviewRequest request)

Finish a pull request review.

The operations that will be performed when finishing a review on a pull request are:

1. Publish any pending comments. Comments will change state from PENDING to OPEN.
2. Add the currently authenticated user as a reviewer, and if a participant status is provided update their status.
3. Add a general comment to the pull request if there is comment text in the request.

Parameters:

request - the request which contains the pull request, comment text and participant status to set on the pull request

Returns:

the number of pending comments that got published

Since:

7.7

getActivities

@Nonnull
Page<PullRequestActivity> getActivities(int repositoryId,
                                                 long pullRequestId,
                                                 @Nonnull
                                                 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

getActivitiesStartingAt

@Nonnull
PullRequestActivityPage<PullRequestActivity> getActivitiesStartingAt(int repositoryId,
                                                                              long pullRequestId,
                                                                              @Nonnull
                                                                              PullRequestEntityType fromType,
                                                                              long fromId,
                                                                              @Nonnull
                                                                              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:

• PullRequestEntityType.ACTIVITY to search for the page of activities starting with the supplied activity
• PullRequestEntityType.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.

getActivitiesById

@Nonnull
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.

getById

@Nullable
PullRequest getById(int repositoryId,
                              long pullRequestId)

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

Specified by:

getById in interface PullRequestSupplier

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

getCommits

@Nonnull
Page<Commit> getCommits(@Nonnull
                                 PullRequestCommitsRequest request,
                                 @Nonnull
                                 PageRequest pageRequest)

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

Parameters:

request - the repository, pull request and other properties describing the commits to return

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

Since:

6.0

getCommits

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

Deprecated. in 6.0 for removal in 8.0. Use getCommits(PullRequestCommitsRequest, PageRequest) instead

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

getMergeConfig

@Nonnull
PullRequestMergeConfig getMergeConfig(@Nonnull
                                               GetPullRequestMergeConfigRequest request)

Retrieves the merge configuration for the specified source. All of the supported merge strategies are returned, but only enabled strategies can be specified when merging pull requests. At least one strategy, the default, is guaranteed to be enabled.

For cross-repository pull requests, the configuration for the target repository controls how the pull request can be merged.

Merge configuration can be applied at 3 different levels, listed from most specific to most generic:

1. Repository
2. Project and SCM
   • The SCM must also be considered because projects can contain multiple repositories which may not always use the same SCM
3. PullRequestMergeConfigType.SCM

If merge configuration has not been applied at any level, defaults for the appropriate SCM are returned.

SCMs are not required to support merge strategies. Plugins should check support for the MERGE_STRATEGIES feature prior to calling this method. If the SCM does not support merge strategies, an exception will be thrown.

Parameters:

request - a request describing the repository, project-and-SCM or SCM to retrieve configuration for

Returns:

merge configuration for pull requests to the specified repository, repositories within the specified project, or repositories of the specified SCM

Throws:

AuthorisationException - if the requesting user does not have access to the source they're retrieving merge configuration for

FeatureUnsupportedScmException - if the SCM does not support merge strategies

Since:

4.9

getParticipants

@Nonnull
Page<PullRequestParticipant> getParticipants(int repositoryId,
                                                      long pullRequestId,
                                                      @Nonnull
                                                      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

getReviewThreads

@Nonnull
Page<CommentThread> getReviewThreads(int repositoryId,
                                              long pullRequestId,
                                              @Nonnull
                                              PageRequest pageRequest)

Get all the threads which have a comment and the state is pending for the currently authenticated user.

Parameters:

repositoryId - the ID of the repository

pullRequestId - the ID of the pull request

pageRequest - the page request

Returns:

the page of threads

Since:

7.7

merge

@Nonnull
PullRequest merge(@Nonnull
                           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

PullRequestMergeVetoedException - if the merge was canceled by an event listener or hook

PullRequestOutOfDateException - if the version of the specified pull request does not match the expected version

removeReviewer

void removeReviewer(int repositoryId,
                    long pullRequestId,
                    @Nonnull
                    String username)

Removes a REVIEWER from a pull request.

If the user is the AUTHOR of the pull request this method will throw IllegalPullRequestStateException; the author may not be removed.

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 instead.

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

Since:

4.2

reopen

@Nonnull
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:

DuplicatePullRequestException - if a pull request with the same source and target refs already exists

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

search

@Nonnull
Page<PullRequest> search(@Nonnull
                                  PullRequestSearchRequest request,
                                  @Nonnull
                                  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 PullRequestSearchRequest.getParticipants() is empty or contains more than one participant (since 4.4)

searchActivities

@Nonnull
Page<PullRequestActivity> searchActivities(@Nonnull
                                                    PullRequestActivitySearchRequest request,
                                                    @Nonnull
                                                    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

searchByCommit

@Nonnull
Page<PullRequest> searchByCommit(@Nonnull
                                          PullRequestCommitSearchRequest request,
                                          @Nonnull
                                          PageRequest pageRequest)

Finds a single page of pull requests containing a specified commit which match the given search criteria.

Parameters:

request - the search request to use

pageRequest - the request specifying the start and limit of the search

Returns:

a page of pull requests

Since:

5.11

searchTasks

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

Deprecated. in 7.0 for removal in 8.0. Tasks are now managed using comments with BLOCKER severity. App developers should use CommentService to create, retrieve and update BLOCKER comments.

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

searchUsers

@Nonnull
Page<ApplicationUser> searchUsers(@Nonnull
                                           PullRequestParticipantSearchRequest searchRequest,
                                           @Nonnull
                                           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

Since:

4.2

setMergeConfig

void setMergeConfig(@Nonnull
                    SetPullRequestMergeConfigRequest request)

Sets the merge configuration for the specified source, setting the default strategy and the complete set of enabled strategies. Any enabled strategy may be requested when merging a pull request, and the specified default must be enabled. The enabled strategies are verified against the SCM to ensure they are all supported.

For cross-repository pull requests, the configuration for the target repository controls how the pull request can be merged.

Merge configuration can be applied at 3 different levels, listed from most specific to most generic, and can only be updated by administrators:

1. Repository
   • Requires REPO_ADMIN permission
2. Project and SCM
   • The SCM must also be considered because projects can contain multiple repositories which may not always use the same SCM
   • Requires PROJECT_ADMIN permission
3. PullRequestMergeConfigType.SCM
   • Requires global ADMIN permission

SCMs are not required to support merge strategies. Plugins should check support for the MERGE_STRATEGIES feature prior to calling this method. If the SCM does not support merge strategies, an exception will be thrown.

Parameters:

request - a request describing the repository, project-and-SCM or SCM to set configuration for, the default strategy to use and the set of strategies that should be enabled

Throws:

ArgumentValidationException - if the default merge strategy is not enabled, or if any of the enabled strategies are not supported by the associated SCM

AuthorisationException - if the updating user does not have the required administrator permission

FeatureUnsupportedScmException - if the SCM does not support merge strategies

Since:

4.9

setReviewerStatus

@Nonnull
PullRequestParticipant setReviewerStatus(int repositoryId,
                                                  long pullRequestId,
                                                  @Nonnull
                                                  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

Since:

4.2

streamChanges

void streamChanges(@Nonnull
                   PullRequestChangesRequest request,
                   @Nonnull
                   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

streamCommits

void streamCommits(@Nonnull
                   PullRequestCommitsRequest request,
                   @Nonnull
                   CommitCallback callback)

Streams commits for the specified pull request.

Parameters:

request - the repository, pull request and other properties describing the commits to stream

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

Since:

6.0

streamCommits

@Deprecated
void streamCommits(int repositoryId,
                               long pullRequestId,
                               @Nonnull
                               CommitCallback callback)

Deprecated. in 6.0 for removal in 8.0. Use streamCommits(PullRequestCommitsRequest, CommitCallback) instead

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

streamDiff

void streamDiff(@Nonnull
                PullRequestDiffRequest request,
                @Nonnull
                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

streamDiff

void streamDiff(@Nonnull
                PullRequestDiffRequest request,
                @Nonnull
                TypeAwareOutputSupplier outputSupplier)

Streams a raw diff for a given PullRequest.

Parameters:

request - the repository, pull request, path and other properties describing the diff to stream

outputSupplier - a supplier which will provide an output stream

Since:

6.7

update

@Nonnull
PullRequest update(@Nonnull
                            PullRequestUpdateRequest request)

Updates a pull request's title, description, and participants.

This method will fire:

• PullRequestUpdatedEvent to inform listeners that the title or description have changed
• PullRequestReviewersUpdatedEvent to inform listeners of any reviewers assigned or unassigned from this role
• PullRequestParticipantsAddedEvent to inform listeners of any users who have participated in the pull request for the first time
• PullRequestRescopedEvent to inform listeners the the destination branch has been updated and rescope has occurred

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

IllegalPullRequestStateException - if trying to update a merged pull request