داده ها را با استفاده از موجودیت های اتاق تعریف کنید

هنگامی که از کتابخانه ماندگاری اتاق برای ذخیره داده های برنامه خود استفاده می کنید، موجودیت هایی را برای نمایش اشیایی که می خواهید ذخیره کنید تعریف می کنید. هر موجودیت مربوط به یک جدول در پایگاه داده اتاق مرتبط است و هر نمونه از یک موجودیت نشان دهنده ردیفی از داده ها در جدول مربوطه است.

این بدان معناست که شما می توانید از موجودیت های Room برای تعریف طرح پایگاه داده خود بدون نوشتن هیچ کد 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;
}

به طور پیش فرض، Room از نام کلاس به عنوان نام جدول پایگاه داده استفاده می کند. اگر می خواهید جدول نام دیگری داشته باشد، ویژگی 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;
}

نادیده گرفتن فیلدها

به‌طور پیش‌فرض، Room برای هر فیلدی که در موجودیت تعریف شده است، یک ستون ایجاد می‌کند. اگر موجودیتی فیلدهایی دارد که نمی‌خواهید باقی بمانند، می‌توانید با استفاده از @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;
}

پشتیبانی از جستجوی جدول را ارائه دهید

Room از انواع مختلفی از حاشیه نویسی پشتیبانی می کند که جستجوی جزئیات در جداول پایگاه داده را برای شما آسان تر می کند. از جستجوی تمام متن استفاده کنید مگر اینکه minSdkVersion برنامه شما کمتر از 16 باشد.

پشتیبانی از جستجوی متن کامل

اگر برنامه شما به دسترسی سریع به اطلاعات پایگاه داده از طریق جستجوی متن کامل (FTS) نیاز دارد، موجودیت های خود را با یک جدول مجازی پشتیبانی کنید که از ماژول افزونه FTS3 یا FTS4 SQLite استفاده می کند. برای استفاده از این قابلیت، موجود در Room 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;
}

Room چندین گزینه دیگر را برای تعریف موجودیت های دارای پشتوانه 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;
}

شامل اشیاء مبتنی بر AutoValue

در Room 2.1.0 و بالاتر، می‌توانید از کلاس‌های ارزش تغییرناپذیر مبتنی بر جاوا که با استفاده از @AutoValue حاشیه‌نویسی می‌کنید، به عنوان موجودیت‌هایی در پایگاه داده برنامه خود استفاده کنید. این پشتیبانی به ویژه زمانی مفید است که دو نمونه از یک موجودیت برابر در نظر گرفته شوند اگر ستون های آنها حاوی مقادیر یکسان باشد.

هنگام استفاده از کلاس های حاشیه نویسی شده با @AutoValue به عنوان موجودیت، می توانید روش های انتزاعی کلاس را با استفاده از @PrimaryKey ، @ColumnInfo ، @Embedded و @Relation حاشیه نویسی کنید. با این حال، هنگام استفاده از این حاشیه‌نویسی‌ها، باید هر بار حاشیه‌نویسی @CopyAnnotations را اضافه کنید تا Room بتواند پیاده‌سازی‌های تولید شده خودکار روش‌ها را به درستی تفسیر کند.

قطعه کد زیر نمونه ای از یک کلاس مشروح شده با @AutoValue را نشان می دهد که Room آن را به عنوان یک موجودیت می شناسد:

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