com.atlassian.bitbucket.repository

Interface RefService

public interface RefService

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

Method Summary

Modifier and Type	Method and Description
Branch	createBranch(CreateBranchRequest request) Create branch with the information provided in the request.
Tag	createTag(CreateTagRequest request) Create tag with the information provided in the request.
Page<Branch>	getBranches(RepositoryBranchesRequest request, PageRequest pageRequest) Retrieves a paged list of branches for the specified repository, optionally filtered by the provided starting text.
Branch	getDefaultBranch(Repository repository) Retrieves the default branch for the specified repository.
Map<Ref,MetadataMap>	getMetadataByRefs(RefMetadataRequest request) Retrieves the associated metadata based on a given collection of refs in a repository.
Page<Tag>	getTags(RepositoryTagsRequest request, PageRequest pageRequest) Retrieves a paged list of tags for the specified repository, optionally filtered by the provided starting text.
Ref	resolveRef(ResolveRefRequest request) Attempts to resolve a Ref from the provided refId.
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.

Method Detail

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

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

See Also:

RepositoryService.getDefaultBranch(Repository)

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