Daten mit Room in einer lokalen Datenbank speichern   Teil von Android Jetpack.

Apps, die mit einer nicht unerheblichen Menge an strukturierten Daten umgehen, können von der lokalen Speicherung dieser Daten erheblich profitieren. Der häufigste Anwendungsfall besteht darin, relevante Daten im Cache zu speichern, damit Nutzer auch dann auf diese Inhalte zugreifen können, wenn das Gerät keinen Zugriff auf das Netzwerk hat.

Die Room-Persistenzbibliothek bietet eine Abstraktionsschicht über SQLite, die einen flüssigen Datenbankzugriff ermöglicht und gleichzeitig die volle Leistung von SQLite nutzt. Room bietet insbesondere folgende Vorteile:

  • Überprüfung von SQL-Abfragen zur Kompilierungszeit
  • Mithilfe von Anmerkungen lassen sich sich wiederholende und fehleranfällige Boilerplate-Codefragmente minimieren.
  • Optimierte Datenbankmigrationspfade

Aus diesen Gründen empfehlen wir Ihnen dringend, Room zu verwenden, anstatt die SQLite APIs direkt zu verwenden.

Einrichten

Wenn Sie Room in Ihrer App verwenden möchten, fügen Sie der Datei build.gradle Ihrer App die folgenden Abhängigkeiten hinzu.

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

Hauptkomponenten

Room besteht aus drei Hauptkomponenten:

  • Die Datenbankklasse, die die Datenbank enthält und als Hauptzugangspunkt für die zugrunde liegende Verbindung zu den gespeicherten Daten Ihrer App dient.
  • Datenentitäten, die Tabellen in der Datenbank Ihrer App darstellen.
  • Datenzugriffsobjekte (DAOs), die Methoden bereitstellen, mit denen Ihre App Daten in der Datenbank abfragen, aktualisieren, einfügen und löschen kann.

Die Datenbankklasse stellt Ihrer App Instanzen der mit dieser Datenbank verknüpften DAOs zur Verfügung. Die App kann dann die DAOs verwenden, um Daten als Instanzen der zugehörigen Datenentitätsobjekte aus der Datenbank abzurufen. Die App kann die definierten Datenentitäten auch verwenden, um Zeilen aus den entsprechenden Tabellen zu aktualisieren oder neue Zeilen zum Einfügen zu erstellen. Abbildung 1 veranschaulicht die Beziehung zwischen den verschiedenen Komponenten von Room.

Abbildung 1: Diagramm der Architektur der Raumbibliothek.

Beispielimplementierung

In diesem Abschnitt wird eine Beispielimplementierung einer Room-Datenbank mit einer einzelnen Datenentität und einer einzelnen DAO vorgestellt.

Datenentität

Im folgenden Code wird ein User-Datenelement definiert. Jede Instanz von User stellt eine Zeile in einer user-Tabelle in der Datenbank der App dar.

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

Weitere Informationen zu Datenentitäten in Room finden Sie unter Daten mit Room-Entitäten definieren.

Data Access Object (DAO)

Im folgenden Code wird eine DAO namens UserDao definiert. UserDao stellt die Methoden bereit, mit denen der Rest der App mit Daten in der Tabelle user interagiert.

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

Weitere Informationen zu DAOs finden Sie unter Mit Room-DAOs auf Daten zugreifen.

Datenbank

Im folgenden Code wird eine AppDatabase-Klasse für die Datenbank definiert. AppDatabase definiert die Datenbankkonfiguration und dient als Hauptzugangspunkt der App auf die gespeicherten Daten. Die Datenbankklasse muss die folgenden Bedingungen erfüllen:

  • Die Klasse muss mit einer @Database-Anmerkung versehen sein, die ein entities-Array enthält, in dem alle mit der Datenbank verknüpften Datenentitäten aufgeführt sind.
  • Die Klasse muss eine abstrakte Klasse sein, die von RoomDatabase abgeleitet ist.
  • Für jede DAO-Klasse, die mit der Datenbank verknüpft ist, muss die Datenbankklasse eine abstrakte Methode mit null Argumenten definieren, die eine Instanz der DAO-Klasse zurückgibt.

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

Hinweis : Wenn Ihre App in einem einzelnen Prozess ausgeführt wird, sollten Sie beim Instanziieren eines AppDatabase-Objekts dem Singleton-Designmuster folgen. Jede RoomDatabase-Instanz ist ziemlich teuer und Sie benötigen selten Zugriff auf mehrere Instanzen innerhalb eines einzelnen Prozesses.

Wenn Ihre App in mehreren Prozessen ausgeführt wird, fügen Sie enableMultiInstanceInvalidation() in die Aufrufe des Datenbankbuilders ein. Wenn Sie also in jedem Prozess eine Instanz von AppDatabase haben, können Sie die freigegebene Datenbankdatei in einem Prozess ungültig machen. Diese Ungültigmachung wird dann automatisch auf die Instanzen von AppDatabase in anderen Prozessen übertragen.

Nutzung

Nachdem Sie das Datenentitäts-, das DAO- und das Datenbankobjekt definiert haben, können Sie mit dem folgenden Code eine Instanz der Datenbank erstellen:

Kotlin

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

Java

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

Anschließend können Sie mit den abstrakten Methoden aus dem AppDatabase eine Instanz der DAO abrufen. Mit den Methoden der DAO-Instanz können Sie dann mit der Datenbank interagieren:

Kotlin

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

Java

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

Weitere Informationen

Weitere Informationen zu Google Tabellen finden Sie in den folgenden Ressourcen:

Produktproben

Codelabs

Blogs