Interface BlobStore

  • All Known Implementing Classes:
    AbstractBlobStore, AESBlobStore, CachingBlobStore, InMemoryBlobStore, LocalBlobStore, S3BlobStore, TransactionalBlobStore

    public interface BlobStore
    Interface for basic access to storage of a Blob (read/write/copy/delete).

    A blob is identified by a key, and holds a stream of bytes. It may have some associated metadata (filename, content type).

    A blob store may have versioning. When this is the case, the write method will return a key that includes a version number. This same complete key must subsequently be provided to the read or delete methods. With versioning, two writes may be requested with the same key in the blob context, and both will succeed because they return keys that include a version number to distinguish them.

    Since:
    11.1
    • Method Detail

      • hasVersioning

        boolean hasVersioning()
        Whether this blob store has versioning.

        With versioning, two writes may use the same key. The returned keys will include a different version number to distinguish the writes.

      • writeBlob

        String writeBlob​(BlobWriteContext blobWriteContext)
                  throws IOException
        Writes a blob.

        Note that the returned key may be different than the one requested by the BlobWriteContext, if the blob store needs additional version info to retrieve it.

        Parameters:
        blobWriteContext - the context of the blob write, including the blob
        Returns:
        the key to use to read this blob in the future
        Throws:
        IOException
      • copyBlobIsOptimized

        boolean copyBlobIsOptimized​(BlobStore sourceStore)
        Checks if blob copy/move from another blob store to this one can be done efficiently.
        Parameters:
        sourceStore - the source store
        Returns:
        true if the copy/move can be done efficiently
      • copyBlob

        boolean copyBlob​(String key,
                         BlobStore sourceStore,
                         String sourceKey,
                         boolean atomicMove)
                  throws IOException
        Writes a file based on a key, as a copy/move from a source in another blob store.

        If the copy/move is requested to be atomic, then the destination file is created atomically. In case of atomic move, in some stores the destination will be created atomically but the source will only be deleted afterwards.

        Parameters:
        key - the key
        sourceStore - the source store
        sourceKey - the source key
        atomicMove - true for an atomic move, false for a regular copy
        Returns:
        true if the file was found in the source store, false if it was not found
        Throws:
        IOException
      • getFile

        @NotNull
        BlobStore.OptionalOrUnknown<PathgetFile​(String key)
        Gets an already-existing file containing the blob for the given key, if present.

        Note that this method is best-effort, it may return unknown even though the blob exists in the store, it's just that it's not handily available locally in a file.

        Parameters:
        key - the blob key
        Returns:
        the file containing the blob, or empty if the blob cannot be found, or unknown if no file is available locally
      • getStream

        @NotNull
        BlobStore.OptionalOrUnknown<InputStreamgetStream​(String key)
                                                    throws IOException
        Gets the stream of the blob for the given key, if present.

        Note that this method is best-effort, it may return unknown even though the blob exists in the store, it's just that it's not efficient to return it as a stream.

        Parameters:
        key - the blob key
        Returns:
        the blob stream, or empty if the blob cannot be found, or unknown if no stream is efficiently available
        Throws:
        IOException
      • readBlob

        boolean readBlob​(String key,
                         Path dest)
                  throws IOException
        Reads a blob based on its key into the given file.
        Parameters:
        key - the blob key
        dest - the file to use to store the fetched data
        Returns:
        true if the file was fetched, false if the file was not found
        Throws:
        IOException
      • deleteBlob

        void deleteBlob​(BlobContext blobContext)
        Deletes a blob.
        Parameters:
        blobContext - the blob context
      • deleteBlob

        void deleteBlob​(String key)
        Deletes a blob based on a key. No error occurs if the blob does not exist.

        This method does not throw IOException, but may log an error message.

        Parameters:
        key - the blob key
      • unwrap

        BlobStore unwrap()
        If this blob store wraps another one, returns it, otherwise returns this.
        Returns:
        the lowest-level blob store