How long02041/ketch works
This project is an Android file downloader library named “Ketch”. Its purpose is to simplify file downloads in Android applications by leveraging WorkManager, while offering features like pause/resume, parallel downloads, and comprehensive notification support. Additionally, there’s a sample Android application (the “app” module) demonstrating how to integrate and use the Ketch library.
Main Components
• Library Module (“ketch”): This is the core of the file downloader library. It contains the full download logic, including network calls, persistence, background work, notifications, and utility functions.
• Sample Application (“app”): This module demonstrates usage in a real-world scenario. It contains the user interface (activities, fragments) and integrates with Ketch to trigger downloads and observe their status.
• External Android Components: Standard Android components such as the WorkManager service (for scheduling work), Retrofit/OkHttp (for network communications), and the Android Notification framework.
Decompose the Library (Ketch Module) Into Sub-Components
a. Download Management:
• Ketch.kt: The entry point and singleton instance built using the builder pattern.
• DownloadManager.kt & DownloadTask.kt: Handle the initiation and management of download requests.
• DownloadRequest.kt: Encapsulates parameters for a download (including URL, file name, path, headers, etc).
• DownloadTitles.kt: Used to customize titles for various download states.
b. Database Persistence:
• DatabaseInstance.kt, DownloadDatabase.kt, DownloadDao.kt, and DownloadEntity.kt: Manage persistent storage of download information such as progress, status, and meta-data.
c. Network Layer:
• RetrofitInstance.kt and DownloadService.kt: These components deal with network calls. Ketch uses Retrofit (and under the hood OkHttp) to facilitate HTTP requests for downloads.
• ApiResponseHeaderChecker.kt: Performs validations and header checks on network responses.
d. Notification & UI Feedback:
• DownloadNotificationManager.kt, NotificationReceiver.kt: Manage download notifications, updating the user on progress, success, failure etc.
• ButtonTextConfig.kt: Provides customizable notification button text.
e. Utility Components:
• Various utility classes in the internal/utils package (FileUtil.kt, MapperUtil.kt, TextUtil.kt, etc): Support operations like file handling, logging, exception handling, and formatting of download info.
f. Worker Integration:
• The worker module (DownloadWorker.kt and related classes in the internal/worker package): This manages the actual background work using WorkManager. It guarantees downloads continue regardless of the app state, ensuring resilience.
Component Interactions
• The Sample App (“app” module) interacts with the Ketch library by initializing it (via its builder pattern in MainApplication.kt), calling download(), and observing download progress through coroutine-based flows.
• Once a download is initiated, Ketch delegates the work to the DownloadManager. Download requests are queued and executed in the background via WorkManager (DownloadWorker).
• The network layer (RetrofitInstance and DownloadService) handles file retrieval from the internet. DownloadManager coordinates with these components.
• Progress and state updates are persisted in the local database. Observers (using Flow) in the sample application receive updates when there’s a status change.
• Internal utilities support data transformations and logging for debugging and operational insights.
Architectural Patterns and Design Principles
• Separation of Concerns – Each module (download handling, persistence, network, notifications) is isolated, making it easy to maintain and test.
• Singleton and Builder Patterns – Ketch is implemented as a singleton with a builder for customization.
• Asynchronous Processing – Heavy reliance on Kotlin coroutines and Flow to observe state and handle background tasks.
• Use of WorkManager – Ensures the background process (downloads) is robust even if the application is in the background.