Générer un projet avec Maven

tosiam-project-generator-maven-plugin est le plugin Maven officiel pour démarrer un projet TOSIAM. Il génère l’arborescence complète d’un projet multi-module (personnalisations d’authentification, de dashboard et de code Java, plus une instance locale QuickStart) et pilote ensuite le cycle de vie de cette instance locale (démarrage, arrêt, redémarrage, suppression, build, administration ssoadm).

Tous les goals sont invocables directement, sans projet Maven préalable :

mvn org.tst.tosiam:tosiam-project-generator-maven-plugin:<version>:<goal> [options]

Générer le projet — goal generate

mvn org.tst.tosiam:tosiam-project-generator-maven-plugin:3.36.0:generate \
    -Dtosiam.version=3.36.0 \
    [-DgroupId=org.tst.tosiam.example] \
    [-DoutputDirectory=.]

¹ Le paramètre a bien une valeur par défaut déclarée (${plugin.version}, c’est-à-dire la version du plugin invoqué), mais cette expression Maven ne se résout que si le plugin est déclaré dans le pom.xml du répertoire courant. Or generate est justement destiné à démarrer un projet dans un répertoire vide, sans pom.xml préalable (Maven utilise alors un “standalone-pom” interne) : dans ce cas l’expression ne se résout pas et Maven échoue avec The parameters 'tosiamVersion' ... are missing or invalid. En pratique, -Dtosiam.version doit donc toujours être précisé lors d’un premier generate dans un répertoire vide.

Ce que fait le goal

Avant toute écriture, le plugin vérifie que tosiam.version correspond bien à une release existante du dépôt theopensourceitrust/tosiam. Si ce n’est pas le cas, il échoue avec la liste des versions publiées disponibles, sans avoir créé ni modifié quoi que ce soit.

Une fois la version validée :

1. git init à la racine du répertoire cible, puis génération d’un .gitignore excluant au minimum tosiam-quickstart/ ;
2. auth/ : clone de tosiam-authentication-ui.git, positionné sur le tag <tosiam.version> ;
3. account/ : clone de tosiam-user-dashboard.git, positionné sur le tag <tosiam.version> ;
4. tosiam-quickstart/ : téléchargement de l’archive tosiam-quickstart-<tosiam.version>.zip (via l’API GitHub) puis décompression.

Structure générée

projet/
├── .git/
├── .gitignore
├── pom.xml
├── bom/
├── auth/
├── account/
├── custom-java/
└── tosiam-quickstart/

pom.xml est le POM parent et agrégateur ; il référence les modules bom, auth, account et custom-java dans <modules>. tosiam-quickstart/ n’est pas un module Maven de ce parent : c’est uniquement l’environnement QuickStart (Tomcat, TOSDJ, script bin/), exclu du dépôt Git via le .gitignore généré. Les modules auth, account et tosiam-quickstart sont conservés dans leur état d’origine, sans aucune modification de contenu.

• bom/ — packaging=pom, centralise ${tosiam.version} en propriété.
• custom-java/ — projet Java standard destiné à vos développements spécifiques, dépendant de org.tst.tosiam:tosiam-server-lib:${tosiam.version}. Son pom.xml copie automatiquement, à chaque build (phase package, maven-resources-plugin), le jar produit vers tosiam-quickstart/apache-tomcat-11.0.14/webapps/tosiam/WEB-INF/lib/ — donc aussi lors du build automatique déclenché par up, restart et deploy.

Piloter l’instance locale — goals up / down / restart / delete

Ces goals pilotent le cycle de vie de l’instance TOSIAM locale d’un projet déjà généré, en invoquant le script tosiam-quickstart/bin/tosiam.sh (sélection automatique de tosiam.bat sous Windows) :

mvn org.tst.tosiam:tosiam-project-generator-maven-plugin:3.36.0:up
mvn org.tst.tosiam:tosiam-project-generator-maven-plugin:3.36.0:down
mvn org.tst.tosiam:tosiam-project-generator-maven-plugin:3.36.0:restart
mvn org.tst.tosiam:tosiam-project-generator-maven-plugin:3.36.0:delete

La variable d’environnement TOSIAM_HOME est positionnée automatiquement sur <projectDirectory>/tosiam-quickstart ; un code retour non nul du script fait échouer le goal Maven.

Build automatique (up, restart, deploy)

Avant de démarrer ou redémarrer l’instance, les goals up et restart (et deploy, qui ne fait que ça) buildent l’intégralité du projet généré :

1. positionnement de TOSIAM_AUTHENTIFICATION (.../tosiam-quickstart/apache-tomcat-11.0.14/webapps/tosiam/auth) et TOSIAM_DASHBOARD (.../account), lues par les builds webpack des modules auth et account pour déterminer leur répertoire de sortie ;
2. exécution de mvn clean install à la racine du projet généré ;
3. copie automatique du jar custom-java dans WEB-INF/lib (voir ci-dessus).

Si ce build échoue, le goal Maven échoue immédiatement et tosiam.sh n’est pas invoqué.

Redéployer sans redémarrer — goal deploy

mvn org.tst.tosiam:tosiam-project-generator-maven-plugin:3.36.0:deploy

Effectue exactement le build décrit ci-dessus, sans invoquer tosiam.sh : le cycle de vie de l’instance locale (démarrée ou non) n’est pas modifié. Utile pour re-builder/redéployer auth, account et custom-java sans redémarrer l’instance.

Administrer l’instance — goal ssoadm

mvn org.tst.tosiam:tosiam-project-generator-maven-plugin:3.36.0:ssoadm \
    -Dssoadm.args="create-realm --realm /myrealm"

La ligne de commande Maven ne permettant pas de passer des arguments positionnels libres à un goal, ssoadm.args est retokenisée en arguments séparés sur les espaces, en respectant les guillemets simples et doubles — ce qui permet de passer des valeurs contenant des espaces :

mvn org.tst.tosiam:tosiam-project-generator-maven-plugin:3.36.0:ssoadm \
    -Dssoadm.args="update-realm --realm /myrealm --attributevalues description='Mon Royaume'"

Ce goal n’effectue aucun build préalable : il suppose une instance déjà démarrée (up exécuté au préalable). Voir la page CLI ssoadm pour la référence complète des commandes disponibles.

Gestion des erreurs

Le plugin échoue avec un message explicite (en français) dans les cas courants suivants :

• variable GITHUB_TOKEN absente/vide, ou version tosiam.version inexistante sur GitHub (liste des versions disponibles fournie dans le message) — goal generate ;
• répertoire cible de generate déjà existant et non vide ;
• répertoire tosiam-quickstart ou script tosiam.sh/ssoadm.sh introuvable — invitation à exécuter d’abord generate, ou à vérifier projectDirectory ;
• build Maven préalable en échec — goals up/restart/deploy ;
• propriété ssoadm.args absente ou vide — goal ssoadm.

Exemple complet

export GITHUB_TOKEN=ghp_xxx

mvn org.tst.tosiam:tosiam-project-generator-maven-plugin:3.36.0:generate \
    -DoutputDirectory=mon-projet-tosiam
cd mon-projet-tosiam

mvn org.tst.tosiam:tosiam-project-generator-maven-plugin:3.36.0:up

mvn org.tst.tosiam:tosiam-project-generator-maven-plugin:3.36.0:ssoadm \
    -Dssoadm.args="create-realm --realm /myrealm"

mvn org.tst.tosiam:tosiam-project-generator-maven-plugin:3.36.0:down