Definisci i dati utilizzando Entità camera

Quando utilizzi la libreria di persistenza della stanza per per archiviare i dati dell'app, tu definisci le entità per rappresentare gli oggetti che vuoi archiviare. Ogni entità corrisponde a una tabella nella stanza associata e ciascuna istanza di un'entità rappresenta una riga di dati e la tabella corrispondente.

Ciò significa che puoi utilizzare le entità Room per definire il database senza scrivere codice SQL.

Anatomia di un'entità

Definisci ogni entità Room come classe annotata con @Entity Un'entità camera include campi per ogni colonna nella tabella corrispondente nel database, incluso uno o più colonne che compongono la chiave principale.

Il codice seguente è un esempio di entità semplice che definisce una tabella User con colonne per ID, nome e cognome:

Kotlin

@Entity
data class User(
    @PrimaryKey val id: Int,

    val firstName: String?,
    val lastName: String?
)

Java

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

    public String firstName;
    public String lastName;
}

Nota: per rendere permanente un campo, la stanza deve potervi accedere. Puoi assicurarti che la funzionalità ha accesso a un campo rendendolo pubblico o fornendo getter metodi setter.

Per impostazione predefinita, la stanza virtuale utilizza il nome della classe come nome della tabella del database. Se desideri un nome diverso, imposta la classe tableName del @Entity. Allo stesso modo, Room utilizza i nomi dei campi come nomi delle colonne nel database per impostazione predefinita. Se vuoi che una colonna abbia un nome diverso, aggiungi il metodo @ColumnInfo nell'annotazione e imposta il campo name proprietà. L'esempio seguente mostra i nomi personalizzati di una tabella e delle relative colonne:

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

Nota: i nomi di tabelle e colonne in SQLite non fanno distinzione tra maiuscole e minuscole.

Definisci una chiave primaria

Ogni entità Room deve definire una chiave principale che identifica in modo univoco ogni riga nella tabella di database corrispondente. Il più il modo più semplice per farlo è annotare una singola colonna con @PrimaryKey:

Kotlin

@PrimaryKey val id: Int

Java

@PrimaryKey
public int id;

Nota: se hai bisogno di Room per assegnare ID automatici alle istanze delle entità, imposta il valore autoGenerate da @PrimaryKey a true.

Definisci una chiave primaria composita

Se hai bisogno che le istanze di un'entità siano identificate in modo univoco da una combinazione di A più colonne, puoi definire una chiave primaria composita elencando quelle nelle colonne primaryKeys di @Entity:

Kotlin

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

Ignora campi

Per impostazione predefinita, la stanza virtuale crea una colonna per ogni campo definito nell'entità. Se un'entità contiene campi che non vuoi rendere persistenti, puoi annotarli utilizzando @Ignore, come mostrato nel seguente snippet di codice:

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

Nei casi in cui un'entità eredita campi da un'entità padre, di solito è più facile utilizzare Proprietà ignoredColumns di l'attributo @Entity:

Kotlin

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

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

Fornisci il supporto per la ricerca di tabelle

La stanza virtuale supporta diversi tipi di annotazioni che semplificano la ricerca per maggiori dettagli nelle tabelle del tuo database. Utilizza la ricerca a testo intero, a meno che non siano minSdkVersion è inferiore a 16.

Supporta la ricerca a testo intero

Se la tua app richiede un accesso molto rapido alle informazioni del database tramite testo completo (FTS), fare in modo che le entità siano supportate da una tabella virtuale che utilizza l'estensione FTS3 o FTS4 SQLite modulo. Per utilizzare questa funzionalità, disponibile nella Stanza 2.1.0 e successive, aggiungi @Fts3 oppure @Fts4 per una determinata entità, come mostrato nel seguente snippet di codice:

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

Nota: le tabelle abilitate per FTS utilizzano sempre una chiave primaria di tipo INTEGER e con il nome colonna "rowid". Se l'entità supportata da tabella FTS definisce una chiave primaria, deve utilizzare quel tipo e quel nome di colonna.

Nei casi in cui una tabella supporta contenuti in più lingue, utilizza il metodo languageId opzione per specificare la colonna in cui sono archiviate le informazioni sulla lingua per ogni riga:

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 offre molte altre opzioni per definire le entità supportate da FTS, tra cui: l'ordinamento dei risultati, i tipi di tokenizzatore e le tabelle gestite come contenuti esterni. Per ulteriori dettagli su queste opzioni, consulta FtsOptions.

Colonne specifiche dell'indice

Se la tua app deve supportare versioni dell'SDK che non supportano FTS3- o Entità supportate dalla tabella FTS4, puoi comunque indicizzare determinate colonne nel database per velocizzare le query. Per aggiungere indici a un'entità, includi il comando indices all'interno di l'annotazione @Entity, che elenca i nomi delle colonne da includere nell'indice indice composto. Il seguente snippet di codice dimostra questa annotazione di elaborazione:

Kotlin

@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?
)

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

A volte, alcuni campi o gruppi di campi di un database devono essere univoci. Puoi applicare questa proprietà di univocità impostando il parametro unique proprietà di un @Index a true. Il seguente esempio di codice impedisce che una tabella abbia due righe contenenti lo stesso insieme di valori per firstName e lastName colonne:

Kotlin

@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?
)

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

Includi oggetti basati su AutoValue

Nota: questa funzionalità è progettata per essere utilizzata solo in entità basate su Java. A la stessa funzionalità nelle entità basate su Kotlin, è meglio usare dati corsi in un secondo momento.

Nella stanza 2.1.0 e successive, puoi utilizzare valore immutabile basato su Java corsi, che annota utilizzando @AutoValue, come entità nel database dell'app. Questo L'assistenza è particolarmente utile quando vengono considerate due istanze di un'entità se le rispettive colonne contengono valori identici.

Quando utilizzi corsi annotati con @AutoValue come entità, puoi annotare le i metodi astratti della classe utilizzando @PrimaryKey, @ColumnInfo, @Embedded e @Relation. Quando utilizzi queste annotazioni, tuttavia, devi includere i campi @CopyAnnotations ogni volta affinché la stanza possa interpretare i metodi le implementazioni generate automaticamente.

Il seguente snippet di codice mostra un esempio di una classe annotata con @AutoValue che la stanza virtuale riconosce come entità:

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