Package io.tus.java.client

Class TusUploader

java.lang.Object
io.tus.java.client.TusUploader
public class TusUploader extends Object
This class is used for doing the actual upload of the files. Instances are returned by TusClient.createUpload(TusUpload), TusClient.createUpload(TusUpload) and TusClient.resumeOrCreateUpload(TusUpload).
After obtaining an instance you can upload a file by following these steps:
  1. Upload a chunk using uploadChunk()
  2. Optionally get the new offset (getOffset() to calculate the progress
  3. Repeat step 1 until the uploadChunk() returns -1
  4. Close HTTP connection and InputStream using finish() to free resources

  • Constructor Summary

    Constructors
    Constructor
    Description
    TusUploader(TusClient client, TusUpload upload, URL uploadURL, io.tus.java.client.TusInputStream input, long offset)
    Begin a new upload request by opening a PATCH request to specified upload URL.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    finish()
    Finish the request by closing the HTTP connection and the InputStream.
    void
    finish(boolean closeInputStream)
    Finish the request by closing the HTTP connection.
    int
    getChunkSize()
    Returns the current chunk size set using setChunkSize(int).
    long
    getOffset()
    Get the current offset for the upload.
    Proxy
    getProxy()
    This methods returns the proxy used when uploading.
    int
    getRequestPayloadSize()
    Get the current maximum payload size for a single request.
    URL
    getUploadURL()
    This methods returns the destination URL of the upload.
    void
    setChunkSize(int size)
    Sets the used chunk size.
    void
    setProxy(Proxy proxy)
    Set the proxy that will be used when uploading.
    void
    setRequestPayloadSize(int size)
    Set the maximum payload size for a single request counted in bytes.
    int
    uploadChunk()
    Upload a part of the file by reading a chunk from the InputStream and writing it to the HTTP request's body.
    int
    uploadChunk(int chunkSize)
    Deprecated.
    This method is inefficient and has been replaced by setChunkSize(int) and uploadChunk() and should not be used anymore.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • TusUploader

      public TusUploader(TusClient client, TusUpload upload, URL uploadURL, io.tus.java.client.TusInputStream input, long offset) throws IOException
      Begin a new upload request by opening a PATCH request to specified upload URL. After this method returns a connection will be ready and you can upload chunks of the file.
      Parameters:
      client - Used for preparing a request (TusClient.prepareConnection(HttpURLConnection)
      upload - TusUpload to be uploaded.
      uploadURL - URL to send the request to
      input - Stream to read (and seek) from and upload to the remote server
      offset - Offset to read from
      Throws:
      IOException - Thrown if an exception occurs while issuing the HTTP request.

  • Method Details

    • setChunkSize

      public void setChunkSize(int size)
      Sets the used chunk size. This number is used by uploadChunk() to indicate how much data is uploaded in a single take. When choosing a value for this parameter you need to consider that uploadChunk() will only return once the specified number of bytes has been sent. For slow internet connections this may take a long time. In addition, a buffer with the chunk size is allocated and kept in memory.
      Parameters:
      size - The new chunk size

    • getChunkSize

      public int getChunkSize()
      Returns the current chunk size set using setChunkSize(int).
      Returns:
      Current chunk size

    • setRequestPayloadSize

      public void setRequestPayloadSize(int size) throws IllegalStateException
      Set the maximum payload size for a single request counted in bytes. This is useful for splitting bigger uploads into multiple requests. For example, if you have a resource of 2MB and the payload size set to 1MB, the upload will be transferred by two requests of 1MB each. The default value for this setting is 10 * 1024 * 1024 bytes (10 MiB). Be aware that setting a low maximum payload size (in the low megabytes or even less range) will result in decreased performance since more requests need to be used for an upload. Each request will come with its overhead in terms of longer upload times. Be aware that setting a high maximum payload size may result in a high memory usage since tus-java-client usually allocates a buffer with the maximum payload size (this buffer is used to allow retransmission of lost data if necessary). If the client is running on a memory- constrained device (e.g. mobile app) and the maximum payload size is too high, it might result in an OutOfMemoryError. This method must not be called when the uploader has currently an open connection to the remote server. In general, try to set the payload size before invoking uploadChunk() the first time.
      Parameters:
      size - Number of bytes for a single payload
      Throws:
      IllegalStateException - Thrown if the uploader currently has a connection open
      See Also:

    • getRequestPayloadSize

      public int getRequestPayloadSize()
      Get the current maximum payload size for a single request.
      Returns:
      Number of bytes for a single payload
      See Also:

    • uploadChunk

      public int uploadChunk() throws IOException, ProtocolException
      Upload a part of the file by reading a chunk from the InputStream and writing it to the HTTP request's body. If the number of available bytes is lower than the chunk's size, all available bytes will be uploaded and nothing more. No new connection will be established when calling this method, instead the connection opened in the previous calls will be used. The size of the read chunk can be obtained using getChunkSize() and changed using setChunkSize(int). In order to obtain the new offset, use getOffset() after this method returns.
      Returns:
      Number of bytes read and written.
      Throws:
      IOException - Thrown if an exception occurs while reading from the source or writing to the HTTP request.
      ProtocolException

    • uploadChunk

      @Deprecated public int uploadChunk(int chunkSize) throws IOException, ProtocolException
      Deprecated.
      This method is inefficient and has been replaced by setChunkSize(int) and uploadChunk() and should not be used anymore. The reason is, that this method allocates a new buffer with the supplied chunk size for each time it's called without reusing it. This results in a high number of memory allocations and should be avoided. The new methods do not have this issue.
      Upload a part of the file by read a chunks specified size from the InputStream and writing it to the HTTP request's body. If the number of available bytes is lower than the chunk's size, all available bytes will be uploaded and nothing more. No new connection will be established when calling this method, instead the connection opened in the previous calls will be used. In order to obtain the new offset, use getOffset() after this method returns. This method ignored the payload size per request, which may be set using setRequestPayloadSize(int). Please, use uploadChunk() instead.
      Parameters:
      chunkSize - Maximum number of bytes which will be uploaded. When choosing a value for this parameter you need to consider that the method call will only return once the specified number of bytes have been sent. For slow internet connections this may take a long time.
      Returns:
      Number of bytes read and written.
      Throws:
      IOException - Thrown if an exception occurs while reading from the source or writing to the HTTP request.
      ProtocolException

    • getOffset

      public long getOffset()
      Get the current offset for the upload. This is the number of all bytes uploaded in total and in all requests (not only this one). You can use it in conjunction with TusUpload.getSize() to calculate the progress.
      Returns:
      The upload's current offset.

    • getUploadURL

      public URL getUploadURL()
      This methods returns the destination URL of the upload.
      Returns:
      The URL of the upload.

    • setProxy

      public void setProxy(Proxy proxy)
      Set the proxy that will be used when uploading.
      Parameters:
      proxy - Proxy to use

    • getProxy

      public Proxy getProxy()
      This methods returns the proxy used when uploading.
      Returns:
      The Proxy used for the upload or null when not set.

    • finish

      public void finish() throws ProtocolException, IOException
      Finish the request by closing the HTTP connection and the InputStream. You can call this method even before the entire file has been uploaded. Use this behavior to enable pausing uploads. This method is equivalent to calling finish(false).
      Throws:
      ProtocolException - Thrown if the server sends an unexpected status code
      IOException - Thrown if an exception occurs while cleaning up.

    • finish

      public void finish(boolean closeInputStream) throws ProtocolException, IOException
      Finish the request by closing the HTTP connection. You can choose whether to close the InputStream or not. You can call this method even before the entire file has been uploaded. Use this behavior to enable pausing uploads. Be aware that it doesn't automatically release local resources if closeStream == false and you do not close the InputStream on your own. To be safe use finish().
      Parameters:
      closeInputStream - Determines whether the InputStream is closed with the HTTP connection. Not closing the Input Stream may be useful for future upload a future continuation of the upload.
      Throws:
      ProtocolException - Thrown if the server sends an unexpected status code
      IOException - Thrown if an exception occurs while cleaning up.