Package com.atlassian.bitbucket.repository

Interface RefService

public interface RefService
A service for interacting with a repository's refs, such as branches and tags.

  • Method Details

    • createBranch

      @Nonnull Branch createBranch(@Nonnull CreateBranchRequest request)
      Create branch with the information provided in the request.
      Parameters:
      request - the branch creation request
      Returns:
      the created branch
      Throws:
      RepositoryHookVetoedException - if branch creation was canceled by one or more repository-hooks

    • createTag

      @Nonnull Tag createTag(@Nonnull CreateTagRequest request)
      Create tag with the information provided in the request.
      Parameters:
      request - the tag creation request
      Returns:
      the created tag
      Throws:
      RepositoryHookVetoedException - if tag creation was canceled by one or more repository-hooks

    • getBranches

      @Nonnull Page<Branch> getBranches(@Nonnull RepositoryBranchesRequest request, @Nonnull PageRequest pageRequest)
      Retrieves a paged list of branches for the specified repository, optionally filtered by the provided starting text.
      Parameters:
      request - request parameters for this query, including repository, filter text and ordering
      pageRequest - the page request defining the page start and limit
      Returns:
      a page containing 0 or more branches

    • getDefaultBranch

      @Nonnull Branch getDefaultBranch(@Nonnull Repository repository) throws NoDefaultBranchException, RepositoryInconsistentException, RepositoryOfflineException
      Retrieves the default branch for the specified repository.

      If the repository is newly created and no commits have been pushed to it, its default branch will not yet exist. As a result, for new repositories, this method can throw NoDefaultBranchException. If you want to know what the configured default branch is, regardless of whether the ref actually exists, use RepositoryService.getDefaultBranch(Repository) instead.

      Parameters:
      repository - the repository to retrieve the default branch for
      Returns:
      the default branch
      Throws:
      NoDefaultBranchException - when no default branch is configured for the repository
      RepositoryInconsistentException - when the repository is inconsistent
      RepositoryOfflineException - when the repository is offline
      See Also:

    • getMetadataByRefs

      @Nonnull Map<Ref,MetadataMap> getMetadataByRefs(@Nonnull RefMetadataRequest request)
      Retrieves the associated metadata based on a given collection of refs in a repository.
      Parameters:
      request - request parameters for this query, including repository and refs to find metadata for
      Returns:
      a containing the associated metadata keyed by Ref

    • getTags

      @Nonnull Page<Tag> getTags(@Nonnull RepositoryTagsRequest request, @Nonnull PageRequest pageRequest)
      Retrieves a paged list of tags for the specified repository, optionally filtered by the provided starting text.
      Parameters:
      request - request parameters for this query, including repository, filter text and ordering
      pageRequest - the page request defining the page start and limit
      Returns:
      a page containing 0 or more tags

    • resolveRef

      @Nullable Ref resolveRef(@Nonnull ResolveRefRequest request)
      Attempts to resolve a Ref from the provided refId. Specifically, the object is resolved as either a Branch or Tag. If the provided refId references something else, such as a commit hash, tree or blob, null is returned.

      If the ID is expected to match a ref of a specific type, the request may be explicitly limited to that type.

      The exact behavior of this method may vary between SCMs. For example, when provided with a commit hash, the SCM implementor may choose to return a Branch or Tag which references that commit, instead of returning null.

      Parameters:
      request - describes the ID to resolve, and the repository to resolve it in
      Returns:
      a Branch or a Tag or null to indicate "something else"
      Since:
      4.6

    • resolveRefs

      @Nonnull Map<String,Ref> resolveRefs(@Nonnull ResolveRefsRequest request)
      Attempts to resolve multiple refs at once, returning a map with the successfully resolved IDs linked to their resolved refs.

      If an ID is expected to match a branch or tag, it should be included in the relevant set. IDs for which the type is not known in advance should be included in the generic ref set.

      The exact behavior of this method may vary between SCMs. For example, when provided with a commit hash, the SCM implementor may choose to resolve it to a Branch or Tag which references that commit, or they may choose to always omit it from the returned map.

      Parameters:
      request - describes the branch, tag and unspecified ref IDs to resolve, and the repository to resolve them in
      Returns:
      a map containing the successfully resolved IDs, which may be empty but never null
      Since:
      4.6

    • setDefaultBranch

      void setDefaultBranch(@Nonnull Repository repository, @Nonnull String branchName)
      Sets the default branch for the specified repository. Support for this operation is SCM-specific, and different SCMs may apply different rules to what values are supported.
      Parameters:
      repository - the repository to update the default branch for
      branchName - the branch to mark as the default within the repository
      Throws:
      FeatureUnsupportedScmException - if the SCM for the specified repository does not support updating the default branch

    • streamBranches

      void streamBranches(@Nonnull RepositoryBranchesRequest request, @Nonnull BranchCallback callback)
      Streams branches to a callback class, for the specified repository, and where the branches match the request.
      Parameters:
      request - request parameters for this query, including repository, filter text and ordering
      callback - a callback to receive the branches
      Since:
      5.1

    • streamTags

      void streamTags(@Nonnull RepositoryTagsRequest request, @Nonnull TagCallback callback)
      Streams tags to a callback class, for the specified repository, and where the tags match the request.
      Parameters:
      request - request parameters for this query, including repository, filter text and ordering
      callback - a callback to receive the tags