org.apache.jackrabbit.api.binary

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 Summary

Modifier and Type	Method and Description
@Nullable java.net.URI	getURI(BinaryDownloadOptions downloadOptions) Returns a URI for downloading this binary directly from the storage location.

Methods inherited from interface javax.jcr.Binary

dispose, getSize, getStream, read

Method Detail

getURI

@Nullable
@Nullable java.net.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:

• Content-Type media type: typically available in a jcr:mimeType property
• Content-Type charset: for media types defining a "charset", typically available in a jcr:encoding property
• Content-Disposition filename: download file name, typically taken from a JCR node name in the parent hierarchy, such as the nt:file node name
• Content-Disposition type: whether to show the content inline of a page (inline) or enforce a download/save as (attachment)

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.