Bergabunglah bersama kami di ⁠#Android11: The Beta Launch Show pada tanggal 3 Juni!

Menentukan data menggunakan entitas Room

Saat menggunakan library persistensi Room, tentukan kumpulan kolom yang terkait sebagai entitas. Untuk setiap entitas, akan ada tabel yang dibuat dalam objek Database yang terkait untuk menampung itemnya. Anda harus mereferensikan class entitas melalui array entities di class Database.

Cuplikan kode berikut menunjukkan cara menentukan entitas:

Kotlin

    @Entity
    data class User(
        @PrimaryKey var id: Int,
        var firstName: String?,
        var lastName: String?
    )
    

Java

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

        public String firstName;
        public String lastName;
    }
    

Untuk mempertahankan kolom, Room harus dapat mengaksesnya. Anda dapat mengatur kolom agar bersifat publik, atau memberikan pengambil (getter) dan penyetel (setter) untuknya. Jika menggunakan pengambil dan penyetel, harap diingat bahwa metode ini didasarkan pada konvensi JavaBeans dalam Room.

Menggunakan kunci utama

Setiap entitas harus menentukan setidaknya satu kolom sebagai kunci utama. Meskipun hanya ada satu kolom, Anda tetap harus menganotasikan kolom dengan anotasi @PrimaryKey. Selain itu, jika Anda ingin Room menetapkan ID otomatis ke entitas, Anda dapat menetapkan properti autoGenerate @PrimaryKey. Jika entitas memiliki kunci utama komposit, Anda dapat menggunakan properti primaryKeys dari anotasi @Entity, seperti yang ditunjukkan dalam cuplikasn kode berikut:

Kotlin

    @Entity(primaryKeys = arrayOf("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;
    }
    

Secara default, Room menggunakan nama class sebagai nama tabel database. Jika Anda ingin tabel memiliki nama yang berbeda, tetapkan properti tableName dari anotasi @Entity, seperti yang ditunjukkan dalam cuplikan kode berikut:

Kotlin

    @Entity(tableName = "users")
    data class User (
        // ...
    )
    

Java

    @Entity(tableName = "users")
    public class User {
        // ...
    }
    

Perhatian: Nama tabel dalam SQLite tidak peka terhadap huruf besar dan kecil.

Seperti properti tableName, Room menggunakan nama kolom sebagai nama kolom di database. Jika Anda ingin kolom memiliki nama yang berbeda, tambahkan anotasi ke @ColumnInfo ke kolom, seperti yang ditunjukkan dalam cuplikan kode berikut:

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

Mengabaikan kolom

Secara default, Room akan membuat kolom bagi setiap kolom yang ditentukan dalam entitas. Jika entitas memiliki kolom yang tidak ingin dipertahankan, anotasikan kolom menggunakan @Ignore, seperti yang ditunjukkan dalam cuplikan kode berikut:

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

Jika suatu entitas mewarisi kolom dari parent entity, biasanya akan lebih mudah untuk menggunakan properti ignoredColumns dari atribut @Entity:

Kotlin

    open class User {
        var picture: Bitmap? = null
    }

    @Entity(ignoredColumns = arrayOf("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;
    }
    

Room mendukung beberapa jenis anotasi yang memudahkan Anda menelusuri detail dalam tabel database. Gunakan penelusuran teks lengkap kecuali minSdkVersion aplikasi Anda kurang dari 16.

Mendukung penelusuran teks lengkap

Jika aplikasi Anda memerlukan akses yang sangat cepat ke informasi database melalui penelusuran teks lengkap (FTS), atur agar entitas Anda didukung oleh tabel virtual yang menggunakan modul ekstensi SQLite FTS3 atau FTS4. Untuk menggunakan kemampuan ini (tersedia di Room 2.1.0 dan yang lebih tinggi), tambahkan anotasi @Fts3 atau @Fts4 ke entitas yang ditentukan, seperti yang ditunjukkan dalam cuplikan kode berikut:

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

Jika tabel mendukung konten dalam berbagai bahasa, gunakan opsi languageId untuk menentukan kolom yang menyimpan informasi bahasa bagi setiap baris:

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 menyediakan beberapa opsi lain untuk menentukan entitas yang didukung FTS, termasuk pengurutan hasil, jenis tokenizer, dan tabel yang dikelola sebagai konten eksternal. Untuk detail selengkapnya tentang opsi ini, lihat referensi FtsOptions.

Mengindeks kolom spesifik

Jika aplikasi Anda harus mendukung versi SDK yang tidak mengizinkan penggunaan entitas yang didukung oleh tabel FTS3 atau FTS4, Anda masih dapat mengindeks kolom tertentu dalam database untuk mempercepat kueri. Untuk menambahkan indeks pada entitas, sertakan properti indices dalam anotasi @Entity, dengan mencantumkan nama kolom yang ingin disertakan pada indeks atau indeks komposit. Cuplikan kode berikut menunjukkan proses anotasi ini:

Kotlin

    @Entity(indices = arrayOf(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;
    }
    

Terkadang, kolom atau grup kolom tertentu dalam database harus bersifat unik. Anda dapat menerapkan properti keunikan ini dengan menetapkan properti unique dari anotasi @Index ke true. Contoh kode berikut mencegah tabel memiliki dua baris yang berisi kumpulan nilai yang sama untuk kolom firstName dan lastName:

Kotlin

    @Entity(indices = arrayOf(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;
    }
    

Menyertakan objek berbasis AutoValue

Pada Room 2.1.0 dan yang lebih tinggi, Anda dapat menggunakan class nilai tetap berbasis Java, yang dianotasikan menggunakan @AutoValue, sebagai entitas dalam database aplikasi Anda. Dukungan ini sangat berguna ketika dua instance dari satu entitas dianggap sama jika kolomnya berisi nilai yang sama.

Saat menggunakan class yang dianotasikan dengan @AutoValue sebagai entitas, Anda dapat menganotasikan metode abstrak class menggunakan @PrimaryKey, @ColumnInfo, @Embedded, dan @Relation. Namun, saat menggunakan anotasi ini, Anda harus selalu menyertakan anotasi @CopyAnnotations agar Room dapat dengan benar menginterpretasikan penerapan yang dihasilkan otomatis oleh metode.

Cuplikan kode berikut memberikan contoh class yang dianotasikan dengan @AutoValue yang dikenali oleh Room sebagai entitas:

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