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

Interface BitbucketApi

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
BitbucketCloudApiClient, BitbucketServerAPIClient
public interface BitbucketApi extends AutoCloseable
Provides access to a specific repository. One API object needs to be created for each repository you want to work with.

  • Method Details

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

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

    • getRepository

      @NonNull BitbucketRepository getRepository() throws IOException
      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.

    • postCommitComment

      void postCommitComment(@NonNull String hash, @NonNull String comment) throws IOException
      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.

    • checkPathExists

      boolean checkPathExists(@NonNull String branchOrHash, @NonNull String path) throws IOException
      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.

    • getDefaultBranch

      @CheckForNull String getDefaultBranch() throws IOException
      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.

    • getBranch

      @CheckForNull BitbucketBranch getBranch(@NonNull String branchName) throws IOException
      Returns a branch in the repository.
      Returns:
      a branch in the repository.
      Throws:
      IOException - if there was a network communications error.

    • 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
      Returns a tag in the repository.
      Returns:
      a tag in the repository.
      Throws:
      IOException - if there was a network communications error.

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

    • resolveCommit

      @NonNull BitbucketCommit resolveCommit(@NonNull BitbucketPullRequest pull) throws IOException
      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.
      Since:
      2.2.14

    • resolveSourceFullHash

      @NonNull String resolveSourceFullHash(@NonNull BitbucketPullRequest pull) throws IOException
      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.

    • registerCommitWebHook

      void registerCommitWebHook(@NonNull BitbucketWebHook hook) throws IOException
      Register a webhook on the repository.
      Parameters:
      hook - the webhook object
      Throws:
      IOException - if there was a network communications error.

    • updateCommitWebHook

      void updateCommitWebHook(@NonNull BitbucketWebHook hook) throws IOException
      Update a webhook on the repository.
      Parameters:
      hook - the webhook object
      Throws:
      IOException - if there was a network communications error.

    • removeCommitWebHook

      void removeCommitWebHook(@NonNull BitbucketWebHook hook) throws IOException
      Remove the webhook (ID field required) from the repository.
      Parameters:
      hook - the webhook object
      Throws:
      IOException - if there was a network communications error.

    • getWebHooks

      @NonNull List<? extends BitbucketWebHook> getWebHooks() throws IOException
      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.

    • getTeam

      @CheckForNull BitbucketTeam getTeam() throws IOException
      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.

    • getTeamAvatar

      @CheckForNull @Deprecated(since="935.0.0", forRemoval=true) jenkins.scm.impl.avatars.AvatarImage getTeamAvatar() throws IOException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use getAvatar(String) with the avatar url link gather from repository, project, workspace or user.
      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.

    • getAvatar

      @CheckForNull jenkins.scm.impl.avatars.AvatarImage getAvatar(@NonNull String url) throws IOException
      Returns an Avatar image from the given URL.

      The URL link could come from repository, project, workspace or user links.

      Returns:
      the resource image.
      Throws:
      IOException - if there was a network communications error.

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

    • isPrivate

      boolean isPrivate() throws IOException
      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.

    • getDirectoryContent

      @NonNull @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
      Return an input stream for the given file.
      Parameters:
      file - an instance of SCM file
      Returns:
      the stream of the given SCMFile
      Throws:
      IOException - if there was a network communications error.

    • getFile

      @NonNull @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) jenkins.scm.api.SCMFile getFile(@NonNull BitbucketSCMFile file) throws IOException
      Return the metadata for the given file.
      Parameters:
      file - an instance of SCM file
      Returns:
      a SCMFile file with updated the metadata
      Throws:
      IOException - if there was a network communications error.

    • close

      void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Throws:
      IOException

    • getCommits

      @NonNull List<? extends BitbucketCommit> getCommits(@CheckForNull String from, @NonNull String to) throws IOException
      Return a set of base informations between the two given commits.
      Parameters:
      from - the commit or reference containing the changes we wish to preview or null to get changes since the beginning.
      to - the commit or reference representing the state to which we want to compare the first commit
      Returns:
      the list of commit between first commit and second source commit.
      Throws:
      IOException - if there was a network communications error.