Ce gabarit est un modèle de projet Gradle pour la construction d'une application Web hébergeant des services web Adélia de type REST 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 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 REST web services build

La création du projet s'obtient en décompressant le fichier %ADELIWS%\Build\templates\Rest web services application.zip  : le répertoire Rest web services application obtenu peut être déplacé et renommé à volonté.

Le poste de construction de l'application Web et le poste de build Adélia peuvent être deux postes différents.

↑ Haut de page

Configuration d'un projet REST web services 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 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'.

toolboxDocxToolBx (optionnel)

Ajoute dans l'application construite le runtime Adélia nécessaire à l'exécution des fonctions de la DLL DocxToolBx. Cet ajout manuel par l'utilisateur est obligatoire dans le cas où des programmes Adélia font un appel dynamique à ces fonctions (via un appel aux ordres APPELER_DLL / APPELER_CLASS, où le "/", les paramètres NomDLLouClasse et Fonction_Methode ne sont pas des littéraux alphanumériques mais des variables alphanumériques. Dans le cas d'un appel classique à la DocxToolBx (via un APPELER_DLL 'DocxToolBx' 'XXX'...), le runtime est ajouté automatiquement (et ce paramètre n'est pas pris en compte).

Ce paramètre a une valeur alphanumérique "Y" (ajout du runtime) ou "N" (pas d'ajout du runtime). Par défaut, ce paramètre vaut "N".

toolboxXlsxToolBx (optionnel)

Ajoute dans l'application construite le runtime Adélia nécessaire à l'exécution des fonctions de la DLL XlsxToolBx. Cet ajout manuel par l'utilisateur est obligatoire dans le cas où des programmes Adélia font un appel dynamique à ces fonctions (via un appel aux ordres APPELER_DLL / APPELER_CLASS, où le "/", les paramètres NomDLLouClasse et Fonction_Methode ne sont pas des littéraux alphanumériques mais des variables alphanumériques. Dans le cas d'un appel classique à la XlsxToolBx (via un APPELER_DLL 'XlsxToolBx' 'XXX'...), le runtime est ajouté automatiquement (et ce paramètre n'est pas pris en compte).

Ce paramètre a une valeur alphanumérique "Y" (ajout du runtime) ou "N" (pas d'ajout du runtime). Par défaut, ce paramètre vaut "N".

toolboxVaToolBxKafka (optionnel)

Ajoute dans l'application construite le runtime Adélia nécessaire à l'exécution des fonctions Kafka de la DLL VaToolBx. Cet ajout manuel par l'utilisateur est obligatoire dans le cas où des programmes Adélia font un appel dynamique à ces fonctions (via un appel aux ordres APPELER_DLL / APPELER_CLASS, où le "/", les paramètres NomDLLouClasse et Fonction_Methode ne sont pas des littéraux alphanumériques mais des variables alphanumériques. Dans le cas d'un appel classique aux fonctions Kafka (via un APPELER_DLL 'VaToolBx' 'VaToolBxSendToAvroKafkaXXX'...), le runtime est ajouté automatiquement (et ce paramètre n'est pas pris en compte).

Ce paramètre a une valeur alphanumérique "Y" (ajout du runtime) ou "N" (pas d'ajout du runtime). Par défaut, ce paramètre vaut "N".

toolboxVaToolBxAmqp (optionnel)

Ajoute dans l'application construite le runtime Adélia nécessaire à l'exécution des fonctions AMPQ de la DLL VaToolBx. Cet ajout manuel par l'utilisateur est obligatoire dans le cas où des programmes Adélia font un appel dynamique à ces fonctions (via un appel aux ordres APPELER_DLL / APPELER_CLASS, où le "/", les paramètres NomDLLouClasse et Fonction_Methode ne sont pas des littéraux alphanumériques mais des variables alphanumériques. Dans le cas d'un appel classique aux fonctions AMQP (via un APPELER_DLL 'VaToolBx' 'VaToolBxAMQPXXX'...), le runtime est ajouté automatiquement (et ce paramètre n'est pas pris en compte).

Ce paramètre a une valeur alphanumérique "Y" (ajout du runtime) ou "N" (pas d'ajout du runtime). Par défaut, ce paramètre vaut "N".

toolboxVaToolBxApe (optionnel)

Ajoute dans l'application construite le runtime Adélia nécessaire à l'exécution des fonctions Adélia Print Engine de la DLL VaToolBx. Cet ajout manuel par l'utilisateur est obligatoire dans le cas où des programmes Adélia font un appel dynamique à ces fonctions (via un appel aux ordres APPELER_DLL / APPELER_CLASS, où le "/", les paramètres NomDLLouClasse et Fonction_Methode ne sont pas des littéraux alphanumériques mais des variables alphanumériques. Dans le cas d'un appel classique aux fonctions de l'APE (via un APPELER_DLL 'VaToolBx' 'VaToolBxAPEXXX'...), le runtime est ajouté automatiquement (et ce paramètre n'est pas pris en compte).

Ce paramètre a une valeur alphanumérique "Y" (ajout du runtime) ou "N" (pas d'ajout du runtime). Par défaut, ce paramètre vaut "N".

↑ Haut de page

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 9.

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 tomcat9ServletApiVersion.

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 (en absolu ou relatif par rapport au répertoire du projet REST web services 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 REST web services 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 des web services Adélia de type REST,

• 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),

  • à vos propres artéfacts d'objets Adélia composant votre application web.  Ces artéfacts sont ceux en version release si vous buildez 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. 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é "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). 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.

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.

↑ Haut de page

Configuration des composants de l'application 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 REST web services 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 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 Pojo dont le nom de fichier est myapp-app_area_1_pojo-1.1.0-SNAPSHOT.jar, il faut saisir runtime group: 'my.company', name : 'myapp-app_area_1_pojo', 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 Pojo dont le nom de fichier est prefix_compo_1_pojo-1.1.0-SNAPSHOT.jar, il faut saisir runtime group: 'my.company', name : 'prefix_compo_1_pojo', 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_compo_1_wsrest-1.1.0-SNAPSHOT.zip, il faut saisir runtime group: 'my.company', name : 'prefix_compo_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

Ces artéfacts ne font pas partie du WAR produit.

Si vous devez exécuter des tests d'intégration sur une application Web qui contient ces composants alors vous devez les déployer à la main avant leur exécution.

↑ Haut de page

Fichiers de paramétrage de l'application 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 :

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 Web. Il est alors nécessaire de propager les modifications des fichiers du site de l'application Web vers les fichiers du projet REST web services build.

Cette propagation peut se faire soit manuellement, soit automatiquement via la tâche Gradle copyWebappConfigurationFilesFromAdeliaWebsite.

Exécution d'un projet REST web services build

Liste des tâches Gradle du build REST web services

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 REST web services 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 Web. Appuyer 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 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 9) est démarré ainsi que l'application 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.

↑ Haut de page