me.desair.tus.server

Class TusFileUploadService

java.lang.Object

me.desair.tus.server.TusFileUploadService

public class TusFileUploadService
extends Object

Helper class that implements the server side tus v1.0.0 upload protocol

Field Summary

Fields

Modifier and Type	Field and Description
static String	TUS_API_VERSION

Constructor Summary

Constructors

Constructor and Description
TusFileUploadService()

Method Summary

Modifier and Type	Method and Description
TusFileUploadService	addTusExtension(TusExtension feature) Add a custom (application-specific) extension that implements the TusExtension interface.
void	cleanup() This method should be invoked periodically.
void	deleteUpload(String uploadURI) Method to delete an upload associated with the given upload URL.
void	deleteUpload(String uploadURI, String ownerKey) Method to delete an upload associated with the given upload URL.
TusFileUploadService	disableTusExtension(String extensionName) Disable the TusExtension for which the getName() method matches the provided string.
protected void	executeProcessingByFeatures(HttpMethod method, TusServletRequest servletRequest, TusServletResponse servletResponse, String ownerKey)
Set<String>	getEnabledFeatures() Get the set of enabled Tus extensions
Set<HttpMethod>	getSupportedHttpMethods() Get all HTTP methods that are supported by this TusUploadService based on the enabled and/or disabled tus extensions
InputStream	getUploadedBytes(String uploadURI) Method to retrieve the bytes that were uploaded to a specific upload URI
InputStream	getUploadedBytes(String uploadURI, String ownerKey) Method to retrieve the bytes that were uploaded to a specific upload URI
UploadInfo	getUploadInfo(String uploadURI) Get the information on the upload corresponding to the given upload URI
UploadInfo	getUploadInfo(String uploadURI, String ownerKey) Get the information on the upload corresponding to the given upload URI
protected void	initFeatures()
void	process(javax.servlet.http.HttpServletRequest servletRequest, javax.servlet.http.HttpServletResponse servletResponse) Process a tus upload request.
void	process(javax.servlet.http.HttpServletRequest servletRequest, javax.servlet.http.HttpServletResponse servletResponse, String ownerKey) Process a tus upload request that belongs to a specific owner.
protected void	processLockedRequest(HttpMethod method, TusServletRequest request, TusServletResponse response, String ownerKey)
protected void	processTusException(HttpMethod method, TusServletRequest request, TusServletResponse response, String ownerKey, TusException exception)
protected void	validateRequest(HttpMethod method, javax.servlet.http.HttpServletRequest servletRequest, String ownerKey)
TusFileUploadService	withChunkedTransferDecoding(boolean isEnabled) Instruct this service to (not) decode any requests with Transfer-Encoding value "chunked".
TusFileUploadService	withDownloadFeature() Enable the unofficial `download` extension that also allows you to download uploaded bytes.
TusFileUploadService	withMaxUploadSize(Long maxUploadSize) Specify the maximum number of bytes that can be uploaded per upload.
TusFileUploadService	withStoragePath(String storagePath) If you're using the default file system-based storage service, you can use this method to specify the path where to store the uploaded bytes and upload information.
TusFileUploadService	withThreadLocalCache(boolean isEnabled) Enable or disable a thread-local based cache of upload data.
TusFileUploadService	withUploadExpirationPeriod(Long expirationPeriod) You can set the number of milliseconds after which an upload is considered as expired and available for cleanup.
TusFileUploadService	withUploadIdFactory(UploadIdFactory uploadIdFactory) Provide a custom UploadIdFactory implementation that should be used to generate identifiers for the different uploads.
TusFileUploadService	withUploadLockingService(UploadLockingService uploadLockingService) Provide a custom UploadLockingService implementation that should be used when processing uploads.
TusFileUploadService	withUploadStorageService(UploadStorageService uploadStorageService) Provide a custom UploadStorageService implementation that should be used to store uploaded bytes and metadata (UploadInfo).
TusFileUploadService	withUploadURI(String uploadURI) Set the URI under which the main tus upload endpoint is hosted.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TUS_API_VERSION

public static final String TUS_API_VERSION

See Also:

Constant Field Values

Constructor Detail

TusFileUploadService

public TusFileUploadService()

Method Detail

initFeatures

protected void initFeatures()

withUploadURI

public TusFileUploadService withUploadURI(String uploadURI)

Set the URI under which the main tus upload endpoint is hosted. Optionally, this URI may contain regex parameters in order to support endpoints that contain URL parameters, for example /users/[0-9]+/files/upload

Parameters:

uploadURI - The URI of the main tus upload endpoint

Returns:

The current service

withMaxUploadSize

public TusFileUploadService withMaxUploadSize(Long maxUploadSize)

Specify the maximum number of bytes that can be uploaded per upload. If you don't call this method, the maximum number of bytes is Long.MAX_VALUE.

Parameters:

maxUploadSize - The maximum upload length that is allowed

Returns:

The current service

withUploadIdFactory

public TusFileUploadService withUploadIdFactory(UploadIdFactory uploadIdFactory)

Provide a custom UploadIdFactory implementation that should be used to generate identifiers for the different uploads. Example implementation are UUIDUploadIdFactory and TimeBasedUploadIdFactory.

Parameters:

uploadIdFactory - The custom UploadIdFactory implementation

Returns:

The current service

withUploadStorageService

public TusFileUploadService withUploadStorageService(UploadStorageService uploadStorageService)

Provide a custom UploadStorageService implementation that should be used to store uploaded bytes and metadata (UploadInfo).

Parameters:

uploadStorageService - The custom UploadStorageService implementation

Returns:

The current service

withUploadLockingService

public TusFileUploadService withUploadLockingService(UploadLockingService uploadLockingService)

Provide a custom UploadLockingService implementation that should be used when processing uploads. The upload locking service is responsible for locking an upload that is being processed so that it cannot be corrupted by simultaneous or delayed requests.

Parameters:

uploadLockingService - The UploadLockingService implementation to use

Returns:

The current service

withStoragePath

public TusFileUploadService withStoragePath(String storagePath)

If you're using the default file system-based storage service, you can use this method to specify the path where to store the uploaded bytes and upload information.

Parameters:

storagePath - The file system path where uploads can be stored (temporarily)

Returns:

The current service

withThreadLocalCache

public TusFileUploadService withThreadLocalCache(boolean isEnabled)

Enable or disable a thread-local based cache of upload data. This can reduce the load on the storage backends. By default this cache is disabled.

Parameters:

isEnabled - True if the cache should be enabled, false otherwise

Returns:

The current service

withChunkedTransferDecoding

public TusFileUploadService withChunkedTransferDecoding(boolean isEnabled)

Instruct this service to (not) decode any requests with Transfer-Encoding value "chunked". Use this method in case the web container in which this service is running does not decode chunked transfers itself. By default, chunked decoding is disabled.

Parameters:

isEnabled - True if chunked requests should be decoded, false otherwise.

Returns:

The current service

withUploadExpirationPeriod

public TusFileUploadService withUploadExpirationPeriod(Long expirationPeriod)

You can set the number of milliseconds after which an upload is considered as expired and available for cleanup.

Parameters:

expirationPeriod - The number of milliseconds after which an upload expires and can be removed

Returns:

The current service

withDownloadFeature

public TusFileUploadService withDownloadFeature()

Enable the unofficial `download` extension that also allows you to download uploaded bytes. By default this feature is disabled.

Returns:

The current service

addTusExtension

public TusFileUploadService addTusExtension(TusExtension feature)

Add a custom (application-specific) extension that implements the TusExtension interface. For example you can add your own extension that checks authentication and authorization policies within your application for the user doing the upload.

Parameters:

feature - The custom extension implementation

Returns:

The current service

disableTusExtension

public TusFileUploadService disableTusExtension(String extensionName)

Disable the TusExtension for which the getName() method matches the provided string. The default extensions have names "creation", "checksum", "expiration", "concatenation", "termination" and "download". You cannot disable the "core" feature.

Parameters:

extensionName - The name of the extension to disable

Returns:

The current service

getSupportedHttpMethods

public Set<HttpMethod> getSupportedHttpMethods()

Get all HTTP methods that are supported by this TusUploadService based on the enabled and/or disabled tus extensions

Returns:

The set of enabled HTTP methods

getEnabledFeatures

public Set<String> getEnabledFeatures()

Get the set of enabled Tus extensions

Returns:

The set of active extensions

process

public void process(javax.servlet.http.HttpServletRequest servletRequest,
                    javax.servlet.http.HttpServletResponse servletResponse)
             throws IOException

Process a tus upload request. Use this method to process any request made to the main and sub tus upload endpoints. This corresponds to the path specified in the withUploadURI() method and any sub-path of that URI.

Parameters:

servletRequest - The HttpServletRequest of the request

servletResponse - The HttpServletResponse of the request

Throws:

IOException - When saving bytes or information of this requests fails

process

public void process(javax.servlet.http.HttpServletRequest servletRequest,
                    javax.servlet.http.HttpServletResponse servletResponse,
                    String ownerKey)
             throws IOException

Process a tus upload request that belongs to a specific owner. Use this method to process any request made to the main and sub tus upload endpoints. This corresponds to the path specified in the withUploadURI() method and any sub-path of that URI.

Parameters:

servletRequest - The HttpServletRequest of the request

servletResponse - The HttpServletResponse of the request

ownerKey - A unique identifier of the owner (group) of this upload

Throws:

IOException - When saving bytes or information of this requests fails

getUploadedBytes

public InputStream getUploadedBytes(String uploadURI)
                             throws IOException,
                                    TusException

Method to retrieve the bytes that were uploaded to a specific upload URI

Parameters:

uploadURI - The URI of the upload

Returns:

An InputStream that will stream the uploaded bytes

Throws:

IOException - When the retreiving the uploaded bytes fails

TusException - When the upload is still in progress or cannot be found

getUploadedBytes

public InputStream getUploadedBytes(String uploadURI,
                                    String ownerKey)
                             throws IOException,
                                    TusException

Method to retrieve the bytes that were uploaded to a specific upload URI

Parameters:

uploadURI - The URI of the upload

ownerKey - The key of the owner of this upload

Returns:

An InputStream that will stream the uploaded bytes

Throws:

IOException - When the retreiving the uploaded bytes fails

TusException - When the upload is still in progress or cannot be found

getUploadInfo

public UploadInfo getUploadInfo(String uploadURI)
                         throws IOException,
                                TusException

Get the information on the upload corresponding to the given upload URI

Parameters:

uploadURI - The URI of the upload

Returns:

Information on the upload

Throws:

IOException - When retrieving the upload information fails

TusException - When the upload is still in progress or cannot be found

getUploadInfo

public UploadInfo getUploadInfo(String uploadURI,
                                String ownerKey)
                         throws IOException,
                                TusException

Get the information on the upload corresponding to the given upload URI

Parameters:

uploadURI - The URI of the upload

ownerKey - The key of the owner of this upload

Returns:

Information on the upload

Throws:

IOException - When retrieving the upload information fails

TusException - When the upload is still in progress or cannot be found

deleteUpload

public void deleteUpload(String uploadURI)
                  throws IOException,
                         TusException

Method to delete an upload associated with the given upload URL. Invoke this method if you no longer need the upload.

Parameters:

uploadURI - The upload URI

Throws:

IOException

TusException

deleteUpload

public void deleteUpload(String uploadURI,
                         String ownerKey)
                  throws IOException,
                         TusException

Method to delete an upload associated with the given upload URL. Invoke this method if you no longer need the upload.

Parameters:

uploadURI - The upload URI

ownerKey - The key of the owner of this upload

Throws:

IOException

TusException

cleanup

public void cleanup()
             throws IOException

This method should be invoked periodically. It will cleanup any expired uploads and stale locks

Throws:

IOException - When cleaning fails

processLockedRequest

protected void processLockedRequest(HttpMethod method,
                                    TusServletRequest request,
                                    TusServletResponse response,
                                    String ownerKey)
                             throws IOException

Throws:

IOException

executeProcessingByFeatures

protected void executeProcessingByFeatures(HttpMethod method,
                                           TusServletRequest servletRequest,
                                           TusServletResponse servletResponse,
                                           String ownerKey)
                                    throws IOException,
                                           TusException

Throws:

IOException

TusException

validateRequest

protected void validateRequest(HttpMethod method,
                               javax.servlet.http.HttpServletRequest servletRequest,
                               String ownerKey)
                        throws TusException,
                               IOException

Throws:

TusException

IOException

processTusException

protected void processTusException(HttpMethod method,
                                   TusServletRequest request,
                                   TusServletResponse response,
                                   String ownerKey,
                                   TusException exception)
                            throws IOException

Throws:

IOException