public interface

ContentService

com.atlassian.bitbucket.content.ContentService

Class Overview

A service for the management of files and their metadata.

Summary

Public Methods
Commit editFile(EditFileRequest request)
Adds a new file or updates the content of an existing file.
@Nonnull 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.
@Nonnull 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.

Public Methods

public Commit editFile (EditFileRequest request)

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

@Nonnull public 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.

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

public 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

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

public void streamArchive (ArchiveRequest request, 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

public 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.

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 onStart(ContentTreeContext) on the supplied instance once followed by zero or more onTreeNode(ContentTreeNode) for each path in the directory and finally followed by a 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

public void streamFile (Repository repository, String objectId, String path, PageRequest pageRequest, boolean withBlame, FileContentCallback fileContentCallback)

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

public 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. 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.