Monitor Uploads

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. You can do the following in Activity, Fragment or Service, but for conciseness we'll se how to do it globally in your app.

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

        RequestObserver(this, ProcessLifecycleOwner.get(), GlobalBroadcastReceiver()).register()
    }
}

GlobalBroadcastReceiver.kt

class GlobalBroadcastReceiver : 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")
    }
}