Package io.tus.java.client

Class TusUploader

    • Constructor Summary

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

    • Constructor Detail

      • TusUploader

        public TusUploader​(TusClient client,
                   TusUpload upload,
                   java.net.URL uploadURL,
                   io.tus.java.client.TusInputStream input,
                   long offset)
            throws java.io.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)
        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:
        java.io.IOException - Thrown if an exception occurs while issuing the HTTP request.

    • Method Detail

      • 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 java.lang.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:
        java.lang.IllegalStateException - Thrown if the uploader currently has a connection open
        See Also:
        getRequestPayloadSize()

      • getRequestPayloadSize

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

      • uploadChunk

        public int uploadChunk()
                throws java.io.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:
        java.io.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 java.io.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:
        java.io.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 java.net.URL getUploadURL()

      • finish

        public void finish()
            throws ProtocolException,
                   java.io.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.
        Throws:
        ProtocolException - Thrown if the server sends an unexpected status code
        java.io.IOException - Thrown if an exception occurs while cleaning up.