Definiowanie danych za pomocą elementów dotyczących sal

Gdy korzystasz z biblioteki trwałości sal do do przechowywania danych aplikacji, definiowanie jednostek, które będą reprezentować obiekty, które chcesz przechowywać. Każda encja odpowiada tabeli w powiązanym pokoju i każde wystąpienie encji reprezentuje wiersz danych w odpowiadającej jej tabeli.

Oznacza to, że za pomocą elementów pokoju możesz zdefiniować bazę danych schemat bez dowolnego kodu SQL.

Anatomia jednostki

Każdą encję określa się jako klasę z adnotacjami @Entity Element „Pokój” zawiera pola dla każdej kolumny w odpowiedniej tabeli w bazie danych, w tym jedno pole lub więcej kolumn, które składają się na klucz podstawowy.

Ten kod to przykład prostej encji definiującej tabelę User z kolumnami ID, first name i last name:

KotlinJava

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

Uwaga: aby zachować pole, sala musi mieć do niego dostęp. Możesz upewnić się, ma dostęp do pola przez udostępnienie go publicznie lub przez zapewnienie funkcji getter i za pomocą metod wyboru.

Domyślnie Sala używa nazwy klasy jako nazwy tabeli bazy danych. Jeśli chcesz, aby atrybut ustaw inną nazwę tabeli, tableName właściwości @Entity adnotacja. Również nazwa pokoju używa nazw pól jako nazw kolumn w z bazą danych. Jeśli chcesz, by kolumna miała inną nazwę, dodaj atrybut @ColumnInfo do i ustaw name usłudze. Ten przykład pokazuje niestandardowe nazwy tabeli i jej kolumn:

KotlinJava

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

Uwaga: w nazwach tabel i kolumn w SQLite wielkość liter nie jest rozróżniana.

Zdefiniuj klucz podstawowy

Każda encja dotycząca pokoju musi mieć zdefiniowany klucz podstawowy jednoznacznie identyfikują każdy wiersz w odpowiedniej tabeli bazy danych. Najbardziej prosty sposób to dodanie adnotacji do pojedynczej kolumny @PrimaryKey:

KotlinJava

@PrimaryKey val id: Int

@PrimaryKey
public int id;

Uwaga: jeśli chcesz, aby sala przypisywała automatyczne identyfikatory do instancji encji, ustaw parametr autoGenerate od @PrimaryKey do true.

Zdefiniuj złożony klucz podstawowy

Jeśli wystąpienia elementu mają być jednoznacznie identyfikowane za pomocą kombinacji w przypadku wielu kolumn, możesz zdefiniować złożony klucz podstawowy, podając je w primaryKeys właściwość @Entity:

KotlinJava

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

Ignoruj pola

Domyślnie Sala tworzy kolumnę dla każdego pola zdefiniowanego w elemencie. Jeśli encja zawiera pola, których nie chcesz zachowywać, możesz dodać do nich adnotacje przy użyciu @Ignore, jako w tym fragmencie kodu:

KotlinJava

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

Gdy jednostka dziedziczy pola z elementu nadrzędnego, zazwyczaj łatwiej jest korzystać ignoredColumns właściwość atrybut @Entity:

KotlinJava

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

Obsługa wyszukiwania w tabelach

Pokoje obsługują kilka typów adnotacji, które ułatwiają wyszukiwanie . Używaj wyszukiwania pełnotekstowego, chyba że minSdkVersion ma wartość mniejszą niż 16.

Obsługa wyszukiwania pełnotekstowego

Jeśli Twoja aplikacja wymaga bardzo szybkiego dostępu do informacji z bazy danych w trybie pełnotekstowym wyszukiwarka (FTS), umieść encje w oparciu o tabelę wirtualną, która używa rozszerzenie SQLite FTS3 lub FTS4 . Aby użyć tej funkcji, dostępnej w Pokoju w wersji 2.1.0 lub nowszej, dodaj parametr @Fts3 lub @Fts4 adnotacja do danego elementu, na przykład w tym fragmencie kodu:

KotlinJava

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

Uwaga: tabele z włączoną funkcją FTS zawsze używają klucza podstawowego typu INTEGER i z nazwa kolumny "rowid". Jeśli encja wspierana przez tabelę FTS definiuje klucz podstawowy, musi używać tego typu i nazwy kolumny.

Jeśli w tabeli znajdują się treści w wielu językach, użyj funkcji Opcja languageId określająca kolumnę, która przechowuje informacje o języku każdy wiersz:

KotlinJava

@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 udostępnia kilka innych opcji definiowania elementów obsługiwanych przez FTS, w tym: kolejność wyników, typy tokenizacji i tabele zarządzane jako treść zewnętrzna. Dla: więcej informacji na temat tych opcji znajdziesz w FtsOptions.

Indeksuj kolumny z konkretnymi

Jeśli Twoja aplikacja musi obsługiwać wersje pakietu SDK, które nie obsługują FTS3- lub jednostek opartych na tabeli FTS4, nadal możesz indeksować niektóre kolumny w bazie danych aby przyspieszyć zapytania. Aby dodać indeksy do elementu, umieść w nim indeksy indices w usłudze @Entity, podając nazwy kolumn, które chcesz uwzględnić w indeksie lub indeksu złożonego. Ten fragment kodu ilustruje tę adnotację proces:

KotlinJava

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

Czasami niektóre pola lub grupy pól w bazie danych muszą być niepowtarzalne. Możesz egzekwować tę właściwość wyjątkowości przez ustawienie atrybutu unique właściwość @Index adnotacja do true. Poniższy przykładowy kod zapobiega sytuacji, w której tabela ma dwa wiersze zawierające ten sam zbiór wartości w kolumnach firstName i Kolumny (lastName):

KotlinJava

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

Uwzględnij obiekty oparte na wartości automatycznej

Uwaga: ta funkcja jest przeznaczona do użycia wyłącznie w elementach opartych na Javie. Do tych samych funkcji w jednostkach opartych na Kotlin, lepiej użyć danych zajęcia

W pokoju 2.1.0 i nowszych możesz użyć stałej wartości w Javie zajęcia, które dodajesz za pomocą adnotacji @AutoValue jako elementów w bazie danych aplikacji. Ten wsparcie jest szczególnie przydatne, gdy brane są pod uwagę dwa przypadki elementu , jeśli ich kolumny zawierają identyczne wartości.

Podczas używania klas oznaczonych jako elementy @AutoValue możesz dodawać adnotacje abstrakcyjne metody klasy z użyciem @PrimaryKey, @ColumnInfo, @Embedded i @Relation. Jeśli jednak używasz tych adnotacji, musisz dodać atrybut @CopyAnnotations za każdym razem, aby sala mogła zinterpretować metodę automatycznie generowanych implementacji.

Poniższy fragment kodu zawiera przykład klasy z adnotacją @AutoValue, który sala rozpoznaje jako encję:

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