How tbiyiktas/android-sqlite-orm works
Project Type and Purpose
• This is an Android mobile application that demonstrates and bundles a lightweight Object-Relational Mapping (ORM) library for SQLite.
• The app module contains both a sample UI (MainActivity) and the full persistence library under lib/persistence.
• The ORM library provides annotation-based mapping, a generic repository API, builder-style queries, command objects, asynchronous callbacks, and clean-code separation.
File Structure Analysis
Top-level “app” module:
• app/src/main/java/com/example/adbkit/MainActivity.java → Presentation layer (Android UI).
• app/src/main/java/lib/persistence/... → Persistence library packages:
– annotations (mapping annotations)
– command/definition, command/manipulation, command/query (Command pattern for DDL/DML/queries)
– domain/entities (model classes, e.g., Todo, Person)
– repositories (concrete TodoRepository)
– profile (metadata, mappers)
– core classes: ADbContext, GenericRepository, RepositoryFactory, DbCallback, DbResult
• Resources: layouts, drawables, XML backup/data-extraction rules.
• Tests: unit and instrumentation tests for both UI and persistence.
README Insights
• ORM Features: annotation-based mapping, generic CRUD repository, fluent SelectQuery builder, asynchronous callbacks, clean architectures (SRP, DRY, DI).
• Usage: define model with @DbTableAnnotation/@DbColumnAnnotation, extend ADbContext for DB setup, extend GenericRepository<T> for model repos, then call insert(), selectWhere(), etc.
Main Components
a. Presentation Layer
• Android Activity/Fragment (MainActivity)
• Android UI framework (View, Layout XML)
b. Domain Layer
• Entity classes (Todo, Person)
c. Persistence Layer (ORM Library)
• Annotation Processor / Metadata Cache (@DbTableAnnotation, @DbColumnAnnotation, RowMapper, Mapper)
• Repository API (GenericRepository<T>, TodoRepository)
• DbContext (ADbContext subclass) → manages SQLiteDatabase lifecycle
• Command Objects
– DDL (CreateTableCommand, DropTableCommand, etc.)
– DML (InsertCommand, UpdateCommand, DeleteCommand)
– Query (SelectQuery, GetQuery)
• Callback mechanism (DbCallback<T>, DbResult<T>) for async operations
d. Data Store
• Android’s built-in SQLiteDatabase engine
e. External / Configuration
• ProGuard/R8 rules, Gradle build system, backup & data-extraction XML
Interactions and Data Flow
1. UI triggers an action (e.g., “Add Todo”) → calls into TodoRepository.insert(...).
2. TodoRepository (extends GenericRepository<Todo>) builds an InsertCommand via repository internals.
3. GenericRepository delegates to ADbContext to get a writable SQLiteDatabase.
4. ADbContext constructs SQL (using metadata from annotations) and executes it on SQLiteDatabase.
5. Operation runs asynchronously on a background thread; result is returned via DbCallback<DbResult<T>>.
6. UI receives callback on success/failure and updates the view.
Architectural Patterns & Principles
• Repository Pattern: decouples data access from business logic/UI.
• Builder Pattern: SelectQuery fluent API for safe, parameterized queries.
• Command Pattern: encapsulates SQL operations in command objects.
• Dependency Injection: inject ADbContext into repositories via constructors.
• Clean Code: SRP (annotations vs. mapping vs. commands in separate packages), DRY (shared SQL utils), testability (interfaces, callbacks).