مهاجرت از اتاق ۲.x به اتاق ۳.۰

Room 3.0 یک به‌روزرسانی عمده نسخه است که کتابخانه را به Kotlin-first منتقل می‌کند. این کتابخانه از Kotlin Multiplatform (KMP) پشتیبانی می‌کند، به Kotlin Symbol Processing (KSP) نیاز دارد و Coroutineها را برای عملیات ناهمزمان اعمال می‌کند.

برای جلوگیری از مشکلات سازگاری با برنامه‌های Room 2.x موجود و وابستگی‌های انتقالی، Room 3.0 در یک بسته جدید قرار دارد: androidx.room3 .

این راهنما مراحل لازم برای انتقال پیاده‌سازی Room 2.x موجود شما به Room 3.0 را شرح می‌دهد.

تغییرات کلیدی در اتاق ۳.۰

قبل از شروع مهاجرت، با تفاوت‌های اصلی آشنا شوید:

• بسته و مصنوعات جدید : همه کلاس‌ها در androidx.room3 قرار دارند. مصنوعات از پیشوند room3 استفاده می‌کنند، مانند androidx.room3:room3-runtime .
• فقط Kotlin و KSP : Room 3.0 از تولید کد جاوا پشتیبانی نمی‌کند. به جای KAPT یا پردازنده‌های حاشیه‌نویسی جاوا از KSP استفاده کنید. Room 3.0 همچنان از منابع جاوا به عنوان ورودی پشتیبانی می‌کند.
• Coroutine first : توابع DAO باید توابع suspend باشند، به جز انواع observable. CoroutineContext جایگزین executorها می‌شود.
• بدون SupportSQLite : رابط‌های برنامه‌نویسی SQLiteDriver Room را پشتیبانی می‌کنند. Room، SupportSQLiteDatabase از رابط‌های برنامه‌نویسی اصلی حذف می‌کند.
• تغییرات API : مهاجرت‌ها و فراخوانی‌های پایگاه داده به جای SupportSQLiteDatabase از SQLiteConnection استفاده می‌کنند.
• مبدل‌ها برای انواع واکنشی : انواع بازگشتی RxJava، LiveData، Guava و Paging نیاز دارند که شما @DaoReturnTypeConverters را ثبت کنید.

ما توصیه می‌کنیم مهاجرت را در دو مرحله مجزا انجام دهید: ابتدا آماده‌سازی و مدرن‌سازی پایگاه کد خود در Room 2.x و سپس انتقال به Room 3.0.

آماده‌سازی و نوسازی در اتاق ۲.x

قبل از مهاجرت به Room 3.0، می‌توانید بیشتر کارهای مدرن‌سازی را با به‌روزرسانی به نسخه فعلی Room 2.x، مانند Room 2.8، انجام دهید. Room 2.8 از Kotlin Multiplatform یا KMP پشتیبانی می‌کند و شامل بسیاری از APIهای درایور است که Room 3.0 از آنها استفاده می‌کند.

به اتاق ۲.۸ و بالاتر ارتقا دهید

پیکربندی ساخت خود را برای استفاده از نسخه فعلی Room 2.x به‌روزرسانی کنید:

[versions]
room2 = "2.8.4" # Use the current Room 2.8 version

[libraries]
androidx-room-runtime = { module = "androidx.room:room-runtime", version.ref = "room2" }
androidx-room-compiler = { module = "androidx.room:room-compiler", version.ref = "room2" }

مهاجرت از KAPT به KSP

روم ۳.۰ از پردازنده‌های حاشیه‌نویسی جاوا یا KAPT پشتیبانی نمی‌کند. شما باید از پردازش نمادهای کاتلین (KSP) استفاده کنید. می‌توانید این انتقال را در حالی که هنوز در روم ۲.x هستید، انجام دهید.

1. در build.gradle.kts ماژول خود، افزونه KSP را اعمال کنید:

   plugins {
       id("com.google.devtools.ksp") version "<ksp_version>"
   }
   

   مطمئن شوید که نسخه KSP با نسخه کاتلین شما سازگار است.

2. برای وابستگی کامپایلر Room kapt یا annotationProcessor را با ksp جایگزین کنید:

   dependencies {
       implementation(libs.androidx.room.runtime)
       ksp(libs.androidx.room.compiler)
   }
   

کوروتین‌ها را بپذیرید

اتاق ۳.۰ برای عملیات ناهمزمان به کوروتین نیاز دارد.

• به‌روزرسانی DAOهای خود: مگر اینکه یک نوع واکنشی قابل مشاهده، مانند انواع Flow یا RxJava، را برگردانند، تمام توابع DAO باید توابع suspend باشند.

// Before (Blocking)
@Dao
interface UserDao {
    @Query("SELECT * FROM User")
    fun getAll(): List<User>
}

// After (Suspend)
@Dao
interface UserDao {
    @Query("SELECT * FROM User")
    suspend fun getAll(): List<User>
}

• اگر RoomDatabase خود را با یک Executor سفارشی برای انجام عملیات پایگاه داده پیکربندی کرده‌اید، با استفاده از setQueryCoroutineContext در سازنده، به CoroutineContext مهاجرت کنید:

Room.databaseBuilder<AppDatabase>(context, "db")
    .setQueryCoroutineContext(Dispatchers.IO)
    .build()

API های درایور را اتخاذ کنید و از پشتیبانی SQLite خودداری کنید

روم ۳.۰ به طور کامل توسط SQLiteDriver پشتیبانی می‌شود و دیگر SupportSQLiteDatabase در APIهای اصلی خود پشتیبانی نمی‌کند.

اگر برای تنظیم SQLiteDriver در سازنده پایگاه داده خود، setDriver فراخوانی نکنید، Room 2.8 در حالت سازگاری عمل می‌کند که در آن هم از SQLite پشتیبانی می‌کند و هم از APIهای درایور. این حالت سازگاری به شما امکان می‌دهد قبل از فعال کردن درایور، کدبیس خود را به صورت تدریجی تبدیل کنید.

• تبدیل مهاجرت‌ها : زیرکلاس‌های Migration و AutoMigrationSpec خود را طوری مهاجرت دهید که به جای SupportSQLiteDatabase از SQLiteConnection استفاده کنند.

// Before (SupportSQLiteDatabase)
val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("ALTER TABLE User ADD COLUMN age INTEGER DEFAULT 0 NOT NULL")
    }
}

// After (SQLiteConnection - Room 2.8)
import androidx.sqlite.SQLiteConnection
import androidx.sqlite.execSQL

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(connection: SQLiteConnection) {
        connection.execSQL(
            "ALTER TABLE User ADD COLUMN age INTEGER DEFAULT 0 NOT NULL"
        )
    }
}

• تبدیل فراخوانی‌های پایگاه داده : پیاده‌سازی‌های RoomDatabase.Callback را برای استفاده از SQLiteConnection به‌روزرسانی کنید:

// Before (SupportSQLiteDatabase)
val callback = object : RoomDatabase.Callback() {
    override fun onCreate(db: SupportSQLiteDatabase) {
        // ...
    }
}

// After (SQLiteConnection - Room 2.8)
val callback = object : RoomDatabase.Callback() {
    override fun onCreate(connection: SQLiteConnection) {
        // ...
    }
}

• تبدیل توابع DAO @RawQuery : برای توابعی که با @RawQuery حاشیه‌نویسی شده‌اند، به جای SupportSQLiteQuery از RoomRawQuery استفاده کنید:

// Before (SupportSQLiteQuery)
@Dao
interface UserDao {
    @RawQuery
    fun getUser(query: SupportSQLiteQuery): User
}

// After (RoomRawQuery)
@Dao
interface UserDao {
    @RawQuery
    suspend fun getUser(query: RoomRawQuery): User
}

شما می‌توانید یک RoomRawQuery در زمان اجرا بسازید:

val query = RoomRawQuery(
    sql = "SELECT * FROM User WHERE id = ?",
    onBindStatement = { statement ->
        statement.bindInt(1, userId)
    }
)

• تبدیل APIهای تراکنش : بلوک‌های withTransaction و runInTransaction که فقط برای اندروید هستند را با useWriterConnection و immediateTransaction جایگزین کنید:

// Before (withTransaction)
db.withTransaction {
    // perform database operations
}

// After (useWriterConnection - Room 2.8)
import androidx.room.useWriterConnection
import androidx.room.immediateTransaction

db.useWriterConnection { connection ->
    connection.immediateTransaction {
        // perform database operations
    }
}

• از استفاده مستقیم از SupportSQLiteDatabase خودداری کنید : اگر کد قدیمی گسترده‌ای دارید که هنوز به SupportSQLiteDatabase نیاز دارد و هنوز نمی‌توانید آن را منتقل کنید، از مصنوع سازگاری androidx.room:room-sqlite-wrapper استفاده کنید:

dependencies {
    implementation("androidx.room:room-sqlite-wrapper:$roomVersion")
}

و سپس، getSupportWrapper برای دریافت SupportSQLiteDatabase از نمونه پایگاه داده Room خود استفاده کنید:

import androidx.room.support.getSupportWrapper

val legacyDb: SupportSQLiteDatabase = roomDatabase.getSupportWrapper()

• تنظیم درایور SQLite : پس از اینکه تمام کاربردهای API اتاق را به APIهای درایور منتقل کردید، با فراخوانی setDriver در سازنده RoomDatabase خود، یک درایور مانند BundledSQLiteDriver یا AndroidSQLiteDriver را پیکربندی کنید:

import androidx.sqlite.driver.bundled.BundledSQLiteDriver

val db = Room.databaseBuilder<AppDatabase>(context, "db")
    .setDriver(BundledSQLiteDriver())
    .build()

ردیابی ابطال مبتنی بر جریان را اتخاذ کنید

اتاق ۲.۸ رابط برنامه‌نویسی کاربردی (API) InvalidationTracker.createFlow را معرفی می‌کند. از این API برای مهاجرت از پیاده‌سازی‌های قدیمی InvalidationTracker.Observer در حالی که هنوز در اتاق ۲.x هستید، استفاده کنید. این کار کدبیس شما را برای اتاق ۳.۰ آماده می‌کند که به طور کامل Observer حذف می‌کند.

// Before (InvalidationTracker.Observer)
val observer = object : InvalidationTracker.Observer("User") {
    override fun onInvalidated(tables: Set<String>) {
        // reload user data
    }
}
db.invalidationTracker.addObserver(observer)

// After (createFlow - Room 2.8)
val userFlow = db.invalidationTracker.createFlow("User").map { _ ->
    userDao.getAllUsers()
}

مهاجرت به اتاق ۳.۰

زمانی که برنامه خود را در Room 2.x مدرن کردید، انتقال به Room 3.0 شامل به‌روزرسانی وابستگی‌ها، وارد کردن بسته‌ها و فراخوانی‌های پایگاه داده می‌شود.

به‌روزرسانی وابستگی‌ها و وارد کردن بسته‌ها

• در پیکربندی ساخت خود، وابستگی‌های androidx.room را با androidx.room3 جایگزین کنید:

[versions]
room3 = "3.0.0" # Use the current Room 3.0 version

[libraries]
androidx-room3-runtime = { module = "androidx.room3:room3-runtime", version.ref = "room3" }
androidx-room3-compiler = { module = "androidx.room3:room3-compiler", version.ref = "room3" }

• بلوک وابستگی‌های خود را به‌روزرسانی کنید:

dependencies {
    implementation(libs.androidx.room3.runtime)
    ksp(libs.androidx.room3.compiler)
}

• بسته‌های import خود را به‌روزرسانی کنید. import androidx.room.* ‎ را با import androidx.room3.* ‎ جایگزین کنید.

به‌روزرسانی APIهای مبدل نوع

اتاق ۳.۰ نام APIهای مبدل نوع را تغییر می‌دهد تا کاربرد آنها برای تبدیل مقادیر ستون را روشن کند و از سردرگمی با مبدل‌های نوع بازگشتی DAO جلوگیری کند.

حاشیه‌نویسی‌ها و توابع زیر را در کدبیس خود به‌روزرسانی کنید:

• نام @TypeConverter را به @ColumnTypeConverter تغییر دهید.
• نام @TypeConverters را به @ColumnTypeConverters تغییر دهید.
• نام @ProvidedTypeConverter را به @ProvidedColumnTypeConverter تغییر دهید.
• نام RoomDatabase.Builder.addTypeConverter را به addColumnTypeConverter تغییر دهید.

مثال:

// Before
@ProvidedTypeConverter
class Converters {
  @TypeConverter
  fun fromTimestamp(value: Long?): Date? = ...
}

@Database(entities = [User::class], version = 1)
@TypeConverters(Converters::class)
abstract class AppDatabase : RoomDatabase()

val db = Room.databaseBuilder<AppDatabase>(...)
  .addTypeConverter(convertersInstance)
  .build()

// After
import androidx.room3.ColumnTypeConverter
import androidx.room3.ColumnTypeConverters
import androidx.room3.ProvidedColumnTypeConverter

@ProvidedColumnTypeConverter
class Converters {
  @ColumnTypeConverter
  fun fromTimestamp(value: Long?): Date? = ...
}

@Database(entities = [User::class], version = 1)
@ColumnTypeConverters(Converters::class)
abstract class AppDatabase : RoomDatabase()

val db = Room.databaseBuilder<AppDatabase>(...)
  .addColumnTypeConverter(convertersInstance)
  .build()

به‌روزرسانی فراخوانی‌های برگشتی برای تعلیق توابع

در اتاق ۳.۰، فراخوانی‌های پایگاه داده و مهاجرت‌ها از SQLiteConnection استفاده می‌کنند و توابع suspend هستند.

• کلاس‌های Migration دستی خود را به‌روزرسانی کنید:

import androidx.sqlite.SQLiteConnection
import androidx.sqlite.async.executeSQL

val MIGRATION_1_2 = object : Migration(1, 2) {
    override suspend fun migrate(connection: SQLiteConnection) {
        connection.executeSQL(
            "ALTER TABLE User ADD COLUMN age INTEGER DEFAULT 0 NOT NULL"
        )
    }
}

• پیاده‌سازی‌های RoomDatabase.Callback خود را به‌روزرسانی کنید:

val callback = object : RoomDatabase.Callback() {
    override suspend fun onCreate(connection: SQLiteConnection) {
        // ...
    }
}

مبدل‌های نوع بازگشتی DAO رجیستر

در اتاق ۳.۰، انواع برگشتی واکنشی، مانند RxJava، LiveData، Guava و Paging، شما را ملزم به ثبت مبدل‌های نوع برگشتی DAO با استفاده از @DaoReturnTypeConverters می‌کنند.

import androidx.room3.paging.PagingSourceDaoReturnTypeConverter

@Dao
@DaoReturnTypeConverters(PagingSourceDaoReturnTypeConverter::class)
interface UserDao {
    @Query("SELECT * FROM User")
    fun getAllPaginated(): PagingSource<Int, User>
}

• صفحه‌بندی ( PagingSource ) : PagingSourceDaoReturnTypeConverter را از مصنوع androidx.room3:room3-paging ثبت می‌کند.
• RxJava( Observable , Flowable , Single , Maybe , Completable ) : RxDaoReturnTypeConverters از مصنوع androidx.room3:room3-rxjava3 ثبت می‌کند.
• Guava ( ListenableFuture ) : GuavaDaoReturnTypeConverter را از مصنوع androidx.room3:room3-guava ثبت می‌کند.
• LiveData ( LiveData ) : از روی مصنوع androidx.room3:room3-livedata LiveDataDaoReturnTypeConverter را ثبت کنید.

تأیید حذف ناظر InvalidationTracker

اتاق ۳.۰ به طور کامل InvalidationTracker.Observer و متدهای ثبت نام مرتبط، مانند addObserver و removeObserver حذف می‌کند.

اگر در فاز ۱ به جریان‌های کوروتین منتقل نشده‌اید، باید تمام کاربردهای Observer را به createFlow منتقل کنید:

val userFlow = db.invalidationTracker.createFlow("User").map { _ ->
    userDao.getAllUsers()
}