Zapisuj dane w lokalnej bazie danych dzięki funkcji Room Część Android Jetpack.

Aplikacje, które przetwarzają nieprostą ilość uporządkowanych danych, mogą znacznie lepiej korzystać z ich lokalnego przechowywania. Najczęstszym przypadkiem użycia jest zapisywanie w pamięci podręcznej odpowiednich danych, dzięki czemu gdy urządzenie nie ma dostępu do sieci, użytkownik może je przeglądać w trybie offline.

Biblioteka trwałości pokoju udostępnia warstwę abstrakcji w stosunku do SQLite, aby umożliwić płynny dostęp do bazy danych przy jednoczesnym wykorzystaniu wszystkich możliwości SQLite. Zalety pokoju:

  • Weryfikacja czasu kompilacji zapytań SQL.
  • Wygodne adnotacje, które minimalizują powtarzalny i podatny na błędy kod stały.
  • Uproszczone ścieżki migracji bazy danych.

Dlatego zdecydowanie zalecamy korzystanie z funkcji Room, a nie bezpośredniego używania interfejsów SQLite API.

Skonfiguruj

Aby korzystać z funkcji Pokoje w aplikacji, dodaj do jej pliku build.gradle te zależności:

Odlotowy

dependencies {
    def room_version = "2.6.1"

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

    // To use Kotlin annotation processing tool (kapt)
    kapt "androidx.room:room-compiler:$room_version"
    // To use Kotlin Symbol Processing (KSP)
    ksp "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"
}

Kotlin

dependencies {
    val room_version = "2.6.1"

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

    // To use Kotlin annotation processing tool (kapt)
    kapt("androidx.room:room-compiler:$room_version")
    // To use Kotlin Symbol Processing (KSP)
    ksp("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")
}

Główne komponenty

W sekcji Pokój są 3 główne elementy:

  • Klasa bazy danych, która zawiera bazę danych i służą za główny punkt dostępu do bazowego połączenia z trwałymi danymi aplikacji.
  • Encje danych reprezentujące tabele w bazie danych aplikacji.
  • Obiekty dostępu do danych (DAO), które udostępniają metody używane przez aplikację do wysyłania zapytań, aktualizowania, wstawiania i usuwania danych z bazy danych.

Klasa bazy danych udostępnia aplikacji instancje DAO powiązane z tą bazą danych. Z kolei aplikacja może używać DAO do pobierania informacji z bazy danych jako instancji powiązanych obiektów encji danych. Aplikacja może też używać zdefiniowanych encji danych do aktualizowania wierszy z odpowiednich tabel lub tworzenia nowych wierszy do wstawiania. Rysunek 1 obrazuje zależność między różnymi elementami zawartości pomieszczenia.

Rysunek 1. Schemat architektury biblioteki sal.

Przykładowa implementacja

W tej sekcji znajdziesz przykładową implementację bazy danych Room z 1 encją danych i 1 DAO.

Encja danych

Poniższy kod definiuje encję danych User. Każde wystąpienie elementu User odpowiada wierszowi w tabeli user w bazie danych aplikacji.

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

Więcej informacji o elementach danych w Pokoju znajdziesz w artykule Definiowanie danych za pomocą elementów danych pokoju.

Obiekt dostępu do danych

Poniższy kod definiuje DAO o nazwie UserDao. UserDao udostępnia metody, których reszta aplikacji używa do interakcji z danymi przedstawionymi w tabeli user.

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

Więcej informacji o DAO znajdziesz w artykule na temat uzyskiwania dostępu do danych za pomocą funkcji DAO dla sal.

Baza danych

Poniższy kod definiuje klasę AppDatabase do przechowywania bazy danych. AppDatabase określa konfigurację bazy danych i służy jako główny punkt dostępu aplikacji do utrwalonych danych. Klasa bazy danych musi spełniać te warunki:

  • Klasa musi być oznaczona adnotacją @Database zawierającą tablicę entities z listą wszystkich encji danych powiązanych z bazą danych.
  • Klasa musi być klasą abstrakcyjną poszerzającą zakres RoomDatabase.
  • Dla każdej klasy DAO powiązanej z bazą danych musi ona zdefiniować metodę abstrakcyjną, która ma zero argumentów i zwraca instancję klasy DAO.

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

Uwaga: jeśli aplikacja działa w ramach jednego procesu, podczas tworzenia instancji obiektu AppDatabase stosuj się do wzorca projektowego typu singleton. Każda instancja RoomDatabase jest dość kosztowna i rzadko trzeba mieć dostęp do wielu instancji w ramach jednego procesu.

Jeśli Twoja aplikacja działa w wielu procesach, dodaj do wywołania kreatora baz danych enableMultiInstanceInvalidation(). Dzięki temu, gdy w każdym procesie masz instancję AppDatabase, możesz unieważnić udostępniony plik bazy danych w jednym procesie. To unieważnienie zostanie automatycznie rozpowszechnione w instancjach AppDatabase w innych procesach.

Wykorzystanie

Po zdefiniowaniu encji danych, DAO i obiektu bazy danych możesz utworzyć instancję bazy danych za pomocą tego kodu:

Kotlin

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

Java

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

Następnie możesz użyć metod abstrakcyjnych z AppDatabase, aby uzyskać wystąpienie DAO. Do interakcji z bazą danych możesz też używać metod z instancji DAO:

Kotlin

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

Java

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

Dodatkowe materiały

Aby dowiedzieć się więcej o salach, zobacz te dodatkowe zasoby:

Próbki

Ćwiczenia z programowania

Blogi