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 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(Repository repository, String objectId)
Attempts to resolve a Ref from the provided objectId.
void setDefaultBranch(Repository repository, String branchName)
Sets the default branch for the specified repository.

Public Methods

@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

@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 (Repository repository, String objectId)

Attempts to resolve a Ref from the provided objectId. Specifically, the object is resolved as either a Branch or Tag. If the provided objectId references something else, such as a commit hash, tree or blob, null is returned.

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
repository the repository to resolve the objectId in
objectId the object within the repository to resolve
Returns
  • a Branch or a Tag or null to indicate "something else"

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