Monitor Uploads

Index

• The RequestObserver
• Subscribing to a single upload request
• Subscribing to all upload requests
• Subscribing to some upload requests

When you make an UploadRequest, you get the notification and the progress displayed for free, but in many cases you need to display progress also in your app screens. This is achieved using the RequestObserver.

The RequestObserver

The RequestObserver is a lifecycle-aware BroadcastReceiver which receives events coming from single or multiple upload requests. It can be used inside Activity, Fragment, Service or globally in your app, depending on your specific needs.

Lifecycle-aware means that once you attach the RequestObserver to a LifecycleOwner, it will honor its lifecycle. So, for example if you attach it to an Activity, it will be around while the activity is alive. It will stop receiving events when the activity gets paused and it will restart receiving events when it gets resumed again. If the upload completes while you are not observing (either with success or error), onCompletedWhileNotObserving will be invoked, so you have a chance to do something in response. When the Activity dies, the RequestObserver dies as well and it won't receive any other event afterwards.

If you are coming from 3.x, this is the substitute for BroadcastReceiver and Delegate and it can be used in the same places you are already using it, in almost the same way.

Subscribing to a single upload request

The easiest and most concise way of monitoring an upload is to subscribe to it. In this way the RequestObserver will receive events only from the subscribed upload request. Simple example with a MultipartUploadRequest.

fun upload(context: Context, lifecycleOwner: LifecycleOwner) {
    MultipartUploadRequest(this, "https://server.url")
        .addFileToUpload(filePath = "/path/to/file", parameterName = "myFile")
        .subscribe(context = context, lifecycleOwner = lifecycleOwner, delegate = object : RequestObserverDelegate() {
            override fun onProgress(context: Context, uploadInfo: UploadInfo) {
                // do your thing
            }

            override fun onSuccess(
                context: Context,
                uploadInfo: UploadInfo,
                serverResponse: ServerResponse
            ) {
                // do your thing
            }

            override fun onError(
                context: Context,
                uploadInfo: UploadInfo,
                exception: Throwable
            ) {
                // do your thing
            }

            override fun onCompleted(context: Context, uploadInfo: UploadInfo) {
                // do your thing
            }

            override fun onCompletedWhileNotObserving() {
                // do your thing
            }
        })
}

From Activity

Supposing you're using the above example function.

class MyActivity : AppCompatActivity() {
   fun myAction() {
       upload(context = this, lifecycleOwner = this)
   }

   fun upload(context: Context, lifecycleOwner: LifecycleOwner) { ... }
}

From Fragment

Supposing you're using the above example function.

class MyFragment: Fragment() {
    fun myAction() {
        upload(context = requireContext(), lifecycleOwner = viewLifecycleOwner)
    }

    fun upload(context: Context, lifecycleOwner: LifecycleOwner) { ... }
}

From Service

Supposing you're using the above example function.

class MyService : LifecycleService() {
    fun myAction() {
        upload(context = this, lifecycleOwner = this)
    }

    fun upload(context: Context, lifecycleOwner: LifecycleOwner) { ... }
}

Subscribing to all upload requests

Do this when you need to perform some custom logic for all the uploads. The following example shows how to do it globally in your app:

class App : Application() {
    override fun onCreate() {
        super.onCreate()

        RequestObserver(this, ProcessLifecycleOwner.get(), GlobalUploadObserver())
    }
}

GlobalUploadObserver.kt

class GlobalUploadObserver : RequestObserverDelegate {
    override fun onProgress(context: Context, uploadInfo: UploadInfo) {
        Log.e("RECEIVER", "Progress: $uploadInfo")
    }

    override fun onSuccess(context: Context, uploadInfo: UploadInfo, serverResponse: ServerResponse) {
        Log.e("RECEIVER", "Success: $serverResponse")
    }

    override fun onError(context: Context, uploadInfo: UploadInfo, exception: Throwable) {
        when (exception) {
            is UserCancelledUploadException -> {
                Log.e("RECEIVER", "Error, user cancelled upload: $uploadInfo")
            }

            is UploadError -> {
                Log.e("RECEIVER", "Error, upload error: ${exception.serverResponse}")
            }

            else -> {
                Log.e("RECEIVER", "Error: $uploadInfo", exception)

            }
        }
    }

    override fun onCompleted(context: Context, uploadInfo: UploadInfo) {
        Log.e("RECEIVER", "Completed: $uploadInfo")
    }

    override fun onCompletedWhileNotObserving() {
        Log.e("RECEIVER", "Completed while not observing")
    }
}

Subscribing to some upload requests

When you need to create a RequestObserver for a specific subset of all of your uploads, you can accept only events coming from specific uploads.

RequestObserver(context, lifecycleOwner, delegate, shouldAcceptEventsFrom = { uploadInfo ->
    // implement your custom business logic here. 
    // return true to accept events from this uploadInfo, false otherwise
})

Example

You have multiple categories of uploads: football, basketball, baseball.

Leveraging UploadRequest

.setUploadID("football-${UUID.randomUUID().toString()}")

method you can assign a custom unique ID to all the football uploads and use that information to make a football-only observer, like this:

RequestObserver(context, lifecycleOwner, delegate, shouldAcceptEventsFrom = { uploadInfo ->
    uploadInfo.uploadId.startsWith("football")
})