public interface

PullRequestService

com.atlassian.stash.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 changesets 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 @Deprecated Comment addDiffComment(int repositoryId, long pullRequestId, String commentText, String path, String srcPath, int line, DiffSegmentType lineType)
This method is deprecated. in 2.11, for removal in 3.0. Use addDiffComment(int, long, AddDiffCommentRequest) instead
@Nonnull Comment addFileComment(int repositoryId, long pullRequestId, AddFileCommentRequest request)
Adds a file-level comment to the pull request.
@Nonnull Comment addFileComment(int repositoryId, long pullRequestId, String commentText, String path, String srcPath)
This method is deprecated. in 2.11, for removal in 3.0. Use addFileComment(int, long, AddFileCommentRequest) instead
@Nonnull Comment addReply(int repositoryId, long pullRequestId, long commentId, String commentText)
Adds a reply to a comment
@Nonnull PullRequestParticipant approve(int repositoryId, long pullRequestId)
Allows a user to give their approval to a pull request.
@Nonnull PullRequestParticipant assignRole(int repositoryId, long pullRequestId, String username, PullRequestRole role)
Assigns a participant to an explicit role in 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 countChangesetsFor(int repositoryId, long pullRequestId)
Counts the number of changesets a pull request has.
long countForParticipant(StashUser user, PullRequestRole role, Boolean approved, PullRequestState state)
Counts the number of pull requests where the specified user is a participant.
long countInDirection(PullRequestDirection direction, int repositoryId, PullRequestState state)
Counts the number of pull request to or from a given repository depending on the direction passed in.
@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(int repositoryId, long pullRequestId, int version)
Declines a pull request.
boolean deleteComment(int repositoryId, long pullRequestId, long commentId, int commentVersion)
Deletes a pull request comment
@Nonnull @Deprecated Page<PullRequest> find(PullRequestState state, PullRequestOrder order, PageRequest pageRequest)
This method is deprecated. in 2.9 for removal in 3.0, For consistency with other services, this method has been replaced by search(PullRequestSearchRequest, PageRequest)
@Nullable @Deprecated PullRequest findById(int repositoryId, long pullRequestId)
This method is deprecated. in 2.8 for removal in 3.0, For consistency with other services, this method has been replaced by getById(int, long)
@Nonnull Page<PullRequest> findByParticipant(StashUser user, PullRequestRole role, Boolean approved, PullRequestState state, PullRequestOrder order, PageRequest pageRequest)
Finds a single page of pull request in the specified state where the specified user is a participant.
@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 @Deprecated Page<PullRequest> findInDirection(PullRequestDirection direction, int repositoryId, String branchId, PullRequestState state, PullRequestOrder order, PageRequest pageRequest)
This method is deprecated. in 2.9 for removal in 3.0, For consistency with other services, this method has been replaced by search(PullRequestSearchRequest, PageRequest)
@Nonnull Page<? extends PullRequestActivity> getActivities(int repositoryId, long pullRequestId, PageRequest pageRequest)
Retrieves a page of the activities for a given pull request.
@Nonnull PullRequestActivityPage<? extends 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<Changeset> getChangesets(int repositoryId, long pullRequestId, PageRequest pageRequest)
Retrieves a page of the changesets for a given pull request.
@Nonnull Comment getComment(int repositoryId, long pullRequestId, long commentId)
Retrieves a comment for the given comment id and pull request id.
@Nonnull Page<? extends PullRequestParticipant> getParticipants(int repositoryId, long pullRequestId, PageRequest pageRequest)
Retrieves a page of the participants for a given pull request.
@Nonnull PullRequest merge(int repositoryId, long pullRequestId, int version)
Merges 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.
@Deprecated void streamChanges(int repositoryId, long pullRequestId, ChangeCallback callback)
This method is deprecated. in 2.11 for removal in 3.0, replaced by streamChanges(PullRequestChangesRequest, ChangeCallback)
void streamChanges(PullRequestChangesRequest request, ChangeCallback callback)
Streams changes for the specified PullRequest to the provided ChangeCallback.
void streamChangesets(int repositoryId, long pullRequestId, ChangesetCallback callback)
Retrieves a page of the changesets for a given 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 streamDiff(int repositoryId, long pullRequestId, String path, String srcPath, DiffContentCallback callback)
This method is deprecated. in 2.4 for removal in 3.0, replaced by streamDiff(PullRequestDiffRequest, DiffContentCallback)
void unassignRole(int repositoryId, long pullRequestId, String username)
Unassigns a participant from any explicit role they may have been given in a pull request.
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 @Deprecated PullRequest update(int repositoryId, long pullRequestId, int version, String title, String description, Set<String> reviewers)
This method is deprecated. in 2.5 for removal in 3.0, replaced by update(PullRequestUpdateRequest)
@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 PullRequestParticipant withdrawApproval(int repositoryId, long pullRequestId)
Allows the current user to withdraw their approval of a pull request.

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 @Deprecated public Comment addDiffComment (int repositoryId, long pullRequestId, String commentText, String path, String srcPath, int line, DiffSegmentType lineType)

This method is deprecated.
in 2.11, for removal in 3.0. Use addDiffComment(int, long, AddDiffCommentRequest) instead

Adds a 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
commentText the comment text
path the path of the file to comment on
srcPath the path the file to comment on used to have, for copies and moves
line the line in the diff
lineType the type of the diff segment
Returns
  • the created comment
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository

@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 addFileComment (int repositoryId, long pullRequestId, String commentText, String path, String srcPath)

This method is deprecated.
in 2.11, for removal in 3.0. Use addFileComment(int, long, AddFileCommentRequest) instead

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
commentText the comment text
path the path of the file to comment on
srcPath the path the file to comment on used to have, for copies and moves
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 approve (int repositoryId, long pullRequestId)

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.

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 public PullRequestParticipant assignRole (int repositoryId, long pullRequestId, String username, PullRequestRole role)

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.
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 countChangesetsFor (int repositoryId, long pullRequestId)

Counts the number of changesets 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 changesets for the pull request
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository

public long countForParticipant (StashUser user, PullRequestRole role, Boolean approved, PullRequestState state)

Counts the number of pull requests where the specified user is a participant. The search criteria can optionally be narrowed by specifying the state the pull request should be in.

Parameters
user the participant
role the optional participant role to narrow the search (defaults to all roles)
approved if role is REVIEWER, then this value determines if                     the pull requests should be narrowed by approval state. A null value means do not narrow.
state the optional state to narrow the search
Returns
  • the page of pull requests

public long countInDirection (PullRequestDirection direction, int repositoryId, PullRequestState state)

Counts the number of pull request to or from a given repository depending on the direction passed in. The search criteria can optionally be narrowed by specifying the state the pull request should be in.

An explanation of the directions:

  • INCOMING counts pull requests to the specified repository
  • OUTGOING counts pull requests from the specified repository

Parameters
direction indicates whether to match the provided repositoryId against pull requests' from or to refs
repositoryId the ID of the repository to count pull requests for
state used to limit the returned pull requests to only those which match the specified state
Returns
  • the count of matching pull requests

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

At present Stash only supports pull requests between branches of the same repository. Supplying two different repositories will result in an exception being thrown.

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
NoSuchChangesetException if the the from or to branches do not exist

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

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
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 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 @Deprecated public Page<PullRequest> find (PullRequestState state, PullRequestOrder order, PageRequest pageRequest)

This method is deprecated.
in 2.9 for removal in 3.0, For consistency with other services, this method has been replaced by search(PullRequestSearchRequest, PageRequest)

Finds a single page of pull request in the specified state or a page of all pull requests in any state if the state is null.

Parameters
state the optional state to narrow the search
order the optional order to return the search results in (defaults to NEWEST first).
pageRequest the request specifying the start and limit of the search
Returns
  • the page of pull requests

@Nullable @Deprecated public PullRequest findById (int repositoryId, long pullRequestId)

This method is deprecated.
in 2.8 for removal in 3.0, For consistency with other services, this method has been replaced by getById(int, long)

Finds 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<PullRequest> findByParticipant (StashUser user, PullRequestRole role, Boolean approved, PullRequestState state, PullRequestOrder order, PageRequest pageRequest)

Finds a single page of pull request in the specified state where the specified user is a participant.

Parameters
user the participant
role the optional participant role to narrow the search (defaults to all roles)
approved if role is REVIEWER, then this value determines if the pull requests should be narrowed by approval state. A null value means do not narrow.
state the optional state to narrow the search
order the optional order to return the search results in (defaults to NEWEST first)
pageRequest the request specifying the start and limit of the search
Returns
  • the page of pull requests

@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 @Deprecated public Page<PullRequest> findInDirection (PullRequestDirection direction, int repositoryId, String branchId, PullRequestState state, PullRequestOrder order, PageRequest pageRequest)

This method is deprecated.
in 2.9 for removal in 3.0, For consistency with other services, this method has been replaced by search(PullRequestSearchRequest, PageRequest)

Finds a single page of pull request to or from a given repository depending on the direction passed in. Results can be further narrowed by optionally specifying the branch of the repository and the state the pull request should be in.

The repositoryId and branchId are evaluated based on the direction being searched:

Parameters
direction the direction to look at when searching
repositoryId the ID of the repository
branchId the fully qualified pull request branch (e.g. "refs/heads/master").
state the desired pull request state (Optional)
order the order to return the search results in (defaults to newest to oldest) (Optional)
pageRequest the request specifying the start and limit of the search @return the page of pull requests
Returns
  • a page of pull requests

@Nonnull public Page<? extends 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 PullRequestActivityPage<? extends 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<Changeset> getChangesets (int repositoryId, long pullRequestId, PageRequest pageRequest)

Retrieves a page of the changesets 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 changesets
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository

@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 for the given id

@Nonnull public Page<? extends 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 (int repositoryId, long pullRequestId, int version)

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

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

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

@Deprecated public void streamChanges (int repositoryId, long pullRequestId, ChangeCallback callback)

This method is deprecated.
in 2.11 for removal in 3.0, replaced by streamChanges(PullRequestChangesRequest, ChangeCallback)

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
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 callback to receive changes
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository

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 streamChangesets (int repositoryId, long pullRequestId, ChangesetCallback callback)

Retrieves a page of the changesets 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
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 streamDiff (int repositoryId, long pullRequestId, String path, String srcPath, DiffContentCallback callback)

This method is deprecated.
in 2.4 for removal in 3.0, replaced by streamDiff(PullRequestDiffRequest, DiffContentCallback)

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
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 within the repository to the file to diff
srcPath the source path, required for copies and moves/renames and null for other types
callback the callback to receive the streamed Diff
Throws
NoSuchPullRequestException if no pull request with the specified ID can be found in the repository

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

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.

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 @Deprecated public PullRequest update (int repositoryId, long pullRequestId, int version, String title, String description, Set<String> reviewers)

This method is deprecated.
in 2.5 for removal in 3.0, replaced by update(PullRequestUpdateRequest)

Updates a pull request's title and description.

This method will fire:

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
title the new title of the pull request
description the new description of the pull request
reviewers the new set of reviewers of the pull request. Any current reviewer not in this set will be relegated to participant status. Any new reviewer not already a participant will start participating. Any existing reviewer in the set will be unaltered.
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

@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 public PullRequestParticipant withdrawApproval (int repositoryId, long pullRequestId)

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.

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