com.atlassian.bitbucket.content

Interface ContentService

public interface ContentService

A service for the management of files and their metadata.

Method Summary

Modifier and Type	Method and Description
Commit	editFile(EditFileRequest request) Adds a new file or updates the content of an existing file.
Page<Blame>	getBlame(Repository repository, String objectId, String path, PageRequest pageRequest) Returns Blame for the lines included by the provided PageRequest for the specified objectId+path in the specified repository.
long	getMaxUploadSize() Retrieves the maximum size, in bytes, for uploading content.
ContentTreeNode.Type	getType(Repository repository, String objectId, String path)
void	streamArchive(ArchiveRequest request, TypeAwareOutputSupplier outputSupplier) Streams an archive of the specified repository at the specified commit, optionally filtering by path.
void	streamDirectory(Repository repository, String objectId, String path, boolean recursive, ContentTreeCallback callback, PageRequest pageRequest) Performs a directory listing for the specified objectId+path from the specified repository, streaming the results to the provided callback.
void	streamFile(Repository repository, String objectId, String path, PageRequest pageRequest, boolean withBlame, FileContentCallback fileContentCallback)
void	streamFile(Repository repository, String objectId, String path, TypeAwareOutputSupplier supplier) Streams the raw content of the file into an OutputStream obtained from the given TypeAwareOutputSupplier.
void	streamPatch(PatchRequest request, TypeAwareOutputSupplier outputSupplier) Streams a patch for a given commit or commit range.

Method Detail

editFile

Commit editFile(@Nonnull
                EditFileRequest request)
         throws ServiceException

Adds a new file or updates the content of an existing file.

Parameters:

request - details for adding/updating a file

Returns:

the commit containing the file edit

Throws:

EditFileFailedException - if the edit operation fails

FeatureUnsupportedScmException - if the SCM for the specified repository does not support editing files

FileAlreadyExistsException - if a file or path exists at the given path on the tip of the branch and no source commit was given

FileContentUnmodifiedException - if the given content is identical to the content of the file at the tip of the given branch

RepositoryHookVetoedException - if one or more hooks canceled the file edit

FileOutOfDateException - if the given file has been changed since the source commit occurred

FileTranscodingException - if the input content could not be transcoded to the existing file's encoding

NoSuchBranchException - if the given branch does not exist in the repository

NoSuchPathException - if the file is not present in the source commit or at the tip of the given branch

ServiceException

Since:

4.13

getBlame

@Nonnull
Page<Blame> getBlame(@Nonnull
                              Repository repository,
                              @Nonnull
                              String objectId,
                              @Nonnull
                              String path,
                              @Nonnull
                              PageRequest pageRequest)

Returns Blame for the lines included by the provided PageRequest for the specified objectId+path in the specified repository.

The objectId provided here can be several things:

• A branch name
• A tag name
• A hash (which can identify a branch, a tag, or a specific commit, among other things)

Parameters:

repository - the repository to use

objectId - an identifier (name or hash) for the branch, tag or commit at which blame should be retrieved

path - the path for which blame should be retrieved

pageRequest - defines the set of lines within the file for which blame should be generated

Returns:

a list containing 0 or more Blame objects, ordered by the line at which they start in the file

Since:

5.0

getMaxUploadSize

long getMaxUploadSize()

Retrieves the maximum size, in bytes, for uploading content. Files larger than this will be rejected by the server.

Returns:

the maximum size, in bytes, for uploading content

Since:

4.13

getType

@Nonnull
ContentTreeNode.Type getType(@Nonnull
                                      Repository repository,
                                      @Nonnull
                                      String objectId,
                                      @Nullable
                                      String path)

streamArchive

void streamArchive(@Nonnull
                   ArchiveRequest request,
                   @Nonnull
                   TypeAwareOutputSupplier outputSupplier)

Streams an archive of the specified repository at the specified commit, optionally filtering by path. The content type for the requested archive format will be provided to the supplier when retrieving the output stream to which the archive will be written.

Parameters:

request - describes the commit to archive, the format to archive it in, and the repository to archive it from

outputSupplier - a supplier which, when given the archive content type, will provide an output stream

Since:

5.1

streamDirectory

void streamDirectory(@Nonnull
                     Repository repository,
                     @Nonnull
                     String objectId,
                     @Nullable
                     String path,
                     boolean recursive,
                     @Nonnull
                     ContentTreeCallback callback,
                     @Nonnull
                     PageRequest pageRequest)

Performs a directory listing for the specified objectId+path from the specified repository, streaming the results to the provided callback.

The objectId provided here can be several things:

• A branch name
• A tag name
• A hash (which can identify a branch, a tag, or a specific commit, among other things)

The listing is provided to the caller via a callback mechanism - the supplied ContentTreeCallback parameter. This method promises to call ContentTreeCallback.onStart(ContentTreeContext) on the supplied instance once followed by zero or more ContentTreeCallback.onTreeNode(ContentTreeNode) for each path in the directory and finally followed by a ContentTreeCallback.onEnd(ContentTreeSummary).

When recursive is false, file sizes will be populated and subdirectories below the specified path will be returned. For recursive listings, subdirectories and file sizes are omitted to improve performance.

Parameters:

repository - the repository to use

objectId - an identifier (name or hash) for the branch, tag or commit at which blame should be retrieved

path - the path for which blame should be retrieved

recursive - whether the directory listing should be recursive

callback - the callback instance to call as the page starts, the children nodes are encountered and as the page ends

pageRequest - defines the range of children in the listing the caller is interested in

streamFile

void streamFile(@Nonnull
                Repository repository,
                @Nonnull
                String objectId,
                @Nonnull
                String path,
                @Nonnull
                PageRequest pageRequest,
                boolean withBlame,
                @Nonnull
                FileContentCallback fileContentCallback)
         throws ServiceException

Parameters:

repository - the repository

objectId - the identifier for a point in the repository. Can be a commit ID, a branch or a tag

path - the path to the file

pageRequest - the page request for the start and limit of the page

withBlame - true to include blame information for content; otherwise, false to omit it

fileContentCallback - the callback for receiving lines and page information

Throws:

ServiceException - if the stream file operation fails

streamFile

void streamFile(@Nonnull
                Repository repository,
                @Nonnull
                String objectId,
                @Nonnull
                String path,
                @Nonnull
                TypeAwareOutputSupplier supplier)
         throws ServiceException

Streams the raw content of the file into an OutputStream obtained from the given TypeAwareOutputSupplier. The implementation might try to detect the mime-type of the file, and pass that information to the TypeAwareOutputSupplier. Note: this method is not paged.

Parameters:

repository - the repository to use

objectId - the identifier for a point in the repository. Can be a commit ID, branch or tag

path - the path to the file

supplier - an object that can return an OutputStream given a mime-type

Throws:

ServiceException - if the stream operation fails.

streamPatch

void streamPatch(@Nonnull
                 PatchRequest request,
                 @Nonnull
                 TypeAwareOutputSupplier outputSupplier)

Streams a patch for a given commit or commit range.

Parameters:

request - describes the commit and repository for which to generate the patch

outputSupplier - a supplier which will provide an output stream

Since:

6.7