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 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.
@Nonnull TaskCount countTasks(PullRequestTaskSearchRequest searchRequest)
Counts the number of tasks in a pull request.
@Nonnull PullRequest create(PullRequestCreateRequest request)
Creates a pull request from the supplied details.
@Nonnull 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.
@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 Page<Commit> getCommits(PullRequestCommitsRequest request, PageRequest pageRequest)
Retrieves a page of the commits for a given pull request.
@Deprecated @Nonnull Page<Commit> getCommits(int repositoryId, long pullRequestId, PageRequest pageRequest)
This method is deprecated. in 6.0 for removal in 7.0. Use getCommits(PullRequestCommitsRequest, PageRequest) instead
@Nonnull PullRequestMergeConfig getMergeConfig(GetPullRequestMergeConfigRequest request)
Retrieves the merge configuration for the specified source.
@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<PullRequest> searchByCommit(PullRequestCommitSearchRequest request, PageRequest pageRequest)
Finds a single page of pull requests containing a specified commit which match the given search criteria.
@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.
void setMergeConfig(SetPullRequestMergeConfigRequest request)
Sets the merge configuration for the specified source, setting the default strategy and the complete set of enabled strategies.
@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.
@Deprecated void streamCommits(int repositoryId, long pullRequestId, CommitCallback callback)
This method is deprecated. in 6.0 for removal in 7.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.
@Nonnull PullRequest update(PullRequestUpdateRequest request)
Updates a pull request's title, description, and participants.
[Expand]
Inherited Methods
From interface com.atlassian.bitbucket.pull.PullRequestSupplier

Public Methods

@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

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

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 RepositoryMergeChecks 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 countByCommit (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

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 (PullRequestCreateRequest request)

Creates a pull request from the supplied details.

Events raised:

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

@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 void delete (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

public void deleteMergeConfig (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

@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 Page<Commit> getCommits (PullRequestCommitsRequest request, 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

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

This method is deprecated.
in 6.0 for removal in 7.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

@Nonnull public PullRequestMergeConfig getMergeConfig (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. 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

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

public void removeReviewer (int repositoryId, long pullRequestId, 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

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

@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<PullRequest> searchByCommit (PullRequestCommitSearchRequest request, 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

@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

public void setMergeConfig (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
  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. SCM

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

@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

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

This method is deprecated.
in 6.0 for removal in 7.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

public void streamCommits (PullRequestCommitsRequest request, 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

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

@Nonnull public PullRequest update (PullRequestUpdateRequest request)

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

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
IllegalPullRequestStateException if trying to update a merged pull request