Downloads

This guide describes how to manage file downloads, track a download progress, get a notification when the download has been completed, etc.

Overview

To get a list of all downloads, associated with the specific Profile, including already completed downloads during this application session and the active downloads, use the following approach:

Java
Kotlin
List<Download> downloads = profile.downloads().list();
val downloads = profile.downloads().list()

Using Engine.downloads() you will get the download service for the default profile.

Accepting download

Every time a Browser instance needs to download a file the StartDownloadCallback callback is invoked. In this callback you can decide whether the file should be downloaded, or the download request must be canceled.

Java
Kotlin
browser.set(StartDownloadCallback.class, (params, tell) -> tell.cancel());
browser.set(StartDownloadCallback::class.java, StartDownloadCallback { params, tell -> tell.cancel() })

By default, all download requests are canceled.

To change the default behavior and allow to download a file, use the following approach:

Java
Kotlin
browser.set(StartDownloadCallback.class, (params, tell) -> {
    Download download = params.download();
    // Download target details.
    DownloadTarget downloadTarget = download.target();
    // Tell the engine to download and save the file.
    tell.download(Paths.get(downloadTarget.suggestedFileName()));
});
browser.set(StartDownloadCallback::class.java, StartDownloadCallback { params, tell ->
    val download = params.download()
    // Download target details.
    val downloadTarget = download.target()
    // Tell the engine to download and save the file.
    tell.download(Path(downloadTarget.suggestedFileName()))
})

In the example above we tell the library that the file can be downloaded and saved to a given destination file.

Make sure that the Chromium main process has rights to create files in the given destination directory. If the given directory already has a file with the given name, then the file will be overwritten automatically. We recommend that you check the rights and the file existence before accepting the file download.

Controlling process

To control the download process use the Download instance you can obtain using the StartDownloadCallback.Params.download() method.

For example:

Java
Kotlin
browser.set(StartDownloadCallback.class, (params, tell) -> {
    Download download = params.download();
    // ...
});
browser.set(StartDownloadCallback::class.java, StartDownloadCallback { params, tell ->
    val download = params.download()
    // ...
})

Pausing download

To pause the download use the Download.pause() method:

Java
Kotlin
download.pause();
download.pause()

Resuming download

To resume the paused download use the Download.resume() method:

Java
Kotlin
if (download.isPaused()) {
    download.resume();
}
if (download.isPaused()) {
    download.resume()
}

Canceling download

You can cancel the download anytime unless the download is in a terminated state. This includes the completed downloads, canceled downloads, and interrupted downloads that cannot be resumed.

To find out whether download is in the terminated state, use the Download.isDone() method.

To cancel the download use the Download.cancel() method:

Java
Kotlin
if (download.state() == DownloadState.IN_PROGRESS) {
    download.cancel();
}
if (download.state() == DownloadState.IN_PROGRESS) {
    download.cancel()
}

Download events

You can track the download progress, get notifications when the download has been canceled, paused, interrupted, or finished.

Download canceled

To get notifications when the Download has been canceled use the DownloadCanceled event:

Java
Kotlin
download.on(DownloadCanceled.class, event -> {});
download.on(DownloadCanceled::class.java) { event -> }

Download finished

To get notifications when the Download has been finished use the DownloadFinished event:

Java
Kotlin
download.on(DownloadFinished.class, event -> {});
download.on(DownloadFinished::class.java) { event -> }

Download paused

To get notifications when the Download has been paused use the DownloadPaused event:

Java
Kotlin
download.on(DownloadPaused.class, event -> {});
download.on(DownloadPaused::class.java) { event -> }

Download updated

To track the download progress use the DownloadUpdated event:

Java
Kotlin
download.on(DownloadUpdated.class, event -> {
    // Print download progress in percents.
    event.progress().ifPresent(progress ->
            System.out.println((int) (progress.value() * 100) + "%"));
    // The current download speed estimate in bytes/second.
    long currentSpeed = event.currentSpeed();
    // The total size of a file in bytes.
    long totalBytes = event.totalBytes();
    // The number or received (downloaded) bytes.
    long receivedBytes = event.receivedBytes();
});
download.on(DownloadUpdated::class.java) { event ->
    // Print download progress in percents.
    event.progress().ifPresent { progress ->
        println("${(progress.value() * 100).toInt()}%")
    }
    // The current download speed estimate in bytes/second.
    val currentSpeed = event.currentSpeed()
    // The total size of a file in bytes.
    val totalBytes = event.totalBytes()
    // The number or received (downloaded) bytes.
    val receivedBytes = event.receivedBytes()
}

Download interrupted

To get notifications when the Download has been interrupted for some reason use the DownloadInterrupted event:

Java
Kotlin
download.on(DownloadInterrupted.class, event -> {
    // The interrupt reason such as file access denied, network failed, etc.
    DownloadInterruptReason reason = event.reason();
});
download.on(DownloadInterrupted::class.java) { event ->
    // The interrupt reason such as file access denied, network failed, etc.
    val reason = event.reason()
}