Uygulamanızın verilerini depolamak için Oda kalıcı kitaplığını kullandığınızda, depolamak istediğiniz nesneleri temsil edecek varlıklar tanımlarsınız. Her öğe, ilişkili Oda veritabanındaki bir tabloya karşılık gelir ve bir varlığın her örneği karşılık gelen tablodaki bir veri satırını temsil eder.
Bu, herhangi bir SQL kodu yazmadan veritabanı şemanızı tanımlamak için Oda varlıklarını kullanabileceğiniz anlamına gelir.
Bir varlığın anatomisi
Her bir Oda varlığını @Entity
ile not eklenmiş bir sınıf olarak tanımlarsınız. Oda varlığı, veritabanındaki karşılık gelen tablodaki her sütun için birincil anahtarı oluşturan bir veya daha fazla sütun dahil olmak üzere çeşitli alanlar içerir.
Aşağıdaki kod, kimlik, ad ve soyadı sütunlarını içeren bir User
tablosunu tanımlayan basit bir varlık örneğidir:
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; }
Varsayılan olarak Room, veritabanı tablosu adı olarak sınıf adını kullanır. Tablonun farklı bir ada sahip olmasını istiyorsanız @Entity
ek açıklamasının tableName
özelliğini ayarlayın. Benzer şekilde, Room varsayılan olarak veritabanında sütun adları olarak alan adlarını kullanır. Bir sütunun farklı bir ada sahip olmasını istiyorsanız alana @ColumnInfo
ek açıklamasını ekleyin ve name
özelliğini ayarlayın. Aşağıdaki örnekte bir tablo ve sütunları için özel adlar gösterilmektedir:
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; }
Birincil anahtar tanımlayın
Her Oda öğesi, ilgili veritabanı tablosundaki her bir satırı benzersiz şekilde tanımlayan bir birincil anahtar tanımlamalıdır. Bunu yapmanın en kolay yolu, @PrimaryKey
kodunu tek bir sütuna eklemektir:
Kotlin
@PrimaryKey val id: Int
Java
@PrimaryKey public int id;
Birleşik birincil anahtar tanımlayın
Bir varlığın örneklerinin birden fazla sütunun bir kombinasyonuyla benzersiz şekilde tanımlanmasını istiyorsanız bu sütunları @Entity
öğesinin primaryKeys
özelliğinde listeleyerek birleşik birincil anahtar tanımlayabilirsiniz:
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; }
Alanları yoksay
Varsayılan olarak Oda, öğede tanımlanan her alan için bir sütun oluşturur.
Bir varlıkta kullanmak istemediğiniz alanlar varsa aşağıdaki kod snippet'inde gösterildiği gibi @Ignore
kullanarak bunlara ek açıklama ekleyebilirsiniz:
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; }
Bir varlığın alanları üst varlıktan devraldığı durumlarda @Entity
özelliğinin ignoredColumns
özelliğini kullanmak genellikle daha kolay olur:
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; }
Tablo arama desteği sağlama
Room, veritabanınızın tablolarında ayrıntılı arama yapmanızı kolaylaştıran çeşitli ek açıklama türlerini destekler. Uygulamanızın minSdkVersion
değeri 16'dan küçük değilse tam metin araması kullanın.
Tam metin araması desteği
Uygulamanız tam metin araması (FTS) aracılığıyla veritabanı bilgilerine çok hızlı erişim gerektiriyorsa varlıklarınızı FTS3 veya FTS4 SQLite uzantı modülünü kullanan bir sanal tablo ile destekleyin. Oda 2.1.0 ve sonraki sürümlerde bulunan bu özelliği kullanmak için belirli bir varlığa aşağıdaki kod snippet'inde gösterildiği gibi @Fts3
veya @Fts4
ek açıklamasını ekleyin:
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; }
Bir tablonun birden çok dildeki içeriği desteklediği durumlarda, her bir satır için dil bilgilerinin depolandığı sütunu belirtmek üzere languageId
seçeneğini kullanın:
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; }
Room; sonuç sıralama, jeton oluşturucu türleri ve harici içerik olarak yönetilen tablolar gibi FTS destekli varlıkları tanımlamak için çeşitli seçenekler sunar. Bu seçenekler hakkında daha fazla bilgi için FtsOptions
referansını inceleyin.
Dizine özel sütunlar
Uygulamanızın FTS3 veya FTS4 tablosu destekli varlıkları desteklemeyen SDK sürümlerini desteklemesi gerekiyorsa sorgularınızı hızlandırmak için veritabanındaki belirli sütunları dizine eklemeye devam edebilirsiniz. Bir varlığa dizin eklemek için indices
özelliğini @Entity
ek açıklamasına dahil ederek dizine veya birleşik dizine eklemek istediğiniz sütunların adlarını listeleyin. Aşağıdaki kod snippet'i bu ek açıklama işlemini göstermektedir:
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; }
Bazen bir veritabanındaki belirli alanlar veya alan grupları benzersiz olmalıdır.
Bir @Index
ek açıklamasının unique
özelliğini true
olarak ayarlayarak bu benzersizlik özelliğini zorunlu kılabilirsiniz. Aşağıdaki kod örneği, bir tablonun firstName
ve lastName
sütunları için aynı değer grubunu içeren iki satıra sahip olmasını engeller:
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; }
AutoValue tabanlı nesneleri dahil et
Oda 2.1.0 ve sonraki sürümlerde, uygulamanızın veritabanında varlıklar olarak @AutoValue
kullanarak ek açıklama eklediğiniz Java tabanlı değişmez değer sınıflarını kullanabilirsiniz. Bu destek, özellikle sütunları aynı değerleri içeren bir varlığın iki örneğinin eşit olarak kabul edildiği durumlarda yararlıdır.
@AutoValue
ek açıklaması bulunan sınıfları varlık olarak kullanırken @PrimaryKey
, @ColumnInfo
, @Embedded
ve @Relation
kullanarak sınıfın soyut yöntemlerine ek açıklama ekleyebilirsiniz. Ancak, bu ek açıklamaları kullanırken Room'un yöntemlerin otomatik olarak oluşturulan uygulamalarını doğru şekilde yorumlayabilmesi için her seferinde @CopyAnnotations
ek açıklamasını eklemeniz gerekir.
Aşağıdaki kod snippet'inde, Room'un varlık olarak tanıdığı @AutoValue
ek açıklamasıyla birlikte bir sınıf örneği gösterilmektedir:
@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); } }