34 lines
2.2 KiB
Markdown
34 lines
2.2 KiB
Markdown
|
# lockstep-jukebox
|
|||
|
|
|
|||
|
|
Gradle project containing **jukebox**, an Android library that implements the **data layer** for a music player: it syncs playlist and track **metadata** from the Lockstep Spotify wrapper API (`https://api.lockstep.at`) into a local **SQLite** database (via Room), so the app can read playlists and tracks offline after sync.
|
|||
|
|
|
|||
|
|
Repository layout:
|
|||
|
|
|
|||
|
|
- **`jukebox/`** — Android library (Java, Retrofit, Gson, Room).
|
|||
|
|
- **`docs/playlists.md`** — HTTP contract for `GET /playlists` and `GET /playlists/{id}`.
|
|||
|
|
- **`schema/playlist_cache.sql`** — reference schema for the on-device cache tables.
|
|||
|
|
|
|||
|
|
The library does **not** handle Spotify login, audio playback, or full Spotify API modeling—only what’s needed to cache the metadata described in the docs.
|
|||
|
|
|
|||
|
|
## Main entry points
|
|||
|
|
|
|||
|
|
| Entry | Role |
|
|||
|
|
| --- | --- |
|
|||
|
|
| **`Jukebox.playlistRepository(Context, Interceptor)`** | Convenience factory. Builds `DefaultPlaylistRepository` with default base URL `https://api.lockstep.at/`. Optional overload passes a custom **`baseUrl`**. You supply an **`Interceptor`** so session cookies, `Authorization`, or other headers stay in the host app. |
|
|||
|
|
| **`DefaultPlaylistRepository.create(...)`** | Same wiring as `Jukebox`; use when you prefer a static factory on the concrete type. |
|
|||
|
|
| **`PlaylistRepository`** | Primary API surface after construction: **`syncInitial()`** (full refresh), **`syncDelta(retainRemovedPlaylists)`** (incremental sync using `snapshot_id`), **`observePlaylists()`** / **`getPlaylists()`**, **`observeTracks(playlistId)`** / **`getTracks(playlistId)`**. Sync methods **block** and perform I/O—call them off the main thread. Observation returns **`LiveData`** for lifecycle-friendly UI updates. |
|
|||
|
|
| **`LockstepPlaylistClient`** | Interface implemented by **`PlaylistRemoteClient`**. Lets tests or advanced setups swap the network backend without changing **`SyncCoordinator`**. |
|
|||
|
|
|
|||
|
|
Errors from the API’s `{ "ok": false, "error": "..." }` shape are thrown as **`LockstepApiException`**. Network failures use **`IOException`**.
|
|||
|
|
|
|||
|
|
## Building
|
|||
|
|
|
|||
|
|
From the repo root (with `ANDROID_HOME` / `local.properties` **`sdk.dir`** set):
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
./gradlew :jukebox:assembleDebug
|
|||
|
|
./gradlew :jukebox:testDebugUnitTest
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
On Windows, use `gradlew.bat` instead of `./gradlew`.
|