Package com.atlassian.bitbucket.content

Interface ContentService

public interface ContentService
A service for the management of files and their metadata.

  • Method Details

    • 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
      RepositoryArchivedException - if repository is archived
      ForbiddenException - if the author or committer is forbidden to make the commit
      ArgumentValidationException - if there are any validation errors in the request
      ServiceException
      Since:
      4.13

    • getBlame

      @Nonnull Page<Blame> getBlame(@Nonnull Repository repository, @Nonnull String commitId, @Nonnull String path, @Nonnull PageRequest pageRequest)
      Calculates Blame for the lines included by the provided PageRequest for the specified path starting from the provided commit.

      A commit ID can be provided in several forms:

      • 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
      commitId - the commit from which the blame traversal should start (which can also be specified as a ref ID)
      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

    • getSize

      @Nonnull OptionalLong getSize(@Nonnull Repository repository, @Nonnull String commitId, @Nonnull String path)
      Retrieves the size of the specified file. If the provided path identifies an empty file the returned size will be of(0L), not empty(); empty() indicates the provided path identifies a directory or submodule, not a file, and therefore has no size.
      Parameters:
      repository - the repository to use
      commitId - the commit ID to retrieve the file size at (which can also be specified as a ref ID)
      path - the path to the file to retrieve the size for
      Returns:
      the file's size, which may be of(0L) if the file is empty or empty() if the path is a directory or submodule
      Throws:
      NoSuchCommitException - if the specified commit does not exist in the repository
      NoSuchPathException - if the specified path does not exist in the commit
      Since:
      7.7

    • getType

      @Nonnull ContentTreeNode.Type getType(@Nonnull Repository repository, @Nonnull String commitId, @Nullable String path)
      Retrieves the type of object at the specified path. This can be used to determine whether a given path identifies a directory, file or submodule.
      Parameters:
      repository - the repository to use
      commitId - the commit ID to retrieve the object type at (which can also be specified as a ref ID)
      path - the path to retrieve the type for
      Returns:
      the path's type, indicating whether it's a directory, file or submodule
      Throws:
      NoSuchCommitException - if the specified commit does not exist in the repository
      NoSuchPathException - if the specified path does not exist in the commit

    • 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