Room'u kullanarak verileri yerel bir veritabanına kaydetme   Android Jetpack'in bir parçasıdır.

Önemli miktarda yapılandırılmış veri işleyen uygulamalar, bu verileri yerel olarak depolayarak büyük fayda sağlayabilir. En yaygın kullanım alanı, cihaz ağa erişemediğinde kullanıcının internete bağlı değilken ilgili içeriğe göz atabilmesi için alakalı veri parçalarını önbelleğe almaktır.

Room kalıcılık kitaplığı, SQLite'in tüm gücünden yararlanırken akıcı veritabanı erişimi sağlamak için SQLite üzerinde bir soyutlama katmanı sağlar. Room'un sağladığı avantajlar şunlardır:

  • SQL sorgularının derleme zamanında doğrulanması.
  • Tekrarlanan ve hataya açık ortak metin kodlarını en aza indiren kolaylık notları.
  • Veritabanı taşıma yolları basitleştirildi.

Bu nedenle, SQLite API'lerini doğrudan kullanmak yerine Room'u kullanmanızı önemle tavsiye ederiz.

Kurulum

Room'u uygulamanızda kullanmak için uygulamanızın build.gradle dosyasına aşağıdaki bağımlılıkları ekleyin.

Kotlin

dependencies {
    val room_version = "2.6.1"

    implementation("androidx.room:room-runtime:$room_version")

    // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)
    // See Add the KSP plugin to your project
    ksp("androidx.room:room-compiler:$room_version")

    // If this project only uses Java source, use the Java annotationProcessor
    // No additional plugins are necessary
    annotationProcessor("androidx.room:room-compiler:$room_version")

    // optional - Kotlin Extensions and Coroutines support for Room
    implementation("androidx.room:room-ktx:$room_version")

    // optional - RxJava2 support for Room
    implementation("androidx.room:room-rxjava2:$room_version")

    // optional - RxJava3 support for Room
    implementation("androidx.room:room-rxjava3:$room_version")

    // optional - Guava support for Room, including Optional and ListenableFuture
    implementation("androidx.room:room-guava:$room_version")

    // optional - Test helpers
    testImplementation("androidx.room:room-testing:$room_version")

    // optional - Paging 3 Integration
    implementation("androidx.room:room-paging:$room_version")
}

Groovy

dependencies {
    def room_version = "2.6.1"

    implementation "androidx.room:room-runtime:$room_version"

    // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)
    // See KSP Quickstart to add KSP to your build
    ksp "androidx.room:room-compiler:$room_version"

    // If this project only uses Java source, use the Java annotationProcessor
    // No additional plugins are necessary
    annotationProcessor "androidx.room:room-compiler:$room_version"

    // optional - RxJava2 support for Room
    implementation "androidx.room:room-rxjava2:$room_version"

    // optional - RxJava3 support for Room
    implementation "androidx.room:room-rxjava3:$room_version"

    // optional - Guava support for Room, including Optional and ListenableFuture
    implementation "androidx.room:room-guava:$room_version"

    // optional - Test helpers
    testImplementation "androidx.room:room-testing:$room_version"

    // optional - Paging 3 Integration
    implementation "androidx.room:room-paging:$room_version"
}

Birincil bileşenler

Room'da üç ana bileşen bulunur:

  • Veritabanını barındıran ve uygulamanızın kalıcı verilerine yönelik temel bağlantının ana erişim noktası olarak hizmet veren veritabanı sınıfı.
  • Uygulamanızın veritabanındaki tabloları temsil eden veri varlıkları.
  • Uygulamanızın veritabanındaki verileri sorgulamak, güncellemek, eklemek ve silmek için kullanabileceği yöntemleri sağlayan veri erişim nesneleri (DAO'lar).

Veritabanı sınıfı, uygulamanıza söz konusu veritabanıyla ilişkili DAO örneklerini sağlar. Uygulama da ilişkili veri varlık nesnelerinin örnekleri olarak veritabanından veri almak için DAO'ları kullanabilir. Uygulama, tanımlanan veri varlıklarını ilgili tablolardaki satırları güncellemek veya eklemek için yeni satır oluşturmak için de kullanabilir. Şekil 1'de, Room'un farklı bileşenleri arasındaki ilişki gösterilmektedir.

Şekil 1. Oda kitaplığı mimarisini gösteren şema.

Örnek uygulama

Bu bölümde, tek bir veri öğesi ve tek bir DAO içeren bir Oda veritabanı örneği uygulaması sunulmaktadır.

Veri varlığı

Aşağıdaki kodda bir User veri öğesi tanımlanmaktadır. Her User örneği, uygulamanın veritabanındaki bir user tablosundaki bir satırı temsil eder.

Kotlin

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

Java

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

    @ColumnInfo(name = "first_name")
    public String firstName;

    @ColumnInfo(name = "last_name")
    public String lastName;
}

Room'daki veri varlıkları hakkında daha fazla bilgi edinmek için Room varlıklarını kullanarak verileri tanımlama başlıklı makaleyi inceleyin.

Veri erişimi nesnesi (DAO)

Aşağıdaki kod, UserDao adlı bir DAO'yu tanımlar. UserDao, uygulamanın geri kalanının user tablosundaki verilerle etkileşimde bulunmak için kullandığı yöntemleri sağlar.

Kotlin

@Dao
interface UserDao {
    @Query("SELECT * FROM user")
    fun getAll(): List<User>

    @Query("SELECT * FROM user WHERE uid IN (:userIds)")
    fun loadAllByIds(userIds: IntArray): List<User>

    @Query("SELECT * FROM user WHERE first_name LIKE :first AND " +
           "last_name LIKE :last LIMIT 1")
    fun findByName(first: String, last: String): User

    @Insert
    fun insertAll(vararg users: User)

    @Delete
    fun delete(user: User)
}

Java

@Dao
public interface UserDao {
    @Query("SELECT * FROM user")
    List<User> getAll();

    @Query("SELECT * FROM user WHERE uid IN (:userIds)")
    List<User> loadAllByIds(int[] userIds);

    @Query("SELECT * FROM user WHERE first_name LIKE :first AND " +
           "last_name LIKE :last LIMIT 1")
    User findByName(String first, String last);

    @Insert
    void insertAll(User... users);

    @Delete
    void delete(User user);
}

DAO'lar hakkında daha fazla bilgi edinmek için Room DAO'larını kullanarak verilere erişme başlıklı makaleyi inceleyin.

Veritabanı

Aşağıdaki kod, veritabanını barındıracak bir AppDatabase sınıfı tanımlar. AppDatabase, veritabanı yapılandırmasını tanımlar ve uygulamanın kalıcı verilere ana erişim noktası olarak kullanılır. Veritabanı sınıfı aşağıdaki koşulları karşılamalıdır:

  • Sınıf, veritabanıyla ilişkili tüm veri öğelerini listeleyen bir entities dizisi içeren bir @Database ek açıklamasıyla ek açıklamaya tabi tutulmalıdır.
  • Sınıf, RoomDatabase sınıfını genişleten soyut bir sınıf olmalıdır.
  • Veritabanı sınıfı, veritabanı ile ilişkili her DAO sınıfı için sıfır bağımsız değişkeni olan ve DAO sınıfının bir örneğini döndüren soyut bir yöntem tanımlamalıdır.

Kotlin

@Database(entities = [User::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}

Java

@Database(entities = {User.class}, version = 1)
public abstract class AppDatabase extends RoomDatabase {
    public abstract UserDao userDao();
}

Not: Uygulamanız tek bir işlemde çalışıyorsa AppDatabase sınıfının bir örneğini oluştururken tekil tasarım kalıbını uygulamanız gerekir. Her RoomDatabase örneği oldukça pahalıdır ve tek bir işlemde birden fazla örneğe erişmenize nadiren ihtiyaç duyulur.

Uygulamanız birden fazla işlemde çalışıyorsa veritabanı oluşturucu çağırmanıza enableMultiInstanceInvalidation() ekleyin. Bu sayede, her işlemde bir AppDatabase örneğiniz olduğunda, paylaşılan veritabanı dosyasını bir işlemde geçersiz kılabilirsiniz. Bu geçersiz kılma işlemi, diğer işlemlerdeki AppDatabase örneklerine otomatik olarak yayılır.

Kullanım

Veri öğesini, DAO'yu ve veritabanı nesnesini tanımladıktan sonra veritabanının bir örneğini oluşturmak için aşağıdaki kodu kullanabilirsiniz:

Kotlin

val db = Room.databaseBuilder(
            applicationContext,
            AppDatabase::class.java, "database-name"
        ).build()

Java

AppDatabase db = Room.databaseBuilder(getApplicationContext(),
        AppDatabase.class, "database-name").build();

Ardından, DAO örneği almak için AppDatabase içindeki soyut yöntemleri kullanabilirsiniz. Ardından, veritabanıyla etkileşim kurmak için DAO örneğindeki yöntemleri kullanabilirsiniz:

Kotlin

val userDao = db.userDao()
val users: List<User> = userDao.getAll()

Java

UserDao userDao = db.userDao();
List<User> users = userDao.getAll();

Ek kaynaklar

Room hakkında daha fazla bilgi edinmek için aşağıdaki ek kaynakları inceleyin:

Örnekler

Codelab uygulamaları

Bloglar