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