تحديد البيانات باستخدام عناصر الغرفة

عند استخدام مكتبة استمرارية الغرفة لتخزين بيانات تطبيقك، يمكنك تحديد عناصر لتمثيل العناصر التي تريد تخزينها. يتجاوب كل كيان مع جدول في قاعدة بيانات الغرفة المرتبطة، ويمثل كل مثيل للكيان صفًا من البيانات في الجدول المقابل.

وهذا يعني أنه يمكنك استخدام كيانات الغرفة لتحديد مخطط قاعدة البيانات بدون كتابة أي رمز SQL.

تشريح العنصر

ويمكنك تحديد كل كيان في الغرفة كفئة تم التعليق عليها باستخدام @Entity. يتضمن كيان الغرفة حقولاً لكل عمود في الجدول المقابل في قاعدة البيانات، بما في ذلك عمود واحد أو أكثر يشكل المفتاح الأساسي.

الرمز التالي هو مثال على كيان بسيط يحدّد جدول User يحتوي على أعمدة للرقم التعريفي والاسم الأول واسم العائلة:

@Entity
data class User(
    @PrimaryKey val id: Int,

    val firstName: String?,
    val lastName: String?
)

@Entity
public class User {
    @PrimaryKey
    public int id;

    public String firstName;
    public String lastName;
}

بشكل تلقائي، تستخدم الغرفة اسم الفئة كاسم جدول قاعدة البيانات. إذا أردت أن يكون للجدول اسمًا مختلفًا، اضبط السمة tableName في التعليق التوضيحي @Entity. وبالمثل، تستخدم Room أسماء الحقول كأسماء أعمدة في قاعدة البيانات بشكل افتراضي. إذا كنت تريد أن يكون للعمود اسمًا مختلفًا، أضِف التعليق التوضيحي @ColumnInfo إلى الحقل واضبط السمة name. يوضِّح المثال التالي الأسماء المخصّصة لجدول وأعمدته:

@Entity(tableName = "users")
data class User (
    @PrimaryKey val id: Int,
    @ColumnInfo(name = "first_name") val firstName: String?,
    @ColumnInfo(name = "last_name") val lastName: String?
)

@Entity(tableName = "users")
public class User {
    @PrimaryKey
    public int id;

    @ColumnInfo(name = "first_name")
    public String firstName;

    @ColumnInfo(name = "last_name")
    public String lastName;
}

تحديد مفتاح أساسي

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

@PrimaryKey val id: Int

@PrimaryKey
public int id;

تحديد مفتاح أساسي مركب

إذا كنت بحاجة إلى تحديد مثيلات الكيان بشكلٍ فريد من خلال مجموعة من الأعمدة المتعدّدة، يمكنك تعريف مفتاح أساسي مركب من خلال إدراج هذه الأعمدة في السمة primaryKeys الخاصة بـ @Entity:

@Entity(primaryKeys = ["firstName", "lastName"])
data class User(
    val firstName: String?,
    val lastName: String?
)

@Entity(primaryKeys = {"firstName", "lastName"})
public class User {
    public String firstName;
    public String lastName;
}

تجاهل الحقول

وفقًا للإعدادات التلقائية، تنشئ الغرفة عمودًا لكل حقل يتم تحديده في الكيان. إذا كان أحد الكيانات يحتوي على حقول لا تريد الاحتفاظ بها، يمكنك إضافة تعليقات توضيحية إليها باستخدام @Ignore، كما يظهر في مقتطف الرمز التالي:

@Entity
data class User(
    @PrimaryKey val id: Int,
    val firstName: String?,
    val lastName: String?,
    @Ignore val picture: Bitmap?
)

@Entity
public class User {
    @PrimaryKey
    public int id;

    public String firstName;
    public String lastName;

    @Ignore
    Bitmap picture;
}

في الحالات التي يكتسب فيها الكيان حقولاً من كيان رئيسي، من الأسهل عادةً استخدام السمة ignoredColumns للسمة @Entity:

open class User {
    var picture: Bitmap? = null
}

@Entity(ignoredColumns = ["picture"])
data class RemoteUser(
    @PrimaryKey val id: Int,
    val hasVpn: Boolean
) : User()

@Entity(ignoredColumns = "picture")
public class RemoteUser extends User {
    @PrimaryKey
    public int id;

    public boolean hasVpn;
}

توفير ميزة البحث في الجداول

تتيح الغرفة العديد من أنواع التعليقات التوضيحية التي تسهل عليك البحث عن التفاصيل في جداول قاعدة البيانات. استخدِم البحث في النص الكامل ما لم يكن minSdkVersion في تطبيقك أقل من 16.

إتاحة البحث في النص الكامل

إذا كان تطبيقك يتطلّب وصولًا سريعًا جدًا إلى معلومات قاعدة البيانات من خلال البحث بالنص الكامل (FTS)، احتفظ بالكيانات مدعومة بجدول افتراضي يستخدم إما وحدة إضافات SQLite FTS3 أو FTS4. لاستخدام هذه الميزة، المتوفّرة في الغرفة 2.1.0 والإصدارات الأحدث، أضِف التعليق التوضيحي @Fts3 أو @Fts4 إلى كيان معيّن، كما هو موضّح في مقتطف الرمز التالي:

// Use `@Fts3` only if your app has strict disk space requirements or if you
// require compatibility with an older SQLite version.
@Fts4
@Entity(tableName = "users")
data class User(
    /* Specifying a primary key for an FTS-table-backed entity is optional, but
       if you include one, it must use this type and column name. */
    @PrimaryKey @ColumnInfo(name = "rowid") val id: Int,
    @ColumnInfo(name = "first_name") val firstName: String?
)

// Use `@Fts3` only if your app has strict disk space requirements or if you
// require compatibility with an older SQLite version.
@Fts4
@Entity(tableName = "users")
public class User {
    // Specifying a primary key for an FTS-table-backed entity is optional, but
    // if you include one, it must use this type and column name.
    @PrimaryKey
    @ColumnInfo(name = "rowid")
    public int id;

    @ColumnInfo(name = "first_name")
    public String firstName;
}

في الحالات التي يتيح فيها الجدول المحتوى بلغات متعددة، استخدِم الخيار languageId لتحديد العمود الذي يخزّن معلومات اللغة لكل صف:

@Fts4(languageId = "lid")
@Entity(tableName = "users")
data class User(
    // ...
    @ColumnInfo(name = "lid") val languageId: Int
)

@Fts4(languageId = "lid")
@Entity(tableName = "users")
public class User {
    // ...

    @ColumnInfo(name = "lid")
    int languageId;
}

توفر الغرفة العديد من الخيارات الأخرى لتحديد الكيانات المدعومة من FTS، بما في ذلك ترتيب النتائج وأنواع الرموز المميّزة والجداول المُدارة كمحتوى خارجي. لمزيد من التفاصيل حول هذه الخيارات، يمكنك الاطّلاع على مرجع FtsOptions.

أعمدة خاصة بالفهرس

إذا كان يجب أن يتوافق تطبيقك مع إصدارات حزمة تطوير البرامج (SDK) التي لا تتوافق مع كيانات FTS3 أو FTS4 المستندة إلى الجدول، لا يزال بإمكانك فهرسة أعمدة معيّنة في قاعدة البيانات لتسريع طلباتك. لإضافة فهارس إلى كيان، أدرِج السمة indices ضمن التعليق التوضيحي @Entity، واذكر أسماء الأعمدة التي تريد تضمينها في الفهرس أو الفهرس المركّب. يوضح مقتطف الرمز التالي عملية التعليق التوضيحي هذه:

@Entity(indices = [Index(value = ["last_name", "address"])])
data class User(
    @PrimaryKey val id: Int,
    val firstName: String?,
    val address: String?,
    @ColumnInfo(name = "last_name") val lastName: String?,
    @Ignore val picture: Bitmap?
)

@Entity(indices = {@Index("name"),
        @Index(value = {"last_name", "address"})})
public class User {
    @PrimaryKey
    public int id;

    public String firstName;
    public String address;

    @ColumnInfo(name = "last_name")
    public String lastName;

    @Ignore
    Bitmap picture;
}

في بعض الأحيان، يجب أن تكون حقول معينة أو مجموعات من الحقول في قاعدة بيانات فريدة من نوعها. يمكنك فرض سمة التفرّد هذه من خلال ضبط السمة unique للتعليق التوضيحي @Index على true. في نموذج الرمز البرمجي التالي، يتم منع الجدول من تضمين صفَّين يحتويان على مجموعة القيم نفسها للعمودَين firstName وlastName:

@Entity(indices = [Index(value = ["first_name", "last_name"],
        unique = true)])
data class User(
    @PrimaryKey val id: Int,
    @ColumnInfo(name = "first_name") val firstName: String?,
    @ColumnInfo(name = "last_name") val lastName: String?,
    @Ignore var picture: Bitmap?
)

@Entity(indices = {@Index(value = {"first_name", "last_name"},
        unique = true)})
public class User {
    @PrimaryKey
    public int id;

    @ColumnInfo(name = "first_name")
    public String firstName;

    @ColumnInfo(name = "last_name")
    public String lastName;

    @Ignore
    Bitmap picture;
}

تضمين العناصر المستندة إلى القيمة التلقائية

في الغرفة 2.1.0 والإصدارات الأحدث، يمكنك استخدام فئات القيم الثابتة المستندة إلى لغة Java، والتي تضيف تعليقات توضيحية إليها باستخدام @AutoValue، ككيانات في قاعدة بيانات تطبيقك. هذا الدعم مفيد بشكل خاص عندما تكون حالتان من الكيان متساويتين إذا كانت أعمدتهما تحتويان على قيم متطابقة.

عند استخدام صفوف تم إضافة تعليقات توضيحية إليها باستخدام @AutoValue كعناصر، يمكنك إضافة تعليقات توضيحية إلى طُرق المجرّد في الصف الدراسي باستخدام @PrimaryKey و@ColumnInfo و@Embedded و@Relation. عند استخدام هذه التعليقات التوضيحية، عليك تضمين تعليق @CopyAnnotations التوضيحي في كل مرة بحيث يمكن لتطبيق Room تفسير عمليات التنفيذ التي يتم إنشاؤها تلقائيًا للطرق بشكل صحيح.

يعرض مقتطف الرمز التالي مثالاً لفئة تم التعليق عليها باستخدام @AutoValue والتي تتعرف عليها الغرفة ككيان:

ملف User.java

@AutoValue
@Entity
public abstract class User {
    // Supported annotations must include `@CopyAnnotations`.
    @CopyAnnotations
    @PrimaryKey
    public abstract long getId();

    public abstract String getFirstName();
    public abstract String getLastName();

    // Room uses this factory method to create User objects.
    public static User create(long id, String firstName, String lastName) {
        return new AutoValue_User(id, firstName, lastName);
    }
}