Contents
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:
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.
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:
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:
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:
download.pause();
download.pause()
Resuming download
To resume the paused download use the Download.resume() method:
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:
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:
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:
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:
download.on(DownloadPaused.class, event -> {});
download.on(DownloadPaused::class.java) { event -> }
Download updated
To track the download progress use the DownloadUpdated event:
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:
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()
}