Table of Contents
List of Tables
- 6.1. Intervalles d'ID
Table of Contents
Dans son architecture globale, Scarab utilise le design pattern MVC (Modèle-Vue-Contrôleur). La partie qui interagit avec l'utilisateur (Vue) est découplée des données qui caractérisent l'état de l'application (Modèle) par un Contrôleur qui gère de manière déclarative la navigation dans Scarab.
Un framework, c'est une certaine manière de faire des applications plus des outils pour les faire. Le framework Turbine (http://jakarta.apache.org/turbine) c'est donc une doctrine pour réaliser des applications web suivant le design pattern MVC et des outils - notamment un certain nombre de composants et de projets - pour les faire. Certains de ces composants, utilisés par Scarab, sont détaillés ci-dessous.
Les données de formulaire soumises par l'utilisateur peuvent être d'abord soumises à un processus de validation (champs obligatoires, réponses bien formées, ...). Cette vérification est effectuée à l'aide d'un composant de Turbine appelé Intake.
Intake est aujourd'hui intégré à Fulcrum.
Note
Intake joue dans Turbine le même rôle que Struts Validator dans Struts, si vous êtes familier de ce framework.
Les règles de validation d'Intake sont décrites en XML dans le fichier
src/conf/intake.xml
La documentation d'Intake est disponible sur l'Internet à cette URL : http://jakarta.apache.org/turbine/fulcrum/fulcrum-intake.
C'est le coeur du framework. Comme dans tous les frameworks de type MVC2, il n'y a (pour l'essentiel) qu'un seul point d'entrée dans l'application, la servlet
scarab
qui est une instance de la classe
org.apache.turbine.Turbine
Le comportement de cette servlet est paramétré par cinq fichiers de properties recensés dans le descripteur de déploiement TurbineConfiguration.xml :
-
custom.properties -
defaultCustom.properties -
PermissionMapping.properties -
TurbineResources.properties -
Torque.properties
Note
Quelle version de Turbine ?
Si vous connaissez Turbine ou si vous avez consulté la documentation sur le site de Jakarta, vous avez dû réaliser que l'architecture des différentes versions de Turbine, notamment 2.3 et 2.4 qui sont les deux versions d'usage courant, est assez différente.
En fait, l'équipe de développement de Scarab tente de faire converger la version utilisée de Turbine avec 2.4. Scarab a en effet été développé avec une pré-version 3 de Turbine -- qui ne verra probablement jamais le jour; nous tentons donc de ramener Scarab dans le fulx normal du développement de Turbine en "baissant" de version.
Les fichiers de configuration mentionnés ci-dessus sont situés dans la distribution de Scarab sous
src/conf/conf/
et dans la web application sous
WEB-INF/conf
.
Turbine lui-même se trouve dans un jar sous www/repository/turbine/jars et les sources correspondantes sous www/repository/turbine/src. Comme expliqué dans la note plus haut, il s'agit d'une version intermédiaire à laquelle il n'est pas nécessairement possible de substituer une version identifiée.
La documentation du projet Turbine est disponible à cette URL : http://jakarta.apache.org/turbine.
L'architecture de Turbine 2.4 est basée sur la notion de services et l'utilisation d'un microconteneur de la famille Avalon. Un certain nombre de ces services (notamment Intake mentionné plus haut) sont intégrés à Fulcrum et utilisés par Scarab.
Les jars de Fulcrum (une bonne dizaine d'archives) sont sous www/repository/fulcrum/jars
La documentation de Fulcrum est disponible à cette URL : http://jakarta.apache.org/turbine/fulcrum/
Les services utilisés par Scarab sont implémentés au-dessus d'un microconteneur de la famille du (défunt) projet Avalon. YAAFI est d'ailleurs l'acronyme de Yet Another Avalon Framework Implementation.
YAAFI est fourni dans www/repository/fulcrum/jars/fulcrum-yaafi-1.0.3.jar
La documentation de YAAFI et de son interfaçage avec Fulcrum est disponible à cette URL : http://jakarta.apache.org/turbine/fulcrum/fulcrum-yaafi.
Les objets Java de l'application Scarab sont peuplés à partir d'une base de données relationnelle et persistés dans cette base en utilisant un composant logiciel autrefois partie intégrante de Turbine mais qui a depuis acquis son autonomie : Torque.
A partir d'une description de haut niveau du schéma de la base en XML, Torque va générer :
- des scripts de création du schéma de la base, pour les différents SGBDR;
- des classes Java qui mappent les différentes tables de la base de données sur des objets Java, avec un certain nombre de méthodes de recherches et d'accesseurs.
Si vous êtes intéressé(e) à en savoir davantage, vous pouvez vous référer au chapitre 3.
Les trois fichiers XML décrivant le schéma de la base sont dans le répertoire src/schema de la distribution Scarab.
La documentation du projet Torque est disponible à cette URL : http://db.apache.org/torque
Turbine peut fort bien s'accomoder des JSP (JavaServer Pages) mais le choix des premiers développeurs de Scarab était d'utiliser plutôt la technologie Velocity pour les pages dynamiques présentées à l'utilisateur.
Velocity est un langage de gabarits (templates); à l'exécution, les valeurs de JavaBeans placés dans le "contexte" du gabarit peuvent être insérées dans un contenu (statique) prédéfini.
Deux différences avec la technologie JSP (qui ont sans doute motivé le choix des initiateurs du projet Scarab) :
- s'il y a bien dans Velocity des structures de contrôle tels que conditions, boucles ou parcours de collection, contrairement aux JSP, il n'est pas possible d'insérer du code Java dans un gabarit; il n'y a donc pas d'équivalent des scriptlets, ce qui peut rendre la maintenance plus facile à long terme car la vue est vraiment découplée du contrôleur et du modèle;
- les JSP ne peuvent en pratique être utilisées que comme gabarits de pages web (c'est-à-dire pour la génération de HTML ou de XML); Velocity est un langage plus général et on peut l'utiliser pour générer des mails, des scripts SQL, du PostScript, etc.
Les gabarits Velocity des pages de Scarab (et des courriels, et de bien d'autres choses) sont sous le répertoire src/webapp/WEB-INF/templates.
La documentation du projet Velocity est disponible à cette URL : http://jakarta.apache.org/velocity.
Note
Notez que le manuel de l'utilisateur de Velocity est disponible en français : http://jakarta.apache.org/velocity/translations/user-guide_fr.html
Table of Contents
Abstract
L'application Scarab peut être construite par l'utilisateur en utilisant Apache Ant. C'est aussi avec Ant qu'est créée et initialisée la base de données.
C'est le fichier utilisé à titre principal pour le build.
La cible par défaut, deploy, génère le code des classes de mapping objet-relationnel (OM) puis compile et assemble l'application Scarab.
La seconde cible intéressante, create-db, est utilisée pour créer et initialiser la base de données de Scarab. Elle réalise ces opérations en utilisant le second fichier de build Ant, décrit dans la section suivante.
Le graphe de dépendance des cibles Ant devrait vous aider à visualiser la relation des cibles entre elles et l'ordre dans lequel elles sont exécutées.
Abstract
La plupart des utilisateurs de Scarab se servent probablement de ant pour construire Scarab. En tant que développeur, vous aurez besoin de Maven pour avoir accès à toutes les fonctionnalités de développement, notamment la génération de la documentation.
Bien que Maven 2 prenne de la vitesse et soit devenu la version officielle depuis fin 2005, Scarab utilise toujours Maven 1.
Maven 1 et Maven 2 sont à peu près équivalents d'un point de vue fonctionnel mais ils ne sont pas syntaxiquement compatibles et utilisent des fichiers de build différents.
Il vous faudra donc installer Maven 1 et vous référer à la documentation de Maven 1 à cette URL: http://maven.apache.org/maven-1.x/
Allez dans le répertoire $SCARAB_ROOT
Lancez Maven de la manière suivante :
maven war -Dmaven.test.skip
-Dmaven.test.skip évite d'exécuter les tests unitaires. Comme les tests sont conçus pour être exécutés avec une base de données, il est possible qu'ils échouent si la vôtre n'est pas encore configurée.
Si vous lancez les tests à présent, ils s'exécuteront sur la base de données que vous avez configurée. Tapez simplement
maven test
Le résultat des tests sera disponible dans $(SCARAB_HOME)/target/test-results/.
Si vous souhaitez exécuter les tests dans un autre environnement de base de données, procédez comme suit :
-
maven clean(il vaut mieux partir sur une base saine pour exécuter les tests) - Configurez votre fichier
build.propertiespour qu'il contienne au moins la valeur correcte de la propriétéscarab.database.type value -
maven war -
maven scarab:create-db(assurez-vous de choisir la même base qu'auparavant!) -
maven test
Table of Contents
Vous aurez besoin du plug-in subclipse pour vous connecter au repository Subversion qui contient et gère le code source de Scarab.
Si vous ne disposez pas de ce plug-in, vous pouvez consulter des instructions détaillées d'installation à cette URL: http://subclipse.tigris.org/install.html
Sélectionnez la perspective SVN Repository Exploring :
Un clic droit dans la vue SVN Repository vous permet de vous connecter à un nouveau repository Subversion :
L'URL de connexion est: http://scarab.tigris.org/svn/scarab
et l'URL racine (Root URL): http://scarab.tigris.org/svn
Si vous êtes un des committers de Scarab, utilisez vos identifiants sur tigris.org pour vous connecter; sinon, vous n'avez pas besoin d'authentification et il n'est donc pas nécessaire de remplir les champs User et Password (mais n'importe quelle paire User/Password fera aussi l'affaire).
Pour extraire la version courante, choisissez la branche 'trunk' (l'équivalent de CVS HEAD pour ceux qui ont pratiqué ce système de contrôle de versions auparavant).
Il vous suffit ensuite de l'extraire comme projet (Checkout As Project), ce qui vous permet de le renommer au passage car sinon il s'appellerait trunk, ce qui n'est pas très expressif.
L'assistant Nouveau Projet (New Project) apparaît. Déclarez qu'il s'agit d'un projet Java.
Le nom du projet vous est demandé (vous pouvez choisir scarab ou un autre nom à votre convenance).
Si vous utilisez Eclipse 3.1, il vous est demandé en plus de préciser avec quel J2SDK scarab doit être compatible. Pour l'instant, l'équipe de développement s'est astreinte à conserver la compatibilité avec le JDK 1.3.
A la dernière étape de l'assistant, il est préférable de modifier le chemin de sortie (Default output folder) pour lui donner la valeur suivante: scarab/target/webapps/scarab/scarab/WEB-INF/classes
Le plug-in Tomcat permet de lancer et arrêter Tomcat à partir d'Eclipse et facilite le débogage de l'application en cours de développement.
Téléchargez la version 3.1 beta du plugin Tomcat de Sysdeo à cette URL: http://www.sysdeo.com/eclipse/tomcatplugin.
Pour installer ce plug-in, il suffit de décompresser l'archive ZIP dans le répertoire plugins de votre installation Eclipse.
A la racine de votre projet Scarab, lancez les commandes:
maven war:inplace
maven eclipse
Cette dernière commande génère ou régénère un fichier .project nécessaire à Eclipse
Dans Window | Preferences... | Tomcat :
- Sélectionnez la version 4.0.x
- Répertoire de Tomcat: le répertoire tomcat dans votre projet Scarab
- Déclaration des contextes: dans server.xml
Dans Project | Properties | Tomcat :
- Cochez l'option 'Est un projet Tomcat'
- Nom du contexte: scarab
- Décochez l'option 'Autoriser la mise à jour de la définition du contexte'
- Cochez l'option 'Autoriser le rechargement automatique de ce contexte' (cette option est normalement cochée par défaut)
- Cochez l'option 'Rediriger les logs de ce contexte vers la console Eclipse'
Table of Contents
L'implémentation actuelle d'un client Subversion pour Netbeans est à l'état de prototype (son nom de code est "teepee", on peut suivre son développement à cette adresse ;http://subversion.netbeans.org/). Pour le moment, il vous faudra donc utiliser un autre client Subversion pour récupérer les sources depuis le repository de Scarab. Si vous développez sur Windows, un client agréable et facile à utiliser est TortoiseSVN - qui est hébergé par Tigris.org, comme Scarab.
Le meilleur moyen de développer Scarab dans Netbeans est très certainement d'utiliser le plug-in Mevenide (qui est d'ailleurs beaucoup plus stable et fonctionnel dans Netbeans qu'il ne l'est dans Eclipse, sans parler de JBuilder).
Téléchargez Mevenide for Netbeans depuis le site de Codehaus à cette URL : http://mevenide.codehaus.org/mevenide-netbeans-project/index.html
Vous obtiendrez ainsi un fichier ZIP contenant 16 nbm (Netbeans modules). Décompressez ce fichier dans un répertoire temporaire.
Tip
Si l'installation de modules dans Netbeans vous est familière, vous pouvez hardiment sauter cette section.
Dans le menu Tools, cliquez Update Center
Cochez 'Install Manually Downloaded Modules (.nbm Files)'
Utilisez le bouton 'Add...' button pour ajouter les 16 fichiers .nbm que vous avez téléchargés.
Cliquez 'Next >', ça suffira.
Il vous faut à présent accepter les différentes licences. Les modules sont alors prêts pour l'installation.
Consultez le certificat (il n'y en a qu'un) et cliquez 'Finish' pour finir d'installer les modules.
Vous devrez redémarrer Netbeans pour l'utiliser avec le plug-in Mevenide que vous venez d'installer.
Accéder au projet Scarab est maintenant aussi simple que possible. Dans le menu 'File', sélectionnez 'Open Project...'
Choisissez le répertoire dans lequel vous avez récupéré Scarab depuis le repository Subversion.
Et voilà!
Pour accéder aux 'buts' (goals) Maven, il suffit de faire un clic droit sur le projet Scarab.
Table of Contents
L'accès aux données de Scarab se fait par le biais de Torque, le mécanisme de mapping objet-relationnel développé pour et avec le framework Turbine -- mais qui a acquis aujourd'hui son indépendance.
Le schéma de la base de Scarab est décrit de manière formelle en XML. Ce schéma est explicité en trois parties et autant de fichiers, sous ./src/schema.
On y distingue :
- la table associée au mécanisme de fabrication de clés primaires (
id-table-schema.xml); - les tables de gestion des utilisateurs (notamment authentification) et des droits du framework Turbine (
turbine-schema.xml); - les tables de l'application Scarab elle-même (
scarab-schema.xml).
A partir de cette définition formelle du schéma de la base, Torque va générer :
- les scripts SQL (DDL) de création de tables pour différents SGBDR;
- un ensemble de classes java qui mappent sous forme d'objets les entités de la base (les "peers").
La plupart des tables du modèle de données de Scarab ont des entiers comme clés primaires. La plupart des SGBDR ont un mécanisme natif pour générer des clés primaires (entiers pas nécessairement consécutifs) : séquences Oracle, colonnes auto-incrémentées dans MySQL ou MSSQL, etc.
Comme Scarab se veut portable, la génération de ces clés primaires ne pouvait facilement se reposer sur ces mécanismes natifs. Scarab utilise donc pour cela une fonctionnalité de Torque ("id broker").
La table
id_table
est donc utilisée pour attribuer les clés primaires aux différentes tables.
Par convention, tous les identifiants inférieurs à 10.000 sont réservés au développement (données par défaut, données d'exemple, etc.)
Table 6.1. Intervalles d'ID
| Intervalle d'ID | Usage |
|---|---|
| 0-99 | Données nécessaires au fonctionnement de Scarab (required data). |
| 100-189 | Données par défaut. |
| 190-199 | Données relatives à l'utilisateur anonyme. |
| 200-299 | Gabarits JIRA. |
| 300-399 | Gabarits Bugzilla. |
| 1000-1999 | Données d'exemple (sample data). |
| 2000-8999 | (Réservé.) |
| 9000-9999 | Réservé à l'utilisateur (gabarits ou types de fiches personnalisés, etc.) |
Ces tables servent à authentifier et à gérer les utilisateurs, leur rôles et leurs droits dans les différents modules.
Les tables de cette partie du modèle sont :
-
turbine_user: contient les utilisateurs, leurs identifiants et authentifiants. -
turbine_role: définit la liste des rôles. Les rôles sont communs à tous les modules de Scarab. -
turbine_permission: définit les différentes permissions associées à l'application. -
turbine_group: cette table, peut-être nécessaire au bon fonctionnement de Turbine à l'exécution, n'est pas utilisée dans Scarab. Elle est toujours vide. - Les tables
turbine_user_group_roleetturbine_role_permissionsont des tables de relation m-à-n dont le fonctionnement est explicité par le diagramme ci-dessous :
La capture d'écran montre la définition des rôles dans Scarab (avec les données d'exemple) :
Voici une illustration du modèle de données correspondant :
Cette capture d'écran montre la gestion des rôles d'un utilisateur (avec les données d'exemple) :
Et voici l'illustration du modèle de données correspondant :
Avant de rentrer dans le coeur de l'application, mentionnons deux séries d'entités simples liées à l'utilisateur.
La liste des modules et les données correspondantes sont stockées dans la table scarab_module.
Tip
Notre responsable Qualité m'a demandé un jour une table de correspondance entre les codes modules et leur nom. Souvent, ce nom ne fait sens que précédé du libellé du module parent. Ce genre de tableau peut s'obtenir assez simplement à partir de la table SCARAB_MODULE en exécutant la requête suivante :
select M1.MODULE_CODE, M2.MODULE_NAME, M1.MODULE_NAME from SCARAB_MODULE M1, SCARAB_MODULE M2 where M1.PARENT_ID = M2.MODULE_ID order by M1.MODULE_CODE;
Et voilà !
Les types de fiches sont stockés dans la table scarab_issue_type. Les modules et les types de fiche sont associés les uns aux autres dans une relation de plusieurs à plusieurs (m-n) par le biais de la table de relation scarab_r_module_issue_type.
Les types de fiches globaux, illustrés ci-dessous sont associés au module "Global" (dont l'ID est 0).
Pour un module et un type de fiches donnéLe regroupement des attributs est utilisé
Table of Contents
Comme il a été dit brièvement dans le chapitre Workflow du Guide de l'utilisateur, Scarab n'a pas de workflow "codé en dur". Les transitions d'état lors de l'enregistrement des fiches sont toutes permises, et cela n'entraîne pas non plus d'interaction avec quelque système externe que ce soit.
Examinons brièvement comment ceci est implémenté.
Techniquement, un workflow est toute classe java qui implémente l'interface org.tigris.scarab.workflow.Workflow (le code source de cette interface se trouve sous src/java).
Le workflow est instancié dynamiquement par Turbine sur base d'une déclaration dans Scarab.properties (ce fichier se trouve à l'exécution dans l'arborescence de l'application web sous WEB-INF/conf).
# The workflow tool
# scarab.workflow.classname=org.tigris.scarab.workflow.DefaultWorkflow
scarab.workflow.classname=org.tigris.scarab.workflow.CheapWorkflow
C'est le workflow par défaut pour toutes les versions de Scarab jusqu'à la milestone 19.
Ce workflow est implémenté dans la classe org.tigris.scarab.workflow.DefaultWorkflow. C'est un bouchon (stub) qui ne fait rien et accepte toutes les transitions.
C'est le workflow par défaut pour les versions de Scarab à partir de la milestone 20. Son fonctionnement est expliqué dans le Guide de l'utilisateur.
Ce workflow est implémenté dans la classe org.tigris.scarab.workflow.CheapWorkflow (malgré les apparences). Il implémente l'interface Workflow indirectement en héritant du workflow par défaut, DefaultWorkflow sans doute pour ne pas devoir redéfinir certains comportements par défaut.
Pour définir un nouveau workflow, utilisant d'autres mécanismes, communiquant avec un ou plusieurs systèmes externes ou simplement adapté aux besoins et aux processus de votre organisation, il vous suffit donc :
- d'écrire une classe java qui implémente l'interface
org.tigris.scarab.workflow.Workflow(soit directement, soit en héritant deorg.tigris.scarab.workflow.DefaultWorkflow); - de définir le nom de cette classe dans le fichier
Scarab.propertiesmentionné plus haut.
Quelqu'un a commencé à implémenter une passerelle entre Scarab et le moteur de workflow open-source WfmOpen. Il reste de cette implémentation une entrée sur le tracker de SourceForge à cette URL : http://sourceforge.net/tracker/index.php?func=detail&aid=961620&group_id=76143&atid=546206.
L'état de ce développement n'est pas connu.
Il est possible d'utiliser à distance les fonctionnalités de Scarab via XML-RPC.
Un exemple d'utilisation se trouve dans l'arborescence des sources (src/java) :
- la classe
org.tigris.scarab.util.SimpleHandler.java(serveur, s'exécute côté Scarab) est utilisée pour l'intégration Scarab-Subversion (se référer au chapitre correspondant du Guide de l'utilisateur); - la classe
org.tigris.scarab.util.SimpleHandlerClient.java(client, s'exécute dans une autre application) est un exemple simple d'utilisation du serveur XML-RPC.