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); // 로컬 디스크에서 콘텐츠 부분 파일이 인식되면 복원
} else {
mDownloadDBHelper.delete(iter); // 로컬 파일이 임의 삭제된 경우 DB에서 제거
}
}
KollusContent.isLoaded()는 SDK가 디스크에 실제 콘텐츠 파일이 존재하는지 확인한 결과입니다.
다운로드 상태 플래그
목록 렌더링 및 예외 처리를 구현할 때 사용하는 KollusContent 핵심 플래그 속성 정의입니다.
| 플래그 | 의미 |
|---|---|
isDownloading() | 다운로드 진행 중 |
isDownloadCompleted() | 다운로드 완료 |
isDownloadError() | 직전 다운로드 시도 실패 |
isLoaded() | 메타 정보를 로드(load)가 완료되어 SDK 내부에 콘텐츠가 정상 인식된 상태 |
setDownloading(boolean)과 같은 내부 Setter 메서드는 SDK가 콜백 내부에서 상태 전이를 처리하기 위해 가공하는 속성입니다.
애플리케이션 레이어 코드에서 임의로 가공하거나 강제로 값을 주입(Set)하지 마세요. 내부 상태 동기화 흐름이 훼손되어 비정상 동작을 유발할 수 있습니다.
다운로드 완료 콘텐츠 관리
SDK가 제공하는 기본 getDownloadList() API만으로도 다운로드 완료된 콘텐츠 목록을 구성할 수 있습니다.
다만, 공식 샘플 앱은 별도의 Room 데이터베이스 테이블인 KollusContentEntity를 구축하여 폴더별 조회 및 정렬 등의 UI 기능을 구현합니다.
해당 로컬 DB 구조는 연동 필수 사항이 아니며, 프로젝트 인프라 UI/UX 요구 사양에 맞춰 선택적으로 적용 가능한 참조용 구현 모델입니다.
// 다운로드 완료 콜백 이벤트 시점에 KollusContentEntity 레코드를 DB에 추가
KollusContentEntity completeContent = new KollusContentEntity(/* 생성자 필드 */);
mKollusContentViewModel.insertKollusContent(completeContent);
// 특정 폴더 경로의 콘텐츠 목록 조회 (filepath: 현재 폴더 경로)
List<KollusContentEntity> folderList = mKollusContentViewModel.findFolderList(filepath);
비교: KollusDownloadContentEntity vs KollusContentEntity
| 구분 | KollusDownloadContentEntity | KollusContentEntity |
|---|---|---|
| 관리 목적 | 다운로드 진행 및 중단 상태 추적 | 다운로드 완료 콘텐츠 목록 구성 및 관리 |
| 데이터 라이프사이클 | 다운로드 시작 시점 생성 ~ 완료/삭제 시 소멸 | 다운로드 완료 시점 생성 ~ 사용자 삭제 시 소멸 |
| 필수 여부 | 앱 재시작 후 큐 복원 처리를 위해 필요 | 선택사항 (SDK가 제공하는 API로 대체 가능) |