@ProviderType public interface JackrabbitValueFactory extends ValueFactory
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.
Currently this interface defines the following optional features:
The features are described in more detail below.
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, direct binary upload and direct binary download.
This feature enables remote clients to upload binaries directly to a storage location.
When adding binaries already present on the same JVM or server as Jackrabbit
or Oak, for example because they were generated locally, please use the
regular JCR API for adding
binaries through input streams
instead. This feature is solely designed for
remote clients.
The direct binary upload process is split into 3 phases:
initiateBinaryUpload(long, int)
and returns the resulting information
to the remote client.
BinaryUpload
returned from the previous call to initiateBinaryUpload(long, int)
contains detailed instructions on
how to complete the upload successfully. For more information, see
the BinaryUpload documentation.
BinaryUpload.getUploadToken()
is passed by the client 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.
The direct binary download process is described in detail in BinaryDownload
.
Modifier and Type | Method and Description |
---|---|
@Nullable Binary |
completeBinaryUpload(@NotNull String uploadToken)
Complete a transaction to upload binary data directly to a storage
location.
|
@Nullable BinaryUpload |
initiateBinaryUpload(long maxSize,
int maxURIs)
Initiate a transaction to upload binary data directly to a storage
location.
|
createBinary, createValue, createValue, createValue, createValue, createValue, createValue, createValue, createValue, createValue, createValue, createValue
@Nullable @Nullable BinaryUpload initiateBinaryUpload(long maxSize, int maxURIs) throws IllegalArgumentException, AccessDeniedException
IllegalArgumentException
will be thrown if an upload
cannot be supported for the required parameters, or if the parameters are
otherwise invalid. 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 of the
implementation or the service provider, IllegalArgumentException
may be thrown.
Each service provider has specific limitations on upload sizes,
multi-part upload support, part sizes, etc. which can result in IllegalArgumentException
being thrown. You should consult the
documentation for your underlying implementation and your service
provider for details.
If this call is successful, a BinaryUpload
is returned
which contains the information a client needs to successfully complete
a direct upload.
maxSize
- The expected maximum size of the binary to be uploaded by
the client. If the actual size of the binary is known, this
size should be used; otherwise, the client should make a best
guess. If a client calls this method with one size and then
later determines that the guess was too small, the transaction
should be restarted by calling this method again with the correct
size.maxURIs
- The maximum number of upload URIs that the client can
accept. The implementation will ensure that an upload of size
maxSize
can be completed by splitting the value of maxSize
into parts, such that the size of the largest part does
not exceed any known implementation or service provider
limitations on upload part size and such that the number of parts
does not exceed the value of maxURIs
. If this is not
possible, IllegalArgumentException
will be thrown. A
client may specify -1 for this value, indicating that any number
of URIs may be returned.BinaryUpload
that can be used by the client to complete
the upload via a call to completeBinaryUpload(String)
,
or null
if the implementation does not support the direct
upload feature.IllegalArgumentException
- if the provided arguments are
invalid or if a valid upload cannot be completed given the
provided arguments.AccessDeniedException
- if it is determined that insufficient
permission exists to perform the upload.@Nullable @Nullable Binary completeBinaryUpload(@NotNull @NotNull String uploadToken) throws IllegalArgumentException, RepositoryException
uploadToken
that can
only be obtained via a previous call to initiateBinaryUpload(long, int)
. If the uploadToken
is
unreadable or invalid, IllegalArgumentException
will be thrown.
Calling this method does not associate the returned Binary
with
any location in the repository. It is the responsibility of the client
to do this if desired.
The uploadToken
can be obtained from the BinaryUpload
returned from a prior call to initiateBinaryUpload(long, int)
. Clients should treat the uploadToken
as an immutable string, and should expect that
implementations will sign the string and verify the signature when this
method is called.
uploadToken
- A String that is used to identify the direct upload
transaction.Binary
, or null
if the
implementation does not support the direct upload feature.IllegalArgumentException
- if the uploadToken
is
unreadable or invalid.RepositoryException
- if a repository access error occurs.Copyright © 2004–2018 The Apache Software Foundation. All rights reserved.