4.x Usage

Contents

• HTTP multipart/form-data upload
• HTTP binary upload
• Management APIs. Programmatically get running uploads and stop them

Foreword

All the upload request methods are non blocking. They trigger a background upload service, so you can fire requests directly from your fragments, activities or services without concerns.

All the examples are in Kotlin, but the library is 100% interoperable with Java, so you can have the same functionality (with a slightly different syntax) even if you have 100% Java codebase, without worries.

If you know Java and not Kotlin, I strongly suggest you this pathway: https://developer.android.com/kotlin/learn-kotlin-java-pathway

What is the Upload ID?

When you create an upload request and call startUpload(), you will get a unique string which identifies the upload task. Using that string you can monitor the upload or stop it using Management APIs.

If you need it, you can generate an upload ID yourself and set it in the upload request by calling .setUploadID("yourID") before startUpload(). When doing that, be careful to always generate unique strings to avoid problems.

HTTP multipart/form-data upload (RFC2388)

When in trouble, follow the troubleshooting procedure

This is the most common way to upload files on a server. It's the same kind of request that browsers do when you use the <form> tag with one or more files. Here's a minimal example:

MultipartUploadRequest(context, serverUrl = "https://my.server.com")
    .setMethod("POST")
    .addFileToUpload(
        filePath = filePath,
        parameterName = "myFile"
    ).startUpload()

Check the other methods available in MultipartUploadRequest class and their docs. You can also add multiple headers, files and parameters. To monitor upload progress and status, check: https://github.com/gotev/android-upload-service/wiki/Monitor-Uploads

feature	description
multiple files in a single request	yes. There are many ways to do it. Example.
support for HTTP Basic and Bearer Auth	yes. Add .setBasicAuth("username", "password") or .setBearerAuth("bearer-token") when you build the request
add custom request headers	yes. You can also set them with request interceptors if you are using OkHttp stack.
add custom request parameters	yes
default charset	UTF-8. Non latin characters are supported out of the box.
resuming uploads	no. If an upload fails at some point, the temporary data will be discarded automatically by your server and the upload will start from the beginning on the next request. The server sees a multipart request as a single stream of data, as per RFC specs. There's no way to resume a multipart upload. You have to start over.

HTTP binary upload

When in trouble, follow the troubleshooting procedure

The binary upload uses a single file as the raw body of the upload request. Here's a minimal example:

BinaryUploadRequest(context, serverUrl = "https://my.server.com")
    .setMethod("POST")
    .setFileToUpload(filePath)
    .startUpload()

Check the other methods available in BinaryUploadRequest class and their docs. You can also add multiple headers. To monitor upload progress and status, check: https://github.com/gotev/android-upload-service/wiki/Monitor-Uploads

feature	description
multiple files in a single request	no. Only one file per request, which will be in the request body. It is more bandwidth efficient than HTTP/Multipart if all you need is to upload only one file to a server, without passing additional data in the request. If you want to pass the original file name to your server using this kind of request, the only way you can do it is by setting a custom header. Bear in mind that HTTP headers are encoded in US-ASCII, so don't use non-latin values.
support for HTTP Basic and Bearer Auth	yes. Add .setBasicAuth("username", "password") or .setBearerAuth("bearer-token") when you build the request
add custom request headers	yes. You can also set them with request interceptors if you are using OkHttp stack.
add custom request parameters	no, the request body consists only of the selected file to upload. There's no room for parameters like multipart requests. Calling addParameter and addArrayParameter methods will have no effect and you'll see a log message.
default charset	US-ASCII. UTF-8 is not supported because you can only set request headers, which must be in US-ASCII encoding
resuming uploads	no. If an upload fails at some point, the temporary data will be discarded automatically by your server and the upload will start from the beginning on the next request. The server sees the request as a single stream of data. There's no way to resume a binary upload. You have to start over.

Management APIs. Programmatically get running uploads and stop them.

You can call the following methods from anywhere you want in your code.

Method	Description
UploadService.taskList	Gets all the currently active upload tasks
UploadService.stopAllUploads()	Stops all the active upload tasks. Listening RequestObserver's onError method will be fired with UserCancelledUploadException for each upload you are monitoring.
UploadService.stopUpload(uploadId)	Stops a specific upload task. Listening RequestObserver's onError method will be fired with UserCancelledUploadException
UploadService.stop(context)	Stops UploadService if no tasks are currently running. It returns a boolean which indicates if the service is shutting down.
UploadService.stop(context, forceStop = true)	Force stops UploadService aborting any currently running tasks. It calls stopAllUploads() and returns a boolean which indicates if the service is shutting down.