Oda varlıklarını kullanarak verileri tanımlama

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:

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

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:

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

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:

@PrimaryKey val id: Int

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

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

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:

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

Bir varlığın alanları üst varlıktan devraldığı durumlarda @Entity özelliğinin ignoredColumns özelliğini kullanmak genellikle daha kolay olur:

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

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:

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

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:

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

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

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:

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

Kullanıcı.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);
    }
}