Gérez vos données localement pour une application Android 100 % hors-ligne

Room offre plusieurs options pour vous permettre, en tant que développeur, de personnaliser son comportement et optimiser ses performances.

Exportez des schémas de base de données

La première option est une option de compilation. Elle permet d'exporter les informations de schéma de votre base de données dans des fichiers JSON dans un répertoire donné.

Les fichiers JSON exportés représentent l'historique des schémas de votre base de données. En effet, au fur et à mesure des mises à jour de votre application, la structure de la base de données qu’elle manipule évolue pour répondre au mieux au besoin fonctionnel de votre application. La structure peut évoluer de multiples façons d’une mise à jour sur l’autre : ajout ou suppression d’une table, ajout ou suppression d’un attribut, etc.

Stocker ces différentes versions de la structure de votre base de données dans le temps au sein de votre projet et de votre système de contrôle des versions permet à Room de créer des versions antérieures de la base de données.

Pour déclarer le répertoire de votre projet dans lequel vous souhaitez que Room exporte les informations de schéma de votre base de données, rendez-vous dans le fichier "build.gradle.kts" du module "app". La suite dépend de la configuration de votre projet.

Si vous utilisez APT dans votre projet :

1. Le blocandroidcontient le blocdefaultConfig, à l'intérieur duquel vous devez déclarer le blocjaveCompileOptions. Dans ce dernier, déclarez le blocannotationProcessorOptions.

2. Au sein de ce dernier bloc, utilisez l’attributargumentspour y ajouter une collectionMap qui prendra l’ensemble des options de compilation. 

Puisque du code vaut mille mots, voici la structure que vous devriez avoir.

android {
  defaultConfig {
    javaCompileOptions {
      annotationProcessorOptions {
        arguments += mapOf(
          //…
        )
      }
    }
  }
}

3. Dans cette collection, déclarez le répertoire de votre projet dans lequel vous souhaitez que Room exporte les informations de schéma de votre base de données. Utilisez pour cela la cléRoom.schemaLocation et comme valeur le chemin vers le répertoire. 

javaCompileOptions {
  annotationProcessorOptions {
    arguments += mapOf(
      "Room.schemaLocation" to "$projectDir/schemas"
    )
  }
}

Si vous utilisez KSP dans votre projet :

1. Déclarez un blockspdans le blocdefaultConfigcontenu dans le bloc android. 

2. Au sein du bloc ksp, utilisez la fonctionargqui prend deux arguments : une clé et une valeur. 

3. Pour déclarer le répertoire de votre projet dans lequel vous souhaitez que Room exporte les informations de schéma de votre base de données, utilisez la clé Room.schemaLocationet comme valeur le chemin vers le répertoire. Par exemple :

ksp {
  arg("Room.schemaLocation", "$projectDir/schemas")
}

Activez le processeur d'annotations incrémentielles Gradle

La deuxième option de compilation permet d'activer le processeur d’annotations incrémentielles Gradle. 

L’avantage est de ne compiler que les annotations qui ont changé depuis la dernière compilation. Cette option d’optimisation accélère considérablement le processus de compilation. Elle est d’autant plus intéressante si votre projet est volumineux.

Que vous utilisiez APT ou KSP, la clé à utiliser pour configurer cette option est  Room.incremental et la valeur booléenne :

• truepour activer l’option ;

• falsepour désactiver l’option.

javaCompileOptions {
  annotationProcessorOptions {
    arguments += mapOf(
      "Room.incremental" to “true”
    )
  }
}

ksp {
  arg("Room.incremental", “true”)
}

Générez des fichiers sources Kotlin au lieu de Java

Par défaut, le code généré par la bibliothèque Room est du code Java. Dans le cas où vous utilisez le langage de programmation Kotlin et l’outil KSP dans votre projet, vous pouvez demander à Room de générer du code Kotlin plutôt que Java. C’est la troisième option.

Pour ce faire, vous devez utiliser la clé  Room.generateKotlinet une valeur booléenne :

• truepour générer du Kotlin ;

• falsepour générer du Java.

Découvrez une alternative avec le plugin Gradle

Depuis la version 2.6.0 de Room, il est possible d’utiliser, en plus des deux dépendances déclarées dans le chapitre précédent, un plugin Gradle. Cette dernière option est une alternative à APT et KSP pour configurer certaines options de Room. 

1. Déclarez le plugin au sein du catalogue Gradle et plus spécifiquement dans la sectionplugins du fichier "libs.versions.toml".

[plugins]
Room = { id = "androidx.Room", version.ref = "Room" }

2. Déclarez son usage. Pour ce faire, rendez-vous dans le fichier "build.gradle.kts" qui se trouve à la racine du projet Android Studio pour y ajouter, dans la sectionplugins, le plugin Room.

// Top-level build file where you can add configuration options common to all sub-projects/modules.
plugins {
  //…
  alias(libs.plugins.Room) apply false
}

3. Activez l’utilisation du plugin au sein du module "app" du projet Android. Rendez-vous donc dans le fichier "build.gradle.kts" qui se trouve, cette fois-ci, dans le dossier "app" de votre projet Android. Cherchez la sectionpluginset ajoutez-y une référence au plugin Room.

plugins {
  //…
  alias(libs.plugins.Room)
}

4. Si vous réalisez la synchronisation de votre projet, vous devriez obtenir l’erreur suivante.

- FAILURE Build completed with 2 failures.
1: Task failed with an exception.
-----------
* What went wrong:
A problem occurred configuring project ':app'.
> The Room Gradle plugin was applied but no schema location was specified. 
Use the `Room { schemaDirectory(...) }` DSL to specify one.

Le message d’erreur précise que l’utilisation de ce plugin nécessite une configuration obligatoire : indiquer le répertoire dans lequel le schéma de votre base de données sera exporté.

L’usage de ce plugin est donc une alternative à la définition de l’optionRoom.schemaLocationvia APT ou KSP. Pour configurer le plugin, vous devez suivre les étapes suivantes :

1. Déclarez dans le fichier "build.gradle.kts" du module "app" un blocRoomau sein du bloc  androidexistant. 

2. Pour préciser le répertoire dans lequel le schéma de votre base de données sera exporté, utilisez la fonctionschemaDirectoryqui prend pour paramètre le chemin du répertoire. 

Room {
  schemaDirectory("$projectDir/schemas")
}

Voici une vidéo qui récapitule les principales étapes pour configurer les options de Room avec le plugin Gradle.

À vous de jouer !

Contexte

La configuration de la base de données Room n’est pas terminée.

Le but de cet exercice est d'ajouter le plugin Gradle Room et de le configurer dans le projet disponible sur GitHub (Java ou Kotlin).

Consignes

1. Dans la section plugins du catalogue Gradle, référencez le plugin Gradle Room.

2. Appliquez cette nouvelle dépendance au projet.

3. Configurez le plugin Gradle Room pour indiquer le répertoire dans lequel le schéma de votre base de données sera exporté.

Livrables

Vous pouvez dupliquer le projet GitHub pour modifier le code source du projet et fournir un projet qui compile.

En résumé

• L'utilisation de Room dans un projet Android nécessite l’ajout de dépendances.

• Il est possible de configurer des options de compilation de Room via APT ou KSP pour personnaliser son comportement et optimiser ses performances.

• La première option de compilation de Room via APT ou KSP est de spécifier le répertoire où exporter les informations de schéma de votre base de données.

• La deuxième option de compilation de Room via APT ou KSP est d’activer ou non le processeur d'annotations incrémentielles Gradle.

• La troisième option de compilation de Room via APT ou KSP est d’indiquer si la génération de code doit se faire en Java ou en Kotlin.

• Pour spécifier le répertoire où exporter les informations de schéma de votre base de données, il est possible d’utiliser le plugin Gradle Room plutôt que la configuration APT ou KSP.

Vous avez configuré avec succès Room au sein de votre projet. Nous pouvons à présent commencer à utiliser la bibliothèque pour créer les premiers éléments de la base de données de l’application PETiSoin.