public interface

RefService

com.atlassian.bitbucket.repository.RefService

Class Overview

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

Summary

Public Methods
@Nonnull Branch createBranch(CreateBranchRequest request)
Create branch with the information provided in the request.
@Nonnull Tag createTag(CreateTagRequest request)
Create tag with the information provided in the request.
@Nonnull Page<Branch> getBranches(RepositoryBranchesRequest request, PageRequest pageRequest)
Retrieves a paged list of branches for the specified repository, optionally filtered by the provided starting text.
@Nonnull Branch getDefaultBranch(Repository repository)
Retrieves the default branch for the specified repository.
@Nonnull Map<Ref, MetadataMap> getMetadataByRefs(RefMetadataRequest request)
Retrieves the associated metadata based on a given collection of refs in a repository.
@Nonnull Page<Tag> getTags(RepositoryTagsRequest request, PageRequest pageRequest)
Retrieves a paged list of tags for the specified repository, optionally filtered by the provided starting text.
@Nullable Ref resolveRef(ResolveRefRequest request)
Attempts to resolve a Ref from the provided refId.
@Nonnull Map<String, Ref> resolveRefs(ResolveRefsRequest request)
Attempts to resolve multiple refs at once, returning a map with the successfully resolved IDs linked to their resolved refs.
void setDefaultBranch(Repository repository, String branchName)
Sets the default branch for the specified repository.
void streamBranches(RepositoryBranchesRequest request, BranchCallback callback)
Streams branches to a callback class, for the specified repository, and where the branches match the request.
void streamTags(RepositoryTagsRequest request, TagCallback callback)
Streams tags to a callback class, for the specified repository, and where the tags match the request.

Public Methods

@Nonnull public Branch createBranch (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

@Nonnull public Tag createTag (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

@Nonnull public Page<Branch> getBranches (RepositoryBranchesRequest request, 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

@Nonnull public Branch getDefaultBranch (Repository repository)

Retrieves the default branch for the specified repository.

If the repository is newly created and no commits have been pushed to it, it will have no default branch. As a result, for new repositories, this method can throw NoDefaultBranchException.

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

@Nonnull public Map<Ref, MetadataMap> getMetadataByRefs (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

@Nonnull public Page<Tag> getTags (RepositoryTagsRequest request, 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

@Nullable public Ref resolveRef (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"

@Nonnull public Map<String, Ref> resolveRefs (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

public void setDefaultBranch (Repository repository, 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

public void streamBranches (RepositoryBranchesRequest request, 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

public void streamTags (RepositoryTagsRequest request, 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