Package com.cloudbees.jenkins.plugins.bitbucket.api

Interface BitbucketApi

All Known Implementing Classes:

BitbucketCloudApiClient, BitbucketServerAPIClient

public interface BitbucketApi

Provides access to a specific repository. One API object needs to be created for each repository you want to work with.

Method Summary

Modifier and Type	Method	Description
boolean	checkPathExists(String branchOrHash, String path)	Checks if the given path exists in the repository at the specified branch.
BitbucketBranch	getBranch(String branchName)	Returns a branch in the repository.
List<? extends BitbucketBranch>	getBranches()	Returns the branches in the repository.
String	getDefaultBranch()	Gets the default branch in the repository.
Iterable<jenkins.scm.api.SCMFile>	getDirectoryContent(BitbucketSCMFile parent)	Returns a list of all children file for the given folder.
InputStream	getFileContent(BitbucketSCMFile file)	Return an input stream for the given file.
String	getOwner()	Returns the owner name for the repository.
BitbucketPullRequest	getPullRequestById(Integer id)	Returns a specific pull request.
List<? extends BitbucketPullRequest>	getPullRequests()	Returns the pull requests in the repository.
List<? extends BitbucketRepository>	getRepositories()	Returns all the repositories for the current owner (even if it's a regular user or a team).
List<? extends BitbucketRepository>	getRepositories(UserRoleInRepository role)	Returns the repositories where the user has the given role.
BitbucketRepository	getRepository()	Returns the repository details.
String	getRepositoryName()	Returns the repository name.
String	getRepositoryUri(BitbucketRepositoryProtocol protocol, String cloneLink, String owner, String repository)	Returns the URI of the repository.
BitbucketBranch	getTag(String tagName)	Returns a tag in the repository.
List<? extends BitbucketBranch>	getTags()	Returns the tags in the repository.
BitbucketTeam	getTeam()	Returns the team of the current owner or null if the current owner is not a team.
AvatarCacheSource.AvatarImage	getTeamAvatar()	Returns the team Avatar of the current owner or null if the current owner is not a team.
List<? extends BitbucketWebHook>	getWebHooks()	Returns the webhooks defined in the repository.
boolean	isPrivate()	Returns true if and only if the repository is private.
void	postBuildStatus(BitbucketBuildStatus status)	Set the build status for the given commit hash.
void	postCommitComment(String hash, String comment)	Post a comment to a given commit hash.
void	registerCommitWebHook(BitbucketWebHook hook)	Register a webhook on the repository.
void	removeCommitWebHook(BitbucketWebHook hook)	Remove the webhook (ID field required) from the repository.
BitbucketCommit	resolveCommit(BitbucketPullRequest pull)	Resolve the head commit object of the pull request source repository branch.
BitbucketCommit	resolveCommit(String hash)	Resolve the commit object given its hash.
String	resolveSourceFullHash(BitbucketPullRequest pull)	Resolve the head commit hash of the pull request source repository branch.
void	updateCommitWebHook(BitbucketWebHook hook)	Update a webhook on the repository.

Method Detail

getOwner

@NonNull
String getOwner()

Returns the owner name for the repository.

Returns:

the repository owner name.

getRepositoryName

@CheckForNull
String getRepositoryName()

Returns the repository name.

Returns:

the repository name.

getRepositoryUri

@NonNull
String getRepositoryUri(@NonNull
                        BitbucketRepositoryProtocol protocol,
                        @CheckForNull
                        String cloneLink,
                        @NonNull
                        String owner,
                        @NonNull
                        String repository)

Returns the URI of the repository.

Parameters:

protocol - the protocol to access the repository with.

cloneLink - the actual clone link for the repository as sent by the server, or null if unknown.

owner - the owner

repository - the repository.

Returns:

the repository URI.

getPullRequests

@NonNull
List<? extends BitbucketPullRequest> getPullRequests()
                                              throws IOException,
                                                     InterruptedException

Returns the pull requests in the repository.

Returns:

the list of pull requests in the repository.

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

getPullRequestById

@NonNull
BitbucketPullRequest getPullRequestById(@NonNull
                                        Integer id)
                                 throws IOException,
                                        InterruptedException

Returns a specific pull request.

Parameters:

id - the pull request ID

Returns:

the pull request or null if the PR does not exist

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

getRepository

@NonNull
BitbucketRepository getRepository()
                           throws IOException,
                                  InterruptedException

Returns the repository details.

Returns:

the repository specified by getOwner()/getRepositoryName() (or null if repositoryName is not set)

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

postCommitComment

void postCommitComment(@NonNull
                       String hash,
                       @NonNull
                       String comment)
                throws IOException,
                       InterruptedException

Post a comment to a given commit hash.

Parameters:

hash - commit hash

comment - string to post as comment

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

checkPathExists

boolean checkPathExists(@NonNull
                        String branchOrHash,
                        @NonNull
                        String path)
                 throws IOException,
                        InterruptedException

Checks if the given path exists in the repository at the specified branch.

Parameters:

branchOrHash - the branch name or commit hash

path - the path to check for

Returns:

true if the path exists

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

getDefaultBranch

@CheckForNull
String getDefaultBranch()
                 throws IOException,
                        InterruptedException

Gets the default branch in the repository.

Returns:

the default branch in the repository or null if no default branch set

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

getBranch

@CheckForNull
BitbucketBranch getBranch(@NonNull
                          String branchName)
                   throws IOException,
                          InterruptedException

Returns a branch in the repository.

Returns:

a branch in the repository.

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

getBranches

@NonNull
List<? extends BitbucketBranch> getBranches()
                                     throws IOException,
                                            InterruptedException

Returns the branches in the repository.

Returns:

the list of branches in the repository.

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

getTag

@CheckForNull
BitbucketBranch getTag(@NonNull
                       String tagName)
                throws IOException,
                       InterruptedException

Returns a tag in the repository.

Returns:

a tag in the repository.

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

getTags

@NonNull
List<? extends BitbucketBranch> getTags()
                                 throws IOException,
                                        InterruptedException

Returns the tags in the repository.

Returns:

the list of tags in the repository.

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

resolveCommit

@CheckForNull
BitbucketCommit resolveCommit(@NonNull
                              String hash)
                       throws IOException,
                              InterruptedException

Resolve the commit object given its hash.

Parameters:

hash - the hash to resolve

Returns:

the commit object or null if the hash does not exist

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

resolveCommit

@NonNull
BitbucketCommit resolveCommit(@NonNull
                              BitbucketPullRequest pull)
                       throws IOException,
                              InterruptedException

Resolve the head commit object of the pull request source repository branch.

Parameters:

pull - the pull request to resolve the source hash from

Returns:

the source head commit object

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

Since:

2.2.14

resolveSourceFullHash

@NonNull
String resolveSourceFullHash(@NonNull
                             BitbucketPullRequest pull)
                      throws IOException,
                             InterruptedException

Resolve the head commit hash of the pull request source repository branch.

Parameters:

pull - the pull request to resolve the source hash from

Returns:

the source head hash

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

registerCommitWebHook

void registerCommitWebHook(@NonNull
                           BitbucketWebHook hook)
                    throws IOException,
                           InterruptedException

Register a webhook on the repository.

Parameters:

hook - the webhook object

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

updateCommitWebHook

void updateCommitWebHook(@NonNull
                         BitbucketWebHook hook)
                  throws IOException,
                         InterruptedException

Update a webhook on the repository.

Parameters:

hook - the webhook object

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

removeCommitWebHook

void removeCommitWebHook(@NonNull
                         BitbucketWebHook hook)
                  throws IOException,
                         InterruptedException

Remove the webhook (ID field required) from the repository.

Parameters:

hook - the webhook object

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

getWebHooks

@NonNull
List<? extends BitbucketWebHook> getWebHooks()
                                      throws IOException,
                                             InterruptedException

Returns the webhooks defined in the repository.

Returns:

the list of webhooks registered in the repository.

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

getTeam

@CheckForNull
BitbucketTeam getTeam()
               throws IOException,
                      InterruptedException

Returns the team of the current owner or null if the current owner is not a team.

Returns:

the team profile of the current owner, or null if getOwner() is not a team ID.

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

getTeamAvatar

@CheckForNull
AvatarCacheSource.AvatarImage getTeamAvatar()
                                     throws IOException,
                                            InterruptedException

Returns the team Avatar of the current owner or null if the current owner is not a team.

Returns:

the team profile of the current owner, or null if getOwner() is not a team ID.

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

getRepositories

@NonNull
List<? extends BitbucketRepository> getRepositories(@CheckForNull
                                                    UserRoleInRepository role)
                                             throws IOException,
                                                    InterruptedException

Returns the repositories where the user has the given role.

Parameters:

role - Filter repositories by the owner having this role in. See UserRoleInRepository for more information. Use role = null if the repoOwner is a team ID.

Returns:

the repositories list (it can be empty)

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

getRepositories

@NonNull
List<? extends BitbucketRepository> getRepositories()
                                             throws IOException,
                                                    InterruptedException

Returns all the repositories for the current owner (even if it's a regular user or a team).

Returns:

all repositories for the current getOwner()

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

postBuildStatus

void postBuildStatus(@NonNull
                     BitbucketBuildStatus status)
              throws IOException,
                     InterruptedException

Set the build status for the given commit hash.

Parameters:

status - the status object to be serialized

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

isPrivate

boolean isPrivate()
           throws IOException,
                  InterruptedException

Returns true if and only if the repository is private.

Returns:

true if the repository (getOwner()/getRepositoryName()) is private.

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

getDirectoryContent

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
Iterable<jenkins.scm.api.SCMFile> getDirectoryContent(BitbucketSCMFile parent)
                                               throws IOException,
                                                      InterruptedException

Returns a list of all children file for the given folder.

Parameters:

parent - to list

Returns:

an iterable of SCMFile children of the given folder.

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.

getFileContent

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
InputStream getFileContent(BitbucketSCMFile file)
                    throws IOException,
                           InterruptedException

Return an input stream for the given file.

Parameters:

file - and instance of SCM file

Returns:

the stream of the given SCMFile

Throws:

IOException - if there was a network communications error.

InterruptedException - if interrupted while waiting on remote communications.