io.tus.java.client

Class TusClient

java.lang.Object

io.tus.java.client.TusClient

public class TusClient
extends java.lang.Object

This class is used for creating or resuming uploads.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	TUS_VERSION Version of the tus protocol used by the client.

Constructor Summary

Constructors

Constructor and Description
TusClient() Create a new tus client.

Method Summary

Modifier and Type	Method and Description
TusUploader	beginOrResumeUploadFromURL(TusUpload upload, java.net.URL uploadURL) Begin an upload or alternatively resume it if the upload has already been started before.
TusUploader	createUpload(TusUpload upload) Create a new upload using the Creation extension.
void	disableRemoveFingerprintOnSuccess() Disable removing fingerprints after a successful upload.
void	disableResuming() Disable resuming started uploads.
void	enableRemoveFingerprintOnSuccess() Enable removing fingerprints after a successful upload.
void	enableResuming(TusURLStore urlStore) Enable resuming already started uploads.
int	getConnectTimeout() Returns the Connection Timeout.
java.util.Map<java.lang.String,java.lang.String>	getHeaders() Get the HTTP headers which should be contained in every request and were configured using setHeaders(Map).
java.net.URL	getUploadCreationURL() Get the current upload creation URL.
void	prepareConnection(java.net.HttpURLConnection connection) Set headers used for every HTTP request.
boolean	removeFingerprintOnSuccessEnabled() Get the current status if removing fingerprints after a successful upload.
TusUploader	resumeOrCreateUpload(TusUpload upload) Try to resume an upload using resumeUpload(TusUpload).
TusUploader	resumeUpload(TusUpload upload) Try to resume an already started upload.
boolean	resumingEnabled() Get the current status if resuming.
void	setConnectTimeout(int timeout) Sets the timeout for a Connection.
void	setHeaders(java.util.Map<java.lang.String,java.lang.String> headers) Set headers which will be added to every HTTP requestes made by this TusClient instance.
void	setUploadCreationURL(java.net.URL uploadCreationURL) Set the URL used for creating new uploads.
protected void	uploadFinished(TusUpload upload) Actions to be performed after a successful upload completion.

Methods inherited from class java.lang.Object

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

Field Detail

TUS_VERSION

public static final java.lang.String TUS_VERSION

Version of the tus protocol used by the client. The remote server needs to support this version, too.

See Also:

Constant Field Values

Constructor Detail

TusClient

public TusClient()

Create a new tus client.

Method Detail

setUploadCreationURL

public void setUploadCreationURL(java.net.URL uploadCreationURL)

Set the URL used for creating new uploads. This is required if you want to initiate new uploads using createUpload(io.tus.java.client.TusUpload) or resumeOrCreateUpload(io.tus.java.client.TusUpload) but is not used if you only resume existing uploads.

Parameters:

uploadCreationURL - Absolute upload creation URL

getUploadCreationURL

public java.net.URL getUploadCreationURL()

Get the current upload creation URL.

Returns:

Current upload creation URL

enableResuming

public void enableResuming(@NotNull
                           TusURLStore urlStore)

Enable resuming already started uploads. This step is required if you want to use resumeUpload(TusUpload).

Parameters:

urlStore - Storage used to save and retrieve upload URLs by its fingerprint.

disableResuming

public void disableResuming()

Disable resuming started uploads.

See Also:

enableResuming(TusURLStore)

resumingEnabled

public boolean resumingEnabled()

Get the current status if resuming.

Returns:

True if resuming has been enabled using enableResuming(TusURLStore)

See Also:

enableResuming(TusURLStore), disableResuming()

enableRemoveFingerprintOnSuccess

public void enableRemoveFingerprintOnSuccess()

Enable removing fingerprints after a successful upload.

See Also:

disableRemoveFingerprintOnSuccess()

disableRemoveFingerprintOnSuccess

public void disableRemoveFingerprintOnSuccess()

Disable removing fingerprints after a successful upload.

See Also:

enableRemoveFingerprintOnSuccess()

removeFingerprintOnSuccessEnabled

public boolean removeFingerprintOnSuccessEnabled()

Get the current status if removing fingerprints after a successful upload.

Returns:

True if resuming has been enabled using enableResuming(TusURLStore)

See Also:

enableRemoveFingerprintOnSuccess(), disableRemoveFingerprintOnSuccess()

setHeaders

public void setHeaders(@Nullable
                       java.util.Map<java.lang.String,java.lang.String> headers)

Set headers which will be added to every HTTP requestes made by this TusClient instance. These may to overwrite tus-specific headers, which can be identified by their Tus-* prefix, and can cause unexpected behavior.

Parameters:

headers - The map of HTTP headers

See Also:

getHeaders(), prepareConnection(HttpURLConnection)

getHeaders

@Nullable
public java.util.Map<java.lang.String,java.lang.String> getHeaders()

Get the HTTP headers which should be contained in every request and were configured using setHeaders(Map).

Returns:

The map of configured HTTP headers

See Also:

setHeaders(Map), prepareConnection(HttpURLConnection)

setConnectTimeout

public void setConnectTimeout(int timeout)

Sets the timeout for a Connection.

Parameters:

timeout - in milliseconds

getConnectTimeout

public int getConnectTimeout()

Returns the Connection Timeout.

Returns:

Timeout in milliseconds.

createUpload

public TusUploader createUpload(@NotNull
                                TusUpload upload)
                         throws ProtocolException,
                                java.io.IOException

Create a new upload using the Creation extension. Before calling this function, an "upload creation URL" must be defined using setUploadCreationURL(URL) or else this function will fail. In order to create the upload a POST request will be issued. The file's chunks must be uploaded manually using the returned TusUploader object.

Parameters:

upload - The file for which a new upload will be created

Returns:

Use TusUploader to upload the file's chunks.

Throws:

ProtocolException - Thrown if the remote server sent an unexpected response, e.g. wrong status codes or missing/invalid headers.

java.io.IOException - Thrown if an exception occurs while issuing the HTTP request.

resumeUpload

public TusUploader resumeUpload(@NotNull
                                TusUpload upload)
                         throws FingerprintNotFoundException,
                                ResumingNotEnabledException,
                                ProtocolException,
                                java.io.IOException

Try to resume an already started upload. Before call this function, resuming must be enabled using enableResuming(TusURLStore). This method will look up the URL for this upload in the TusURLStore using the upload's fingerprint (see TusUpload.getFingerprint()). After a successful lookup a HEAD request will be issued to find the current offset without uploading the file, yet.

Parameters:

upload - The file for which an upload will be resumed

Returns:

Use TusUploader to upload the remaining file's chunks.

Throws:

FingerprintNotFoundException - Thrown if no matching fingerprint has been found in TusURLStore. Use createUpload(TusUpload) to create a new upload.

ResumingNotEnabledException - Throw if resuming has not been enabled using enableResuming(TusURLStore).

ProtocolException - Thrown if the remote server sent an unexpected response, e.g. wrong status codes or missing/invalid headers.

java.io.IOException - Thrown if an exception occurs while issuing the HTTP request.

beginOrResumeUploadFromURL

public TusUploader beginOrResumeUploadFromURL(@NotNull
                                              TusUpload upload,
                                              @NotNull
                                              java.net.URL uploadURL)
                                       throws ProtocolException,
                                              java.io.IOException

Begin an upload or alternatively resume it if the upload has already been started before. In contrast to createUpload(TusUpload) and resumeOrCreateUpload(TusUpload) this method will not create a new upload. The user must obtain the upload location URL on their own as this method will not send the POST request which is normally used to create a new upload. Therefore, this method is only useful if you are uploading to a service which takes care of creating the tus upload for yourself. One example of such a service is the Vimeo API. When called a HEAD request will be issued to find the current offset without uploading the file, yet. The uploading can be started by using the returned TusUploader object.

Parameters:

upload - The file for which an upload will be resumed

uploadURL - The upload location URL at which has already been created and this file should be uploaded to.

Returns:

Use TusUploader to upload the remaining file's chunks.

Throws:

ProtocolException - Thrown if the remote server sent an unexpected response, e.g. wrong status codes or missing/invalid headers.

java.io.IOException - Thrown if an exception occurs while issuing the HTTP request.

resumeOrCreateUpload

public TusUploader resumeOrCreateUpload(@NotNull
                                        TusUpload upload)
                                 throws ProtocolException,
                                        java.io.IOException

Try to resume an upload using resumeUpload(TusUpload). If the method call throws an ResumingNotEnabledException or FingerprintNotFoundException, a new upload will be created using createUpload(TusUpload).

Parameters:

upload - The file for which an upload will be resumed

Returns:

TusUploader instance.

Throws:

ProtocolException - Thrown if the remote server sent an unexpected response, e.g. wrong status codes or missing/invalid headers.

java.io.IOException - Thrown if an exception occurs while issuing the HTTP request.

prepareConnection

public void prepareConnection(@NotNull
                              java.net.HttpURLConnection connection)

Set headers used for every HTTP request. Currently, this will add the Tus-Resumable header and any custom header which can be configured using setHeaders(Map),

Parameters:

connection - The connection whose headers will be modified.

uploadFinished

protected void uploadFinished(@NotNull
                              TusUpload upload)

Actions to be performed after a successful upload completion. Manages URL removal from the URL store if remove fingerprint on success is enabled

Parameters:

upload - that has been finished