Ce gabarit est un modèle de projet Gradle pour la construction d'une application Adélia Web sous la forme d'un fichier au format WAR.
Cette construction impose que les objets Adélia faisant partie de cette application soient regroupés sous la forme d'artéfacts produits par un projet Adélia build.
De plus, ce gabarit permet, via le plugin Gretty (https://github.com/akhikhl/gretty), d'exécuter l'application Adélia Web sous Tomcat et d'exécuter des tests d'intégration.
Ces tests doivent être définis dans un autre projet Gradle.
Création d'un projet Adélia Web build
La création du projet s'obtient en décompressant le fichier %ADELIWS%\Build\templates\adelia web application.zip : le répertoire adelia web application obtenu peut être déplacé et renommé à volonté.
Le poste de construction de l'application Adélia Web et le poste de build Adélia peuvent être deux postes différents. ↑ Haut de page
Configuration d'un projet Adélia Web build
Après avoir créé un projet, il est nécessaire de le configurer avant de pouvoir l'exécuter. La configuration et l'initialisation d'un projet de build se basent sur les paramètres renseignés dans le fichier gradle.properties, à savoir :
Paramètres généraux
adeliaVersion (obligatoire)
Chaîne alphanumérique représentant le numéro de version du runtime Adélia inclus dans le WAR de l'application Adélia Web.
Cette version de runtime doit être supérieure ou égale à celle utilisée par le poste de build Adélia pour générer les artéfacts.
version (obligatoire)
Chaîne alphanumérique représentant le numéro de version de l'application. Chaque artéfact construit aura le même numéro de version. On distingue plusieurs types de version :
Les versions release (ou finales) représentant les versions officielles de l'application (ex : 1.0.0),
Les versions snapshot (ou instantanées) représentant les versions en cours de développement de l'application (ex : 1.0.1-SNAPSHOT),
Les versions pré-release (ou release-candidate) représentant les versions candidates à être les versions finales (ex : 1.0.1-RC01).
group (obligatoire)
Chaîne alphanumérique représentant l'identifiant du groupe ou de l'organisation à l'origine du projet.
La valeur suit les mêmes règles de nommage que les packages Java (ex : com.hardis), et on choisit généralement comme valeur le nom du top package du projet.
appWarName (optionnel)
Chaîne alphanumérique représentant le nom du fichier WAR produit. Par défaut, ce fichier a pour nom <nom du répertoire du projet>-<valeur du paramètre version>.war.
Si ce paramètre est renseigné, le fichier aura pour nom <valeur du paramètre appWarName>-<valeur du paramètre version>.war.
jwtProviderSupport (optionnel)
Ajouter la fonctionnalité de gestion de jetons d'authentification basée sur la technologie JWT. Ce paramètre a une valeur alphanumérique 'Y' (ajout du support) ou 'N' (pas d'ajout du support). Par défaut, ce paramètre vaut 'Y'.
openIDSupport (optionnel)
Ajouter la fonctionnalité d'authentification basée sur la technologie OpenID. Ce paramètre a une valeur alphanumérique 'Y' (ajout du support) ou 'N' (pas d'ajout du support). Par défaut, ce paramètre vaut 'N'.
Paramètres Gretty
Gretty (http://akhikhl.github.io/gretty-doc/index.html) est un plugin Gradle permettant d'exécuter des applications Web au sein de conteneurs de servlets J2EE intégrés.
Gretty supporte Jetty en version 7, 8 et 9 et Tomcat en version 8.5 et 9.
Par défaut, les versions exactes de Tomcat utilisés sont 8.5.35 et 9.0.13, mais il est possible de changer ces numéros de version.
La configuration de Gretty (http://akhikhl.github.io/gretty-doc/Gretty-configuration.html) et la configuration de l'exécution de l'application Web doivent se faire principalement dans le fichier build.gradle du projet (Dans ce gabarit, le conteneur de servlet paramétré est Tomcat 8).
tomcat9Version (optionnel)
Chaîne alphanumérique représentant le numéro de version du Tomcat 9 à utiliser (https://archive.apache.org/dist/tomcat/tomcat-9/).
Assurez-vous que le changement de valeur de version reste en cohérence avec la valeur du paramètre tomcat8ServletApiVersion.
tomcat9ServletApiVersion (optionnel)
Chaîne alphanumérique représentant le numéro de version de la spécification de l'API Servlet utilisée par l'implémentation du Tomcat défini par tomcat9Version.
Cette valeur est donnée dans le tableau disponible à l'adresse suivante : https://tomcat.apache.org/whichversion.html.
tomcat85Version (optionnel)
Chaîne alphanumérique représentant le numéro de version du Tomcat 8.5 à utiliser (https://archive.apache.org/dist/tomcat/tomcat-8/).
Assurez-vous que le changement de valeur de version reste en cohérence avec la valeur du paramètre tomcat85ServletApiVersion.
tomcat85ServletApiVersion (optionnel)
Chaîne alphanumérique représentant le numéro de version de la spécification de l'API Servlet utilisée par l'implémentation du Tomcat défini par tomcat85Version.
Cette valeur est donnée dans le tableau disponible à l'adresse suivante : https://tomcat.apache.org/whichversion.html. ↑ Haut de page
Paramètres d'exécution des tests d'intégration
Il est possible d'exécuter les tests d'intégration sur l'application Web après le démarrage de Tomcat.
Ces tests doivent être définis sous la forme d'un projet Gradle qui sera exécuté une fois l'application Web démarrée. Pour plus de détails, consultez la page d'aide sur la construction de tests d'intégration.
pathToIntegrationTestBuildFile (optionnel)
Définit le chemin (absolu ou relatif par rapport au répertoire du projet Adélia Web build) du fichier build.gradle qui déclare les tests à exécuter. ↑ Haut de page
Paramètres des gestionnaires de référentiels
L'utilisation des référentiels d'artéfacts lors de l'exécution d'un build Adélia Web se fait lors des phases suivantes :
Dans la phase de création du fichier WAR, le build utilise un référentiel pour télécharger (référentiel de download) les artéfacts nécessaires à la construction de l'artéfact de l'application Web. Ces artéfacts sont :
les artéfacts du runtime Adélia nécessaires à l'exécution d'une application Adélia Web,
vos propres artéfacts d'objets Adélia composant l'application web : ceux-ci sont issus de l'exécution d'un projet Adélia build.
Dans la phase finale de stockage de l'artéfact construit, il est possible de définir un référentiel pour transférer (référentiel d'upload) cet artéfact versionné.
En fonction du type de version (release ou snapshot), il est possible de définir le référentiel associé.
downloadArtifactsReleaseRepo (obligatoire)
URL d'accès au référentiel de download des artéfacts dépendants nécessaires au build. Ce référentiel doit permettre d'accéder :
aux artéfacts du référentiel Hardis (runtime Adélia Web),
à vos propres artéfacts d'objets Adélia composant votre application web. Ces artéfacts sont ceux en version release si vous builder votre application Web en version release.
Par défaut, et uniquement à titre d'exemple, la valeur de ce paramètre est l'URL du référentiel est fourni par Hardis.
A la place, dans votre Nexus, il faut créer votre propre référentiel privé pour qu'il soit un regroupement du référentiel Hardis et de votre référentiel privé en version release (suivant votre propre configuration du Nexus utilisé pour vos projets Adélia build, il s'agit soit du référentiel crée par défaut par Nexus et nommé "Releases", soit un autre référentiel "hosted repository" ayant une "Repository policy" à Release et créée par vos soins).
Pour cela, après connexion à votre Nexus, à partir de la vue "Repositories", il faut ajouter un nouveau référentiel défini comme groupe des référentiels décrits plus haut :
Ouvrez la fenêtre de définition d'un référentiel via la commande "Add repository group",
A partir de la section "Available Repositories", ajoutez, dans la section "Ordered Group Repositories", le référentiel privé qui est proxy du référentiel Hardis ainsi que le référentiel privé hosted qui sert de stockage à vos artéfacts en version release.
Pour finir, remplacez la valeur du paramètre downloadArtifcatsReleaseRepo par l'URL "Repository Path" du référentiel de groupe nouvellement créée.
downloadArtifactsReleaseRepo.username / downloadArtifactsReleaseRepo.password (optionnels)
Définit le profil utilisateur et le mot de passe utilisés pour la connexion au référentiel de download. Par défaut, et à titre d'exemple, ces identifiants sont ceux du référentiel de download Hardis, mais il faut les remplacer par ceux de votre propre référentiel privé de groupe (cf. downloadArtifactsReleaseRepo ci-dessus).
Comme on accède à ce référentiel en lecture seule, Nexus autorise une connexion anonyme : dans ce cas, laissez les champs "username" et "password" non renseignés.
downloadArtifactsSnapshotRepo (optionnel)
URL d'accès au référentiel de download des artéfacts dépendants nécessaires au build. Ce référentiel doit permettre d'accéder :
aux artéfacts du référentiel Hardis (runtime Adélia Web). Ces artéfacts ne sont disponibles qu'en version release,
à vos propres artéfacts d'objets Adélia composant votre application web. Ces artéfacts sont ceux en version snapshot si vous construisez votre application Web en version snapshot.
Dans votre Nexus, il faut créer votre propre référentiel privé pour qu'il soit un regroupement du référentiel Hardis et de votre référentiel privé en version snapshot. En fonction de votre propre configuration du Nexus utilisé pour vos projets Adélia build, il s'agit soit du référentiel crée par défaut par Nexus et nommé "Snapshots", soit un autre référentiel "hosted repository" ayant une "Repository policy" à Snapshot et créée par vos soins.
Pour cela, après connexion à votre Nexus, à partir de la vue "Repositories", il faut ajouter un nouveau référentiel défini comme groupe des référentiels décrits plus haut :
Ouvrez la fenêtre de définition d'un référentiel via la commande "Add repository group",
A partir de la section "Available Repositories", ajoutez, dans la section "Ordered Group Repositories", le référentiel privé qui est proxy du référentiel Hardis ainsi que le référentiel privé hosted qui sert de stockage à vos artéfacts en version snapshot.
Pour finir, remplacez la valeur du paramètre downloadArtifcatsSnapshotRepo par l'URL "Repository Path" du référentiel de groupe nouvellement créée.
downloadArtifactsSnapshotRepo.username / downloadArtifactsSnapshotRepo.password (optionnels)
Définit le profil utilisateur et le mot de passe utilisés pour la connexion au référentiel de download.
Ce profil doit permettre d'accéder à votre propre référentiel privé de groupe (cf. downloadArtifactsSnapshotRepo ci-dessus). Comme on accède à ce référentiel en lecture seule, Nexus autorise une connexion anonyme : dans ce cas, laissez les champs "username" et "password" non renseignés.
uploadArchivesReleaseRepo (optionnel)
URL d'accès au référentiel d'upload utilisé pour le stockage de l'artéfact WAR construit avec une version release.
Ce référentiel permettra de mettre à disposition les artéfacts en version finale.
uploadArchivesReleaseRepo.username / uploadArchivesReleaseRepo.password (optionnels)
Définit le profil utilisateur et le mot de passe utilisés pour la connexion au référentiel d'upload des artéfacts en version release.
Par défaut, Nexus permet d'utiliser le profil deployment (username et password fixés à la valeur "deployment").
uploadArchivesSnapshotRepo (optionnel)
URL d'accès au référentiel d'upload utilisé pour le stockage de l'artéfact WAR construit avec une version snapshot.
Ce référentiel permettra de mettre à disposition les artéfacts en cours de développement.
uploadArchivesReleaseRepo.username / uploadArchivesReleaseRepo.password (optionnels)
Définit le profil utilisateur et le mot de passe utilisés pour la connexion au référentiel d'upload des artéfacts en version snapshot.
Par défaut, Nexus permet d'utiliser le profil deployment (username et password fixés à la valeur "deployment"). ↑ Haut de page
Configuration des composants de l'application Adelia Web à builder
Ces composants sont les artéfacts d'objets Adélia issus de l'exécution d'un projet Adélia build. Il est nécessaire de les déclarer dans le projet Adélia Web build pour qu'ils soient ajoutés dans le WAR produit.
Pour cela :
ouvrez le fichier build.gradle avec un éditeur texte, puis,
dans la section "dependencies" (Declare your artifacts needed to build the web application here), déclarez vos artéfacts.
Artéfacts de type Web / Pojo
Ces artéfacts doivent être déclarés en insérant l'instruction suivante :
runtime group: '<nom du groupe de l'artéfact>', name : '<nom du fichier de l'artéfact sans la version>', version: '<numéro de version de l'artéfact>'
Exemple de déclaration d'artéfact issu d'un build par domaine :
Pour l'artéfact de type Web dont le nom de fichier est myapp-app_area_1_web-1.1.0-SNAPSHOT.jar, il faut saisir runtime group: 'my.company', name : 'myapp-app_area_1_web', version: '1.1.0-SNAPSHOT'.
La valeur de group est celle du paramètre group dans le fichier gradle.properties du projet Adélia build ayant construit l'artéfact.
Exemple de déclaration d'artéfact issu d'un build par composant :
Pour l'artéfact de type Web dont le nom de fichier est prefix_compo_1_web-1.1.0-SNAPSHOT.jar, il faut saisir runtime group: 'my.company', name : 'prefix_compo_1_web', version: '1.1.0-SNAPSHOT'.
La valeur de group est celle du paramètre "groupId" du composant dont est issu l'artéfact.
Artéfacts de type WSSoapJar
Ces artéfacts doivent être déclarés en insérant l'instruction suivante :
wsSoapJar group: '<nom du groupe de l'artéfact>', name : '<nom du fichier de l'artéfact sans la version>', version: '<numéro de version de l'artéfact>'
Exemple de déclaration d'artéfact issu d'un build par domaine :
Pour l'artéfact de type WSSoapJar dont le nom de fichier est myapp-_commons_wssoapjar-1.1.0-SNAPSHOT.jar, il faut saisir wsSoapJar group: 'my.company', name : 'myapp-_commons_wssoapjar', version: '1.1.0-SNAPSHOT'.
La valeur de group est celle du paramètre "group" dans le fichier gradle.properties du projet Adélia build ayant construit l'artéfact.
Exemple de déclaration d'artéfact issu d'un build par composant :
Pour l'artéfact de type WSSoapJar dont le nom de fichier est prefix_compo_1_wssoapjar-1.1.0-SNAPSHOT.jar, il faut saisir wsSoapJar group: 'my.company', name : 'prefix_compo_1_wssoapjar', version: '1.1.0-SNAPSHOT'.
La valeur de group est celle du paramètre "groupId" du composant dont est issu l'artéfact.
Artéfacts de type WSSoapAar
Ces artéfacts doivent être déclarés en insérant l'instruction suivante :
wsSoapAar group: '<nom du groupe de l'artéfact>', name : '<nom du fichier de l'artéfact sans la version>', version: '<numéro de version de l'artéfact>'
Exemple de déclaration d'artéfact issu d'un build par domaine :
Pour l'artéfact de type WSSoapAar dont le nom de fichier est myapp-_commons_wssoapjar-1.1.0-SNAPSHOT.zip, il faut saisir wsSoapAar group: 'my.company', name : 'myapp-_commons_wssoapaar', version: '1.1.0-SNAPSHOT'.
La valeur de group est celle du paramètre "group" dans le fichier gradle.properties du projet Adélia build ayant construit l'artéfact.
Exemple de déclaration d'artéfact issu d'un build par composant :
Pour l'artéfact de type WSSoapAar dont le nom de fichier est prefix_compo_1_wssoapjar-1.1.0-SNAPSHOT.zip, il faut saisir wsSoapAar group: 'my.company', name : 'prefix_compo_1_wssoapaar', version: '1.1.0-SNAPSHOT'.
La valeur de group est celle du paramètre "groupId" du composant dont est issu l'artéfact.
Artéfacts de type WSRest
Ces artéfacts doivent être déclarés en insérant l'instruction suivante :
runtime group: '<nom du groupe de l'artéfact>', name : '<nom du fichier de l'artéfact sans la version>', version: '<numéro de version de l'artéfact>'
Exemple de déclaration d'artéfact issu d'un build par domaine :
Pour l'artéfact de type WSRest dont le nom de fichier est myapp-_app_area_2_wsrest-1.1.0-SNAPSHOT.zip, il faut saisir runtime group: 'my.company', name : 'myapp-_app_area_2_wsrest', version: '1.1.0-SNAPSHOT '.
La valeur de group est celle du paramètre "group" dans le fichier gradle.properties du projet Adélia build ayant construit l'artéfact.
Exemple de déclaration d'artéfact issu d'un build par composant :
Pour l'artéfact de type WSRest dont le nom de fichier est prefix_comp_1_wsrest-1.1.0-SNAPSHOT.zip, il faut saisir runtime group: 'my.company', name : 'prefix_comp_1_wsrest', version: '1.1.0-SNAPSHOT '.
La valeur de group est celle du paramètre "groupId" du composant dont est issu l'artéfact.
Artéfacts de type XXServer / CrystalReportsWeb
Ces artéfacts ne font pas partie du WAR produit. Si vous devez exécuter des tests d'intégration sur une application Adélia Web qui contient ces composants, vous devez les déployer à la main avant leur exécution. ↑ Haut de page
Fichiers de paramétrage de l'application Adélia Web à builder
Par défaut, un certain nombre de fichiers de configuration sont livrés avec ce gabarit. Ces fichiers sont décrits dans le tableau suivant :
Nom du fichier |
Chemin dans le site Web (dans l'arborescence du site créé par Adélia Web via l'option "Créer/Actualiser le site") |
Chemin dans le projet Adelia Web build |
AWSMobileDevices.properties |
<web-app>\WEB-INF\classes\ AWSMobileDevices.properties |
<projet web build>\src\main\resources\ AWSMobileDevices.properties |
axis2.xml |
<web-app>\WEB-INF\conf\axis2.xml |
<projet web build>\src\main\webapp\WEB-INF\conf\axis2.xml |
axis2.xml |
<web-app>\Axis2\conf\axis2.xml |
<projet web build>\src\main\webapp\Axis2\conf\axis2.xml |
CfgConfiguration.properties |
<web-app>\WEB-INF\classes\ CfgConfiguration.properties |
<projet web build>\src\main\resources\ CfgConfiguration.properties |
ehcacheAdelWeb.xml |
<web-app>\WEB-INF\classes\ ehcacheAdelWeb.xml |
<projet web build>\src\main\resources\ ehcacheAdelWeb.xml |
RSJwtSecurity.key |
<web-app>\WEB-INF\conf\RSJwtSecurity.key |
<projet web build>\src\main\webapp\WEB-INF\conf\RSJwtSecurity.key |
server-config.wsdd |
<web-app>\WEB-INF\server-config.wsdd |
<projet web build>\src\main\webapp\WEB-INF\server-config.wsdd |
swagger.html |
<web-app>\swagger.html |
<projet web build>\ src\main\webapp\swagger.html |
web.xml |
<web-app>\WEB-INF\web.xml |
<projet web build>\src\main\webapp\WEB-INF\web.xml |
Tableau 1 : Fichiers de configuration
Il se peut qu'un certain nombre de ces fichiers aient été modifiés par l'utilisateur lors de la phase de développement de l'application Adélia Web. Il est alors nécessaire de propager les modifications des fichiers du site de l'application Web vers les fichiers du projet Adélia Web build. Cette propagation peut se faire soit manuellement, soit automatiquement via la tâche Gradle copyWebappConfigurationFilesFromAdeliaWebsite. ↑ Haut de page
Exécution d'un projet Adelia Web build
Liste des tâches Gradle du build Adélia Web
copyWebappConfigurationFilesFromAdeliaWebsite
Tâche de copie des fichiers de configuration (cf. tableau 1 ci-dessus) à partir d'un site d'une application Adélia Web. Le chemin du site doit être défini en fixant une valeur au paramètre pathToAdeliaWebsite présent dans le fichier gradle.properties.
L'ensemble des fichiers de configuration dans le répertoire du projet Adélia Web build sont remplacés par ceux présents dans le répertoire pathToAdeliaWebsite.
Cette tâche doit être appelée avant la tâche build.
build
Tâche de construction de l'artéfact WAR. Celui-ci est placé dans le sous-répertoire build\libs du projet de build.
clean
Tâche permettant de supprimer les objets créés lors de l'exécution de la tache build (le sous-répertoire build est supprimé).
appRunWar (tâche Gretty)
Démarre le conteneur de servlet paramétré (par défaut Tomcat 9) ainsi que l'application Adélia Web. Appuyez sur une touche dans la fenêtre de commande DOS qui a exécuté cette tâche pour arrêter le conteneur de servlet (cf. http://akhikhl.github.io/gretty-doc/Gretty-tasks.html).
appStartWar (tâche Gretty)
Démarre le conteneur de servlet paramétré (par défaut Tomcat 9) ainsi que l'application Adélia Web. Dans ce cas, la tâche appStop doit être exécutée pour arrêter le conteneur de servlet (cf. http://akhikhl.github.io/gretty-doc/Gretty-tasks.html).
farmIntegrationTest (tâche Gretty)
Déclenche l'exécution des tests d'intégration (si le paramètre pathToIntegrationTestBuildFile est renseigné).
Cette tâche est issue du plugin Gretty : le conteneur de servlets paramétré (par défaut Tomcat 8) est démarré ainsi que l'application Adélia Web, puis les tests d'intégration sont exécutés, et enfin le conteneur de servlet est arrêté.
Si l'artéfact WAR n'existe pas à l'appel de la tâche farmIntegrationTest, celui-ci est créé avant l'exécution de cette tâche.
uploadArchives
Cette tâche permet de transférer l'artéfact construit dans le référentiel d'upload.
Il est nécessaire de renseigner la clé uploadArchivesReleaseRepo ou uploadArchivesSnapshotRepo en fonction du type de version de l'artéfact.