Configuration

NOTE: This is work in progress. More to come soon.

Index

• Notifications
  • UploadNotificationConfig
  • UploadNotificationStatusConfig
    • Placeholders
    • Actions
  • Notification Handler
• HTTP Stack
  • Default HurlStack
  • HurlStack with custom configuration
  • OkHttpStack (recommended)
  • Custom HTTP Stack
• Cookies

Notifications

When you create a new upload request and you start it, Upload Service asks UploadServiceConfig.notificationConfigFactory to create a notification for it. You can set your own notificationConfigFactory and also override the default per single upload using request.setNotificationConfig depending on what you need.

Both UploadServiceConfig.notificationConfigFactory and request.setNotificationConfig have the same interface and expect you to return an UploadNotificationConfig:

// Global default configuration for all uploads
// It's advised you do this one time and right after you have 
// initialized the library in your Application
UploadServiceConfig.notificationConfigFactory = { context, uploadId ->
    // your implementation
}

// Custom configuration for a single upload
// You can do this in any place you find convenient
MultipartUploadRequest(context, "https://my.secure.server")
    .setNotificationConfig { context, uploadId ->
        // your implementation
    }

UploadNotificationConfig

Minimal Upload Notification Config looks like this:

UploadNotificationConfig(
    notificationChannelId = UploadServiceConfig.defaultNotificationChannel!!,
    isRingToneEnabled = true,
    progress = UploadNotificationStatusConfig(
        title = "progress",
        message = "some progress message"
    ),
    success = UploadNotificationStatusConfig(
        title = "success",
        message = "some success message"
    ),
    error = UploadNotificationStatusConfig(
        title = "error",
        message = "some error message"
    ),
    cancelled = UploadNotificationStatusConfig(
        title = "cancelled",
        message = "some cancelled message"
    )
)

It specifies:

• the notification channel on which to operate. You can safely use UploadServiceConfig.defaultNotificationChannel!! which is guaranteed non-null after you performed Upload Service initialization. You can also use another custom notification channel, but remember to create it first and configure it, like you've done with the default one!
• isRingToneEnabled. This affects the behaviour on only Android < API 26 and sets whether you want the notification sound. On Android API >= 26 this setting is done when you create the notification channel.
• progress. Configuration for the notification when the upload is in progress.
• success. Configuration for the notification when the upload has been completed successfully.
• error. Configuration for the notification when the upload has failed.
• cancelled. Configuration for the notification when the upload has been cancelled by the user.

Take also a look to the default which is richer, but keep reading below to understand it fully.

UploadNotificationStatusConfig

Minimal:

UploadNotificationStatusConfig(
    title = "progress",
    message = "message"
)

Take a look to the docs in the code to discover all the available options.

You can use your own localised strings and drawable resources, but keep in mind to only use the context which is given to you in the lambda where you set the notification configuration, to prevent memory leaks and unwanted crashes!

Placeholders

You can make your title and message richer by using Placeholders which gets replaced at runtime by Upload Service with information about the upload. You can use them from the code:

UploadNotificationStatusConfig(
    title = "progress: ${Placeholder.Progress}",
    message = "message"
)

or add the equivalent literal in your strings.xml

<string name="progress">progress: [[PROGRESS]]</string>

and use it:

UploadNotificationStatusConfig(
    title = context.getString(R.string.progress),
    message = "message"
)

You can safely use many placeholders in a single string 😉

Actions

For each UploadNotificationStatusConfig you can specify one or more actions (Google advises a max of 3):

UploadNotificationAction(
    icon = android.R.drawable.ic_menu_close_clear_cancel,
    title = "Cancel",
    intent = context.getCancelUploadIntent(uploadId)
)

The action has an icon (applied only on Android older than 7), a title (you can use localized strings) and a PendingIntent to be performed when the user taps on the action. The PendingIntent can be whatever you need. There are no limitations. To ease you adding an upload cancel option which aborts the upload, you can use context.getCancelUploadIntent(uploadId). This is also the default set in the bundled UploadServiceConfig.notificationConfigFactory.

Notification Handler

By default, Android Upload Service creates one notification for each upload request you make, honoring all the configurations described in the previous paragraphs. The default behaviour may not be what you had in mind for your app, for that reason you can implement your own Notification Handler.

To make things easier for your custom implementation:

• Look at NotificationHandler for a handler which creates one notification for each task.
• Look at AbstractSingleNotificationHandler and ExampleSingleNotificationHandler for a handler which manages a single notification for all the tasks. To allow maximum customisation, in updateNotification method you will get a Map<String, TaskData> where the key is the uploadID and TaskData the last known information about that upload task, including the corresponding UploadNotificationStatusConfig. It's entirely up to you to decide which settings to honor and which to ignore. Remember to call removeTask(uploadID) for the either failed or succeeded tasks you don't want to display anymore to free memory. No automatic garbage collection has been added to allow maximum flexibility.

To set your custom Notification Handler:

UploadServiceConfig.setNotificationHandlerFactory { service ->
  // instantiate your implementation
}

HTTP Stack

By default, Android Upload Service uses system's HttpURLConnection network stack, referred to as HurlStack. It supports OkHttp and has interfaces which allows to implement a custom HTTP Stack.

Default HurlStack

You don't have to do anything. This is the default configuration:

• userAgent: Android Upload Service User Agent
• followRedirects: true
• useCaches: false
• connectTimeoutMillis: 15000
• readTimeoutMillis: 30000

HurlStack with custom configuration

Set it into your Application subclass, right after UploadServiceConfig.initialize. Example:

UploadServiceConfig.httpStack = HurlStack(
    userAgent = "MyCustomUserAgent",
    followRedirects = true,
    useCaches = false,
    connectTimeoutMillis = 20000,
    readTimeoutMillis = 60000
)

OkHttpStack

This is the recommended configuration.

starting from Android 4.4 KitKat, OkHttp is used internally to provide HttpURLConnection implementation, as reported here. The version used changes across different Android releases, so you may experience different behaviours and encounter some known bugs on older releases. To avoid having to deal with that, I suggest you to switch to the OkHttp stack implementation, to be sure to have a consistent behaviour across all Android versions and to have the most updated version of OkHttp as well.

Add this to your build.gradle:

implementation "net.gotev:uploadservice-okhttp:$uploadServiceVersion"

Then sync the project and set the following into your Application subclass, right after UploadServiceConfig.initialize:

UploadServiceConfig.httpStack = OkHttpStack()

This will create a new OkHttpClient with the same default settings as HurlStack. If you're already using OkHttp in your project, you can pass your own client instance to Upload Service like this:

UploadServiceConfig.httpStack = OkHttpStack(yourOkHttpClient)

Custom HTTP Stack

Not finding the HTTP stack you want to use? No problem, you can use your own network stack, too. You have to implement the following interfaces and base classes:

• HttpStack: Connection factory which creates new requests
• HttpRequest: HTTP request implementation
• BodyWriter: HttpRequest delegate which handles writing the request body payload

ServerResponse is the Parcelable data class which holds a response got from the server.

See HurlStack and OkHttp stack implementations as a guideline.

Cookies

Use Android Cookie Store which provides a persistent cookie storage that can be used in conjunction with Android Upload Service, for both HttpURLConnection and OkHttp stacks.