نقل بيانات الغرفة إلى نظام أساسي متعدّد لغة Kotlin

يوضِّح هذا المستند كيفية نقل بيانات غرفة حالية إلى غرفة واحدة التي تستخدم Kotlin Multiplatform (KMP).

نقل استخدامات الغرفة في قاعدة رموز Android حالية إلى منصّة KMP مشتركة مشتركة قد تختلف اختلافًا كبيرًا في مستوى الصعوبة اعتمادًا على واجهات برمجة تطبيقات الغرفة المستخدمة أو ما إذا فإن قاعدة الأكواد تستخدم الكوروتينات بالفعل. يقدّم هذا القسم بعض الإرشادات والنصائح. عند محاولة نقل استخدامات الغرفة إلى وحدة شائعة الاستخدام.

من المهم أن تتعرف أولاً على الاختلافات الميزات بين إصدار Android من الغرفة وإصدار KMP إلى جانب الإعداد المتضمنة. وفي جوهرها، تتضمن عملية الهجرة الناجحة إعادة الهيكلة استخدامات واجهات برمجة تطبيقات SupportSQLite* واستبدالها بواجهات SQLite Driver APIs إلى جانب نقل بيانات الغرفة (فئة @Database تتضمن تعليقات توضيحية، DAO، والكيانات وما إلى ذلك) إلى تعليمات برمجية مشتركة.

يُرجى مراجعة المعلومات التالية قبل المتابعة:

• مستندات حول إعداد "منصّة KMP" في الغرفة
• مستندات SQLite KMP

توضح الأقسام التالية الخطوات المختلفة المطلوبة لتحقيق نجاح وترحيلها.

الانتقال من Support SQLite إلى برنامج تشغيل SQLite

إنّ واجهات برمجة التطبيقات في androidx.sqlite.db مخصّصة لنظام التشغيل Android فقط، وأي استخدامات يجب أن تكون باستخدام واجهات برمجة تطبيقات SQLite Driver. للتوافق مع الأنظمة القديمة، وما دامت يتم ضبط RoomDatabase باستخدام SupportSQLiteOpenHelper.Factory (أي لم يتم ضبط SQLiteDriver)، ثم تعمل الغرفة في "وضع التوافق". أين كل من دعم واجهات برمجة تطبيقات SQLite وSQLite Driver API يعملان كما هو متوقع. وهذا يمكّن وعمليات ترحيل تدريجية بحيث لا تحتاج إلى تحويل كل Support SQLite استخدامات SQLite Driver في تغيير واحد.

الأمثلة التالية هي الاستخدامات الشائعة لـ Support SQLite وSQLite نظراء السائقين:

val database: SupportSQLiteDatabase = ...
database.execSQL("ALTER TABLE ...")

val database: SupportSQLiteDatabase = ...
database.query("SELECT * FROM Pet").use { cursor ->
  while (cusor.moveToNext()) {
    // read columns
    cursor.getInt(0)
    cursor.getString(1)
  }
}

database.query("SELECT * FROM Pet WHERE id = ?", id).use { cursor ->
  if (cursor.moveToNext()) {
    // row found, read columns
  } else {
    // row not found
  }
}

val connection: SQLiteConnection = ...
connection.execSQL("ALTER TABLE ...")

val connection: SQLiteConnection = ...
connection.prepare("SELECT * FROM Pet").use { statement ->
  while (statement.step()) {
    // read columns
    statement.getInt(0)
    statement.getText(1)
  }
}

connection.prepare("SELECT * FROM Pet WHERE id = ?").use { statement ->
  statement.bindInt(1, id)
  if (statement.step()) {
    // row found, read columns
  } else {
    // row not found
  }
}

تتوفّر واجهات برمجة التطبيقات لمعاملات قاعدة البيانات مباشرةً في SupportSQLiteDatabase مع beginTransaction() وsetTransactionSuccessful() وendTransaction() وهي متوفِّرة أيضًا من خلال الغرفة باستخدام "runInTransaction()". نقل هذه البيانات الاستخدام لواجهات برمجة تطبيقات SQLite Driver.

val database: RoomDatabase = ...
database.runInTransaction {
  // perform database operations in transaction
}

val database: SupportSQLiteDatabase = ...
database.beginTransaction()
try {
  // perform database operations in transaction
  database.setTransactionSuccessful()
} finally {
  database.endTransaction()
}

val database: RoomDatabase = ...
database.useWriterConnection { transactor ->
  transactor.immediateTransaction {
    // perform database operations in transaction
  }
}

val connection: SQLiteConnection = ...
connection.execSQL("BEGIN IMMEDIATE TRANSACTION")
try {
  // perform database operations in transaction
  connection.execSQL("END TRANSACTION")
} catch(t: Throwable) {
  connection.execSQL("ROLLBACK TRANSACTION")
}

يجب أيضًا نقل العديد من عمليات إلغاء معاودة الاتصال إلى نظرائها من السائقين:

object Migration_1_2 : Migration(1, 2) {
  override fun migrate(db: SupportSQLiteDatabase) {
    // ...
  }
}

class AutoMigrationSpec_1_2 : AutoMigrationSpec {
  override fun onPostMigrate(db: SupportSQLiteDatabase) {
    // ...
  }
}

object MyRoomCallback : RoomDatabase.Callback {
  override fun onCreate(db: SupportSQLiteDatabase) {
    // ...
  }

  override fun onDestructiveMigration(db: SupportSQLiteDatabase) {
    // ...
  }

  override fun onOpen(db: SupportSQLiteDatabase) {
    // ...
  }
}

object Migration_1_2 : Migration(1, 2) {
  override fun migrate(connection: SQLiteConnection) {
    // ...
  }
}

class AutoMigrationSpec_1_2 : AutoMigrationSpec {
  override fun onPostMigrate(connection: SQLiteConnection) {
    // ...
  }
}

object MyRoomCallback : RoomDatabase.Callback {
  override fun onCreate(connection: SQLiteConnection) {
    // ...
  }

  override fun onDestructiveMigration(connection: SQLiteConnection) {
    // ...
  }

  override fun onOpen(connection: SQLiteConnection) {
    // ...
  }
}

للتلخيص، استبدل استخدامات SQLiteDatabase بـ SQLiteConnection عند لا تتوفر RoomDatabase، كما هو الحال في عمليات إلغاء معاودة الاتصال (onMigrate، onCreate، إلخ). في حال توفّر RoomDatabase، يمكنك الوصول إلى المعرّف الأساسي. اتصال قاعدة بيانات باستخدام RoomDatabase.useReaderConnection RoomDatabase.useWriterConnection بدلاً من RoomDatabase.openHelper.writtableDatabase

تحويل دوال DAO الكتلية إلى دوال التعليق

يعتمد إصدار KMP من الغرفة على الكوروتين لإجراء عمليات الإدخال والإخراج. العمليات على CoroutineContext التي تم إعدادها. هذا يعني أنك إلى ترحيل أي دوال DAO محظورة لتعليق الدوال.

@Query("SELECT * FROM Todo")
fun getAllTodos(): List<Todo>

@Query("SELECT * FROM Todo")
suspend fun getAllTodos(): List<Todo>

يمكن نقل دوال المنع الحالية DAO إلى تعليق الدوال إذا كان قاعدة الرموز الحالية لا تتضمّن الكوروتينات. يمكنك الرجوع إلى مقالة الكوروتينات في Android لبدء استخدام الكوروتين. في قاعدة التعليمات البرمجية.

تحويل أنواع الإرجاع التفاعلية إلى تدفق

لا يلزم أن تكون جميع دوال DAO دوال تعليق. دوال DAO التي تُرجع يجب عدم تحويل الأنواع التفاعلية، مثل LiveData أو Flowable في RxJava. تعليق الدوال. في المقابل، بعض الأنواع، مثل LiveData، لا تُعدّ KMP. متوافقة. يجب نقل دوال DAO ذات أنواع الإرجاع التفاعلية إلى تدفقات الكوروتين.

@Query("SELECT * FROM Todo")
fun getTodosLiveData(): LiveData<List<Todo>>

@Query("SELECT * FROM Todo")
fun getTodosFlow(): Flow<List<Todo>>

يُرجى الرجوع إلى التدفقات في Android لبدء استخدام ميزة "التدفق" في أو قاعدة التعليمات البرمجية.

ضبط سياق الكوروتين (اختياري)

يمكن إعداد RoomDatabase بشكل اختياري مع التطبيق المشترك تنفيذين يستخدمان RoomDatabase.Builder.setQueryExecutor() لتنفيذ قاعدة البيانات العمليات التجارية. بما أنّ مدراء التنفيذ غير متوافقين مع "منصّة KMP"، يجب أن تتوفّر setQueryExecutor() في الغرفة. واجهة برمجة التطبيقات غير متاحة للمصادر الشائعة. بدلاً من ذلك RoomDatabase يجب مع CoroutineContext. يمكن تعيين السياق باستخدام RoomDatabase.Builder.setCoroutineContext()، إذا لم يتم ضبط أي قيمة، يتم سيتم ضبط الإعدادات التلقائية لـ "RoomDatabase" على استخدام "Dispatchers.IO".

إعداد برنامج تشغيل SQLite

وبعد نقل استخدامات Support SQLite إلى واجهات برمجة تطبيقات SQLite Driver، لن يتم نقل يجب إعداد برنامج التشغيل باستخدام RoomDatabase.Builder.setDriver. تشير رسالة الأشكال البيانية برنامج التشغيل الموصى به هو BundledSQLiteDriver. اطّلِع على عمليات تنفيذ برامج التشغيل لـ أوصاف لعمليات تنفيذ برامج التشغيل المتاحة.

تم ضبط SupportSQLiteOpenHelper.Factory المخصّص باستخدام RoomDatabase.Builder.openHelperFactory() غير متوافقة في KMP، الميزات التي يقدمها المساعد المفتوح المخصص يجب إعادة تنفيذها مع واجهات برنامج تشغيل SQLite.

طلبات نقل بيانات الغرفة

بعد اكتمال معظم خطوات نقل البيانات، يمكن للمرء نقل الغرفة. تعريفات لمجموعة مصادر شائعة. يُرجى العلم أنّه يمكن للاستراتيجيات expect من actual استخدامها لنقل التعريفات ذات الصلة بالغرفة بشكل تدريجي. على سبيل المثال، إن لم تكن جميعها حظر دوال DAO إلى تعليق الدوال، فيمكن تعريف واجهة expect @Dao التي تتضمّن تعليقات توضيحية وتكون فارغة في الرمز البرمجي العام يحتوي على دوال حظر في Android.

// shared/src/commonMain/kotlin/Database.kt

@Database(entities = [TodoEntity::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
  abstract fun getDao(): TodoDao
  abstract fun getBlockingDao(): BlockingTodoDao
}

@Dao
interface TodoDao {
    @Query("SELECT count(*) FROM TodoEntity")
    suspend fun count(): Int
}

@Dao
expect interface BlockingTodoDao

// shared/src/androidMain/kotlin/BlockingTodoDao.kt

@Dao
actual interface BlockingTodoDao {
    @Query("SELECT count(*) FROM TodoEntity")
    fun count(): Int
}