io.tus.java.client

Class TusUploader

java.lang.Object

io.tus.java.client.TusUploader

public class TusUploader
extends java.lang.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 and 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.

Method Summary

Modifier and Type	Method and 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.
int	getRequestPayloadSize() Get the current maximum payload size for a single request.
java.net.URL	getUploadURL() This methods returns the destination URL of the upload.
void	setChunkSize(int size) Sets the used chunk size.
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. 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.

Methods inherited from class java.lang.Object

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

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)

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:

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()

This methods returns the destination URL of the upload.

Returns:

The URL of the upload.

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. This method is equivalent to calling finish(false).

Throws:

ProtocolException - Thrown if the server sends an unexpected status code

java.io.IOException - Thrown if an exception occurs while cleaning up.

finish

public void finish(boolean closeInputStream)
            throws ProtocolException,
                   java.io.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

java.io.IOException - Thrown if an exception occurs while cleaning up.