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.
@Deprecated @Nonnull List<Blame> getBlame(Repository repository, String objectId, String path, PageRequest pageRequest)
This method is deprecated. in 4.6 to note that the return type will change to Page<Blame> in 5.0.
long getMaxUploadSize()
Retrieves the maximum size, in bytes, for uploading content.
@Nonnull ContentTreeNode.Type getType(Repository repository, String objectId, String 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
FileEditCanceledException if one or more listeners for FileEditRequestedEvent 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

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

This method is deprecated.
in 4.6 to note that the return type will change to Page<Blame> in 5.0.

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)

This method has been deprecated because it doesn't return a normal Page response. That makes it impossible to efficiently determine whether there is another page of blame after the requested page; the only way to know is to request the next page and check the result.

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