XWoot - logo

Ce document accompagne le Livrable L4 : Prototype XWiki Concerto V1 - Services P2P de base et Services de réconciliation des données.

Rédacteurs : Julien Maire, Pascal Molli, Gérôme Canals (INRIA)

Il est organisé de la manière suivante :

  • la partie 1 est une introduction et replace le livrable dans le contexte du projet,
  • la partie 2 constitue une documentation à destination des utilisateurs,
  • la partie 3 contient la documentation de développement pour l'ensemble des composants du prototype.

Introduction

L'application XWoot est le prototype XWiki Concerto V1. Ce prototype implante des services P2P de base pour la dissémination de patchs sur un réseau P2P ainsi qu'un service de réconciliation de données basés sur l'algorithme Woot.

Cette implantation est basée sur l'architecture et les spécifications fournies dans le livrable L2-2, août 2007, section 2.4.1.2. Elle se base donc sur :

  • l'algorithme WOOT (WithOut Operational Transformation) pour la synchronisation des données textuelles (contenu des pages),
  • l'algorithme LPBCast pour la propagation des messages entre les différents noeuds du réseau.
  • la librairie JLibDiff développée par l'équipe ECOO (LORIA) pour le calcul des différences entre deux contenus.
  • l'utilisation d'une règle de Thomas (ThomasRuleEngine) pour la synchronisation des méta-données XWiki (attributs attachés aux pages).
XWoot est une application indépendante de XWiki qui a pour fonction principale la réplication de pages wiki sur un réseau P2P. Dans sa version actuelle, l'accès à XWiki n'est réalisé que pour des raisons de test et de démonstration. Cette connexion est réalisée à travers l'interface XML-RPC de XWiki. Cette interface est trés limitante puisqu'elle permet seulement

  • d'accéder au contenu courant d'une page et de quelques méta-données,
  • de positionner le contenu d'une page et de quelques méta-données.
Cette interface impose donc à l'application XWoot :

  • des limitations sur la réplication et la synchronisation des méta-données : toutes ne sont pas traitées,
  • de calculer elle même les patchs correspondant aux changements de contenu des pages,
  • de systématiquement et régulièrement accéder au contenu des toutes les pages pour détecter les éventuels changement.
Le dernier point pénalise particulièrement les performances de l'application. Il est donc conseillé de ne l'utiliser qu'en environnement de développement selon des scénarii d'utilisations bien précis (l'utilisation en environnement de production est déconseillée et se fera à vos risques et périls...).

La prochaine version de XWoot sera connectée à XWiki de manière plus efficace, c'est à dire en utilisant l'interface de publication de patchs qui doit venir étendre XWiki. L'utilisation de cette interface résoudra les limitations citées ci-dessus.

Documentation utilisateur

Installation

Fichier war

L'application compilée se présente sous la forme d'un fichier war, qui peut être déployé dans un container de Servlet (Ex recommandé : Tomcat -- voir l'installation de tomcat ).

Les sources de l'application sont disponibles sur le repository SVN suivant: http://svn.xwiki.org/svnroot/sandbox/org.xwoot/ . Le projet est sous Maven2 -- voir la documentation développeur pour plus de détail.

Configuration (fichiers de propriétés)

Une fois l'application Web déployée par le container de Servlet (i.e. création du dossier de même nom), il faut compléter deux fichiers de propriétés avec les valeurs appropriées. Ces fichiers se trouvent à la base du répertoire déployé (xwiki.properties et xwoot.properties).

xwiki.properties

  • xwiki.server : adresse de base du serveur XWiki auquel se connecter (ex : citrouille.loria.fr/xwiki)
  • xwiki.username : username utilisé pour la connexion à XWiki (ex : Admin -- les tests n'ont été effectués qu'avec le login de l'administrateur)
  • xwiki.password : password de l'utilisateur
  • xwiki.space : espace par défaut (exemple : Main)
  • xwiki.pageid : page par défaut (exemple : WebHome)
xwoot.properties

Warning: Sous windows il est nécessaire de doubler le caractère '\' dans les path.

  • xwoot.working.dir : dossier dans lequel sont stockés les objets sérialisés (dossier de travail de l'application : il doit exister et être accessible en lecture/écriture -- ex : /tmp/xwoot)
  • xwoot.site.id : identificateur unique du noeud (l'adresse IP peut faire l'affaire si elle ne dépasse pas 2147483648, car la valeur est stockée dans un entier ex : 152811181 )
  • xwoot.server.url : url de déploiement de l'application xwoot. Il est conseillé de ne pas utiliser localhost (faire un alias local de la forme "http://alias.fr/xwoot" ou utiliser un DNS) -- ex : http://concerto.loria:8080/xwoot)
  • xwoot.server.name : inutile mais doit être renseigner (laisser la valeur par défaut)
  • xwoot.refresh.log.delay : inutile mais doit être renseigner (laisser la valeur par défaut)
  • xwoot.neighbors.list.size : nombre maximal de voisins dans la table
  • xwoot.pbcast.round : nombre de rebond de chaque message (mettre le même nombre que celui de voisins)

Première exécution

Taper l'adresse de déploiement de l'application dans un navigateur Web. La servlet de bootstrap doit alors initialiser l'application et afficher la page principal de configuration de XWoot. Si un problème se pose par rapport aux données des fichiers de propriété, un message s'affiche.

Présentation de l’interface

L'interface principale permet (de haut en bas) :

  • d'ajouter l'ensemble des pages du Wiki aux pages à synchroniser
  • d'accéder à un menu de sélection manuelle des pages à synchroniser
  • de supprimer toutes les pages ajoutées dans les pages à synchroniser
  • de lancer une synchronisation
  • de voir une liste des voisins (avec pour chaque voisin la possibilité de le supprimer, de lancer un échange d'état ou une anti-entropie)
  • de voir une liste des pages à synchroniser

Conclusion

Du fait du mode d'interaction avec le serveur XWiki (interface XML-RPC), ce prototype fonctionne pour un nombre restreint de pages (ce nombre est fonction de la taille du contenu des pages). Un début de solution est aussi appliqué aux méta-données. La gestion des patchs transférée à l'application XWiki allègera considérablement l'application de réplication et permettra de résoudre les différents problèmes rencontrés.

Documentation développeur

Installation

Sources

Récupération des sources du projet : SVN http://svn.xwiki.org/svnroot/sandbox/org.xwoot

Les sources du projet s'articulent dans le format Maven2. L'ensemble des sources est en Java 1.5.

Maven2

Le projet XWoot est un projet Maven2 multi-module : à chaque composant de l'application correspond un module :

A la base du répertoire des sources se trouve le fichier pom principal de l'application ; il fait référence à chaque module dont il dépend. Dans chaque dossier de chaque module, se trouve un fichier pom.xml correspondant au composant. Ainsi, chaque composant peut être compilé séparément. Si la compilation réussie, un dossier target contenant le résultat de la compilation se met à jour (fichier jar ou war ...).

L'application XWoot correspond au module XWootApp ; c'est donc en compilant ce module que l'on peut obtenir le fichier war à déployer. Il est cependant préférable de compiler directement depuis le fichier pom principal (à la base du répertoire des sources), qui lui va compiler chacun des modules.

Les plugins maven2 utilisés sont :

  • Jalopy : formatage standard du code
  • Junit
  • Javadoc

Compiler le code

Après avoir déployer localement la librairie JLibDiff (depuis la base du projet XWoot) :

mvn install:install-file -Dfile=./xwootApp/src/main/resources/jlibdiff.jar -DgroupId=fr.loria.ecoo -DartifactId=JLibDiff -Dversion=2.0 -Dpackaging=jar

Remarque : il est prévu de créer un repository public permettant de directement télécharger la librairie JLibDiff lors de l'installation maven. En attendant, celle-ci est incluse dans le projet.

Afin d'obtenir un fichier war directement utilisable, il est nécessaire de spécifier les bonnes valeurs dans le fichier src/main/filters/filter.properties du module XWootApp. Cette étape est cependant optionnelle, puisque si elle n'est pas effectuée, le développeur pourra toujours modifier les fichiers de propriétés de l'application, une fois le War déployé par Tomcat.

Effectuer la commande suivante (depuis la base du projet XWoot) :

mvn install

un fichier war est générer dans le dossier target du module XWootApp. On peut aussi trouver le dossier de chacun des autres modules le jar correspondant.

Warning: par défaut, le cycle d'exécution de la commande mvn install contient l'exécution des tests unitaires (mvn test). Ainsi, pour compiler le projet XWoot, il est nécessaire que l'ensemble des tests valident. Or, l'application XWootApp a besoin de l'accès en XML-RPC de 3 applications XWiki pour pouvoir effectuer et réussir les tests. C'est pourquoi, pour réussir à compiler il faut :
  • Soit bien paramétrer les fichiers de propriétés utilisés par les tests dans chaque module (XWootApp src/test/ressources et WikiContentManager src/test/ressources)
  • Soit compiler avec l'option -Dmaven.test.skip=true (i.e : mvn install -Dmaven.test.skip=true)

Environnement de développement

l'ensemble du code a été développé sous l'environnement de développement Eclipse Standard, auquel peuvent être ajoutés les plugins suivants :

L'application a été principalement testée avec Firefox en environnement Linux.

Container de servlet

Pour déployer le fichier war, il est nécessaire d'utiliser un container de Servlet. Pour l'ensemble du développement, le container Tomcat a été utilisé.

Tests

Il est recommandé de lire les tests pour s'approprier plus facilement le code.

L'ensemble des tests a été réalisé avec Junit 4.4.

Les principaux composants utilisés par l'application XWoot possèdent un ensemble de tests JUnit. L'utilisation de Maven2 simplifie leurs exécutions ("mvn test" en ligne de commande dans le dossier du composant à tester, ou dans le dossier principal de l'application pour lancer l'ensemble des tests ; "run as mvn test" avec le plugin maven2 de Eclipse).

Log

La bibliothèque Log4J est utilisée dans les composants principaux pour logger le déroulement des opérations durant l'exécution.

Ainsi, un fichier xwoot.log est généré à la base du répertoire de l'application Tomcat (par défaut ; ceci est dépendant de la configuration de chacun).

Pour que ce fichier soit généré il est cependant nécessaire de configurer Tomcat selon la procédure décrite sur le site de Tomcat

JAVA Doc

Les classes principales de chaque composants ont une JavaDoc complétée. Celle-ci peut être facilement générée en utiliasant Maven2.

Architecture de l'application

archi_xwoot_proto_mars.jpg

Diagramme de composant de l'application XWoot

Les différents composants

Version 1.74 last modified by Julien MAIRE on 28/07/2008 at 11:32

Comments 0

No comments for this document

Attachments 3

BIN
XWoot - logo 1.1
PostedBy: Julien MAIRE on 20/02/2008 (14kb )
Image
archi_xwoot_proto_mars.jpg 1.1
PostedBy: Julien MAIRE on 20/02/2008 (195kb )
BIN
xwootApp.war 1.1
PostedBy: Julien MAIRE on 16/07/2008 (1Mb )
Partenaires


Creator: Julien MAIRE on 2008/02/20 08:58
Copyright INRIA, ENST, EISTI, Mandriva, XPertNet
1.1.1