Installation de l'AMBSS
Pour installer l'application, vous devez disposer d'un JDK ou JRE 1.8 au minimum.
L'application standard est packagée dans un fichier ZIP nommé ambss-distrib-XXX.zip, disponible dans le répertoire %ADELIWS%\distrib\AdeliaBrokerSubscribersService.
Remarque : L'installation d'une application personnalisée construite par le gabarit de construction d'une application AMBSS suit les mêmes principes (que ce soit à partir d'un fichier ZIP ou d'un fichier TAR produit).
Le contenu de l'archive est le suivant :
- Répertoire "bin" : contient les scripts pour lancer l'application.
- Répertoire "config" : contient les fichiers de configuration application.yml et application-dev.yml permettant d'externaliser la configuration de l'application Spring Boot Adelia Message Broker Subscriber Service (niveau de log, port d'écoute, etc.) ainsi que la configuration du runtime de l'AMBSS,
Répertoire "extdConfig" : contient les fichiers de configuration du runtime Adélia (wagon.xml, wagon.key, CfgConfiguration.properties, wicfgvla.ini et Pool.properties).
Il contient également le fichier "bean-context.xml" permettant de personnaliser la désérialisation JSON et le fichier de configuration des souscripteurs Adélia subscribersConf.yml.
- Répertoire "lib" : contient le binaire de l'application, à savoir ambss-XXX-exec.jar.
- Répertoire "samples" : contient une configuration exemple basée sur un souscripteur MQTT (disponible uniquement dans la distribution standard).
De plus, dans le cas d'une application personnalisée, l'archive peut contenir des sous-répertoires contenant les binaires des programmes Adélia à exécuter (par défaut, les répertoires "lib" et "class").
Il est possible de lancer l'application de deux façons :
- soit de manière ponctuelle (lancée à partir d'un interpréteur de commande), via les scripts pour Windows ambss.bat / ambss-dev.bat ou pour Unix ambss.sh / ambss-dev.sh,
- soit en tant que service (sous Windows uniquement), via le script ambssService.bat.
Options de lancement
L'AMBSS (standard ou personnalisé) se lance via les scripts de démarrage ambss.<bat/sh> ou ambss-dev.<bat/sh>.
Le script ambss-dev.<bat/sh> est à utiliser lors du développement des programmes EADELIA : il s'appuie sur le fichier de configuration application-dev.yml.
Le script ambss.<bat/sh> est à utiliser en production : il s'appuie sur le fichier de configuration application.yml.
Généralités
Pour afficher les options de la ligne de commande, lancer le script de démarrage avec l'option "-h" (les deux scripts offrent les mêmes options) :
Répertoire de génération
Pour indiquer un ou plusieurs répertoires contenant les programmes Adélia à exécuter (les répertoires de génération Adélia) ou les artéfacts de ces programmes, il faut utiliser l'option "-Dloader.path". Un répertoire peut être absolu ou relatif (dans ce cas il est relatif par rapport au répertoire parent du répertoire "bin", qui contient le script de démarrage lancé). Le séparateur de répertoire est "," (virgule).
Exemple : Si vous avez développé un programme EADELIA qui appelle un programme VA_B, qui utilise une classe Adélia, et que votre environnement Adélia est configuré pour générer les EADELIA dans "d:\adeliaGen\event", les VA_B dans "d:\adeliaGen\batch" et les classes dans "d:\adeliaGen\pojo", alors vous devez lancer la ligne de commande suivante :
ambss.bat -JVMoptions "-Dloader.path=d:/adeliaGen/event,d:/adeliaGen/batch,d:/adeliaGen/pojo"
Remarque : Cette option est plus utilisée en développement qu'en production. Pour la production, nous vous conseillons d'utiliser le gabarit pour la construction d'une application AMBSS car celui-ci produit un script de démarrage qui intègre l'option "-Dloader.path" avec le(s) répertoire(s) spécifié(s) en paramètre de la construction.
Configuration de souscripteurs Adélia
Comme l'ABMSS peut fonctionner sans fichier de configuration de souscripteurs Adélia, la prise en compte d'un fichier doit se faire via la ligne de commande en utilisant l'option "–ambss.subscribers.configuration". On peut indiquer soit une URI, soit un chemin dans le système de fichiers local. Ce chemin peut être absolu ou relatif (dans ce cas il est relatif par rapport au répertoire parent du répertoire "bin" qui contient le script de démarrage lancé).
Exemple : Pour utiliser le fichier subscribersConf.yml livré dans le sous-répertoire "extdConfig", vous devez lancer la ligne de commande suivante :
ambss.bat -APPparams "--ambss.subscribers.configuration=./extdConfig/subscribersConf.yml"
Remarque : Cette option est plus utilisée en développement qu'en production. Pour la production, nous vous conseillons d'utiliser le gabarit pour la construction d'une application AMBSS car celui-ci produit un script de démarrage qui intègre l'option "--ambss.subscribers.configuration".
Paramètres Spring Boot
Il est possible de spécifier dans la ligne de commande des paramètres Spring Boot en utilisant l'option -JVMoptions "-D<nom_paramètre>=<valeur>".
Par exemple, il est possible de changer le port d'écoute de l'application Spring Boot elle-même, via l'option "-Dserver.port=<port_number>", où "port_number" est le numéro de port HTTP défini pour l'application J2EE. La valeur par défaut est 8080.
De manière générale, la prise en compte d'une propriété Spring Boot dans la ligne de commande est prioritaire à celle définie dans le fichier application(-dev).yml.
Pour lancer l'application en tant que service Windows, il faut utiliser le script ambssService.bat.
Gestion du service Windows
Le script ambssService.bat permet d'installer, de désinstaller, de démarrer et d'arrêter l'application AMBSS en tant que service Windows. Ce script doit se lancer dans une fenêtre de commande DOS exécutée en tant qu'administrateur.
Pour rendre le service opérationnel, il est nécessaire de l'installer, puis de le démarrer. Lancez la commande ambssService.bat sans paramètres pour voir les options disponibles :
- install : Commande d'installation de l'application. C'est lors de cette étape que l'on peut spécifier des fichiers de configuration autres que ceux par défaut.
- start : Commande de démarrage de l'application,
- stop : Commande d'arrêt de l'application,
- uninstall : Commande de désinstallation de l'application (avec arrêt automatique de l'application avant désinstallation).
Pour installer le service AMBSS avec les options exemples ci-dessus, utilisez les options d'installation comme ceci :
ambssService.bat "mon service ambss" -install -JVMoptions "-Dloader.path=d:/adeliaGen/event,d:/adeliaGen/batch,d:/adeliaGen/pojo" -APPparams "--ambss.subscribers.configuration=./extdConfig/subscribersConf.yml"
Par défaut, deux fichiers de journalisation (contenant les journaux de sortie et d'erreur de la console) nommés <nom du service>_out.log et <nom du service>_err.log sont créés dans le sous-répertoire bin (contenant le script ambssService.bat). ↑ Haut de page
Administration du pool de sessions Middleware
Lors de l'exécution de l'AMBSS il est possible de voir l'état du pool de sessions Middleware utilisées par les programmes EADELIA. Pour cela, une URL est mise à disposition : http://<host ambss>:<port ambss>/ambss/PoAdmin. Elle permet d'accéder à la servlet d'administration du pool de sessions Middleware.
Remarque : Cette URL est en libre accès lorsque l'AMBSS est lancé avec le profil de développement (script ambss-dev.<bat/sh>), mais est uniquement accessible avec un jeton JWT ayant le rôle ADMIN lorsque l'AMBSS est lancé avec le profil de production (script ambss.<bat/sh>) et que l'authentification par jeton JWT est activée (propriété "ambss.security.enabled"). ↑ Haut de page
Environnement d'exemples
L'environnement BDCADEL contient un programme EADELIA d'exemple (programme SUBSCRIBE_MQTT dans le domaine EADELIA). Ce programme est un souscripteur MQTT v3 et v5.
Pour le tester, il faut un courtier de message MQTT comme par exemple Mosquitto, disponible sous Windows, Mac OS et Linux.
Configuration de l'AMBSS
La distribution standard de l'AMBSS (disponible dans le répertoire %ADELIWS%\distrib\AdeliaBrokerSubscribersService) contient dans le sous-répertoire "sample" un fichier de configuration de souscripteurs exemple utilisable avec le programme SUBSCRIBE_MQTT.
Il faut lancer l'AMBSS avec les options suivantes :
ambss.bat -JVMoptions "-Dloader.path=d:/adeliaGen/event/classes" -APPparams "–ambss.subscribers.configuration=./samples/subscribersConf_MQTT_sample.yml"
où "d:/adeliaGen/event/classes" est le répertoire de génération des objets du programme SUBSCRIBE_MQTT.
Lancement de l'écosystème MQTT Mosquitto
Avant de lancer l'AMBSS, veillez à démarrer le courtier de messages Mosquitto via l'exécutable mosquitto.exe (voir l'aide en ligne). Le courtier démarre par défaut sur le port 1883. Sous Windows, il faut le lancer avec les droits Administrateur (dans une fenêtre de commandes en mode Administrateur par exemple).
Exemple : Pour lancer le courtier en mode verbeux :
mosquitto.exe -v
Pour envoyer un message, il faut utiliser l'exécutable mosquitto_pub (voir l'aide en ligne).
Exemples :
Pour envoyer un message MQTTv3 sur le topic "ambssTopicTest/topic1" à destination des souscripteurs "subMQTTv3_1" et "subMQTTv3_3" :
mosquitto_pub.exe -t ambssTopicTest/topic1 -m "My first message"
Pour envoyer un message MQTTv3 sur le topic "ambssTopicTest/topic2" à destination des souscripteurs "subMQTTv3_2" et "subMQTTv3_3" :
mosquitto_pub.exe -t ambssTopicTest/topic2 -m "My second message"
Pour envoyer un message MQTTv5 sur le topic "ambssTopicTest/topic3" à destination du souscripteur "subMQTTv5_1" (message contenant des couples de propriétés utilisateur) :
mosquitto_pub.exe -t ambssTopicTest/topic3 -m "My third message" -V mqttv5 -D PUBLISH user-property "userKey1" "userValue1" -D PUBLISH user-property "userKey2" "userValue2"
Test des API REST
Il est possible de tester ces API à l'aide d'un client REST (non fourni) comme Insomnia ou Postman. Le sous-répertoire samples contient deux fichiers ambss-rest-api-mqtt-sample-insomnia-export.yaml (compatible avec Insomnia) et ambss-rest-api-mqtt-sample-http-archive-format-export.har (compatible avec Postman ou tout client supportant le format "HTTP Achive Format"). Ces fichiers contiennent l'ensemble des API REST à tester dans le contexte d'exécution de l'exemple MQTT (subscribersConf_MQTT_sample.yml).