Tutoriel sur le développement d'une application Web GWT de prise de commandes fonctionnant en mode hors-ligne

Cette application, pour un client fictif et qu'il soit en ligne ou non, doit répondre aux besoins suivants :

1. Présenter la liste des articles, des commandes et de leur contenu à l'utilisateur ;
2. Permettre à l'utilisateur de saisir de nouveaux articles et de nouvelles commandes, et modifier celles-ci ;
3. Chaque article en base a la possibilité d'être associé à deux fichiers : une image et une fiche technique. Ces fichiers doivent être consultables ;
4. Les transitions entre mode en ligne et mode hors-ligne doivent être transparentes pour l'utilisateur.

À des fins de simplification, nous aurons à gérer trois tables :

• articles : stocke les données de chaque article du catalogue ;
• orders : stocke les en-têtes des commandes ;
• order_items : stocke les postes de chaque commande.

Ces tables existent dans la base de données serveur et dans la base de données du navigateur (SQL.js embarqué).

II-A. Côté serveur▲

II-B. Côté client▲

II-C. Simple, non ?▲

Avant de rentrer dans les détails, je voudrais vous présenter l'architecture à grosse maille de notre application.

Côté serveur, nous avons trois composants importants.

• ManifestServlet : cette servlet génère le fichier manifest demandé par le navigateur. On doit mettre en cache non seulement les fichiers statiques de l'application (index.html, les fichiers js, les fichiers css,etc.), mais aussi les fichiers générés lors de la compilation GWT ainsi que les fichiers (images et fiches techniques) associés aux articles.
• UploadServlet : cette servlet reçoit les requêtes POST du client, stocke les fichiers envoyés et les associe aux articles souhaités (en stockant le nom des fichiers dans les enregistrements de la base de données).
• SyncServiceServlet : cette servlet permet le dialogue entre client et serveur afin de synchroniser les bases de données.

Côté client, nos données sont stockées dans une base de données SQLite, par-dessus laquelle nous trouvons la classe DataAccess qui donne un accès indépendant de la base au reste de l'application, et sous forme de DTO.

Des deux côtés, nous trouverons les classes UpstreamSynchroManager et DownstreamSynchroManager qui géreront respectivement la synchronisation montante et la synchronisation descendante.

La particularité de cette architecture consiste dans le fait que la partie cliente fonctionne de façon autonome, avec sa propre base de données, celle-ci étant synchronisée avec celle du serveur par des composants indépendants.

En fait, la majeure partie de l'application cliente n'a pas conscience de la présence d'un serveur dans l'architecture. En effet, les accès aux données sont faits directement depuis la base SQLite locale. Cela a deux effets.

• L'accès aux données est synchrone pour le client. Cela permet de simplifier énormément le code client (plus de callback à implémenter pour attendre les données).
• La couche de synchronisation travaille directement sur la base de données et voit donc des modifications « atomiques » et non des appels de méthodes fonctionnels. Cela peut rendre plus difficile la gestion de la sécurité et des droits (rien n'empêche un utilisateur de pirater l'application cliente en ajoutant des données dans la base locale). Il faudra donc bien réfléchir avant d'adopter cette architecture, en répondant à la question : « Puis-je implémenter un contrôle de droits d'accès au niveau de la couche de stockage plutôt qu'au niveau de la couche métier ? ».

Le fichier manifest est utilisé par le navigateur afin de recenser tous les fichiers qui doivent être stockés dans le cache applicatif (Application Cache). Tout fichier présent dans ce manifest sera téléchargé par le navigateur et rendu disponible à l'application quand le serveur sera injoignable.

Le manifest contiendra des entrées correspondant à des fichiers provenant de trois sources différentes :

• les fichiers statiques de l'application. Ce sont les fichiers tels que index.html, les bibliothèques Javascript utilisées par l'application et aussi les css, etc. ;
• les fichiers javascript issus de la compilation GWT. Ceux-ci seront listés dans un fichier « offlinedemo-artifacts.lst » généré par le linker spécial que nous ajoutons à la compilation GWT (AppCacheLinker) ;
• les fichiers référencés par les articles contenus dans la base de données.

Nous voyons donc que la liste des fichiers n'est pas connue à l'avance. Nous allons donc générer le manifest grâce à la servlet ManifestServlet. Cette servlet contient deux méthodes notoires :

• readFile() : lit le contenu d'un fichier ligne par ligne et ajoute chaque entrée dans le manifest ;
• listFiles() : parcourt récursivement le contenu d'un répertoire et ajoute chaque fichier trouvé au manifest.

Nous utilisons ces deux méthodes pour inclure dans le manifest les fichiers générés par la compilation GWT, ainsi que tous les fichiers à transférer vers le serveur par les utilisateurs.

Nous allons maintenant voir comment mettre en place un SGBD dans le navigateur, en restant compatible avec tous les grands navigateurs du marché.

VI-A. SQL.js▲

VI-B. Persistance de la base▲

VI-C. Initialisation de la base▲

Une fois cette persistance obtenue, il faudra ensuite charger la base de données au démarrage de l'application. Voici le diagramme de fonctionnement :

Si une sauvegarde de la base a déjà été effectuée, nous trouverons dans le Local Storage la chaîne de caractères, au format JSON représentant ce tableau d'entiers, qui lui-même représente un fichier SQLite binaire.

Dans le cas contraire (la base n'a jamais été sauvegardée), nous créons une instance toute fraîche, puis nous exécutons les instructions DDL permettant la création des tables requises par notre application. Les instructions DDL se trouvent dans le fichier schema.sql, que nous chargeons par le biais du mécanisme GWT des ClientBundle.

VI-D. Consultation et stockage des Entités, côté client (mini ORM)▲

JavaScriptObject jsoResult = sqlDb.execute( "select * from articles where code like '%xx%' group by price" );  
SQLiteResult result = new SQLiteResult( jsoResult );  
for( SQLiteResult.Row row : result ) {  
 int id = row.getInt( "id" );  
 String code = row.getString( "code" );  
}

TableRecordSerializer<article> serializer = Serializer.getSerializer( "articles" );  
JavaScriptObject jsoResult = sqlDb.execute( "select * from articles where code like '%xx%' group by price" );  
SQLiteResult result = new SQLiteResult( jsoResult );  
for( SQLiteResult.Row row : result ) {  
 Article article = serializer.rowToDto( row );  
}

public List<article> getArticles() {  
 JavaScriptObject sqlResults = sqlDb.execute( "select * from articles" );  
 return deserializeRecords( sqlResults, "articles" );  
}  
  
private <T> List<T> deserializeRecords( JavaScriptObject sqlResults, String tableName ) {  
 TableRecordSerializer<t> recordSerializer = Serializer.getSerializer( tableName );  
 List<t> res = new ArrayList<t>();  
 SQLiteResult rows = new SQLiteResult( sqlResults );  
 for( SQLiteResult.Row row : rows )  
  res.add( recordSerializer.rowToDto( row ) );  
 return res;  
}

VI-E. Exportation de la base pour sauvegarde ou consultation externe▲

// when the user clicks, we serialize the database content into  
// a Base 64 encoded Data URI  
// this leads the browser to show the "download file" dialog  
  
// export the SQLite database into an integer array  
JsArrayInteger data = DataAccess.get().exportDbData();  
  
// convert it into a Base64 stream  
byte[] bytes = new byte[data.length()];  
for( int i = 0; i < bytes.length; i++ )  
 bytes[i] = (byte) data.get( i );  
String encoded = new String( Base64Coder.encode( bytes ) );  
  
// we change the element's attributes before the default event  
// handling happens  
// so that the browser shows a file download, although all  
// happens locally in the browser.  
// Please note that i'm not sure that this will support 5Mb  
// files.  
exportDb.getElement().setAttribute( "download", "OfflineDemo.db" );  
exportDb.setHref( "data:application/octet-stream;charset=UTF-8;base64," + encoded );  
exportDb.setTarget( "_blank" );

Nous voilà donc rendus au problème de synchronisation : nous avons une base de données sur la couche serveur et une sur la couche cliente, il va falloir les synchroniser.

Afin de simplifier la problématique, je découpe en deux sous-problèmes : faire remonter les informations récentes depuis le serveur vers le client (nous l'appellerons la synchronisation descendante), et envoyer les informations récentes du client vers le serveur (ça sera la synchronisation montante).

VII-A. Synchronisation descendante▲

VII-B. Synchronisation montante▲

VII-C. Gestion des erreurs et des conflits▲

Dans le cahier des charges, nous avons émis le souhait de pouvoir associer des fichiers aux fiches article. Comment faire ?

Une première idée (naïve) consisterait à sérialiser en JSON le contenu des fichiers en question et de les stocker dans le Local Storage. Cependant, outre la complexité d'une telle technique, l'espace du Local Storage est limité à cinq Mo et est déjà utilisé par la base de données.

Nous allons utiliser une autre technique : la manipulation de l'Application Cache.

Lorsque le client transfère un fichier vers le serveur, le serveur associe le fichier ainsi créé à l'enregistrement de la table articles correspondant. Ce fichier va donc être inclus dans la prochaine version générée du manifest. Lorsque le client a terminé son envoi vers le serveur, nous demandons simplement au navigateur de mettre à jour son cache d'application, ce qui va avoir pour effet de stocker le fichier nouvellement transféré dans le cache du navigateur.

Un avantage notable est que le cache d'application n'a pas de limite de stockage prédéfinie et est réglable dans les options du navigateur. Un autre avantage est que nous pourrons désigner les fichiers par leur URL, que l'on soit en ligne ou pas.

VIII-A. Upload (pas en mode hors-ligne, quoique !)▲

Le fichier readme explique comment compiler et lancer l'application.

Pour son utilisation, c'est très simple. Il y a les vues Articles, Orders et Order detail qui permettent d'éditer les différentes tables de la base.

Voici un descriptif des boutons :

• la coche indique l'état de l'Application Cache. Dans cet état il est clean, mais l'application peut vous signifier qu'une nouvelle version du manifest est disponible et que vous pouvez recharger la page pour en profiter ;
• le signal permet de savoir si on est en mode « en ligne » ou « hors-ligne ». Lorsqu'il est vert, c'est en ligne, gris pour hors-ligne ;
• le bouton de sauvegarde permet de sauvegarder, en base de données locale, les modifications que vous avez effectuées dans la vue actuelle. En effet, vos modifications ne sont pas sauvegardées tant que vous ne cliquez pas ;
• le bouton de rafraîchissement permet de rafraîchir la vue courante avec les dernières informations reçues du serveur. Lorsque la synchronisation met à jour les données locales, le bouton clignote en rouge, pour vous signifier que c'est le moment de rafraîchir (ici une automatisation est possible !) ;
• le bouton « poubelle » efface toutes les données locales. Si vous rechargez ensuite la page, vous repartez de zéro ;
• le bouton download permet de récupérer une version binaire du fichier SQLite, à des fins de sauvegarde ou bien pour explorer la base de données locale avec un outil externe.

Vous pouvez vous amuser à éteindre et rallumer le serveur, avec plusieurs clients ouverts. Vous pouvez même utiliser votre téléphone ou votre tablette, c'est compatible !

Voilà, je vous invite à télécharger le projet sur github à cette adresse, afin de tester tout cela.

Cet article n'est pas rentré dans le fond des détails, mais survole l'architecture. Avec le code disponible, les deux se compléteront mutuellement. N'hésitez pas, si vous avez des difficultés de compréhension à poster un commentaire, j'essaierais d'approfondir l'article si besoin.

Cet article a été publié avec l'aimable autorisation de la société LTE ConsultingLTE Consulting.

Nous tenons à remercier jacques_jean pour sa relecture attentive de cet article et Mickaël Baron pour la mise au gabarit.