Package io.tus.java.client

Class TusClient

java.lang.Object
io.tus.java.client.TusClient
public class TusClient extends Object
This class is used for creating or resuming uploads.

  • Field Details

    • TUS_VERSION

      public static final String TUS_VERSION
      Version of the tus protocol used by the client. The remote server needs to support this version, too.
      See Also:

  • Constructor Details

    • TusClient

      public TusClient()
      Create a new tus client.

  • Method Details

    • setUploadCreationURL

      public void setUploadCreationURL(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 URL getUploadCreationURL()
      Get the current upload creation URL.
      Returns:
      Current upload creation URL

    • setProxy

      public void setProxy(Proxy proxy)
      Set the proxy that will be used for all requests.
      Parameters:
      proxy - Proxy to use

    • getProxy

      public Proxy getProxy()
      Get the current proxy used for all requests.
      Returns:
      Current proxy

    • enableResuming

      public void enableResuming(@NotNull @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:

    • resumingEnabled

      public boolean resumingEnabled()
      Get the current status if resuming.
      Returns:
      True if resuming has been enabled using enableResuming(TusURLStore)
      See Also:

    • enableRemoveFingerprintOnSuccess

      public void enableRemoveFingerprintOnSuccess()
      Enable removing fingerprints after a successful upload.
      See Also:

    • disableRemoveFingerprintOnSuccess

      public void disableRemoveFingerprintOnSuccess()
      Disable removing fingerprints after a successful upload.
      See Also:

    • 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:

    • setHeaders

      public void setHeaders(@Nullable @Nullable Map<String,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

      @Nullable public @Nullable Map<String,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:

    • 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 @NotNull TusUpload upload) throws ProtocolException, 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.
      IOException - Thrown if an exception occurs while issuing the HTTP request.

    • resumeUpload

      public TusUploader resumeUpload(@NotNull @NotNull TusUpload upload) throws FingerprintNotFoundException, ResumingNotEnabledException, ProtocolException, 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.
      IOException - Thrown if an exception occurs while issuing the HTTP request.

    • beginOrResumeUploadFromURL

      public TusUploader beginOrResumeUploadFromURL(@NotNull @NotNull TusUpload upload, @NotNull @NotNull URL uploadURL) throws ProtocolException, 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.
      IOException - Thrown if an exception occurs while issuing the HTTP request.

    • resumeOrCreateUpload

      public TusUploader resumeOrCreateUpload(@NotNull @NotNull TusUpload upload) throws ProtocolException, 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.
      IOException - Thrown if an exception occurs while issuing the HTTP request.

    • prepareConnection

      public void prepareConnection(@NotNull @NotNull 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 @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