Interface BinaryDownload

  • All Superinterfaces:
    Binary

    @ProviderType
    public interface BinaryDownload
    extends Binary
    This extension interface provides a mechanism whereby a client can download a Binary directly from a storage location.
    • Method Detail

      • getURI

        @Nullable
        @Nullable URI getURI​(BinaryDownloadOptions downloadOptions)
                      throws RepositoryException
        Returns a URI for downloading this binary directly from the storage location.

        Using the downloadOptions parameter, some response headers of the download request can be overwritten, if supported by the storage provider. This is necessary to pass information that is only stored in the JCR in application specific structures, and not reliably available in the binary storage. BinaryDownloadOptions supports, but is not limited to:

        Specifying BinaryDownloadOptions.DEFAULT will use mostly empty defaults, relying on the storage provider attributes for this binary (that might be empty or different from the information in the JCR).

        Security considerations:

        • The URI cannot be shared with other users. It must only be returned to authenticated requests corresponding to this session user or trusted system components.
        • The URI must not be persisted for later use and will typically be time limited.
        • The URI will only grant access to this particular binary.
        • The client cannot infer any semantics from the URI structure and path names. It would typically include a cryptographic signature. Any change to the URI will likely result in a failing request.
        • If the client is a browser, consider use of Content-Disposition type = attachment for executable media types such as HTML or Javascript if the content cannot be trusted.
        Parameters:
        downloadOptions - A BinaryDownloadOptions instance which is used to request specific options on the binary to be downloaded. BinaryDownloadOptions.DEFAULT should be used if the caller wishes to accept the storage provider's default behavior.
        Returns:
        A URI for downloading the binary directly, or null if the binary cannot be downloaded directly or if the underlying implementation does not support this capability.
        Throws:
        RepositoryException - if an error occurs trying to locate the binary.