Utilisation de Maven

Introduction

Le développement sous Lutèce, notamment la construction et l'assemblage des composants, est basé sur l'outil Apache Maven. La très grande modularité de Lutèce engendre nécessairement une complexité liée à l'assemblage des composants et à la gestion des dépendances. Cette complexité est gérée par le modèle proposé par Maven par le biais du Project Object Model (POM). Afin de tirer le meilleur profit de cet outil, un plugin spécifique pour Lutece a été réalisé pour traiter les tâches complexes de construction et d'assemblage.

Le plugin Lutèce pour Maven

Le plugin Lutèce Maven permet d'encadrer les tâches de développement et de distribution de Lutèce et de ses plugins. Il permet de plus de préparer des sites web en "assemblant" une version du Core Lutèce et un certain nombre de plugins.

Les goals

Le plugin Lutece pour Maven introduit les goals suivants :

Création d'une webapp de test

Webapp mono-projet

Pour tester manuellement le plugin développé, dans une webapp Lutèce, utiliser le goal lutece:exploded :

$ mvn lutece:exploded

Cela va :

• récupérer l'artefact lutece-core du repository Maven.
• installer et préparer la version du Core dans le dossier target/lutece.
• copier les composants spécifiques au plugin vers ce répertoire.
• copier tous les fichiers de configuration spécifiés.

Suite à ce processus, le dossier target/lutece contient une instance de Lutèce avec votre plugin installé.

Webapp multi-projets

Lorsque les développements en cours concernent plusieurs composants, la construction d'une webapp de test nécessite de récupérer ces composants localement. Ceci peut-être réalisé de deux manières :

• En plaçant les composants dans le dépôt Maven local.
• En utilisant un projet parent multi module ayant ces composants comme modules.

Utilisation du dépot maven local

Un composant peut être pousser dans le dépot Maven local en invoquant la phase maven install :

$ mvn install

Une fois la commande exécutée la nouvelle version du composant sera disponible pour la construction de webapp avec les goals du plugin Lutèce Maven (lutece:exploded ou lutece:site-assembly).

Utilisation d'un projet multi-module

Voir Fonctionnement de lutece-maven-plugin partie Utilisation du Maven Reactor (multi module) pour savoir comment utiliser un projet multi-module avec le plugin Lutèce Maven.

Création de distribution

Génération d'une distribution du plugin

$ mvn lutece:assembly

Cette commande va générer deux archives :

• un ZIP contenant les sources du plugin
• un ZIP contenant une version binaire du plugin pouvant être collée sur une webapp existante (le plugin devra être activé dans l'interface d'administration)

Génération d'une distribution du Core

$ mvn lutece:assembly

Cette commande va générer deux archives :

• un ZIP contenant les sources du coeur
• un ZIP contenant :
  • un fichier WAR, d'une webapp du Core, minimale, prête à être déployée et pouvant servir de base au déploiement de plugins (qui devront être activés dans l'interface d'administration).
  • les fichiers d'initialisation de la base de donnée

Note Dans le cas d'une webapp destinée à exploiter plusieurs plugins, il est conseillé de réaliser un site Lutèce.

Autres utilisations de Maven

Obtenir des informations

Le plugin Maven Help permet d'obtenir des informations sur le projet ou le système.

La commande suivante permet par exemple de voir le POM construit par Maven à partir des POMs pris en compte par le projet (effective POM) :

$ mvn help:effective-pom

Initialiser la base de données

Sur les projets Lutèce construits avec le goal "lutece:exploded", le goal antrun:run permet l'initialisation de la base de données. Si la base de données existe alors elle est réinitialisée.

$ mvn antrun:run

La connexion avec celle-ci est configurée dans le fichier WEB-INF/conf/db.properties (voir Accès aux données).

Il est possible de surcharger le fichier db.properties du projet en passant un des arguments suivants dans la commande pour indiquer quel système de base de données utiliser :

• -Dlutece-test-mysql
• -Dlutece-test-postgresql
• -Dlutece-test-hsql

En fonction du système de base de données choisi, le db.properties sera surchargé par le modèle de db.properties pour ce système. Des arguments falcultatifs peuvent être ajoutés pour configurer la connection avec la base de données (pour MySQL ou PostGreSQL uniquement) :

• -Dlutece-antrun-db-host=XXX
• -Dlutece-antrun-db-name=XXX
• -Dlutece-antrun-db-user=XXX
• -Dlutece-antrun-db-password=XXX

Les valeurs par défaut pour ces derniers arguments sont les suivants :

• lutece-antrun-db-host : localhost,
• lutece-antrun-db-name : lutece,
• lutece-antrun-db-user : lutece,
• lutece-antrun-db-password : motdepasse.

Exemples :

# crée une base hsql fichier dans target/
$ mvn lutece:exploded antrun:run \
    -Dlutece-test-hsql

# PostGreSQL
$ mvn clean lutece:exploded antrun:run \
    -Dlutece-test-postgresql \
    -Dlutece-antrun-db-user=postgres \
    -Dlutece-antrun-db-password=postgres

# MySQL distant
$ mvn clean lutece:exploded antrun:run \
    -Dlutece-test-mysql \
    -Dlutece-antrun-db-host=vm18:3307 \
    -Dlutece-antrun-db-user=user19 \
    -Dlutece-antrun-db-password=$3cr3t \
    -Dlutece-antrun-db-name=test29

Appliquer les tests unitaire

Pour tester automatiquement le plugin (tests unitaires), on peut utiliser la commande suivante :

$ mvn lutece:exploded antrun:run test

Cela va :

• commencer par les opérations décrites dans l'étape précédente (test manuel).
• effacer et réinitialiser une base de donnée.
• lancer les test unitaires avec maven.

Gérer les dépendances

Le plugin Maven Dependency apporte des goals permettant de gérer les dépendances des projets. Parmi ceux-ci on peut citer :

• Le goal dependency:purge-local-repository qui permet de dupprimer les dépendances du projet dans le référentiel local et éventuellement de les résoudre de nouveau.

$ mvn dependency:purge-local-repository

• Le goal dependency:tree montre les différentes dépendances entre les packages :

$ mvn dependency:tree -Dverbose
# see only the Lutece dependencies
$ mvn dependency:tree -Dverbose -Dincludes=fr.paris.lutece*

• Le goal dependency:resolve liste les dépendances du site :

# list only the Lutece dependencies
$ mvn dependency:resolve -Dsort -DincludeGroupIds=fr.paris.lutece

Générer la documentation et les rapports de code

La phase site est utilisée pour construire un site maven contenant la documentation sur le projet courant et les rapports de code :

$ mvn site

On peut générer la documentation sans les rapports pour que l'opération soit plus rapide :

$ mvn site -DgenerateReports=false -Dmaven.test.skip=true

Voir aussi la documentation du plugin Maven Site pour plus d'informations.

Remarque Il faut allouer plus de mémoire à Maven pour générer les rapports via la variable d'env MAVEN_OPTS=-Xmx1024m

Documentation Markdown

Un plugin Maven spécifique à Lutece permet de convertir la page d'accueil de la documentation au format xDoc (voir Normes de Documentation) en un fichier README.md au format Markdown utilisé par GitHub :

$ mvn xdoc2md:readme

Formater le code

Le plugin Maven Formatter permet de formater le code source suivant les règles du projet Lutèce :

$ mvn formatter:format

Mettre la licence Lutèce dans le code source

Le global POM fait référence au plugin License Maven qui permet d'ajouter ou de mettre à jour les licences dans les entêtes des fichiers sources.

Le plugin License Maven utilise le goal license:format pour ajouter ou mettre à jour la licence Lutèce dans les fichiers sources :

$ mvn license:format