org.apache.jackrabbit.api

Interface JackrabbitValueFactory

All Superinterfaces:

ValueFactory

All Known Implementing Classes:

ValueFactoryImpl

@ProviderType
public interface JackrabbitValueFactory
extends ValueFactory

Defines optional functionality that a ValueFactory may choose to provide. A ValueFactory may also implement this interface without supporting all of the capabilities in this interface. Each method of the interface describes the behavior of that method if the underlying capability is not available.

This interface defines the following optional features:

• Direct Binary Access - enable a client to upload or download binaries directly to/from a storage location

The features are described in more detail below.

Direct Binary Access

The Direct Binary Access feature provides the capability for a client to upload or download binaries directly to/from a storage location. For example, this might be a cloud storage providing high-bandwidth direct network access. This API allows for requests to be authenticated and for access permission checks to take place within the repository, but for clients to then access the storage location directly.

The feature consists of two parts, download and upload.

Direct Binary Download

This feature enables remote clients to download binaries directly from a storage location without streaming the binary through the Jackrabbit-based application.

For an existing Binary value that implements BinaryDownload, a read-only URI (see BinaryDownload.getURI(BinaryDownloadOptions)) can be retrieved and passed to a remote client, such as a browser.

Direct Binary Upload

This feature enables remote clients to upload binaries directly to a storage location.

Note: When adding binaries already present on the same JVM/server as the JCR repository, for example because they were generated locally, please use the regular JCR API ValueFactory.createBinary(InputStream) instead. This feature is solely designed for remote clients.

The direct binary upload process is split into 3 phases:

1. Initialize: A remote client makes request to the Jackrabbit-based application to request an upload, which calls initiateBinaryUpload(long, int) and returns the resulting instructions to the remote client. A client may optionally choose to provide a BinaryUploadOptions via initiateBinaryUpload(long, int, BinaryUploadOptions) if additional options must be specified.
2. Upload: The remote client performs the actual binary upload directly to the binary storage provider. The BinaryUpload returned from the previous call to initiateBinaryUpload(long, int) contains detailed instructions on how to complete the upload successfully.
3. Complete: The remote client notifies the Jackrabbit-based application that step 2 is complete. The upload token returned in the first step (obtained by calling BinaryUpload.getUploadToken() is passed by the application to completeBinaryUpload(String). This will provide the application with a regular JCR Binary that can then be used to write JCR content including the binary (such as an nt:file structure) and persist it using Session.save().

Method Summary

Modifier and Type	Method and Description
@Nullable Binary	completeBinaryUpload(@NotNull java.lang.String uploadToken) Complete the transaction of uploading a binary directly to a storage location and return a Binary to set as value for a binary JCR property.
@Nullable BinaryUpload	initiateBinaryUpload(long maxSize, int maxURIs) Initiate a transaction to upload a binary directly to a storage location and return BinaryUpload instructions for a remote client.
@Nullable BinaryUpload	initiateBinaryUpload(long maxSize, int maxURIs, BinaryUploadOptions options) Initiate a transaction to upload a binary directly to a storage location and return BinaryUpload instructions for a remote client.

Methods inherited from interface javax.jcr.ValueFactory

createBinary, createValue, createValue, createValue, createValue, createValue, createValue, createValue, createValue, createValue, createValue, createValue

Method Detail

initiateBinaryUpload

@Nullable
@Nullable BinaryUpload initiateBinaryUpload(long maxSize,
                                                      int maxURIs)
                                               throws java.lang.IllegalArgumentException,
                                                      AccessDeniedException

Initiate a transaction to upload a binary directly to a storage location and return BinaryUpload instructions for a remote client. Returns null if the feature is not available.

IllegalArgumentException will be thrown if an upload cannot be supported for the required parameters, or if the parameters are otherwise invalid. Each service provider has specific limitations.

Parameters:

maxSize - The exact size of the binary to be uploaded or the estimated maximum size if the exact size is unknown. If the estimation was too small, the transaction should be restarted by invoking this method again using the correct size.

maxURIs - The maximum number of upload URIs that the client can accept, for example due to message size limitations. A value of -1 indicates no limit. Upon a successful return, it is ensured that an upload of maxSize can be completed by splitting the binary into maxURIs parts, otherwise IllegalArgumentException will be thrown.

Returns:

A BinaryUpload providing the upload instructions, or null if the implementation does not support the direct upload feature.

Throws:

java.lang.IllegalArgumentException - if the provided arguments are invalid or if an upload cannot be completed given the provided arguments. For example, if the value of maxSize exceeds the size limits for a single binary upload for the implementation or the service provider, or if the value of maxSize divided by maxParts exceeds the size limit for an upload or upload part.

AccessDeniedException - if the session has insufficient permission to perform the upload.

initiateBinaryUpload

@Nullable
@Nullable BinaryUpload initiateBinaryUpload(long maxSize,
                                                      int maxURIs,
                                                      BinaryUploadOptions options)
                                               throws java.lang.IllegalArgumentException,
                                                      AccessDeniedException

Initiate a transaction to upload a binary directly to a storage location and return BinaryUpload instructions for a remote client. Returns null if the feature is not available.

IllegalArgumentException will be thrown if an upload cannot be supported for the required parameters, or if the parameters are otherwise invalid. Each service provider has specific limitations.

Parameters:

maxSize - The exact size of the binary to be uploaded or the estimated maximum size if the exact size is unknown. If the estimation was too small, the transaction should be restarted by invoking this method again using the correct size.

maxURIs - The maximum number of upload URIs that the client can accept, for example due to message size limitations. A value of -1 indicates no limit. Upon a successful return, it is ensured that an upload of maxSize can be completed by splitting the binary into maxURIs parts, otherwise IllegalArgumentException will be thrown.

options - A BinaryUploadOptions instance containing any options for this call.

Returns:

A BinaryUpload providing the upload instructions, or null if the implementation does not support the direct upload feature.

Throws:

java.lang.IllegalArgumentException - if the provided arguments are invalid or if an upload cannot be completed given the provided arguments. For example, if the value of maxSize exceeds the size limits for a single binary upload for the implementation or the service provider, or if the value of maxSize divided by maxParts exceeds the size limit for an upload or upload part.

AccessDeniedException - if the session has insufficient permission to perform the upload.

completeBinaryUpload

@Nullable
@Nullable Binary completeBinaryUpload(@NotNull
                                                @NotNull java.lang.String uploadToken)
                                         throws java.lang.IllegalArgumentException,
                                                RepositoryException

Complete the transaction of uploading a binary directly to a storage location and return a Binary to set as value for a binary JCR property. The binary is not automatically associated with any location in the JCR.

The client must provide a valid upload token, obtained from BinaryUpload.getUploadToken() when this transaction was initialized using initiateBinaryUpload(long, int). If the uploadToken is unreadable or invalid, an IllegalArgumentException will be thrown. This method is idempotent. Calling the method more than one time with the same upload token must not cause an existing binary to be modified; thus if a prior call with this upload token succeeded in creating the binary, subsequent calls with the same upload token have no effect on the binary. This method should always return the binary that was uploaded with this upload token, even in subsequent calls with the same upload token (in other words, calling this method twice with the same upload token results in the same binary being returned both times).

Parameters:

uploadToken - A String identifying the upload transaction.

Returns:

The uploaded Binary, or null if the implementation does not support the direct upload feature.

Throws:

java.lang.IllegalArgumentException - if the uploadToken is invalid or does not identify a known binary upload.

RepositoryException - if another error occurs.