Package com.atlassian.bitbucket.filestore

Interface PluginFileStore

public interface PluginFileStore
A service provider interface (SPI) that allows plugins to provide their own implementation of a file store for Bitbucket Data Center to use.

This interface encapsulates access to a hierarchical file store. However, the model isn't a pure POSIX style filesystem. Instead, it should be thought of as a pseudo-hierarchical store. This is the case because there may be multiple implementations of the store, each with its own limitations and capabilities, so this aims to provide the basic set of operations on a model that can be implemented by all stores. Such stores may include a POSIX filesystem, or an object store such as AWS S3.

The store is namespaced, and every request has a namespace parameter. This allows many users of the store such that, assuming they all select different namespaces, they can't conflict with each other. The namespace is a string that includes the characters [a-zA-Z0-9_-].

Each request that operates on a file then includes a FilePath parameter that describes the path to the file. These paths should be separated by the forward slash character '/'.

The file store does not support directories in the traditional sense; there are directory operations (such as deleteRecursive(DeleteRecursiveRequest)), however this can also be thought of as simple being a request to "delete all files with a given prefix". For the same reason the filesystem doesn't model the concept of an empty directory. This decision has limited impact, but does mean a directory/file conflict is not possible if no files exist in a given directory. For example if a file "foo/bar" exists, then a file "foo" cannot exist. But there is no situation where "foo" exists as an empty directory preventing the creation of a file "foo/bar".

Since:
9.3

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    deleteFiles(com.atlassian.bitbucket.filestore.DeleteFilesRequest request)
    Delete files from the file store.
    long
    deleteRecursive(com.atlassian.bitbucket.filestore.DeleteRecursiveRequest request)
    Delete files from the file store recursively.
    boolean
    fileExists(com.atlassian.bitbucket.filestore.FileExistsRequest request)
    Check if a file exists in the file store.
    com.atlassian.bitbucket.filestore.GenerateGetUrlResponse
    generateGetUrl(com.atlassian.bitbucket.filestore.GenerateGetUrlRequest request)
    Get a URL to "GET" a file from the file store.
    com.atlassian.bitbucket.filestore.GeneratePutUrlResponse
    generatePutUrl(com.atlassian.bitbucket.filestore.GeneratePutUrlRequest request)
    Get a URL to "PUT" a file to the file store.
    Optional<Long>
    getFreeSpace()
    Returns the number of bytes of free space available in the file store.
    InputStream
    readFile(com.atlassian.bitbucket.filestore.ReadFileRequest request)
    Read a file from the file store.

  • Method Details

    • deleteFiles

      long deleteFiles(@Nonnull com.atlassian.bitbucket.filestore.DeleteFilesRequest request)
      Delete files from the file store.

      Implementation notes:

      • Implementations should throw FileStoreException if the operation fails
      • It is safe to assume the 'namespace' parameter is non-null and is not an empty string
      • If the underlying filesystem supports empty directories, whenever this method deletes all files in a directory, the directory should be delete. The API doesn't have the concept of an empty directory and by cleaning up it avoids file/directory name conflicts.
      Parameters:
      request - describes the files to delete
      Returns:
      the number of files deleted

    • deleteRecursive

      long deleteRecursive(@Nonnull com.atlassian.bitbucket.filestore.DeleteRecursiveRequest request)
      Delete files from the file store recursively.

      Implementation notes:

      • Implementations should throw FileStoreException if the operation fails
      • It is safe to assume the 'namespace' parameter is non-null and is not an empty string
      • If the underlying filesystem supports empty directories, whenever this method deletes all files in a directory, the directory should be delete. The API doesn't have the concept of an empty directory and by cleaning up it avoids file/directory name conflicts.
      Parameters:
      request - describes the directories to delete
      Returns:
      the number of files deleted

    • fileExists

      boolean fileExists(@Nonnull com.atlassian.bitbucket.filestore.FileExistsRequest request)
      Check if a file exists in the file store.

      Implementation notes:

      • Implementations should throw FileStoreException if the operation fails
      • It is safe to assume the 'namespace' parameter is non-null and is not an empty string
      • It is safe to assume the 'path' parameter is non-null and is not an empty string
      Parameters:
      request - describes the file to check exists
      Returns:
      true if the file exists, false otherwise

    • generateGetUrl

      @Nonnull com.atlassian.bitbucket.filestore.GenerateGetUrlResponse generateGetUrl(@Nonnull com.atlassian.bitbucket.filestore.GenerateGetUrlRequest request)
      Get a URL to "GET" a file from the file store.

      Implementation notes:

      • Implementations should throw FileStoreException if the operation fails
      • It is safe to assume the 'namespace' parameter is non-null and is not an empty string
      • It is safe to assume the 'path' parameter is non-null and is not an empty string
      Parameters:
      request - describes the file to get, and other optional parameters
      Returns:
      a URL to "GET" file from the file store

    • generatePutUrl

      @Nonnull com.atlassian.bitbucket.filestore.GeneratePutUrlResponse generatePutUrl(@Nonnull com.atlassian.bitbucket.filestore.GeneratePutUrlRequest request)
      Get a URL to "PUT" a file to the file store.

      Implementation notes:

      • Implementations should throw FileStoreException if the operation fails
      • It is safe to assume the 'namespace' parameter is non-null and is not an empty string
      • It is safe to assume the 'path' parameter is non-null and is not an empty string
      • The store should never store partial files; if during this call an exception wasn't thrown, the entire object was stored.
      • The file upload should be atomic; the file should not be visible via other API request until it is fully uploaded. It should never be visible but incomplete and if checksum validation is requested, until that has completed successfully).
      Parameters:
      request - describes the file to put, and other optional parameters
      Returns:
      a URL to "PUT" file to the file store

    • getFreeSpace

      @Nonnull Optional<Long> getFreeSpace()
      Returns the number of bytes of free space available in the file store.

      Implementers can assume that the typical usage of this method involves "proceeding at risk" if Optional.empty() is returned. That is, if a Long is returned then it is used to decide if a write operation should be attempted. However, if Optional.empty() is returned, the operation would always be attempted.

      Returns:
      the number of bytes of free space available in the file store. Or Optional.empty() if the file store implementation does not support the concept of free space (e.g. a cloud store).

    • readFile

      @Nonnull InputStream readFile(@Nonnull com.atlassian.bitbucket.filestore.ReadFileRequest request)
      Read a file from the file store.
      Parameters:
      request - describes the file to read, and other optional parameters
      Returns:
      an InputStream from which the file can be read. It is the responsibility of the caller to close the input stream when they have finished reading from it.