4. Download List Management

Explains how to query and manage content data registered in the SDK storage by status. In particular, this document covers local DB storage patterns for safely restoring the previous download queue list even in environments where the application restarts due to network disconnection or forced termination.

All example code in this document is based on the official sample app kollus_player_v2_android.

Query download content list

Query method	API	Notes
All downloaded content by disk	`multiStorage.getDownloadList(diskIndex)`	Specify `diskIndex == -1` to query across all disks
Query by single content key (mck)	`storage.getKollusContent(content, mck)`	Loads a single object matching the `mck`
Query by local path	`multiStorage.getDownloadKollusContent(path)`	Converts to `MultiKollusContent` type
Download execution status (global)	`DownloadService.isDownloading()`	Static method to check current download status

The list array returned by the getDownloadList method contains a mix of content objects in downloading, completed, and failed states. Therefore, when building the actual UI list, you must explicitly branch using KollusContent flag conditions by referring to the Download status flags section below.

Save metadata to local DB

The official sample app stores and manages the download task queue in a Room-based local DB to ensure the reliability of the download pipeline. (See the KollusContentRepository, KollusDownloadContentEntity pattern)

KollusDownloadContentEntity is a data model for precisely tracking tasks that are currently in progress or temporarily suspended. It stores real-time progress rates and status codes so that the previous download queue array can be fully restored even after the app is force-closed and restarted.

Once the download of the content is complete, the lifecycle of this entity ends. For managing completed files, refer to the Completed content management section below.

`KollusDownloadContentEntity` column specifications

Column	Type	Description
`filename`	`String`	Content filename
`thumbnail_path`	`String`	Local thumbnail image path
`download_start`	`long`	Timestamp when the download task first started (epoch milliseconds)
`download_file_size`	`long`	Content file size
`download_receiving_size`	`long`	Received size
`download_status`	`int`	Download status code (0: pending)
`disk_index`	`int`	Local disk index where content will be stored
`disk_type`	`int`	Disk type (internal or SD)
`download_percent`	`int`	Download progress (0–100)
`media_content_key`	`String`	Media content key (mck)
`folder`	`String`	User custom classification folder path

Download restoration pipeline after app restart

// DownloadService.onCreate()
Vector<DownloadInfo> list = mDownloadDBHelper.list();
for (DownloadInfo iter : list) {
    if (iter.getMultiKollusContent().getKollusContent().isLoaded()) {
        mDownloadInfoList.add(iter);   // Restore if partial content file is recognized on local disk
    } else {
        mDownloadDBHelper.delete(iter); // Remove from DB if local file has been deleted arbitrarily
    }
}

KollusContent.isLoaded() is the result of the SDK checking whether the actual content file exists on disk.

Download status flags

Definitions of key KollusContent flag properties used when implementing list rendering and exception handling.

Flag	Description
`isDownloading()`	Download in progress
`isDownloadCompleted()`	Download completed
`isDownloadError()`	Previous download attempt failed
`isLoaded()`	Metadata `load` has completed and the content is properly recognized within the SDK

Caution

Internal setter methods such as setDownloading(boolean) are properties that the SDK processes internally within callbacks to handle state transitions. Do not arbitrarily modify or forcibly inject (set) values from application layer code. Doing so may corrupt the internal state synchronization flow and cause abnormal behavior.

Completed content management

You can build a list of downloaded content using only the basic getDownloadList() API provided by the SDK. However, the official sample app builds a separate Room database table, KollusContentEntity, to implement UI features such as folder-based queries and sorting. This local DB structure is not a mandatory integration requirement and is an optional reference implementation model that can be applied selectively according to the UI/UX requirements of your project infrastructure.

// Add a KollusContentEntity record to the DB at the point of the download completion callback event
KollusContentEntity completeContent = new KollusContentEntity(/* constructor fields */);
mKollusContentViewModel.insertKollusContent(completeContent);

// Query content list for a specific folder path (filepath: current folder path)
List<KollusContentEntity> folderList = mKollusContentViewModel.findFolderList(filepath);

Compare: `KollusDownloadContentEntity` vs `KollusContentEntity`

	`KollusDownloadContentEntity`	`KollusContentEntity`
Purpose	Track download progress and suspended states	Build and manage completed download content list
Data lifecycle	Created at download start ~ destroyed on completion/deletion	Created at download completion ~ destroyed on user deletion
Required	Required for queue restoration after app restart	Optional (can be replaced with APIs provided by the SDK)

Query download content list​

Save metadata to local DB​

KollusDownloadContentEntity column specifications​

Download restoration pipeline after app restart​

Download status flags​

Completed content management​

Compare: KollusDownloadContentEntity vs KollusContentEntity​