4. ダウンロードリスト管理
このドキュメントは機械翻訳で作成された下書きであり、現在レビュー中です。機械翻訳の特性上、一部の内容が不正確であったり、韓国語の原文と異なる場合があります。より正確な情報については、韓国語のドキュメントをご参照ください。
SDK ストレージに登録されたコンテンツデータを状態別に照会・管理する方法について説明します。 特に、ネットワーク切断や強制終了などアプリケーションが再起動される環境でも、直前のダウンロードアップロードキュー(Queue)リストを安全に復元するためのローカル DB 保存パターンを併せて扱います。
このドキュメントのすべてのサンプルコードは、公式サンプルアプリ kollus_player_v2_android をもとに作成されています。
ダウンロードコンテンツリストの照会
| リスト照会方法 | API | 備考 |
|---|---|---|
| ディスク別全ダウンロードコンテンツ | multiStorage.getDownloadList(diskIndex) | diskIndex == -1 指定時は全ディスク統合照会 |
| 単一コンテンツキー(mck)ベースの照会 | storage.getKollusContent(content, mck) | mck と一致する単一オブジェクトデー タをロード |
| ローカルパスベースの照会 | multiStorage.getDownloadKollusContent(path) | MultiKollusContent 型への変換 |
| ダウンロード実行状態（グローバル） | DownloadService.isDownloading() | 静的(static)メソッドで現在のダウンロード状態を確認 |
getDownloadList メソッドが返すリスト配列には、ダウンロード中・完了・失敗状態のコンテンツオブジェクトが混在しています。
そのため、実際の UI リストを構成する際は、下記のダウンロード状態フラグ定義セクションを参照し、KollusContent フラグ条件によって明示的に分岐処理する必要があります。
メタデータのローカル DB 保存
公式サンプルアプリは、ダウンロードパイプラインの安全性を保証するために、ダウンロードタスクアップロードキューを Room ベースのローカル DB に保存して管理します。（KollusContentRepository、KollusDownloadContentEntity パターン参照）
KollusDownloadContentEntity は、ダウンロードが現在進行中または一時的に中断された状態のタスクを精密に追跡するためのデータモデルです。
アプリが強制終了後に再起動されても、直前のダウンロードアップロードキュー配列をそのまま復元できるよう、リアルタイムの進行率と状態コードを保存します。
該当コンテンツのダウンロードが完了すると、このエンティティのライフサイクルは終了します。完了したファイルの管理については、下記のダウンロード完了コンテンツ管理セクションを参照してください。
KollusDownloadContentEntity カラム仕様
| カラム | タイプ | 意味 |
|---|---|---|
filename | String | コンテンツファイル名 |
thumbnail_path | String | ローカルサムネイル画像パス |
download_start | long | ダウンロードタスクが最初に開始されたタイムスタンプ(epoch milliseconds) |
download_file_size | long | コンテンツファイルサイズ |
download_receiving_size | long | 受信済みサイズ |
download_status | int | ダウンロード状態コード（0: 待機状態） |
disk_index | int | コンテンツが保存されるローカルディスクインデックス |
disk_type | int | ディスクタイプ（内蔵または SD） |
download_percent | int | ダウンロード進行率（0〜100） |
media_content_key | String | メディアコンテンツキー(mck) |
folder | String | ユーザーカスタム分類フォルダーパス |
アプリ再起動後のダウンロード復元パイプライン
// DownloadService.onCreate()
Vector<DownloadInfo> list = mDownloadDBHelper.list();
for (DownloadInfo iter : list) {
if (iter.getMultiKollusContent().getKollusContent().isLoaded()) {
mDownloadInfoList.add(iter); // Restore if a partial content file is recognized on local disk
} else {
mDownloadDBHelper.delete(iter); // Remove from DB if the local file has been deleted arbitrarily
}
}
KollusContent.isLoaded() は、SDK がディスク上に実際のコンテンツファイルが存在するかどうかを確認した結果です。
ダウンロード状態フラグ
リストレンダリングおよび例外処理を実装する際に使用する KollusContent の主要フラグプロパティの定義です。
| フラグ | 意味 |
|---|---|
isDownloading() | ダウンロード進行中 |
isDownloadCompleted() | ダウンロード完了 |
isDownloadError() | 直前のダウンロード試行失敗 |
isLoaded() | メタ情報のロード(load)が完了し、SDK 内部にコンテンツが正常に認識された状態 |
setDownloading(boolean) などの内部 Setter メソッドは、SDK が Callback 内部で状態遷移を処理するために使用するプロパティです。
アプリケーションレイヤーのコードから任意に操作したり、強制的に値を注入(Set)したりしないでください。内部状態同期フローが破損し、異常動作を引き起こす可能性があります。
ダウンロード完了コンテンツ管理
SDK が提供する基本の getDownloadList() API のみでも、ダウンロード完了済みコンテンツリストを構成することができます。
ただし、公式サンプルアプリは別途の Room データベーステーブルである KollusContentEntity を構築し、フォルダー別照会やソートなどの UI 機能を実装しています。
このローカル DB 構造は連携必須事項ではなく、プロジェクトインフラの UI/UX 要件に合わせて選択的に適用可能な参照用実装モデルです。
// Add a KollusContentEntity record to the DB at the download completion callback event
KollusContentEntity completeContent = new KollusContentEntity(/* constructor fields */);
mKollusContentViewModel.insertKollusContent(completeContent);
// Query the content list for a specific folder path (filepath: current folder path)
List<KollusContentEntity> folderList = mKollusContentViewModel.findFolderList(filepath);
比較：KollusDownloadContentEntity vs KollusContentEntity
| 区分 | KollusDownloadContentEntity | KollusContentEntity |
|---|---|---|
| 管理目的 | ダウンロード進行および中断状態の追跡 | ダウンロード完了コンテンツリストの構成と管理 |
| データライフサイクル | ダウンロード開始時点に生成〜完了/削除時に消滅 | ダウンロード完了時点に生成〜ユーザー削除時に消滅 |
| 必須有無 | アプリ再起動後のアップロードキュー復元処理に必要 | オプション（SDK が提供する API で代替可能） |