Bàsic

#Introducció

En la programació orientada a objectes, estem acostumats que els objectes mantinguin referències a altres objectes, formant algun tipus de graf d’objectes. No obstant això, les bases de dades relacionals tradicionals d’estil SQL treballen amb taules de dades primitives, utilitzant claus foranes i taules d’unió per expressar relacions. Esbrinar com mapar les nostres classes a taules relacionals pot ser frustrant i normalment comporta molt codi repetitiu.

Un ORM típic treballa a partir de codi Kotlin i, o bé genera una estructura de base de dades adequada, o bé col·labora amb tu per identificar com s’han de mapar les classes a una estructura de taules existent. L’ORM normalment et genera part del codi i et proporciona una llibreria que, combinades, amaguen bona part dels detalls de la base de dades.

#ORM

Crea un projecte amb el nom room-basic amb Amper i Idea.

Utilitza la plantilla “JVM Console Application”.

Per utilitzar Room, necessites dues dependències al teu fitxer module.yaml:

1. La llibreria de temps d’execució (runtime)
2. Un processador d’anotacions (veure Kotlin Symbol Processing)

product: jvm/app
dependencies:
  - androidx.room:room-ktx:2.8.0
settings:
  kotlin:
    ksp:
      processors:
        - androidx.room:room-compiler:2.8.0

Maven Repository - androidx.room

A grans trets, l’ús de Room es basa en tres conjunts de classes:

1. Entitats (Entities), que són classes senzilles que modelen les dades que transfereixes cap a i des de la base de dades
2. L’objecte d’accés a dades (DAO), que proporciona la descripció de l’API que vols per treballar amb determinades entitats
3. La base de dades, que uneix totes les entitats i els DAOs per a una única base de dades SQLite

#Entities

Les entitats són classes que representen:

• les dades que vols emmagatzemar en una taula, i
• una unitat típica d’un conjunt de resultats que intentes recuperar de la base de dades

Des del punt de vista del codi, una entitat és una classe Kotlin marcada amb l’anotació @Entity.

Crea el fitxer src/Database.kt.

Per exemple, aquí tens una classe Note que fa d’entitat de Room:

import androidx.room.*

@Entity(tableName = "Note")
data class Note(
    @PrimaryKey val id: String,
    val title: String,
    val text: String,
    val version: Int
)

No hi ha cap superclasse específica requerida per a les entitats, i s’espera que sovint siguin classes de dades senzilles, com veiem aquí.

L’anotació @Entity pot tenir propietats per personalitzar el comportament de la teva entitat i com Room hi treballa. En aquest cas, tenim la propietat tableName. El nom per defecte de la taula SQLite és el mateix que el de la classe de l’entitat, però tableName et permet sobreescriure’l i proporcionar el teu propi nom de taula. Aquí, el sobreescrivim perquè sigui Note.

De vegades, les teves propietats estaran marcades amb anotacions que descriuen el seu rol.

En aquest exemple, el camp id té l’anotació @PrimaryKey, que indica a Room que és l’identificador únic d’aquesta entitat. Room ho utilitzarà per saber com actualitzar i eliminar objectes Note pels seus valors de clau primària.

#DAO

“Data access object” (DAO) és una manera elegant de dir “l’API cap a les dades”. La idea és que tinguis un DAO que proporcioni mètodes per a les operacions de base de dades que necessites: consultes, insercions, actualitzacions, eliminacions, etc.

A Room, el DAO s’identifica amb l’anotació @Dao, aplicada a una classe abstracta o a una interfície. La implementació concreta real te la generarà el processador d’anotacions de Room.

El rol principal de la interface anotada amb @Dao és tenir un o més mètodes, cadascun amb les seves anotacions de Room, que identifiquen què vols fer amb la base de dades i les teves entitats. Això fa el mateix paper que les funcions anotades amb @GET o @POST en una interfície de Ktorfit.

Modifica el fitxer src/Database.kt per afegir el DAO.

@Entity(tableName = "Note")
data class Note(
    @PrimaryKey val id: String,
    val title: String,
    val text: String,
    val version: Int
) {
    @Dao
    interface SQL {
        @Query("select * from Note")
        suspend fun select(): List<Note>

        @Insert
        suspend fun insert(note: Note)

        @Update
        suspend fun update(note: Note)

        @Delete
        suspend fun delete(vararg note: Note)
    }
}

A banda de l’anotació @Dao a la interfície SQL, tenim quatre funcions, cadascuna amb la seva pròpia anotació: @Query, @Insert, @Update i @Delete, que es corresponen amb les operacions de base de dades.

La funció select() té l’anotació @Query. Principalment, @Query s’utilitzarà per a sentències SQL SELECT, on poses l’SQL mateix dins de l’anotació. Aquí, estem recuperant tot de la taula Note.

Les tres funcions restants utilitzen les anotacions @Insert, @Update i @Delete, mapejades a funcions del mateix nom. Els noms de les funcions, de fet, no importen: podrien ser larry(), curly() i moe() i funcionarien igual. Com pots esperar, @Insert insereix una entitat a la taula, @Update actualitza una fila existent per reflectir les propietats de l’entitat subministrada, i @Delete elimina les files corresponents a les claus primàries de les entitats proporcionades. En aquest exemple, insert() i update() accepten cadascuna una Note, mentre que delete() accepta un vararg de Note. Room admet ambdós patrons, així com d’altres, com ara un List<Note> — tria el que s’ajusti a les teves necessitats.

#Database

A més de les entitats i els DAOs, tindràs almenys una classe abstracta anotada amb @Database, que estèn RoomDatabase. Aquesta classe connecta el fitxer de base de dades, les entitats i els DAOs.

Al projecte d’exemple, tenim una NoteDatabase que compleix aquest rol:

@Database(entities = [NoteEntity::class], version = 1)
abstract class NoteDatabase : RoomDatabase() {
    abstract fun note(): Note.SQL
}