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

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

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

تشريح الكيان

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

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

Kotlin

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

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

Java

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

    public String firstName;
    public String lastName;
}

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

Kotlin

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

Java

@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:

Kotlin

@PrimaryKey val id: Int

Java

@PrimaryKey
public int id;

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

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

Kotlin

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

Java

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

تجاهل الحقول

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

Kotlin

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

Java

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

    public String firstName;
    public String lastName;

    @Ignore
    Bitmap picture;
}

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

Kotlin

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

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

Java

@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 إلى كيان معيَّن، كما هو موضَّح في مقتطف الرمز التالي:

Kotlin

// 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?
)

Java

// 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 لتحديد العمود الذي يخزّن معلومات اللغة لكل صف:

Kotlin

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

Java

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

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

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

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

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

Kotlin

@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?
)

Java

@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:

Kotlin

@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?
)

Java

@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);
    }
}