Room: nədir, ORM kitabxanası və SQLite ilə iş

Room ORM kitabxanası nədir?

Room Android Jetpack paketinə daxil olan, Google tərəfindən Android platformasında lokal SQLite verilənlər bazaları ilə işi asanlaşdırmaq üçün yaradılmış ORM kitabxanasıdır. O, məlumat sxemini təsvir etmək üçün annotasiyalar təmin edir və kompilasiya mərhələsində DAO interfeyslərinin implementasiyasını avtomatik yaradır. SQLiteOpenHelper-in birbaşa istifadəsindən fərqli olaraq, Room tərtibatçını verilənlər bazası ilə əlaqə yaratmaq, açmaq və idarə etmək üçün əhəmiyyətli miqdarda şablon kodu yazmaqdan azad edir.

Kitabxana Google I/O 2017-də Android arxitektura komponentlərinin bir hissəsi kimi təqdim edilmişdir. O zamandan bəri Room lokal məlumat saxlama üçün de-fakto standarta çevrilmiş, Android üçün GreenDAO və Realm kimi həlləri populyarlıqda geridə qoymuşdur. Google məlumatlarına görə, kitabxana Google Play-də dərc edilmiş, cihazda lokal məlumatlarla işləyən tətbiqlərin 60%-dən çoxunda istifadə olunur.

Əsas xüsusiyyət — annotasiya prosessoru vasitəsilə SQL sorğularının kompilasiya mərhələsində yoxlanılması. Əgər tərtibatçı SQL əmrində səhv edərsə, məsələn, mövcud olmayan sütun adı göstərərsə, tətbiq quraşdırılmazdan əvvəl kompilasiya xəta ilə başa çatır. Bu, SQLiteOpenHelper yanaşmasından köklü şəkildə fərqlənir, bu cür səhvlər yalnız icra zamanı, çox vaxt istehsalda aşkar edilir.

Qeyri-standart tiplər üçün TypeConverter-lər

SQLite yalnız beş məlumat tipini dəstəkləyir: TEXT, INTEGER, REAL, BLOB və NULL. Lakin Java və Kotlin-də mürəkkəb tiplər istifadə olunur: Date, List, Enum və fərdi obyektlər. Onları saxlamaq üçün Room TypeConverters mexanizmini təmin edir — mürəkkəb tipi SQLite üçün anlaşılan primitiv tipə çevirən statik metodlar. Məsələn, Date obyekti Long-a (timestamp), List<String> isə Gson və ya Moshi vasitəsilə JSON sətrinə çevrilir.

@Database(entities = [User::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}

val db = Room
    .databaseBuilder(context, AppDatabase::class.java, "app-db")
    .build()

Konvertoru elan etmək üçün statik metoda @TypeConverter annotasiyası əlavə etmək və verilənlər bazası səviyyəsində @TypeConverters annotasiyasında konvertor sinfini göstərmək kifayətdir. Room hər SQL sorğusunda müvafiq tipin oxunması və yazılması zamanı konvertoru avtomatik tətbiq edir, çevirmə metodlarını əl ilə çağırmağa ehtiyac qalmır.

Room arxitekturası: üç əsas komponent

Room üç əsas komponentdən ibarətdir: Entity, DAO və Database. Hər biri ciddi şəkildə müəyyən edilmiş rol oynayır və müvafiq annotasiya ilə işarələnir. Birlikdə onlar tətbiqin biznes məntiqini SQLite implementasiya detallarından təcrid edən tam hüquqlu məlumat giriş qatını təşkil edirlər.

Entity — verilənlər bazası cədvəli

Entity bazada bir cədvəlin strukturunu təsvir edən məlumat sinfidir. Sinfin hər bir sahəsi cədvəl sütununa, bazadakı hər bir sətir isə sinfin bir nümunəsinə uyğun gəlir. @Entity annotasiyası Room-a sinfin cədvəl olduğunu bildirir. @PrimaryKey annotasiyası olan sahə avtomatik artan və ya mürəkkəb ola bilən əsas açarı təyin edir. Cədvəllər arasında əlaqə üçün @ForeignKey istifadə olunur, baza səviyyəsində məlumat bütövlüyünü təmin edir.

@Entity(tableName = "users")
data class User(
    @PrimaryKey(autoGenerate = true)
    val id: Int = 0,
    @ColumnInfo(name = "full_name")
    val name: String,
    val age: Int,
    val email: String
)

DAO — məlumat əməliyyatları

DAO (Data Access Object) məlumatlarla işləmək üçün əməliyyatları bəyan edən interfeys və ya abstrakt sinifdir: daxiletmə, oxuma, yeniləmə və silmə. Hər bir əməliyyat @Insert, @Query, @Update və ya @Delete ilə annotasiya olunur. Room bu interfeysin implementasiyasını kompilasiya mərhələsində avtomatik yaradır. Xüsusi dəyər @Query annotasiyasına malikdir — o, SQL sorğusunu sətir kimi qəbul edir və onun düzgünlüyünü kompilasiya mərhələsində yoxlayır.

@Dao
interface UserDao {
    @Insert
    suspend fun insert(user: User): Long

    @Query("SELECT * FROM users WHERE id = :userId")
    suspend fun getUserById(userId: Int): User?

    @Query("SELECT * FROM users")
    fun getAllUsers(): Flow<List<User>>

    @Delete
    suspend fun delete(user: User)
}

Database — giriş nöqtəsi

Database RoomDatabase-dən miras alan, verilənlər bazasına giriş nöqtəsi kimi xidmət edən abstrakt sinifdir. O, bütün Entity-lərin siyahısını ehtiva edir və DAO əldə etmək üçün abstrakt metodlar təqdim edir. Sinif @Database ilə annotasiya olunur, burada sxem versiyası və varlıqların siyahısı göstərilir. Baza nümunəsinin yaradılması Room.databaseBuilder vasitəsilə tətbiq konteksti, fayl adı və Database sinfi göstərilməklə həyata keçirilir.

Room SQLite ilə daxili olaraq necə işləyir

Room SQLite-i əvəz etmir, əksinə onun üzərində abstraksiya qatı kimi işləyir. Daxili arxitektura annotasiya prosessorunu, kod generatorunu və əlaqə hovuzunu əhatə edir. Kompilasiya mərhələsində annotasiya prosessoru Entity, DAO və Database siniflərini təhlil edir, sonra _Impl şəkilçisi ilə implementasiya siniflərini yaradır. Bütün yaradılmış siniflər kompilasiya paketinə yerləşdirilir və tərtibatçıya birbaşa görünmür.

Kompilasiya mərhələsində kodun yaradılması Room-un mərkəzi mexanizmidir. Hər bir DAO interfeysi üçün bütün annotasiya olunmuş metodların tam implementasiyası ilə sinif yaradılır. @Query annotasiyasından SQL sorğuları düzgünlük baxımından yoxlanılır: prosessor sütun adlarını Entity sahələri ilə uyğunlaşdırır və SQL sintaksisini yoxlayır. Xəta aşkar edildikdə, kompilasiya başa düşülən mesajla dayandırılır. Bu, xammal SQLiteOpenHelper istifadəsi ilə mümkün deyil, orada səhvlər yalnız runtime-də üzə çıxır.

Kompilasiya mərhələsində kodun yaradılması

Yaratma prosesi üç mərhələdən ibarətdir. Birinci — sxemin yoxlanılması: prosessor @Database-də sadalanan bütün siniflərin düzgün Entity olub-olmadığını yoxlayır. İkinci — DAO gövdəsinin yaradılması: hər bir metod üçün hazırlanmış sorğuları yerinə yetirən daxili RoomSQLiteQuery obyektindən istifadə edərək implementasiya yaradılır. Üçüncü — Database_Impl sinfinin yaradılması, bazanın yaradılması və açılmasını, həmçinin bütün DAO obyektlərinin inisializasiyasını həyata keçirir.

class UserDao_Impl(private val __db: RoomDatabase) : UserDao {
    private val __insertionAdapter = __db
        .createInsertionAdapter(User::class, 0)

    override suspend fun insert(user: User): Long {
        __db.assertNotSuspendingTransaction()
        return __db.runInTransaction {
            __insertionAdapter.insertAndReturnId(user)
        }
    }
}

Room baza əməliyyatları üçün ayrıca thread hovuzu yaratmır. Defolt olaraq sorğular çağıran thread-də bir məhdudiyyətlə yerinə yetirilir: oxuma və yazma thread-i bloklayır. Asinxron iş üçün Room Kotlin korutinləri ilə suspend-funksiyalar vasitəsilə, LiveData ilə qaytarılan dəyərlər vasitəsilə və Flow ilə reaktiv sarğıclar vasitəsilə inteqrasiya olunur. Bu, tərtibatçıya konkret tapşırıq üçün arxitektura həllini seçməkdə çeviklik verir.

Room-dan Android tətbiqində istifadə nümunəsi

Room istifadə edərək qeydləri saxlamaq üçün tətbiq yaratmağın praktik nümunəsinə baxaq. Tətbiq id, title, content və timestamp sahələri olan bir Note cədvəlini ehtiva edir. İstifadəçi qeydlər əlavə edə, baxa və silə biləcək. Nümayiş üçün asinxron əməliyyatlar üçün korutinlərdən istifadə olunur.

Gradle asılılıqlarının konfiqurasiyası

Room-u Android layihəsinə qoşmaq üçün tətbiq modulunun build.gradle faylına asılılıqlar əlavə etmək lazımdır. Room üç komponent tələb edir: runtime kitabxanası, kapt annotasiya prosessoru və korutinlər üçün opsional dəstək. Kitabxana versiyası yeniləmə rahatlığı üçün room_version dəyişənində göstərilir. Room 2.4.0-dan başlayaraq, daha yüksək kompilasiya sürəti ilə kapt-a alternativ olaraq KSP dəstəklənir.

dependencies {
    def room_version = "2.6.1"
    implementation "androidx.room:room-runtime:$room_version"
    kapt "androidx.room:room-compiler:$room_version"
    implementation "androidx.room:room-ktx:$room_version"
    // Opsional: test etmə
    testImplementation "androidx.room:room-testing:$room_version"
}

Asılılıqlar konfiqurasiya edildikdən sonra üç fayl yaradılır: Note Entity, NoteDao interfeysi və AppDatabase sinfi. Note Entity-si @PrimaryKey və @ColumnInfo annotasiyaları olan sahələri ehtiva edir. DAO daxiletmə, siyahı əldə etmə və silmə üçün metodlar təqdim edir. Database @Database annotasiyası vasitəsilə Entity və DAO-nu birləşdirir.

@Entity(tableName = "notes")
data class Note(
    @PrimaryKey(autoGenerate = true)
    val id: Int = 0,
    val title: String,
    val content: String,
    @ColumnInfo(name = "created_at")
    val timestamp: Long = System.currentTimeMillis()
)

@Dao
interface NoteDao {
    @Insert
    suspend fun insert(note: Note)

    @Query("SELECT * FROM notes ORDER BY created_at DESC")
    fun getAllNotes(): Flow<List<Note>>

    @Delete
    suspend fun delete(note: Note)
}

AppDatabase faylı RoomDatabase-dən miras alan abstrakt sinif kimi elan edilir. @Database annotasiyasında cari versiyanın bütün Entity-ləri və sxem versiya nömrəsi göstərilir. Nümunə əldə etmək üçün tətbiq konteksti ilə Room.databaseBuilder build metodu vasitəsilə singleton nümunəsindən istifadə olunur. Baza nümunəsinin keşləşdirilməsi yaddaş sızmasına səbəb ola biləcək çoxsaylı yaratmaların qarşısını alır.

Room-da verilənlər bazası miqrasiyaları

Miqrasiyalar Room-da mövcud məlumatları itirmədən tətbiq yeniləməsi zamanı verilənlər bazası sxemini dəyişdirmək üçün mexanizmdir. İstifadəçi dəyişdirilmiş Entity-lərlə yeni versiya quraşdırdıqda, Room versiyaların uyğunsuzluğunu aşkar edir və göstərilən miqrasiya addımlarını yerinə yetirir. Miqrasiya olmadan verilənlər bazası silinəcək və yenidən yaradılacaq, bu da bütün saxlanmış istifadəçi məlumatlarının itirilməsinə səbəb olacaq.

Miqrasiya bazanın ilkin və son versiyasını qəbul edən Migration sinfi ilə təsvir olunur. migrate metodu daxilində sxemi dəyişdirmək üçün ALTER TABLE və ya CREATE TABLE SQL sorğusu yerinə yetirilir. Room sxem dəyişikliklərini avtomatik müəyyən edə bilmir — tərtibatçı Entity-də hər dəyişiklik üçün əl ilə miqrasiya yazmalıdır. Room 2.4.0 versiyasından başlayaraq, miqrasiyaların avtomatik yaradılması üçün eksperimental autoMigrations funksiyası mövcuddur.

autoMigrations ilə avtomatik miqrasiyalar

autoMigrations funksiyası Room-a Entity versiyaları arasındakı fərqlər əsasında miqrasiyaları avtomatik yaratmağa imkan verir. İstifadə etmək üçün @Database-də @AutoMigration annotasiyası əlavə etmək və sxemin JSON-a ixracını təyin etmək kifayətdir. Room qonşu versiyaların sxemlərini müqayisə edir və lazımi ALTER sorğularını yaradır. Lakin autoMigrations yalnız geriyə uyğun dəyişiklikləri dəstəkləyir: sütunların əlavə edilməsi, indekslərin yaradılması və uyğun çevrilmələrlə tiplərin dəyişdirilməsi.

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL(
            "ALTER TABLE users ADD COLUMN phone TEXT"
        )
    }
}

val db = Room
    .databaseBuilder(context, AppDatabase::class.java, "app-db")
    .addMigrations(MIGRATION_1_2)
    .build()

Sütunların adlandırılması və ya cədvəllərin birləşdirilməsi kimi mürəkkəb dəyişikliklər əlavə edilərkən, aralıq cədvəllərdən istifadə edərək əl ilə miqrasiya tələb olunur. Tipik ssenari: köhnə sxemlə müvəqqəti cədvəl yaratmaq, köhnə cədvəldən məlumatları çevrilmələrlə yeni cədvələ köçürmək, köhnə cədvəli silmək və müvəqqəti cədvəlin adını dəyişmək. Room bütün miqrasiyaların bir tranzaksiyada yerinə yetirildiyinə və xəta baş verdikdə dəyişikliklərin tam geri qaytarılmasına zəmanət verir.